安装问题排查

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：deploy/chengos.sh、deploy/.env.example、chengflow/docs/release-operations-guide.md

几乎每一次 ChengOS 安装失败都是四件事之一：端口已被占用、数据库连不上、占位密钥没改，或者某个路径在两个进程眼中含义不同。在往下细读之前，先按下面的分诊步骤过一遍。

分诊

./chengos.sh status                      # 进程、端口、版本、健康状况
curl http://127.0.0.1:3000/health        # API 活着吗？
tail -n 100 deploy/logs/cheng-api.log    # 为什么没活着？

status 加上 API 日志能定位大多数情况。请从这次启动尝试的开头读日志，而不是从末尾读——第一条错误才是原因，之后的都是后果。

API 无法启动

端口已被占用

ss -tlnp | grep -E '3000|8080|5055|5432|6379|6333'

要么停掉冲突的进程，要么在 deploy/.env 中改端口（PORT/API_PORT、UI_PORT、APP_PORT）。注意 PORT 和 API_PORT 同时存在，二者应保持一致。

数据库连接被拒绝

pg_isready -h 127.0.0.1 -p 5432

按以下顺序检查：

1. 数据库在运行吗？./chengos.sh status 会报告。
2. DATABASE_URL 用的是符合你部署模式的主机名吗？原生和 managed-process 用 127.0.0.1；Docker 用 postgres / redis / qdrant；分布式用你自己的主机。仅这一个错误就占了「原生能跑、Docker 失败」这类反馈的大多数。
3. DATABASE_URL 中的密码与 POSTGRES_PASSWORD 一致吗？它们是两个独立变量，必须一致。
4. 离散的 DB_HOST / DB_PORT / DB_NAME / DB_USER / DB_PASSWORD 与 DATABASE_URL 一致吗？智能体记忆节点读取的是前者而非 URL，因此不一致会造成一个能正常启动、但只在记忆节点运行时才失败的系统。

占位密钥

仍保留模板值的安装无法正常工作：

grep -E 'replace_with|change_this' deploy/.env

生成真实值：

openssl rand -hex 32   # CREDENTIAL_MASTER_KEY_1、JWT_SECRET
openssl rand -hex 16   # POSTGRES_PASSWORD、REDIS_PASSWORD

在已存在凭证之后再更改 CREDENTIAL_MASTER_KEY_1 会让这些凭证无法读取——请在存入任何内容之前就设定它，此后视其为不可恢复。

迁移没有执行

RUN_MIGRATIONS=true 会在启动时应用数据库迁移。如果 schema 看起来是空的，请确认它已设置，并且——这一点很重要——CHENG_DEMO_MODE 不是 true，因为演示模式会完全忽略 RUN_MIGRATIONS。因此在全新数据库上以演示模式安装，既没有 schema 也没有办法创建 schema，这正是演示模式必须在正常初始化之后才启用的原因。

界面能打开，但功能都不可用

浏览器能访问 UI，不代表 UI 能访问 API。

打开浏览器控制台和网络面板。失败的 /api/v1/* 请求指向以下原因：

• CORS。 生产环境应设 CORS_PERMISSIVE=false，并在 CORS_ALLOWED_ORIGINS 中列出真实来源。被拦截的请求表现为 CORS 错误，而不是 4xx。
• API 地址不对。 检查 UI_API_BASE_URL 和 UI_WS_URL——通常是同一个反向代理后的 /api/v1 与 /ws。
• Docker 中的 BIND_ADDRESS。 必须是 0.0.0.0。在 API 容器内设为 127.0.0.1 会让 UI 容器无法访问它——隔离来自宿主机端口绑定，而不是进程的绑定地址。
• WebSocket 未被代理。 反向代理需要显式处理协议升级；REST 正常但实时更新始终不到，正是这个问题的典型特征。

首次初始化问题

在全新数据库上，GET /api/v1/auth/bootstrap-status 返回 needsSetup: true，界面会引导你去初始化。如果没有：

• 在你认为是空库的情况下返回 needsSetup: false，说明你连的是另一个数据库。
• 注册被拒绝，说明该部署的注册策略或用户数上限生效了。
• 如果演示模式开着，初始化写入会被阻止。先关闭它，完成初始化，再重新启用。

CLI 无法连接

请记住 CLI 的优先级顺序——参数、环境变量、配置文件、默认值。一个陈旧的 ~/.config/cheng/config.json 悄悄覆盖你的意图，是常见的意外。

Docker 相关

docker compose ps
docker compose logs api --tail=100

更新与回滚失败

缺失的可选功能

有些功能是因为没配置而缺失，并非出了故障：

校验发布包

./scripts/verify-release-archive.sh --archive PATH --expect-version 1.2.0
./scripts/check-release-consistency.sh --tag v1.2.0

下一步

• 执行失败排查——安装没问题但运行有问题时。
• 环境变量参考——上文提到的所有配置项。
• 升级与回滚——更新机制。