aios/aios
1
0
Fork 0
Code Issues Pull Requests 5 Actions Packages Projects Releases Wiki Activity
Files
1791c91c5b868e5becbf79ef8b2a8d6c9d874d37
aios/docs/aios-v2/03-MIGRATION-AND-DELIVERY.md
T

7.5 KiB
Raw Blame History

AIOS V2 迁移与交付策略

  • 文档版本：V2R1C0-candidate
  • 交付原则：增量迁移、能力复用、控制权收敛、GitOps 唯一变更入口

1. 迁移目标

AIOS V2 不通过一次性重写替换现有系统，而是在保留 OpenClaw、Hermes、Agent Router、GitOps 和既有运行能力的前提下，将租户、策略、任务、审批、审计和发布治理收敛到 AIOS Control Plane。

迁移完成的标志不是“新代码存在”，而是：

  • AIOS 成为唯一权威控制面；
  • OpenClaw/Hermes 不再保存第二套控制状态；
  • 所有控制功能 Web/API 化；
  • 所有模块通过租户隔离、测试和预发布门禁；
  • 本地 Git、Gitea、测试、部署和回滚证据可追踪。

2. 为什么采用增量迁移

2.1 避免能力回退

OpenClaw、Hermes 和 Agent Router 已经包含大量运行经验、边界处理和执行能力。整体重写会扩大风险面，并导致业务能力、操作流程和历史数据回退。

2.2 保持可回滚

每个迁移步骤必须：

  • 独立分支；
  • 小范围提交；
  • 独立测试；
  • 可单独回滚；
  • 不要求立即关闭旧执行路径。

2.3 先收敛控制权，再优化内部实现

迁移优先级：

唯一入口
  -> 权威租户/任务/策略
  -> Runtime Adapter
  -> 数据层生产化
  -> Web 与可观测
  -> 性能与 HA

3. 分阶段迁移路线

Phase 0：GitOps 与架构事实源

目标：建立可靠变更链和权威设计基线。

已完成候选能力：

  • Controller detached guard；
  • 避免 fetch 到已检出本地分支；
  • Gitea SSH 镜像；
  • docs/aios-v2/ 架构事实源；
  • 候选分支、部署和回滚资产。

退出条件：

  • Controller detached 且 clean；
  • 本地/Gitea OID 一致；
  • 架构与需求文档纳入版本。

Phase 1：Control Plane 权威化

目标：将 Tenant、Agent、Task、Policy、Approval 和 Audit 收敛到 AIOS。

候选实现：

  • aios_v2/control_plane.py
  • aios_v2/persistence.py
  • aios_v2/gateway.py
  • aios_v2/app.py

退出条件：

  • 任务状态机统一；
  • 幂等、revision、审计和跨租户拒绝通过测试；
  • 服务重启后权威状态恢复。

Phase 2：OpenClaw 解耦

目标：OpenClaw 从控制逻辑转为执行适配器。

步骤：

  1. 定义签名命令合同；
  2. 引入 Adapter；
  3. 将直接调用迁移到 AIOS Orchestrator；
  4. Runtime 只返回执行结果和健康状态；
  5. 关闭或网络隔离旧公共控制入口。

退出条件：

  • 未批准任务无法生成有效命令；
  • 命令绑定 tenant/task/trace/idempotency；
  • 旧控制接口冻结并记录替代路径。

Phase 3：Hermes 解耦

目标：Hermes 只承担租户分区队列和 Worker Runtime。

步骤：

  1. 定义 HermesJob/HermesResult；
  2. 强制 tenant/cell/profile 分区；
  3. 引入 claim/lease/heartbeat；
  4. 将结果统一回写 AIOS；
  5. 移除 Hermes 内部策略和任务事实源。

退出条件：

  • Worker 无权创建 AIOS Task；
  • 租约过期后 Job 可恢复；
  • 跨租户 claim/read/result 被拒绝。

Phase 4：Web 与运维统一

目标：所有用户与运维功能通过 AIOS Web/API。

范围：

  • Tenant、Agent、Task、Runtime、Audit、Execution Evidence、GitOps；
  • systemd/Docker/Compose；
  • healthcheck、rollback、release report。

退出条件：

  • 浏览器不直接调用 Runtime；
  • 生产身份代理和权限模型通过验证；
  • 部署、重启和回滚演练通过。

Phase 5：生产数据层与 HA

目标：将候选 SQLite/内存运行状态替换或强化为生产级后端。

要求：

  • 数据迁移；
  • RLS 或物理隔离；
  • 备份恢复；
  • HA 与容量；
  • 多实例并发；
  • 灾难恢复目标。

