Docker 部署

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：deploy/README.md、deploy/docker/、deploy/.env.example

Docker 模式把每个 ChengOS 服务都作为容器运行在 Docker Compose 之下。它是推荐的生产部署方式：版本被固定到确切的镜像标签，数据存储默认绑定在回环地址上，更新与回滚替换的是整个镜像，而不是主机上的二进制文件。

前置要求

• 带 Compose 插件的 Docker Engine（docker compose version 必须可用）
• 属于 docker 组的用户，或者对 Docker 命令有 sudo 权限
• 主机上 8080 与 5055 端口空闲，回环地址上 3000 端口空闲

安装与启动

在 deploy/ 目录下执行：

./chengos.sh install --mode docker --with api,ui,app,cli
./chengos.sh start

安装器会写入 deploy/.env，生成那些绝不能保留模板值的密钥，并拉起 Compose 项目。使用 ./chengos.sh stop 停止，./chengos.sh status 查看容器、端口占用与实时日志。

固定发布版本

四个 ChengOS 镜像的标签都来自 deploy/.env 中的同一个值：

CHENGOS_VERSION=0.1.0

因为所有镜像读取同一个值，Docker 安装永远不会混用来自不同发布版本的镜像。latest 仅仅是首次安装时的便捷默认值——它不是可复现的生产版本，也永远不是更新或回滚的目标。在这套安装承载任何重要内容之前，请固定一个确切版本。

针对私有镜像仓库和本地开发构建，可以按服务覆盖：

CHENGOS_API_IMAGE=registry.example.com/chengos/chengos:0.1.0
CHENGOS_UI_IMAGE=registry.example.com/chengos/chengos_ui:0.1.0
CHENGOS_APP_IMAGE=registry.example.com/chengos/chengos_app:0.1.0
CHENGOS_CLI_IMAGE=registry.example.com/chengos/chengos_cli:0.1.0

对该服务而言，覆盖项优先于 CHENGOS_VERSION。但要注意代价：只要设置了任何一个覆盖项，Docker 的协调式版本更新就会被禁用，chengos.sh status 会明确提示这一点。在依赖 chengos.sh update 之前，请先移除这些覆盖项。

连接串在不同模式下并不相同

这是把 .env 在不同模式之间搬运时最常见的错误。DATABASE_URL、REDIS_URL 和 QDRANT_URL 中的主机名取决于数据存储实际运行在哪里：

在 Compose 网络内部，容器之间通过服务名互相访问。API 容器内指向 127.0.0.1 的 DATABASE_URL 解析到的是容器自身，而不是数据库。

网络与暴露面

Compose 已经把 API、PostgreSQL、Valkey 和 Qdrant 的宿主机端口绑定到 127.0.0.1，因此它们无法从机器外部访问。对外只公开反向代理的 443，并在那里终止 TLS。

有一个陷阱值得单独警告：不要在 API 容器内把 BIND_ADDRESS 设为 127.0.0.1。 容器内的回环地址只代表该容器自身，这样一来 UI 容器就无法通过 Compose 网络访问 API。Docker 环境中的正确取值是 0.0.0.0；隔离来自宿主机端口绑定，而不是进程的绑定地址。

公共只读演示模式

要把一套安装作为只读演示公开，设置 CHENG_DEMO_MODE=true。这是一个 fail-closed 白名单：只有健康检查、登录/刷新/校验、工作区定位，以及工作流和节点定义查询保持可用。工作流保存与删除、REST 与 WebSocket 执行、注册、修改密码、凭证、文件、文档、渠道、MCP 和调度器全部返回 403 DEMO_MODE_RESTRICTED。

演示模式无法自举，因为创建演示用户恰好是它所阻止的操作之一。要先初始化，再切换：

# 1. 在受信任网络中以普通模式启动
#    deploy/.env：CHENG_DEMO_MODE=false
./chengos.sh start
#    通过界面创建固定的演示用户及其默认工作区
./chengos.sh stop

# 2. 将 deploy/.env 改为 CHENG_DEMO_MODE=true，然后重新启动
./chengos.sh start

演示模式开启期间，RUN_MIGRATIONS 会被忽略，后台任务也不会启动——调度器、MCP 恢复、渠道轮询与流式接收、OAuth 令牌刷新、代码索引、文件 watcher 和清理任务全部被抑制。要迁移、重置或更新演示数据时，应先把实例从公网摘除，关闭演示模式，完成维护后再重新启用。

更新与回滚

chengos.sh update 是仅升级的，并且在触碰运行中的系统之前先做校验：核对 SHA-256 校验和与签名，比对包内嵌的 VERSION 与所选发布版本是否一致，停止服务，然后替换镜像。只有更新后的健康检查通过，版本记录才会写入；失败时会自动恢复到此前的包。

chengos.sh rollback 会恢复最近一次备份的发布版本，并重新执行启动与健康校验。如果已安装的版本声明了不可逆的数据库迁移——即删除或改写了旧版本无法读取的数据——它会拒绝执行，转而打印手工恢复步骤。

下一步

• 环境变量参考——你可能需要设置的全部取值，以及哪些是必填的。
• 安装 ChengOS——原生模式，以及仅安装 CLI 的方式。