排障索引
本页是 Open ACE 部署排障的跨组件入口：按症状索引到对应指南。如果已能定位故障组件，请直接查看该指南自带的排障章节 —— 下表条目均已经过核对，指向真实存在的排障内容。
症状索引
| 症状 | 可能组件 | 去哪篇 |
|---|---|---|
| WebUI iframe 空白；HTTPS 页面浏览器控制台报混合内容 | 反向代理 / HTTPS 下的 webui | NGINX.md —— 问题 A 与排障节 "Blank iframe" |
远程 Agent 一直离线；Agent 日志在 /api/remote/agent/message 上反复出现 HTTP 413 | nginx client_max_body_size（默认 1 MB） | NGINX.md —— 问题 E |
| 远程终端空闲恰好 5 分钟后断开（"Connection closed. Reconnecting..."） | nginx proxy_read_timeout | NGINX.md —— 问题 F |
| 经代理访问时远程会话 API 返回 "Not Found" | 全局 sub_filter 改写了 API 路径 | NGINX.md —— 排障节 "Remote session returns Not Found" |
| 远程机器无法注册：安装脚本 404；Agent 连不上服务器；Agent 陷入 WebSocket 405 重连循环 | 远程工作区服务端 / 注册令牌 | REMOTE_WORKSPACE.md —— 排障节 |
| Agent 无法连接；CLI 工具找不到；浏览器终端连不上；会话同步不工作 | 机器上的远程 Agent | REMOTE_AGENT.md —— 排障节 |
alembic upgrade 失败；/readyz 返回 503 且 schema_version 不兼容 / 落后 | 数据库 schema 迁移 | SCHEMA_MIGRATION_GUIDE.md —— Troubleshooting 节；原地升级失败与回滚见 UPGRADING.md —— Migration Failure Handling 节 |
| 沙箱 pod 异常、工作区创建被 fail-closed 原因码拒绝 | 沙箱后端（legacy / OpenSandbox） | SANDBOX_BACKENDS.md —— 第 10 节 故障排查 |
| 服务或容器启动失败：端口被占用、数据库锁死 / 连接失败、权限问题、code-server 安装验证 | 部署 / 运行环境 | DEPLOYMENT.md —— 故障排查节 |
| 多用户 WebUI 无法启动或某用户的工作区实例异常（启动错误、运行时问题） | 多用户工作区 | MULTI_USER_WORKSPACE.md —— 故障排查节 |
| 备份 CronJob 失败、恢复 Job 报错、备份完整性校验失败 | 数据库备份工具链 | DATABASE_BACKUP.md —— 恢复流程与常见故障 |
SSO 登录失败；浏览器 URL 带 ?sso_error=<code>（签名失败、时钟偏移、redirect_uri_not_allowed 等） | SSO Provider 配置 | SSO_CONFIG.md —— Testing and Troubleshooting 节 |
| 导入会话中飞书 / 钉钉的用户名或群名没有解析出来 | 飞书 / 钉钉集成 | FEISHU_CONFIG.md / DINGTALK_CONFIG.md —— 排障节 |
| Pod 卡在未就绪；存活 / 就绪探针失败 | 健康探针与依赖 | OPERATIONS.md —— 健康与监控端点 |
| 集群层面的部署、扩缩容或 Ingress 问题 | Kubernetes 清单 | KUBERNETES.md |
收集诊断信息
深入具体指南之前，先收集以下基线信息：
- 就绪与存活（Web 服务，19888 端口）：
curl -s http://localhost:19888/readyz | python3 -m json.tool
curl -s http://localhost:19888/livez
/readyz 会逐项报告检查结果（database、schema_version、config_dir、workspace_dir、encryption_keys、init_status、security_mode、ssh_sync、frontend_build），503 时附 action 提示 —— 例如 schema 落后时提示 alembic upgrade head。
- 安全基线：
curl -s http://localhost:19888/security-status | python3 -m json.tool
-
调度器 worker（9090 端口）：
curl http://localhost:9090/health返回is_leader；/metrics暴露 Prometheus 指标。 -
日志：
- Docker Compose：
docker compose ps，然后docker compose logs -f open-ace与docker compose logs -f scheduler。应用还会写容器内/app/logs，Compose 中绑定挂载到宿主机./logs。 - Kubernetes：
kubectl -n open-ace get pods、kubectl -n open-ace describe pod <pod>（探针失败事件）、kubectl -n open-ace logs <pod>。
- Docker Compose：
-
SSH 同步告警文件：安全 SSH 同步失败时会写
/var/log/openace/ssh-sync-failure.warning（人类可读，含修复提示）与/var/log/openace/ssh-sync-failure.json（结构化）。.warning文件存在期间，/readyz的ssh_sync检查失败。详情见/var/log/openace/ssh-sync.log。修复原因后才可删除告警文件。