该阶段不得改变上层合同，避免 Runtime 和 Web 再次耦合存储实现。

4. 分支与提交策略

4.1 分支类型

类型 用途
task/* 可执行任务合同与主体实现
patch/* 独立修复或窄范围增强
integration/* 多模块候选收敛
result/* 自动执行结果与证据
release/* 受控发布候选

4.2 规则

  • 禁止直接修改 main；
  • 一个提交应可独立审阅和回滚；
  • 大文件和大范围变更应拆分；
  • 所有行为变化必须同步文档和测试；
  • 生产 Tag、部署和回滚需要 Owner 批准。

5. GitOps 交付流程

需求/架构更新
      |
      v
任务分支 + 文档 + 测试
      |
      v
代码提交 + Secret Gate
      |
      v
本地 bare repo 同步
      |
      v
Gitea 镜像与 OID 校验
      |
      v
Candidate 集成
      |
      v
自动测试与预发布
      |
      v
Owner 审批
      |
      v
Merge / Tag / Production Deploy

5.1 同步状态

GitOps 返回必须区分：

  • local sync；
  • Gitea sync；
  • branch OID；
  • workspace mode；
  • dirty state。

仅返回 common_git_dir synced 不足以证明 Web 远端可见。

6. 发布门禁

Gate A：设计完整性

  • 用户需求、目标架构、模块契约、ADR 和追踪矩阵同步；
  • 无冲突标记、断链或过期路径。

Gate B：代码质量

  • 包可导入；
  • 静态编译通过；
  • Secret Scanner 通过；
  • 无已知越权旁路。

Gate C：测试

  • 单元、集成、多租户负向、重启恢复、Runtime 边界测试通过；
  • 记录 commit、命令、exit code、pass/fail 和 artifact digest。

Gate D：预发布

  • systemd 或 Compose 启动成功；
  • 健康检查通过；
  • OpenClaw/Hermes 真实联调通过；
  • 备份、重启和回滚演练通过；
  • 日志中无敏感信息。

Gate E：生产批准

  • Owner 批准 merge、Tag 和生产部署；
  • 发布窗口、回滚负责人和观察指标明确；
  • 生产变更通过 GitOps 记录。

7. 回滚策略

7.1 代码回滚

  • 使用 /opt/aios/current 原子 symlink 切换；
  • 回滚前备份状态；
  • 健康检查失败自动恢复 previous release。

7.2 状态回滚

默认不自动回滚状态，避免覆盖候选运行期间新增的 Task、Audit 和 Evidence。

状态恢复只有在：

  • 明确确认 schema 不兼容；
  • 数据备份可验证；
  • Owner 显式授权；

时启用。

7.3 Runtime 回滚

OpenClaw/Hermes Adapter 采用稳定合同。若候选执行层失败，可恢复旧 Runtime 版本，但不得恢复旧控制权旁路。

8. Bug 修复流程

生产或预发布 Bug：

  1. 创建 patch/bugfix/*；
  2. 添加可复现测试；
  3. 修复代码；
  4. 更新相关需求/架构/契约/ADR；
  5. 运行候选验收；
  6. 进入新的 release candidate；
  7. Owner 批准部署。

禁止在生产目录直接编辑文件后不回写 Git。

9. 文档同步规则

以下变化必须更新文档：

  • 用户行为或页面；
  • API 路径、Header、请求/响应；
  • 数据模型、状态机、策略；
  • OpenClaw/Hermes/Router 边界；
  • 多租户与安全模型；
  • 部署、健康检查、回滚；
  • 测试或发布门禁。

对应关系：

  • 需求变化：更新 01-USER-REQUIREMENTS.md；
  • 架构变化：更新 02-TARGET-ARCHITECTURE.md 和 ADR；
  • 迁移/发布变化：更新本文件；
  • 合同变化：更新 04-MODULE-CONTRACTS.md；
  • 代码/测试路径变化：更新 05-TRACEABILITY-MATRIX.md。

10. 当前候选后续步骤

  1. 完成文档同步门禁和 Acceptance Runner；
  2. 在精确 Candidate commit 执行测试；
  3. 推送 Gitea 并校验 OID；
  4. 部署隔离预发布环境；
  5. 联调真实 OpenClaw/Hermes；
  6. 执行重启、性能、安全和回滚演练；
  7. 生成最终 evidence；
  8. 请求 Owner 的 merge/Tag/production approval。
Reference in New Issue View Git Blame Copy Permalink