部署模式选择

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

ChengOS 支持三种部署形态。它们读取同一份 deploy/.env，也都由 chengos.sh 驱动，因此选择的是进程跑在哪里，而不是要学三套不同的系统。

如何选择

如果拿不定主意：试用用原生，正式跑用 Docker。 只有在确实需要分离数据库主机时才考虑分布式。

原生（hybrid）

编译好的 cheng-api 二进制直接跑在主机上，并由同一个包提供网页静态资源。无需拉取镜像，也无需维护容器运行时。

./chengos.sh install --mode native --db-install-mode managed-process --with api,ui,app,cli
./chengos.sh start
./chengos.sh status

其中 --db-install-mode 的选择最为关键：

managed-process 正是让你能在完全没有管理员权限的主机上安装 ChengOS 的原因。而当你希望数据库由操作系统托管、随其他服务一起开机自启时，system-service 是更好的选择。

模式相关脚本位于 deploy/hybrid/（start.sh、stop.sh、status.sh、generate-env.sh）。

Docker

每个服务都作为 Compose 容器运行，四个镜像统一由 CHENGOS_VERSION 固定版本。

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

deploy/docker/ 中的 Compose 文件：

请记住这种模式下数据存储的主机名会变——是 postgres、redis、qdrant 而不是 127.0.0.1。完整细节见 Docker 部署。

分布式

数据存储在一台主机，应用在另一台，二者都是原生运行——彻底移除 Docker，以最小化运行时开销。

• VPS A（数据库服务器）：原生 PostgreSQL 18、Redis 和 Qdrant。
• VPS B（应用服务器）：编译好的 cheng-api 二进制。

在 VPS A 上：

bash distributed/install_db.sh

脚本会提示输入 VPS B 的 IP 地址，原生安装数据库，配置 UFW，并生成安全密码。它会写出 vps_b_env.txt，其中包含 VPS B 所需的确切 .env 配置。

在 VPS B 上解开发布包，把 vps_b_env.txt 复制过去，然后启动。这个生成的文件是两台主机之间的权威交接物——不要手工誊写连接串，因为 DATABASE_URL 与离散的 DB_* 变量之间的不一致会导致看上去与配置无关的故障。

共享资源（.env.example、skills/、bin/、runtime/、logs/）保留在 deploy/ 根目录，三种模式共用。

选择模块

--with 接受 api,ui,app,cli 的任意子集：

运维一套安装

以下命令在所有模式下都适用：

./chengos.sh start      # 启动
./chengos.sh stop       # 停止（可选是否连数据库一起停）
./chengos.sh restart    # 重载配置并重启
./chengos.sh status     # 进程/容器、端口、版本、健康状况、实时日志
./chengos.sh update     # 经校验的升级
./chengos.sh rollback   # 恢复上一个版本
./chengos.sh uninstall  # 拆除，可选择保留或清除数据

不带参数运行 ./chengos.sh 会进入交互式中英双语菜单。

下一步

• Docker 部署——生产路径的细节。
• 升级与回滚——版本如何变更。
• 环境变量参考——所有配置项。