cheng 命令参考手册

适用范围: ChengOS v0.1.0+ ｜ 最后验证: 2026-08-14 ｜ 来源: deploy/chengos.sh, deploy/lib/release-update.sh

chengos.sh 是 ChengOS 的统一入口脚本，负责安装、运维、更新与卸载。 不带参数运行时进入交互式菜单，带命令动词时以非交互 CLI 方式执行。 本文是全部命令、参数与模式的完整参考。

引导模式

当脚本在一台尚未安装 ChengOS 的机器上运行时（没有 start.sh、hybrid/、deploy/）， 它会作为引导安装器工作：

curl -fsSL https://raw.githubusercontent.com/chengrouter/chengos/main/deploy/chengos.sh | bash

引导流程：

1. 询问安装目录（默认 ./chengos）。
2. 在当前目录查找本地发布包。
3. 如果没有找到，从 GitHub 下载最新发布包。
4. 解压后重新以本地模式启动 chengos.sh。

你也可以在运行前将发布包放在脚本同级目录——引导器会自动检测 chengos-full-linux-amd64*.tar.gz 并使用它，跳过下载。

交互式菜单

不带参数运行 chengos.sh 时启动双语（中文 / English）交互菜单：

./chengos.sh

选项	功能
1	安装 / 初始化模块
2	启动服务
3	停止服务（可选是否同时停止数据库）
4	重启服务
5	更新模块（脚本、包或两者；强制更新；低磁盘模式）
6	单独安装 CLI（本机或远程）
7	服务状态（进程、端口、CLI 状态）
8	安装系统快捷命令（chengos 和 cheng 软链接）
9	卸载 / 停用模块
10	切换语言
11	退出
12	重置登录凭据
13	回滚到上一个版本

语言偏好保存在 .chengos_lang 中，跨会话记忆。

命令

所有命令均可通过传入命令动词以非交互方式执行。

install

./chengos.sh install --mode native --with api,ui,app,cli --db-install-mode managed-process \
    --ui-port 8080 --app-port 5055

参数	默认值	说明
--mode	自动检测	native 或 docker
--with	api,ui,app,pg,redis,qdrant	逗号分隔的模块列表
--db-install-mode	managed-process	managed-process（无需 root）或 system-service（需 sudo）
--ui-port	8080	UI 服务端口
--app-port	5055	Chat App 端口
--workspace-root	./workspaces	工作区存储路径

模块：api、ui、app、cli、redis（Valkey）、qdrant、pg（PostgreSQL）。

当 chengflow/ 和 chengflow-ui/ 源码目录存在时，安装器从源码编译而非解压发布包。

start

./chengos.sh start --mode native

启动所有已记录的模块。模块集从 .chengos_modules（安装时写入）读取，无需重复 --with。

stop

./chengos.sh stop --mode native
./chengos.sh stop --mode native --with-infra

--with-infra 同时停止数据库服务（PostgreSQL、Valkey、Qdrant）。

restart

./chengos.sh restart --mode native

先停止再以已记录的模块集启动。

status

./chengos.sh status --mode native

输出已安装版本、最新可用版本、进程 PID 和端口状态。 API 不可用时退出码非零——可用作监控脚本的健康探针。

version

./chengos.sh version

输出纯版本字符串（或 unknown），专为脚本调用设计。

update

./chengos.sh update                          # 脚本 + 包（推荐）
./chengos.sh update --scripts-only           # 仅脚本
./chengos.sh update --package-only           # 仅包（二进制、前端、配置）
./chengos.sh update --force                  # 强制更新包，跳过版本检查
./chengos.sh update --low                    # 低磁盘模式（见下文）
./chengos.sh update --to v0.2.0              # 指定目标版本
./chengos.sh update --package-only --force   # 强制重装包
./chengos.sh update --package-only --low     # 低磁盘仅包更新

