环境变量配置参考-ChengOS 可视化工作流编排 · MCP 原生支持

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

ChengOS 的每种部署模式——原生、Docker 与分布式——读取的都是同一个 deploy/.env 文件。本文是参数字典。具体怎么部署，参见安装 ChengOS 和 Docker 部署。

请从模板出发，而不是从空文件开始：

cp deploy/.env.example deploy/.env

chengos.sh install 和 generate-env.sh 会填入生成的密钥并推导端口与路径，因此多数情况下你只需要修改与默认值不同的部分。

必填密钥

这些在模板中是占位值。保留不改的安装是不安全的。在对外暴露系统之前，请逐个生成。

变量	生成方式	说明
`CREDENTIAL_MASTER_KEY_1`	`openssl rand -hex 32`	加密所有已存储的凭证。丢失它会导致已存凭证无法恢复；更换它会让现有凭证失效。
`JWT_SECRET`	`openssl rand -hex 32`	签发 API 访问令牌。更换它会使所有已签发的会话失效。
`POSTGRES_PASSWORD`	`openssl rand -hex 16`	必须与 `DATABASE_URL` 中的密码一致。
`REDIS_PASSWORD`	`openssl rand -hex 16`	必须与 `REDIS_URL` 中的密码一致。

数据存储连接

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

主机名取决于部署模式：原生与 managed-process 安装用 127.0.0.1，Docker 用 Compose 服务名 postgres / redis / qdrant，分布式安装用你自己的主机。

智能体记忆节点读取的是离散取值而非 URL，因此以下变量必须与 DATABASE_URL、REDIS_URL 保持一致：

变量	默认值
`DB_HOST` / `DB_PORT`	`127.0.0.1` / `5432`
`DB_NAME` / `DB_USER` / `DB_PASSWORD`	`master_router` / `tianai_db` / —
`REDIS_HOST` / `REDIS_PORT` / `REDIS_DB`	`127.0.0.1` / `6379` / `0`

两者都可以调整连接池：DATABASE_MAX_CONNECTIONS（10）、DATABASE_MIN_CONNECTIONS（1）、DATABASE_CONNECTION_TIMEOUT（30），以及对应的 REDIS_MAX_CONNECTIONS、REDIS_MIN_CONNECTIONS、REDIS_CONNECTION_TIMEOUT。

端口与服务绑定

变量	默认值	服务
`PORT` / `API_PORT`	`3000`	API 后端与 WebSocket
`UI_PORT`	`8080`	可视化编辑器与管理控制台
`APP_PORT`	`5055`	对话应用与移动端 H5
`BIND_ADDRESS`	`0.0.0.0`	API 绑定地址

在 Docker 中请保持 BIND_ADDRESS=0.0.0.0，改为在宿主机端口绑定层面限制暴露面；容器内的回环地址对 UI 容器是不可达的。

版本固定

变量	默认值	说明
`CHENGOS_VERSION`	`latest`	四个 Docker 镜像统一的版本固定值。生产环境请设置确切版本。
`CHENGOS_<SERVICE>_IMAGE`	未设置	面向私有镜像仓库的按镜像覆盖。任一覆盖项都会禁用协调式版本更新。
`CHENGOS_IMAGE`	`chengos/chengos:latest`	供旧版 Compose 覆盖文件使用的遗留别名。优先使用 `CHENGOS_VERSION`。

运行时行为

变量	默认值	说明
`RUN_MIGRATIONS`	`true`	启动时应用数据库迁移。演示模式开启时被忽略。
`CHENG_DEMO_MODE`	`false`	fail-closed 的公共演示白名单。启用之前要先初始化演示用户。
`RUST_LOG`	`info`	日志级别。
`RUST_BACKTRACE`	`1`	错误日志中包含调用栈。
`DB_INSTALL_MODE`	`managed-process`	`managed-process`（用户沙箱，无需 root）或 `system-service`（apt + systemd，需要 `sudo`）。
`ENABLE_REDIS`	`false`	使用智能体记忆时打开。
`ENABLE_QDRANT`	`false`	使用 RAG 检索时打开。

调度器

控制定时与触发式的工作流运行。

