# WP13 / P2-WP11 Compose 产品交付、备份与恢复

本目录提供首期示范环境的可执行交付链。它以
`deploy/docker/docker-compose.yml` 为唯一 Compose 定义，不建立第二套人工维护的
服务清单。

## 1. 联网构建机生成离线包

先同步发布副本并构建默认服务镜像：

```bash
bash deployment/sync_release.sh
docker compose -f deploy/docker/docker-compose.yml build backend runner frontend
bash deployment/compose/package_offline.sh --version <发布版本>
```

产物位于 `dist/dataops-platform-offline-<发布版本>.tar.gz`，包含默认 profile
所需镜像、Compose 配置、数据库迁移、三环境配置、OpenAPI、CycloneDX SBOM、
可追溯版本清单和全文件 SHA-256。固定 `--source-date-epoch` 时，相同输入生成相同归档。
可选的 MCP、LightRAG shadow profile 不属于示范版默认启动范围，应另行生成并验收
扩展镜像包。

## 2. 离线主机安装或升级

```bash
tar -xzf dataops-platform-offline-<发布版本>.tar.gz
cd dataops-platform-offline-<发布版本>
cp deploy/docker/.env.example deploy/docker/.env.local
# 通过企业批准的密钥渠道填写 .env.local，不在终端或工单中粘贴密钥。
bash operations/install_offline.sh \
  --bundle-root "$PWD" \
  --environment-profile environments/test.json
```

安装顺序固定为：校验全部文件、载入镜像、解析 Compose、检查镜像、启动
`--no-build`、等待健康、核对 Alembic current/head。升级不调用数据库 downgrade。

## 3. 一致性备份

备份会先导出 PostgreSQL 逻辑备份，再在明确的维护窗口内停止 Compose 项目，
对所有带该项目标签的卷做一致性快照，最后自动重启原项目：

```bash
bash deployment/compose/backup.sh \
  --compose-file deploy/docker/docker-compose.yml \
  --project-name dataops-test \
  --output-dir /safe/dataops-backups/<备份编号> \
  --confirm-maintenance-window
```

输出包括 `postgres-all.sql`、`alembic-current.txt`、所有卷归档、
`backup-manifest.txt` 和 `checksums.sha256`。备份目录不得放入 Git。生产环境还需
复制到独立故障域、加密并按企业保留策略管理。

## 4. 恢复演练

默认禁止原项目原位恢复。演练必须使用新的项目名、独立端口和精确确认：

```bash
cp deployment/compose/.env.rehearsal.example /tmp/wp13-rehearsal.env
bash deployment/compose/restore.sh \
  --backup-dir /safe/dataops-backups/<备份编号> \
  --compose-file deploy/docker/docker-compose.yml \
  --env-file /tmp/wp13-rehearsal.env \
  --project-name dataops-wp13-restore \
  --confirm-project dataops-wp13-restore \
  --start
```

恢复先验签，再确认目标不存在，随后创建目标项目专属卷并解包。任何确认不一致、
校验失败、目标已存在或与源项目同名的情况都会在写入前失败关闭。

## 5. 版本回滚

回滚需要同时指定“上一版离线包”和“升级前备份”，并恢复到新的候选项目。验证完成
后由变更负责人执行流量切换：

```bash
bash <上一版目录>/operations/rollback.sh \
  --release-root <上一版目录> \
  --backup-dir <升级前备份> \
  --env-file /tmp/wp13-rehearsal.env \
  --project-name dataops-rollback-candidate \
  --confirm-project dataops-rollback-candidate \
  --start
```

本流程不会执行 Alembic downgrade。正式生产切换、旧项目下线和备份删除均需要企业
变更审批，不由脚本自动执行。

## 6. P2-WP11 产品工程控制

`product_engineering.py` 提供环境差异、Compose 六类就绪采集、治理对象晋级包验证、
客户迁移 dry-run、版本清单和 SBOM 生成。详细输入契约和操作步骤见
`docs/runbooks/P2_WP11_PRODUCT_DELIVERY_RUNBOOK.md`。晋级和迁移命令只生成/验证证据，
不自动修改目标环境或客户源系统。