# ADR-003: 本地 Agent 双阶段人工发布

## 状态

Accepted；取代 ADR-001 的自动 CI/CD 决策。

## 日期

2026-07-22

## 背景

AI Gateway 的交付重点是 API 制品能够启动、迁移数据库并通过核心兼容接口。原有 PR、`main` 和 Tag 三套重复质量门禁占用单并发 Runner，发布还要等待外部 dispatcher，反馈与上线时间不符合当前小团队由 Agent 主导运维的模式。

## 决策

- 删除所有 Gitea Actions，不监听 Push、PR、Tag、Webhook、轮询或定时事件。`main` 不设置保护规则或 required status，允许经用户授权的 Agent 直接提交和推送。
- Git 操作与生产授权彻底分离。commit、push、merge 和 Tag 都不会构建或部署。
- 发布分成两次独立的人工作业：本地 `publish` 负责验证、构建、simulation 冒烟、推送不可变镜像并生成带 SHA-256 内容完整性校验的 JSON manifest；用户再次确认后，`deploy` 才把该 manifest 应用到生产。
- 只允许发布工作区干净、已提交且属于 `origin/main` 历史的完整 SHA。Registry Tag 使用完整 SHA，生产 Compose 只接受 `repository@sha256:...`。
- publish 相对当前线上 manifest 选择 API/Web 变更；未变化的组件沿用现有 digest。两阶段之间如果线上基线变化，客户端和服务器都拒绝过期 manifest。
- 待发布镜像在本地临时 PostgreSQL 中执行全部迁移，并逐项记录 health、readiness、OpenAPI、鉴权、模型列表、Chat Completions、Responses、Images 和 Web 反代冒烟。生成接口使用 5ms simulation，不调用真实上游。
- 只有迁移变化时生产才创建并验证 PostgreSQL custom-format 备份。生产探活失败自动恢复上一应用 digest；数据库恢复仍需人工决定。
- 完整测试、依赖审计和漏洞扫描保留为按需人工命令，不再影响镜像发布关键路径。

## 影响

- 不再有自动质量证据或自动发布；用户和 Agent 必须严格遵守两次显式授权边界。
- 允许直接推送 `main` 提高速度，也取消了服务端代码审查强制约束。可追溯性改由干净提交、main 历史、OCI revision、Registry digest 和服务器 release manifest 保证。
- 本机是 `Darwin arm64`，发布脚本必须使用 Buildx 构建并实际运行 `linux/amd64` 镜像。
- Registry、SSH 或生产 helper 不可用时发布失败关闭，不允许退回 `latest`、重建制品或直接修改 Compose。