ttpos-doctor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ttpos-doctor

ttpos-doctor

先读
ttpos-shared
。遇到环境问题先跑它,别逐个猜。
bash
ttpos doctor --format json             # 只查本机,不访问 TTPOS 服务端
ttpos doctor --network --format json   # 追加 upstream 项,实际连一次服务端
agent 必须显式加
--format json
:这条命令被调用时默认仍输出文本。
Read
ttpos-shared
first. When encountering an environment issue, run it first instead of guessing one thing at a time.
bash
ttpos doctor --format json             # Checks only the local machine and does not access the TTPOS server
ttpos doctor --network --format json   # Adds the upstream check and actually connects to the server once
The agent must explicitly add
--format json
: when this command is invoked, it still outputs text by default.

读输出

Reading the Output

json
{"ok":false,"checks":[{"id":"auth","status":"fail","label":"登录态","detail":"未登录","fix":"运行 ttpos auth login"}],"summary":{"ok":3,"warn":2,"fail":1,"skip":0}}
  • 顶层
    ok
    :没有
    fail
    就是
    true
    ,
    warn
    、
    skip
    不影响。能不能继续跑业务命令读它就够。
  • status
    :
    ok
    warn
    fail
    skip
    。
    skip
    不是通过,是前序失败后没有跑。
  • fix
    可能不存在,这时线索在
    detail
    (如
    upstream
    失败时是服务端原文)。
退出码与其他命令不同:
0
没有 fail;
1
至少一项 fail(未登录也是 1,不是 3);
2
用法错误。
json
{"ok":false,"checks":[{"id":"auth","status":"fail","label":"登录态","detail":"未登录","fix":"运行 ttpos auth login"}],"summary":{"ok":3,"warn":2,"fail":1,"skip":0}}
  • Top-level
    ok
    : it is
    true
    when there are no
    fail
    results;
    warn
    and
    skip
    do not affect it. Reading this field is sufficient to determine whether business commands can continue.
  • status
    :
    ok
    ,
    warn
    ,
    fail
    , or
    skip
    .
    skip
    does not mean success; the check was not run because an earlier check failed.
  • fix
    may be absent, in which case the clue is in
    detail
    (for example, an
    upstream
    failure contains the server's original response text).
Exit codes differ from those of other commands:
0
means there are no failures;
1
means at least one check failed (not being logged in is also
1
, not
3
);
2
means a usage error.

各项检查

Individual Checks

id异常时怎么处理
cli-version
warn
表示开发构建,不阻断
gateway
会话库被占用:等其他 ttpos 进程结束后重试,不要设
TTPOS_CONFIG_DIR
绕开
,那会打开第二份空库。权限问题:检查数据目录,或设
TTPOS_CONFIG_DIR
指向可写目录。
warn
是版本不一致,不阻断
credentials
没有 token 也是
ok
,登录态只看
auth
。
warn
是凭证文件权限不是 0600,按
fix
执行
chmod
。
fail
看
detail
data-dir
只会
ok
或
warn
,不受其他项影响。检查目录权限(容器要挂可写卷)。
auth
fail
:请人运行
ttpos auth login
。
skip
:先解决
gateway
shop-context
warn
:没配默认商户,属可选项,可用
ttpos shop use <标识>
或每次传
--shop
。
fail
:配置文件损坏,按
detail
里的路径修复
upstream
只在
--network
时出现。
skip
:先解决
gateway
、
auth
。
fail
:看
detail
连锁规则:
gateway
为
fail
时
auth
、
upstream
跳过;
auth
不是
ok
时
upstream
跳过。
gateway
只是
warn
不会触发跳过。
idHow to handle an abnormal result
cli-version
warn
indicates a development build and does not block execution.
gateway
The session store is in use: wait for other ttpos processes to finish, then retry. Do not set
TTPOS_CONFIG_DIR
to bypass this
, because that would open a second empty store. For permission issues, inspect the data directory or set
TTPOS_CONFIG_DIR
to a writable directory.
warn
indicates a version mismatch and does not block execution.
credentials
Having no token is also
ok
; only
auth
determines the login state.
warn
means the credential file permissions are not
0600
; run
chmod
according to
fix
. For
fail
, inspect
detail
.
data-dir
It can only be
ok
or
warn
and is not affected by other checks. Check directory permissions (mount a writable volume in a container).
auth
For
fail
, ask someone to run
ttpos auth login
. For
skip
, resolve
gateway
first.
shop-context
warn
means no default merchant has been configured. This is optional and can be handled with
ttpos shop use <identifier>
or by passing
--shop
each time. For
fail
, the configuration file is corrupted; repair it using the path in
detail
.
upstream
It appears only with
--network
. For
skip
, resolve
gateway
and
auth
first. For
fail
, inspect
detail
.
Chained rules: when
gateway
is
fail
,
auth
and
upstream
are skipped. When
auth
is not
ok
,
upstream
is skipped. A
warn
from
gateway
alone does not trigger any skips.