Repository navigation
Troubleshooting.zh cn
C-F0x edited this page Oct 26, 2026
·
1 revision
本指南汇总了 CompileGateway 运行与使用过程中的常见故障症状、根本原因以及对应的修复方案。
-
症状:
cgw clients test或执行任务时报错提示主机公钥指纹与已保存记录不一致。 - 原因:初次信任(TOFU)机制记录了首次连接的主机公钥。目标机重装系统、重建虚拟机或更换 SSH 密钥导致指纹发生变化。
-
处置方案:
- 核对报错信息或 WebUI 弹窗中展示的对端实际出示指纹(
presentedKey)。 - 显式信任新指纹:
cgw clients hostkey <clientId> --trust <SHA256:...>
- 或清除历史记录(下次连接重新走初次信任):
cgw clients hostkey <clientId> --forget
- 核对报错信息或 WebUI 弹窗中展示的对端实际出示指纹(
- 症状:Daemon 提示不支持使用 AES-CBC 加密的传统 PEM 私钥。
-
原因:传统 OpenSSL PEM 加密(
EVP_BytesToKey配合 AES-CBC)属于陈旧格式,系统明确拒绝以保证密码学安全性。 -
处置方案:使用 OpenSSL 一键转换为标准 PKCS#8 格式:
openssl pkcs8 -topk8 -v2 aes-256-cbc -in old.key -out new.key
-
症状:新登记的项目首次执行
build任务时,在第一步立即报错文件不存在。 -
原因:
build任务只负责执行远程构建,架构上绝不会自动隐式推送源码。 -
处置方案:
- 构建前先手动执行一次推送:
cgw push <project> --wait
- 或直接使用内置的
push-build-pull跨项目工作流模板:cgw workflows apply <project> push-build-pull --apply --run --wait
- 构建前先手动执行一次推送:
- 症状:Shell 脚本或 Gradle Wrapper 在远端 Unix 主机上执行报换行符错误。
-
原因:Windows 检出代码带有 CRLF(
\r\n)换行符。 -
处置方案:CompileGateway 在执行
push时会自动识别带 Shebang(#!)的脚本并转换为 LF。若此前指定了--keep-crlf,去掉该参数重新推送即可:cgw push <project> --wait
-
症状:构建步骤退出码为 0,但 Job 状态最终标记为
failed,错误码为artifactMissing。 -
原因:构建执行成功,但 Manifest 或任务声明的预期产物路径(
artifactPath或outputs)在远端磁盘上并不存在。 -
处置方案:
- 使用
cgw tree <project> build --side remote查看远端实际生成的产物路径与文件名。 - 修改任务参数或 Manifest 中的
artifactPath使其与真实路径匹配。
- 使用
-
症状:执行任务或 Batch 时报错
409 projectBusy。 - 原因:该项目已有正在执行或排队中的 Job 占用了项目锁。
-
处置方案:
- 等待前序 Job 完成,或使用诊断命令查看当前任务状态:
cgw doctor cgw jobs - 使用排队模式提交任务:
cgw run <project> <task> --enqueue cgw batch run <project> <batch> --enqueue
- 若前序任务异常挂起,可显式取消:
cgw jobs cancel <jobId>
- 等待前序 Job 完成,或使用诊断命令查看当前任务状态:
-
症状:执行任务报错
409 hostBusy。 -
原因:配置中开启了全局
hostLock,且当前同一台物理客户机上已有其他项目的构建正在运行。 -
处置方案:使用
--enqueue排队等待主机释放,或关闭全局主机互斥锁:cgw set host-lock off
- 症状:Daemon 启动失败并报错套接字绑定失败。
-
原因:
config.json中配置的固定端口已被其他系统进程占用。 -
处置方案:修改
config.json将"port": 0改为由系统动态分配,或更换为其他空闲端口。
- 症状:日志提示默认 MCP 端口 3994 被占用。
-
机制说明:Daemon 会自动退让并由系统分配空闲端口,实际端口写入
runtime.json。可随时通过以下命令查看当前实际 MCP 地址:cgw mcp url
-
症状:浏览目录或登记项目时报错 403
outsideRoot。 -
原因:访问的宿主机目录超出了用户主目录范围且不在
allowedRoots白名单中。 -
处置方案:将目标目录添加至受控白名单:
cgw set roots add "D:/MyProjects"
- 症状:连续尝试登录报错 HTTP 429。
-
原因:触发了基于来源 IP 的防爆破登录限流(
loginIntervalSeconds)。 -
处置方案:等待错误响应中返回的
retryAfterSeconds秒数后再行尝试。
- 安全规则:CompileGateway 的访问密码只能在本机免密环境(127.0.0.1)下修改。
-
处置方案:直接在运行 Daemon 的宿主机上使用 CLI 或 WebUI 重置密码:
cgw set user alice
← 首页