Skip to content

故障排查 ​

按现象索引。每行给出第一步检查与深入链接;通用诊断命令在文末。

现象索引 ​

现象第一步检查深入
网页缺失或占位页构建顺序:前端 → 拷贝 dist → Go;deploy doctor 看 web.built从源码构建
实时日志不刷新反代 WebSocket Upgrade/Connection 头、proxy_buffering offsystemd 与反代
Git 准备失败凭据「测试连接」;工作目录为空或已是该仓库;服务端到 Git 托管方连通性Git 准备阶段
找不到构建工具登录 Shell 读 /etc/profile 而非 ~/.bashrc;工具链面板装工具工具链安装
中间件容器退出端口冲突(ss -lntup)、目录权限、middleware logs <key>安装与参数配置
镜像拉取卡约 60s回退本地镜像的警告不是失败;无本地镜像查 Docker 连通性/代理安装与参数配置
CLI 鉴权失败(退出码 3)所选服务器与令牌;JWT 过期换 dk_ API Token登录与身份
HTTP 200 但操作失败响应体 success、运行终态、退出码输出约定与退出码
选择性运行报命令不存在项目命令 ID 已因 update 重生成:重新 project get命令与脚本
--step-id 跑错步任务增删步骤移动了位置;task get 核对步骤 ID
运行一直 queued全局闸门 maxConcurrentRuns、同目标 queue 策略、在跑长构建生命周期与并发
日志缺一段单运行超 logMaxBytes 截断;或过期清理日志与实时跟随
Hook 429每令牌 60/min 限流;调用侧降频/去重(idempotencyKey 为预留字段,未生效)HTTP Hook
middleware 端点不存在服务端版本过旧需升级升级备份
nothingToDo: true组件已安装;确需重建才加 --force安装与参数配置
Secret 解密失败/凭据失效secret.key 与数据库是否同批恢复安全加固
提交超时不知是否受理runs list 查是否已有运行,避免重复触发运行历史与取消
等待中断退出码 0 但仍在跑中断只断跟随;以终态 success 为准运行历史与取消

通用诊断命令 ​

bash
# 服务端存活与版本
curl -fsS http://127.0.0.1:10055/api/v1/healthz
journalctl -u deploy-server -n 100 --no-pager

# 环境自检(工具/目录/Shell/前端)
deploy doctor --json

# 当前连接与身份
deploy whoami --json
deploy server list

# 运行与日志
deploy runs list --project <key> --status failed
deploy logs <runId>            # 回放
deploy logs <runId> -f         # 跟随

# 资源采样(CPU/内存/磁盘,≥75% 或剩余 <2GiB 告警)
# 网页 /server-info 或 GET /api/v1/system/info

排查纪律 ​

  • 先看日志再重试:重试掩盖端口冲突、凭据失效等根因。
  • 区分 CLI 退出码与运行终态:退出码 0 只代表 CLI 成功;运行终态另看。
  • 区分受理与完成:run 响应只是受理;终态才是结论。
  • 失败子运行优先:依赖管道失败时看失败依赖的日志,不是父摘要。
  • 变更类故障先回滚脚本/配置(任务脚本应幂等带备份),再查根因。

延伸阅读 ​