升级指南

本文档指导 wesgine 引擎的版本升级，包括版本策略、数据迁移、兼容性处理、回滚方案和升级检查清单。

版本策略

语义版本

wesgine 遵循语义版本：MAJOR.MINOR.PATCH

开发阶段约束（DEV-1）

开发阶段（版本对外锁定之前），Schema 变更 = 清库重建，不做旧数据兼容。正式发布后，所有迁移必须保证幂等。

版本构建指纹

每次启动时，wesgine 会打印构建指纹：

wesgine: boot: version=1.0.0 commit=abc1234 built=2026-09-14T10:00:00Z

部署后务必检查——版本降级可能导致数据损坏（见下方"版本错配风险"）。

数据迁移

双轨迁移机制

wesgine 使用双轨迁移：主 DB 迁移 + 辅助 Migrate() 方法。

主 DB 迁移

• 跟踪：schema_migrations 表
• 文件：internal/db/migrations/*.sql
• 按文件名排序执行
• 每文件一个事务

辅助 Migrate()

执行顺序

db.Open(dsn) → 主 DB 迁移
  → cellStore.Migrate()
  → agentCatalog.Migrate()
  → revocationStore.Migrate()

Cell 三层数据库

每个 Cell 有三个 SQLite 数据库：

INV-RESIL-03：单 Layer 损坏不扩散。sessions.db 损坏不影响 state.db。

迁移幂等要求

所有迁移重跑 N 次结果一致（INV-RESIL-10）：

-- ✅ 幂等
CREATE TABLE IF NOT EXISTS cells (id TEXT PRIMARY KEY, ...);
ALTER TABLE cells ADD COLUMN new_field TEXT;  -- 吞 duplicate column 错误

-- ❌ 非幂等
CREATE TABLE cells (id TEXT PRIMARY KEY, ...);  -- 第二次报错

兼容性矩阵

CellSpec 字段兼容性

CellSpec 字段带 wesgine:"immutable|mutable|restricted" tag：

Provider 配置兼容性

v1.0.1 破坏性变更示例：

❌ 旧版（v1.0.0）
ProviderConfig.SupportsVision  // Provider 级
ProviderConfig.VisionModel     // Provider 级

✅ 新版（v1.0.1）
Models[].SupportsVision        // Model 级

hypervisor.db 兼容性

hypervisor.db 没有清库路径——渠道凭证、MCP 声明、Agent 配置在别处没有第二份副本。变化通过读侧容忍 + 写侧收敛吸收：

读到旧形状 → 照常解析
写回时 → 一律写新形状
开机收敛 → convergePersistedSpec

版本错配风险

实证案例（2026-09）

现场时序：较新版本的 ChannelInstance.channels.token 改为 SecretRef（object），现场跑的引擎仍是 string：

旧引擎读新格式 spec
  → 解码失败
  → Cell 不 attach
  → GET /admin/cells/{id} 返回 404
  → CellResolver 报 "not found"
  → CellAutoProvisioner 触发
  → POST /admin/cells → 旧引擎把在册目录当孤儿归档
  → 会话、记忆、知识库从活动目录消失

防护措施

1. 引擎只升不降
2. 确需回退时，先确认旧版能解码现有 hypervisor.db
3. 回退前后的 version= 指纹要留档
4. 看到 spec bytes are not decodable 先比对指纹，不要建同名空间

回滚方案

回滚前准备

1. 备份 DataDir

# 停止 wesgine
systemctl stop wesgine

# 备份整个数据目录
cp -a /var/lib/wesgine /var/lib/wesgine.bak-$(date +%Y%m%d)

2. 备份 Cell 数据

# 导出关键 Cell
curl -H "Authorization: Bearer <token>" \
  http://localhost:9091/admin/cells/dept-legal/export > dept-legal.tar.gz

回滚步骤

# 1. 停止当前版本
systemctl stop wesgine

# 2. 替换二进制
cp /path/to/old/wesgine /usr/local/bin/wesgine

# 3. 如果 hypervisor.db 格式不兼容，恢复备份
cp /var/lib/wesgine.bak-YYYYMMDD/hypervisor.db /var/lib/wesgine/

# 4. 启动旧版本
systemctl start wesgine

# 5. 检查启动日志中的版本指纹
journalctl -u wesgine | head -20
# 或查看引擎日志
cat /var/lib/wesgine/logs/wesgine-stderr.log | head -5

回滚后验证

# 健康检查
curl http://localhost:9091/health

# Cell 列表
curl -H "Authorization: Bearer <token>" \
  http://localhost:9091/admin/cells

# 关键 Cell 可访问
curl -H "Authorization: Bearer <token>" \
  http://localhost:9091/admin/cells/dept-legal

升级检查清单

升级前

• 阅读 Release Notes 中的破坏性变更
• 备份 DataDir（包括 hypervisor.db 和所有 cells/*/ 目录）
• 导出关键 Cell 作为额外备份
• 确认新版本的 Go 版本要求
• 确认新版本的依赖变化
• 如果是 MAJOR 版本升级，查阅迁移指南

升级中

• 停止 wesgine 进程
• 替换二进制文件
• 更新 systemd service 文件（如有变化）
• 启动新版本
• 检查启动日志中的版本指纹
• 等待 ActivatePersisted 完成（后台热身）

升级后

• 健康检查通过（/health 返回 ready）
• 所有 Cell 可访问
• 关键业务流程验证（发送一条消息并确认响应）
• 监控指标正常（无异常的降级层或错误率）
• 如果有 Schema 变更，确认迁移日志无错误

回滚决策

以下情况立即回滚：

• /health 长时间不返回 ready
• 多个 Cell 不可访问
• spec bytes are not decodable 错误
• 数据库迁移失败且无法修复

从 v0.2 升级到 v1.0

这是一次 MAJOR 版本升级，包含大量破坏性变更：

关键变化

迁移路径

1. 更新 boot 代码：NewHypervisor + Cells().GetOrCreate
2. 所有 handler 从 eng.Xxx() 迁移到 cell.Xxx()
3. 签名从 (engine, ...) 改为 (cell, ...)
4. 外设从 engine 级改为 CellSpec 声明式
5. OwnerID 改为 Actor（必填一等字段）
6. 运行 make verify 确认

最佳实践

1. 每次升级前备份——即使是 PATCH 版本
2. 在测试环境先跑——生产前确认兼容性
3. 检查版本指纹——升级后确认运行的是新版本
4. 监控降级状态——升级后关注 degraded_layers 和 degraded_secrets
5. 保留旧二进制——回滚时需要
6. 文档化每次升级——记录版本、时间、操作人、异常