Skip to content

输出约定与退出码 ​

本页是脚本与 AI 对接的契约页:--json 的输出分工、ANSI 处理、退出码 0/1/2/3/4,以及 doctor / config / version 三个辅助命令。API 侧的响应封装与错误码见 认证与通用约定。

--json:stdout 只有数据 ​

  • stdout 只出现机器可读的 JSON;run -f --json / logs -f --json 是 JSONL 日志事件 + 一行结果对象(见 运行与日志)。
  • 所有提示、警告、错误一律走 stderr,不会污染 stdout。
  • 人类可读的表格、彩色摘要只在非 --json 时输出。
bash
deploy server list --json | jq '.current'
deploy run my-app --wait --json > result.json 2> progress.log

ANSI 与颜色 ​

  • TTY 下原样保留日志里的 ANSI 颜色。
  • 非 TTY、--no-color 或 NO_COLOR=1 时剥离 ANSI 转义序列;跨数据块被切分的转义序列也能正确剥离。
  • --verbose 的调试信息(HTTP 请求、重连、配置来源)始终走 stderr。

退出码 ​

退出码含义触发场景
0成功命令正常完成;run / logs -f 的运行终态为 success;跟随被 Ctrl+C 打断但没有取消运行
1部署失败运行终态为 failed / timeout / error / canceled
2用法错误参数不合法、命令/子命令不存在、非法 key、K=V 格式错误、--server 点名的服务器不存在、本地配置文件损坏、errorCode 为 40000/40400/40900 及其它 4xx
3鉴权失败未登录(token 为空)、HTTP 401、errorCode 40100、403 / 40300
4网络或服务不可用连接被拒、DNS 失败、超时、HTTP 5xx / errorCode 50000、42900 限流、响应不符合契约

注意区分「脚本退出码」与「CLI 退出码」:运行摘要里的退出码是部署脚本自身的返回值,CLI 只按运行终态映射 0/1。

bash 判断示例 ​

bash
deploy run my-app -f || case $? in
  1) echo "部署失败" ;;
  3) deploy login -a "$DEPLOY_ADDRESS" -u "$USER" -p "$PASS"; deploy run my-app -f ;;
  4) echo "服务端不可达,稍后重试" ;;
esac

PowerShell 判断示例 ​

powershell
deploy run my-app -f
switch ($LASTEXITCODE) {
  0 { "部署成功" }
  1 { "部署失败" }
  2 { "命令用法写错了" }
  3 { "token 过期,需要重新登录" }
  4 { "服务端不可达" }
}

doctor:服务端环境自检 ​

bash
deploy doctor            # 调 GET /system/doctor,彩色通过/失败标记 + 安装提示
deploy doctor --json     # 原样输出契约里的 doctor data

输出客户端/服务端版本、主机名、运行时长、workdir 与数据目录可写性、Shell 选择,以及逐项工具检查(git、docker、node 等);缺失项附安装提示。平台不代为安装工具链,只报告缺什么、怎么装。doctor 需要鉴权:未登录返回退出码 3。环境问题的进一步排查见 故障排查。

config:低层配置接口 ​

config 是键值读写的低层接口,面向脚本;日常与多服务器场景请用 server 命令组(见 安装与服务器管理)——它带校验、能整段管理一个服务器,并且不会因为只改一个字段而把别的字段清掉。

bash
deploy config get                       # 全部配置(token 打码)
deploy config get address               # 单项
deploy config get token                 # 唯一输出 token 明文的命令(供脚本使用)
deploy config set address http://127.0.0.1:10055
deploy config set token dk_xxxxxxxx
deploy config set current prod          # 切换默认服务器(低层写法,优先用 server use)
deploy config list                      # 所有服务器(NAME=名字,即配置里的键)
deploy config path                      # 配置文件路径

JSON 形状:

命令输出
config get --json{ current, address, token(打码), user, path }
config get address --json{ key, value, server:<当前服务器名字> }
config list --json{ current, servers:[{key,name,address,user,token,active}] }(key 与 name 同值)
config path --json{ path }

可写的键为 address / token / user / current,作用于当前服务器。token 打码的全局约定见 登录与身份。

version:版本信息 ​

bash
deploy version           # deploy <版本> (commit <hash>, built <时间>, <os>/<arch>, <go 版本>)
deploy version --short   # 只打印版本号
deploy version --json    # { version, commit, buildTime, go, os, arch }
deploy --version         # 等价写法

版本变量通过 -ldflags -X 在构建时注入(见 安装);未注入时显示开发默认值。