环境与部署：概览与上手

项目上线后，你通常不止有一个运行环境：测试环境给自己验证，预发环境给团队联调，生产环境给用户使用。环境管理把这些环境登记在项目里，让「发布到测试环境」成为一句话或一次点击，而不是每次都要回忆脚本、参数和该发哪个版本。

环境管理解决什么问题

• 按名字发布：环境登记后，可以直接对 Agent 说「发布到测试环境」，或在 RunLogos 里点「发布…」，不需要每次说明部署方式。
• 每个环境的状态有据可查：每个环境当前跑的是哪个版本、上一个版本是什么、最近一次冒烟是否通过，都记录在本机部署账本里，在 RunLogos 面板里一眼可见。
• 有没有流水线都能用：有 CI 流水线的团队，由 OpenLogos 触发并观察流水线运行；没有流水线的个人开发者，用仓库里的部署脚本直接部署。
• 生产可以设门禁：可以要求版本先在上游环境冒烟通过才能发到下游，也可以要求每个版本发布到生产前必须由人批准。

OpenLogos 与 RunLogos 的分工

二者共享同一个项目目录：你在 RunLogos 面板里做的每一次发布，背后都是 OpenLogos 命令；你在终端或通过 Agent 执行的部署，也会出现在 RunLogos 面板里。

版本要求

• OpenLogos CLI ≥ 0.16.7：环境管理、部署执行、晋级与审批、提案默认部署环境（proposal_default_env）。升级：npm install -g @miniidealab/openlogos@latest，升级后在项目根目录运行一次 openlogos sync。
• RunLogos 1.0.4 起：环境面板与 OPENLOGOS 侧栏「环境」卡。

环境登记表是可选的：不建登记表，变更提案、verify、部署方案与 smoke 等既有流程完全不受影响。

上手：登记一个测试环境并发布

下面用一个只含测试环境、用仓库内脚本部署的最小登记表，走完一次「检查 → 部署 → 冒烟」。

第 1 步：建立登记表

在项目根目录新建 logos/environments.yaml（也可以在 RunLogos 环境面板点「新建登记表」用表单填写，或对 Agent 说「按部署方案生成环境登记表」）：

schema_version: 1
environments:
  - id: test
    name: 测试环境
    tier: test
    aliases: [测试]
    health: https://test.example.com/healthz
    secrets: [TEST_DEPLOY_TOKEN]
    deploy:
      mode: script
      script: scripts/deploy-test.sh
      args: ["{ref}"]

这只是示意：scripts/deploy-test.sh 是你自己仓库里的部署脚本，必须已提交到 git 且带可执行权限；TEST_DEPLOY_TOKEN 是部署脚本需要的环境变量名，登记表里只写名字，值在 RunLogos「密钥」标签里设置。完整字段见 OpenLogos 官网的 环境登记表规范。

第 2 步：在 RunLogos 中发布

1. 打开菜单 项目 → 环境...，进入「环境管理」；
2. 在「密钥」标签为测试环境的 TEST_DEPLOY_TOKEN 点「设置值」；
3. 回到「概览」标签，点「发布…」，选择「当前代码（HEAD）」；
4. 点「检查（dry-run）」：只做检查、不执行，展示将部署的版本、脚本与门禁结论；
5. 在确认层点「执行」，等待部署完成；
6. 点「运行冒烟」，在当前环境执行冒烟测试；
7. 回到「概览」，可以看到「当前版本」与「最近冒烟」的结果。

面板每个按钮的细节见 RunLogos 环境面板。

等价 CLI

在项目根目录（logos/logos.config.json 所在目录）运行，效果与上面的面板操作一致：

openlogos env check                                # 校验登记表
openlogos deploy --env test --ref HEAD --dry-run   # 预演：只检查、不执行、不写文件
openlogos deploy --env test --ref HEAD             # 实际部署当前提交
openlogos smoke --env test                         # 在测试环境运行冒烟

没有处于待部署阶段的活跃提案时，openlogos deploy 按版本发布，必须用 --ref 指定版本（--ref HEAD 即当前提交，对应面板上的「当前代码（HEAD）」）。从终端直接执行时，env check 与 deploy 都会检查登记表声明的密钥变量是否在当前 shell 中存在（RunLogos 启动的命令会自动注入「密钥」标签里保存的值）。命令参数见 OpenLogos 官网 env 命令 与 deploy 命令。

登记表与部署方式要点

• 环境定义进仓库，部署状态只存本机：logos/environments.yaml 随代码提交，团队共享同一份环境定义；每次部署、冒烟、审批的记录写在本机部署账本里，不进 git。
• 三种部署方式：
  • script：在请求版本的隔离工作树里执行仓库内的部署脚本，适合没有流水线的个人项目；
  • ci：触发 GitHub Actions 工作流（或用自定义触发 / 状态脚本对接其他 CI），并观察运行结果；
  • agent：由 Agent 按部署方案中的指定章节执行部署，完成后回报结果。
• 密钥只写变量名：secrets 只列环境变量名，绝不写值；值放在 RunLogos「密钥」标签，加密保存在本机，部署时注入。

全量字段、三种方式的参数与占位符、错误码与处理方式，请查阅 OpenLogos 官网 环境登记表规范 与 deploy 命令。

晋级、审批与回滚要点

• 晋级 promote_from：为下游环境（如生产）指定上游环境（如预发）。只有在上游环境用同一个版本冒烟通过并计为已验证，才能部署到下游，否则部署停在「晋级未满足」。
• 审批 require_approval：为 true 时，每个版本部署到该环境前都必须先用 openlogos approve 批准（或在 RunLogos 面板点「批准版本…」）。审批绑定具体的提交，每份审批只能用一次：成功部署一次后，再次部署同一版本需要重新批准。
• 回滚：在面板点「回滚 → 上一个版本」，即按版本通道重新部署该环境的上一个版本；它记为一次普通部署，照常经过晋级与审批检查。

AI 的边界：openlogos approve 和越过晋级（--force-promote）只能由人执行——你在终端执行，或在 RunLogos 界面点击；Agent 调用这些命令时需要你在宿主里亲自批准，无人值守时一律被拦下。已配置门禁的登记表，修改也同样需要你批准。

全自动下的硬停点：全自动（--auto）的 standing 授权不覆盖审批与晋级。目标环境要求审批而该版本还没批准，或晋级检查没通过时，驱动会停在「等待审批」或「晋级未满足」——这和「代码未绿」一样，是任何模式都不会自动越过的硬停点。你批准版本（或先在上游完成冒烟）之后，重新驱动即可继续。

参数与语义细节见 OpenLogos 官网 approve 命令 与 deploy 命令。

与变更提案流程的关系

• 提案通道：活跃提案已通过验收、处于待部署状态时，部署默认走提案通道——发布当前提交，并在成功后写入 DEPLOY_DONE，随后可以冒烟与归档。
• 版本通道：用 --ref 指定 tag、分支或提交来部署，不依附任何提案，结果只记入部署账本；适合日常把某个版本发到测试环境，或回滚。
• 提案默认部署环境：登记表顶层写 proposal_default_env: test 后，需要部署的新提案默认部署到该环境，Agent 写提案时不再逐个追问目标环境。它不决定提案是否需要部署（纯文档、纯规格类提案仍判为无需部署），不授权自动部署，也不绕过晋级与审批门禁。在 RunLogos 面板「概览」的「提案默认」行可以直接设置。

下一步

• 逐个了解面板按钮与标签：RunLogos 环境面板
• 无人值守驱动遇到「等待审批」怎么办：遇阻与恢复
• 完整 CLI 参考：openlogos.ai →