# Docker API 部署 — Secrets 快速清单

与 [docker-build-deploy.yml](docker-build-deploy.yml) 保持一致。在 **Settings → Secrets and variables → Actions** 中配置（仓库级 Secrets）。

## 必需

| Secret | 说明 |
|--------|------|
| `STAGING_SSH_PRIVATE_KEY` | 预发机 SSH 私钥全文 |
| `STAGING_SSH_HOST` | 预发机主机名或 IP |
| `STAGING_SSH_USER` | SSH 用户名 |
| `STAGING_SSH_PORT` | SSH 端口（默认 `22`） |
| `STAGING_DEPLOY_PATH` | 预发机上的部署目录 |
| `PROD_SSH_PRIVATE_KEY` | 生产机 SSH 私钥（可与预发不同） |
| `PROD_SSH_HOST` | 生产机主机 |
| `PROD_SSH_USER` | 生产 SSH 用户 |
| `PROD_SSH_PORT` | 生产 SSH 端口 |
| `PROD_DEPLOY_PATH` | 生产部署目录 |
| `ALIYUN_CR_USERNAME` | 阿里云 ACR 用户名 |
| `ALIYUN_CR_PASSWORD` | 阿里云 ACR 密码 |

> **Tag 部署**：推送 `v*.*.*`（如 `v1.2.0`）时使用 `PROD_*`。**main 分支推送**使用 `STAGING_*`。

## 触发条件

- `push` 到 `main`：改动了 `api/**` 或 `.github/workflows/**` 时，先跑 **API tests**（`uv sync --dev` + `pytest`），再构建镜像并部署预发。
- `push` tag `v*.*.*`：同上路径过滤；部署生产。
- **workflow_dispatch**：可选手动指定 ref。

仓库内需存在 **`api/.env.staging`** / **`api/.env.production`**（供部署 job 校验与上传）；勿将真实密钥提交到公开分支。

## 本地验证 SSH

```bash
ssh -i ~/.ssh/your_key -p 22 user@your-host
```

## 本地验证 registry 登录

```bash
docker login <registry> --username=<ACR_USERNAME> --password-stdin
```

（密码从控制台或密钥管理读取，勿写入文档。）