# 部署

生产部署由 `.gitea/workflows/deploy.yaml` 驱动，推到 `main`/`master` 即自动发布。

## 前提

- **Gitea Runner 已配置 KUBECONFIG**（指向 `gitdata` 集群），workflow 不再注入集群凭据。
- Runner 能访问 `harbor.gitdata.me`（拉取镜像 tag 列表 + 后续 `helm upgrade` 触发的镜像拉取）。
- 仓库已配置以下 **Repository Secrets**（Settings → Actions → Secrets）：

| Secret | 用途 |
| --- | --- |
| `PROD_SECRET_VALUES` | 生产 values 的 `secret:` 块（见下） |
| `DOCKER_USERNAME` / `DOCKER_PASSWORD` | Harbor 登录，用于校验镜像已推送 |
| `DOCKER_REGISTER` | 可选，默认 `harbor.gitdata.me` |

## 配置拆分：为什么有两个文件

Helm values 分成两层，避免把凭据写进 git：

| 文件 | 内容 | 入库 |
| --- | --- | --- |
| `deploy/values/prod.yaml` | 域名、副本数、资源配置、AI 模型等**非敏感**项 | ✅ |
| Gitea Secret `PROD_SECRET_VALUES` | 数据库 URL、SMTP 口令、各签名/加密密钥、Redis 口令、AI API key | ❌ |

`PROD_SECRET_VALUES` 的完整内容（**19 项**，直接复制粘贴到 Gitea 即可）：

```yaml
secret:
  create: true
  env:
    APP_DATABASE__URL: "..."
    APP_REDIS__URL: "..."
    APP_CACHE__REDIS__URL: "..."
    APP_S3__ACCESS_KEY_ID: "..."
    APP_S3__SECRET_ACCESS_KEY: "..."
    APP_SEARCH__API_KEY: "..."
    APP_LIVEKIT__API_KEY: "..."
    APP_LIVEKIT__API_SECRET: "..."
    APP_SESSION__KEY: "..."
    APP_SESSION__DATABASE_KEY: "..."
    APP_POW__MAC_KEY: "..."
    APP_AUTH__TOTP_ENCRYPTION_KEY: "..."
    APP_AUTH__CHAT_JWT_SEC: "..."
    APP_CI__SECRET_ENCRYPTION_KEY: "..."
    APP_IMPORT__TOKEN_SECRET: "..."
    APP_AI__API_KEY: "..."
    APP_EMAIL__SMTP_PASSWORD: "..."
    APP_ADMIN__SEED_USERNAME: "..."
    APP_ADMIN__SEED_PASSWORD: "..."
```

实际值在集群运维手上（本机备份：`C:\Users\ZhenYi\k8s-backups\<date>\gitea-secret-values.yaml`）。
**轮换任何密钥时，只需改 Gitea Secret，不用改仓库。**

## Workflow 做什么

1. **Resolve image tag** — 默认取本次提交的 `sha-<short>`，可手动指定
2. **Verify image exists** — 轮询 Harbor tags API（最长 ~10min）。
   `docker-build-push` 与本 workflow 并行触发，不加这步会 `ImagePullBackOff`
3. **Assemble values** — `prod.yaml` + `PROD_SECRET_VALUES` 拼成一份，日志里脱敏
4. **Render** — `helm template` 先渲染，语法/模板错误在这里就暴露
5. **Diff** — 与线上 manifest 逐行对比，评审者可在日志里看到本次真实改动
6. **Deploy** — `helm upgrade --install --atomic --wait --timeout 15m`
   `--atomic` 保证失败自动回滚到上一版本
7. **Verify rollout** — pod 状态、实际镜像、逐 deployment rollout、Warning 事件

## 手动操作

```bash
# 仅校验不部署
gitea: workflow_dispatch -> dry_run=true

# 指定镜像 tag 重发（例如回滚到某个已构建的镜像）
gitea: workflow_dispatch -> image_tag=sha-xxxxxxx

# 本地复现 CI 的渲染步骤
cat deploy/values/prod.yaml > /tmp/values.yaml
printf '\n' >> /tmp/values.yaml
cat /path/to/gitea-secret-values.yaml >> /tmp/values.yaml
helm template gitdata ./chart --namespace gitdata --set image.tag=sha-xxxxxxx -f /tmp/values.yaml

# 查看当前 release
helm history gitdata -n gitdata
```

## 注意

- **部署串行**：`concurrency.group = deploy-gitdata` 且 `cancel-in-progress: false`，
  避免两次 upgrade 互相打断。
- **迁移 Job**：`migrate.enabled=true` 时作为 pre-upgrade hook 运行，失败会阻断发布。
- **PVC 不在 chart 管理范围**：`gitdata-repos`（2Ti）由 kubectl 独立管理，
  `helm uninstall` 不会回收数据。
- **回滚**：`helm rollback gitdata <revision> -n gitdata`，
  或用 `image_tag` 重发上一个镜像。