主题
输出约定与退出码
本页是脚本与 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.logANSI 与颜色
- 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 "服务端不可达,稍后重试" ;;
esacPowerShell 判断示例
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 在构建时注入(见 安装);未注入时显示开发默认值。