原生模式部署

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：deploy/hybrid/start.sh、deploy/hybrid/status.sh、deploy/hybrid/stop.sh、deploy/chengos.sh、deploy/.env.example

原生部署——脚本里叫「hybrid」——把编译好的 cheng-api 二进制直接跑在宿主机上，不需要容器运行时。当你要最低开销，或者在这台机器上根本没有 root 时，就选它。

部署模式对比了它与 Docker、分布式；本页讲怎么把它跑起来。

安装

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

chengos.sh 不带参数时会以交互菜单运行，支持中英文。非交互命令有 install、start、stop、restart、status、version、update 和 uninstall。

模块用 --with 选择：api、ui、app、cli，以及可选基础设施 redis 和 qdrant。安装器提供全量、最小（Postgres + API + UI）和自定义三种配置。

status 在 API 未提供服务时以非零退出，这是刻意设计的，因此它可以直接用作监控脚本里的健康探针。

数据库这道选择题

DB_INSTALL_MODE 是决定其余一切的那个选择：

managed-process 会在安装目录内用 initdb 创建 PostgreSQL 数据目录，并以你自己的用户身份用 pg_ctl 在 5432 端口启动它。全程不碰系统包管理器，也不需要提权。正因如此，ChengOS 才能装在共享主机或权限受限的虚拟机上。

system-service 安装系统包并用 systemctl enable --now postgresql（启用 Redis 时还有 valkey-server）启用它们，于是数据库随机器一起启动。start.sh 会预先检查 sudo，而不是跑到一半才失败。

从 system-service 切换到 managed-process 时，脚本会先停止并禁用系统服务，避免两者同时抢占 5432 端口。

如果宿主机上根本没有 initdb 和 postgres，脚本会带着明确提示失败而不是瞎猜——装上 Postgres 客户端工具再重跑。

按次覆盖：

./chengos.sh start --db-install-mode system-service

配置

一切都读 deploy/.env。首次运行时 start.sh 会从 .env.example 复制出 .env，然后停下来让你去编辑——它不会带着占位密钥启动。

原生模式下的要点是：

DATABASE_URL=postgres://tianai_db:…@127.0.0.1:5432/master_router
REDIS_URL=redis://:…@127.0.0.1:6379
QDRANT_URL=http://127.0.0.1:6334

DB_INSTALL_MODE=managed-process
ENABLE_REDIS=false
ENABLE_QDRANT=false

PORT=3000
API_PORT=3000
UI_PORT=8080
APP_PORT=5055
BIND_ADDRESS=0.0.0.0

CREDENTIAL_MASTER_KEY_1=<64 位十六进制>   # openssl rand -hex 32
JWT_SECRET=<64 位十六进制>

原生模式下主机是 127.0.0.1，不是 Docker 用的那些 compose 服务名。这是模式之间最常见的复制粘贴错误。见存储、Redis 与向量配置。

ENABLE_REDIS 和 ENABLE_QDRANT 默认为 false：最小安装只跑 PostgreSQL。需要定时或智能体记忆时再开 Redis，需要 RAG 时再开 Qdrant。

deploy/generate-env.sh 会生成一份带随机密钥而非占位符的 .env。

目录布局

start.sh 会创建并使用：

<安装根目录>/
  bin/cheng-api          二进制
  .env
  logs/                  cheng-api.log、ui-server.log、app-server.log
  runtime/               pid 文件、数据库数据目录
  skills/                Skill 包
  ui/  app/              提供出去的前端资源

日志路径可用 CHENG_API_LOG_FILE、CHENG_UI_LOG_FILE、CHENG_APP_LOG_FILE 覆盖。

日常运维

./chengos.sh start                 # 启动选定模块
./chengos.sh status                # 进程状态与版本；API 挂了则非零退出
./chengos.sh restart               # 按记录的模块集停止再启动
./chengos.sh stop                  # 停止服务
./chengos.sh version
./chengos.sh update                # 脚本与安装包
./chengos.sh update --scripts-only # 只更新脚本
./chengos.sh uninstall

stop 有一个选项控制数据库是否随应用一起停止——如果还有别的东西在用它们，就让它们继续跑。

status 会报告已安装版本以及是否有更新可用；更新流程见升级与回滚。

底层脚本在 deploy/hybrid/（start.sh、stop.sh、status.sh、generate-env.sh），也可以直接调用，例如 bash hybrid/start.sh --with api,ui。但优先用 chengos.sh：它记录了安装模式和模块集，因此 restart 和 update 不用你重复敲那些参数就能做对事。

从源码安装

如果安装根目录里存在 chengflow/ 和 chengflow-ui/，安装器会识别为开发者工作区并从源码编译，而不是解包发行归档。在服务器上你几乎肯定想要发行包；在开发机上这才是便利。

排查

下一步

• 部署模式——与 Docker 的对比。
• 环境变量参考——所有变量。
• 升级与回滚——保持最新。