ChengOS 安装指南（原生模式）

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

ChengOS 通过单个管理脚本 chengos.sh 安装，两种部署模式都由它处理。本文介绍在单台机器上把系统跑起来的最快路径。如果你已经确定要用容器，可以直接跳到 Docker 部署。

开始之前

你需要一台 64 位 Linux 主机，至少 4 GB 内存和 10 GB 可用磁盘。其余要求取决于你选择哪种模式：

原生模式更轻量：它直接在主机上运行编译好的 cheng-api 二进制，并由同一个包提供网页静态资源，因此不需要拉取镜像，也不需要维护容器运行时。

原生模式安装

在 deploy/ 目录下执行（该脚本在仓库根目录同样可用）：

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

这就是全部安装步骤。三个参数值得理解：

• --mode native 在主机上直接运行 API 二进制与静态资源，不使用 Docker。
• --db-install-mode managed-process 把 PostgreSQL、Valkey 和 Qdrant 以普通用户进程的方式启动在安装目录内，不需要 root 或 sudo。另一个取值 --db-install-mode system-service 会通过 apt-get 安装数据库并注册为 systemd 服务，那需要 sudo。
• --with api,ui,app,cli 指定要安装的模块。不需要的可以去掉——例如 --with api,ui 就会跳过对话网关和终端客户端。

不带参数直接运行 ./chengos.sh 会进入交互式中英双语菜单，覆盖同样的操作，另外还包含更新、回滚和卸载。

安装完成后

chengos.sh start 报告成功后，会有四个服务在监听：

Valkey（6379）和 Qdrant（6333/6334）在原生模式下会安装但默认关闭——参见环境变量参考中的 ENABLE_REDIS 与 ENABLE_QDRANT。当你开始使用智能体记忆或 RAG 检索时再打开它们。

在浏览器中打开 http://<你的主机>:8080。全新数据库中还没有任何用户，因此界面会引导你进入首次初始化流程，你在那里创建的账号即为管理员。

创建 cheng 与 chengos 快捷命令

安装器可以把两个启动器软链接到 /usr/local/bin，这样在任意目录下都能使用。在交互式菜单中选择 安装系统快捷命令，之后：

• chengos 在任意终端打开管理控制台菜单。
• cheng 在任意终端启动 CLI 对话客户端。

只安装 CLI

如果只是想从笔记本或另一台机器上驱动已有的 ChengOS 服务，可以只安装终端客户端：

./chengos.sh cli

向导会询问这是本机安装还是远程安装。本机安装自动连接 http://127.0.0.1:3000；远程安装会提示输入服务器地址——例如 https://your-server.example.com——并保存为 CHENG_SERVER_URL。之后在任意终端运行 cheng 即可开始对话。

上生产前先固定版本

首次安装时 deploy/.env 中的 CHENGOS_VERSION 默认为 latest。这只是为了方便试用。latest 是一个会移动的指针，它会让安装无法复现，也会让回滚变得含糊，因为并不存在一个确定的目标版本。

在依赖这套安装之前，请编辑 deploy/.env 固定确切版本：

CHENGOS_VERSION=0.1.0

chengos.sh update 会替你改写这个值，但只在目标版本通过校验之后才写入，并且会记录旧值，以便 chengos.sh rollback 能够恢复。

验证安装

# API 响应健康检查
curl http://127.0.0.1:3000/health

# 进程、端口占用与最近日志
./chengos.sh status

健康的系统会响应 /health，并且 status 中所有已选模块都处于运行状态。如果不是这样，先查看 deploy/logs/——启动失败几乎总是数据库连接问题或端口被占用。

下一步

• 在编辑器中搭建第一个工作流。
• 配置环境变量，尤其是生产环境绝不能保留默认值的那些密钥。
• 如果你想要容器化安装，参见 Docker 部署。