anenreo个人数字操作系统文档

← 返回首页

升级指南

# anenreo v2.0 Foundation 升级指南

适用于从最新 v1.3 回归基线上升级到 v2.0 Foundation 候选版。

## 升级前必须完成

1. 停止 API、Web、移动 H5 和后台任务。
2. 备份 PostgreSQL，并单独备份对象存储清单。
3. 复制现有 `.env` 到仓库外的安全位置。
4. 确认备份可读，记录当前应用提交和数据库迁移版本。
5. 不要把真实 API Key 写入迁移、种子或 Git。

## 新增根密钥

生产环境必须配置 `SETTINGS_ENCRYPTION_KEY`，用于加密 AI 连接密钥。根密钥必须由安全随机源生成，并与数据库备份分离保存。

```dotenv
# 示例仅说明键名，不可直接用于生产
SETTINGS_ENCRYPTION_KEY=replace-with-a-strong-random-secret
```

根密钥丢失会导致 AI Provider 秘密无法解密；根密钥泄露则会危及所有已保存连接。

## 迁移顺序

| 序号 | 迁移 | 作用 |
|---|---|---|
| 0000 | `0000_full_system.sql` | 既有 24 模块和平台基线。 |
| 0001 | `0001_ai_user_settings.sql` | 旧版用户级 AI 配置。 |
| 0002 | `0002_ai_orchestration_forms_capture.sql` | 多 AI 连接、模型、路由、隐私、Prompt、Schema、表单、统一输入和提案。 |
| 0003 | `0003_canonical_record_relations.sql` | 正式记录跨模块关系与提案应用关联。 |
| 0004 | `0004_v2_foundation.sql` | 系统/用户字典、关系定义、自建实体记录与修订，以及实体、字段和视图元数据扩展。 |

## 推荐升级命令

```bash
corepack enable
corepack prepare pnpm@11.13.0 --activate
pnpm install

# 先做依赖无关审计
pnpm check:offline

# 使用显式隔离端口启动；入口会完成构建、迁移和可选演示数据
pwsh -File scripts/runtime/start-local.ps1 -GenerateDemoPassword -SeedDemo `
  -PostgresPort 45432 -ApiPort 45400 -WebPort 45300 -MobilePort 45173 -DocsPort 45174 `
  -MinioApiPort 45900 -MinioConsolePort 45901

# 完整构建和测试
pnpm build
pnpm typecheck
pnpm test
pnpm test:integration
pnpm test:e2e
pnpm backup:restore-test

# 只停止上述入口创建并由 runtime state 核对归属的资源
pwsh -File scripts/runtime/stop-local.ps1 -RemoveVolumes
```

## 首次配置

1. 登录 PC Web。
2. 进入“AI 与自动化 → AI 连接”。
3. 建立云端、本机、局域网或隧道连接。
4. 测试连接并发现模型。
5. 选择路由预设；推荐“混合平衡”。
6. 确认 `PRIVATE` 云回退开关仍为关闭。
7. 配置脱敏档案，但不要用脱敏放宽 `SECRET` 或 `LEGACY_ONLY`。
8. 进入“数据模型与表单”，检查 24 模块系统配置；再创建一个用户实体、字段、字典、表单和视图进行验证。
9. 执行 `pnpm db:seed:demo` 创建“林知远”虚拟数据；随后创建一条非敏感统一输入，验证提案、审核、应用和撤销。

## 回滚原则

- 不要删除 0002/0003 迁移文件。
- 代码回滚不等于数据库回滚；优先恢复升级前快照。
- 已经使用新 Schema 创建的数据，回滚前必须导出并评估兼容性。
- AI 密钥的密文需要匹配原根密钥，不能通过重新生成密钥恢复。
- 表单发布可以在 PC 中回滚到旧版本，但核心数据库迁移只能通过恢复备份回退。

## 验收清单

- Provider 增删改查、密钥轮换、模型发现和健康探测。
- `PRIVATE` 默认不进入云端审计。
- `SECRET`/`LEGACY_ONLY` 在所有路由下都拒绝云端。
- 统一输入原文不变，提案可审核、应用和撤销。
- 24 模块和用户自建实体的 Web 与移动表单读取已发布配置。
- 字典项修改后，绑定字段运行时不改代码即可使用新选项。
- 精确、日期、月份、年份、区间、模糊和未知时间使用不同语义并正确保存。
- 图片、音频、视频、文档、链接等附件字段使用类型化组件。
- 移动端无 Provider、API Key、Prompt 和 Schema 写接口。
- 备份恢复后 AI 配置、表单版本、提案和正式修订均完整。