主题
故障排查
按现象索引。每行给出第一步检查与深入链接;通用诊断命令在文末。
现象索引
| 现象 | 第一步检查 | 深入 |
|---|---|---|
| 网页缺失或占位页 | 构建顺序:前端 → 拷贝 dist → Go;deploy doctor 看 web.built | 从源码构建 |
| 实时日志不刷新 | 反代 WebSocket Upgrade/Connection 头、proxy_buffering off | systemd 与反代 |
| 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 响应只是受理;终态才是结论。
- 失败子运行优先:依赖管道失败时看失败依赖的日志,不是父摘要。
- 变更类故障先回滚脚本/配置(任务脚本应幂等带备份),再查根因。