参数	说明
--scripts-only	仅更新 chengos.sh、start.sh、stop.sh、status.sh、generate-env.sh
--package-only	仅更新发布包（二进制、前端、配置、技能、模板）
--force	跳过版本检查；强制重装或降级
--low	低磁盘模式：逐步操作以降低峰值磁盘占用（见下文）
--to <version>	指定目标版本而非最新版

默认仅升级：要求 远端版本 > 本地版本。使用 --force 可覆盖。

完整更新流程见升级与回滚。

rollback

./chengos.sh rollback --mode native

恢复 .chengos_backups/ 中最近的备份，重启服务并执行健康检查。 被消耗的备份会被删除，因此第二次回滚会回到更早一个版本。

install-cli

./chengos.sh install-cli --target local --server-url http://127.0.0.1:3000
./chengos.sh install-cli --target remote --server-url https://your-server.example.com

安装 cheng CLI 二进制并写入指向指定 API 服务器的配置文件。

reset-credentials

./chengos.sh reset-credentials
./chengos.sh reset-admin

重置登录用户名、邮箱和/或密码。两个别名等效。

uninstall

./chengos.sh uninstall --mode native

停止所有服务并删除包文件。数据库数据默认保留，除非在提示时选择同时清理数据库。

低磁盘模式（--low）

当安装文件系统可用空间很少（例如 1 GB）时，正常更新流程可能因空间检查失败而中止—— 因为它需要同时容纳下载包、解压目录、备份和暂存副本。

--low 将更新重构为顺序流水线，最小化峰值磁盘占用：

步骤	正常模式	低磁盘模式
空间检查	4× 压缩包大小（~260 MB）	2× 压缩包大小（~130 MB）
解压后	保留压缩包	立即删除压缩包（释放 ~65 MB）
备份前	保留旧备份（最多 3 个）	清理旧备份只留 1 个（释放 ~400 MB）
文件替换	cp→暂存, mv→退役, mv→暂存→目标	mv→退役, cp→目标直接复制（无暂存副本）
安装后	暂存目录保留至函数返回	健康检查前清理暂存目录
备份保留	保留 3 个	保留 1 个

回滚安全仍保留：始终保留 1 个备份，健康检查失败仍自动回滚。

./chengos.sh update --low                    # 脚本 + 包，低磁盘
./chengos.sh update --package-only --low     # 仅包，低磁盘

环境变量

以下变量控制更新与脚本行为。可在 Shell 或 .env 中设置。

变量	默认值	说明
CHENGOS_BACKUP_KEEP	3	更新后保留的备份数量
CHENGOS_META_TIMEOUT	10	发布元数据查询超时（秒）
CHENGOS_DOWNLOAD_TIMEOUT	1800	下载超时（秒）
CHENGOS_HEALTH_TIMEOUT	90	更新后健康检查超时（秒）
CHENGOS_REQUIRE_SIGNATURE	auto	auto、required 或 off
CHENGOS_LOCAL_TARBALL	—	本地发布包路径（覆盖下载）
CHENGOS_UPDATE_BRANCH	main	脚本更新使用的 GitHub 分支
CHENGOS_RAW_BASE_URL	由分支推导	脚本下载的基础 URL

文件与元数据

文件	用途
.chengos_lang	语言偏好（zh 或 en）
.chengos_install_mode	安装模式（native 或 docker）
.chengos_version	已安装的发布版本
.chengos_modules	已安装模块的逗号分隔列表
.chengos_cli_target	CLI 安装目标路径
.chengos_docker_version	Docker 镜像版本固定
.chengos_backups/	版本化备份目录

系统快捷命令

菜单选项 8（或手动设置）在 /usr/local/bin 创建两个软链接：

• chengos → 从任意终端启动管理菜单。
• cheng → 启动 CLI 对话客户端（使用文件凭据存储）。

下一步

• 原生部署 — 原生模式的日常运维。
• 升级与回滚 — 更新流程详解。
• 部署模式 — 原生 vs Docker vs 分布式。
• 环境变量参考 — 全部 .env 变量。