变量	默认值	说明
`SCHEDULER_ENABLED`	`true`	总开关。
`SCHEDULER_NODE_ID`	`node-1`	多实例部署中每个实例必须唯一。
`SCHEDULER_MAX_CONCURRENCY`	`8`	同时进行的定时执行数量。
`SCHEDULER_HOT_WINDOW_SECS`	`60`	临近任务的预读窗口。
`SCHEDULER_WARM_WINDOW_SECS`	`300`	即将到来任务的预读窗口。
`SCHEDULER_SWEEPER_INTERVAL_SECS`	`30`	到期任务的扫描间隔。
`SCHEDULER_LOCK_TIMEOUT_SECS`	`60`	其他实例可以接管任务前的锁租期。

CORS

CORS_PERMISSIVE=true
CORS_ALLOWED_ORIGINS=https://your-frontend.example.com

CORS_PERMISSIVE=true 允许所有来源，这是开发期的便利设置。生产环境应设为 false，并在 CORS_ALLOWED_ORIGINS 中列出真实来源。

工作区与沙箱

变量	说明
`CHENG_CLI_ALLOWED_ROOTS`	冒号分隔的绝对路径，可用作 CLI 沙箱。未配置时 CLI 会话会被完全禁用。 CLI 与 API 必须在同一文件系统命名空间中看到这些路径。
`CHENG_WORKSPACE_ROOT`	没有 CLI 沙箱时，`code_shell` / `code_python` 的基准目录。默认为 `{repo_root}/workspaces` 或 `./workspaces`。
`SKILLS_DIR`	技能库位置。默认 `./skills`。
`NODE_SKILLS_DIR`	按节点划分的技能定义。Docker 默认 `/app/node_skills`。
`CHENG_GLOBAL_CONFIG_DIR`	共享的 `shortcuts.yaml` 与 `presets.yaml`。Docker 为 `/app/config`，原生部署自动探测。按工作区的配置会覆盖这些。
`TEMPLATE_WORKFLOWS_DIR`	只读的内置工作流模板，在初始化时安装进新工作区。Docker 为 `/app/workflow-templates`，原生部署自动探测。

代码执行与模型端点

变量	默认值	说明
`CHENG_ENABLE_CODE_PYTHON`	`true`	启用 `tools/code_python` 节点。
`CHENG_ENABLE_CODE_JS`	`true`	启用 `tools/code_js` 节点。
`ALLOW_PRIVATE_LLM_ENDPOINTS`	`true`	允许使用内网地址上的模型端点，例如本地 Ollama。设为 `false` 可阻止对私有网段的请求。

可选集成

MCP——MCP_ENABLED（false）会把应用级 MCP 服务挂载在 /mcp。MCP_SERVER_TOKEN 设置静态 bearer 令牌；不设置则使用数据库托管的 MCP 令牌，这是更推荐的方式。MCP_GATEWAY_PORT_START（9100）是按工作流动态启动的服务所用的起始端口。

OAuth2——客户端 ID 与密钥来自各供应商的应用控制台：OAUTH2_OPENAI_*、OAUTH2_ANTHROPIC_*、OAUTH2_GOOGLE_*、OAUTH2_GITHUB_*、OAUTH2_MICROSOFT_*。PKCE 供应商不需要 client secret，GitHub OAuth 应用通常需要。OAUTH2_REDIRECT_URI 必须与供应商处注册的回调地址完全一致。

邮件——先设 EMAIL_ENABLED（false），再配置 SMTP_HOST、SMTP_PORT、SMTP_USERNAME、SMTP_PASSWORD、SMTP_FROM 和 PASSWORD_RESET_BASE_URL。密码重置邮件需要它们。

公开地址——供 Docker 部署告知前端从哪里访问后端：UI_API_BASE_URL（/api/v1）、UI_WS_URL（/ws）、APP_API_BASE_URL、APP_WS_URL（/ws/executions）、APP_CHANNEL_ID、APP_BOUND_WORKFLOW_ID，以及对外可见的 PUBLIC_UI_URL、PUBLIC_APP_URL、PUBLIC_API_URL。

CLI——CHENG_SERVER_URL 是 cheng 客户端连接的服务器地址。Docker 部署默认为 http://api:3000。

下一步

REST API 总览——这些接口和请求头究竟是什么。
Docker 部署——各模式下的主机名规则。

文章版权归作者所有，未经允许请勿转载。

THE END

配置与部署

环境变量配置参考