数据库迁移

数据库迁移属于后端应用部署，不属于 Bundle 安装。db-service 提供数据库 Instance、Logical Database、 Profile、Allocation 和连接配置解析；Hosted Service 项目版本发布首次从主线固定运行程序与迁移声明， 部署时在目标 Project Environment 上编排、执行和审计迁移。

以下组件不参与这条应用发布链路：Bundle、Module、App Runtime、baijimu-agent、Control Plane 和 release-control。

版本使用严格 SemVer，并与 Cargo.toml 的 package.version 完全一致。首次请求固定源码；失败、取消或请求中断后的重试沿用原版本来源，主线变化不会换源。修改源码必须发布新版本。SHA 只用于内部来源追溯，不再作为构建输入。

同源版本不变量

一次 hosted_service_release 可以包含：

• 一个运行程序及 hosted-service.toml；
• 零或一个 Schema Migration；
• 零或多个按清单身份排序的 Data Migration。

运行程序和迁移必须来自同一个 Project、同一个主线 commit 和同一个 Cargo package.version。平台不接受 “运行代码来自一个 commit、迁移来自另一个 commit”的组合，也不在部署阶段重新构建或接收额外 Artifact ID。

Schema Migration

Schema 迁移目录根部必须包含 changelog.yaml 和 migration.json。一个项目只能有一个满足该结构的目录。 migration.json 使用固定协议：

{
  "protocolVersion": "1.0.0",
  "migrationKey": "business-schema",
  "migrationVersion": "2.1.0",
  "ownerComponentKey": "business-service"
}

migrationVersion 必须是规范的 SemVer 2.0.0；changelog.yaml 路径和迁移身份会进入不可变项目版本清单。

Data Migration

Data Migration 放在 data-migrations/ 下。每个迁移目录只能有一个 manifest.json，当前支持 migration-agent 1.0.0 和 2.0.0 协议。清单使用与 Schema Migration 相同的四个身份字段，并声明 数据库方言、事务、前置检查和有界更新步骤。精确结构以当前协议 Schema 和发布校验错误为准。

发布器按 migrationKey、migrationVersion 和清单路径生成确定顺序，避免调用方通过命令参数改变执行顺序。

发布并随版本部署

迁移和运行程序使用同一条项目版本发布命令：

baijimu hosted-service project release <projectId> \
  --workspace-id <workspaceId> \
  --version <projectVersion> \
  --json

baijimu hosted-service project release-status <releaseOperationId> \
  --workspace-id <workspaceId> \
  --json

Release Operation 成功后按版本部署，不再传 schemaMigrationArtifactId 或 dataMigrationArtifactId：

baijimu hosted-service project deploy-version <projectId> \
  --workspace-id <workspaceId> \
  --environment-id <environmentId> \
  --version <projectVersion> \
  --json

平台在数据库 Allocation 维度串行执行 Schema → Data，全部成功后才部署运行程序并切换 Endpoint。 Data Migration 先 dry-run、冻结候选数，再在单个事务中 apply；同一不可变版本重试幂等，不同内容复用同一 迁移版本会失败。

凭据只在当前执行内存和受控子进程中存在，不会写入迁移 Operation、Attempt 或日志。不要把数据库 URL、 密码或 Profile Token 放入源码、Artifact、普通环境 JSON 或部署参数。

状态、失败与恢复

Deployment 记录中的 databaseMigrations 保存按顺序创建的 Migration Operation；每次执行形成只追加的 Attempt。部署请求被接受不代表迁移或服务已成功，必须持续查询 deployment，直到迁移和运行部署都进入 终态，并完成真实业务验证。

迁移失败时，新的运行程序和 Endpoint 不会切换，旧部署继续服务；但此前已成功提交的数据库变更不会自动 回滚。应用和迁移必须采用 expand/contract 兼容策略，并把失败恢复设计为新的向前迁移：

1. 先增加兼容结构或数据，使新旧程序都可运行。
2. 部署并验证新程序。
3. 确认旧程序和旧数据路径不再使用后，在后续版本中收缩。

不要把破坏性逆向 SQL、手工修改生产库或在应用启动时补跑迁移当作标准回滚机制。