# Docker API 部署 — Secrets 快速清单

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

## 必需

| Secret | 说明 |
|--------|------|
| `SSH_PRIVATE_KEY` | 预发（Staging）机 SSH 私钥全文 |
| `SSH_HOST` | 预发机主机名或 IP |
| `SSH_USER` | 预发 SSH 用户名 |
| `SSH_PORT` | 预发 SSH 端口（默认 `22`） |
| `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 密码 |

> **Staging**：`main` 发布使用无前缀 `SSH_*` 与 `DEPLOY_PATH`。<br>
> **Production**：`v*.*.*` tag 发布使用 `PROD_*`。

## 触发条件

- `push` 到 `main`：改动了 `api/**` 或 `.github/workflows/**` 时，先跑 **API tests**（`uv sync --dev` + `pytest`），再构建镜像并部署预发。
- `push` tag `v*.*.*`：同上路径过滤；部署生产。
- **workflow_dispatch**：仅用于补跑 `main` / `master`（Staging）或 `vMAJOR.MINOR.PATCH` tag（Production）；其它 ref 会直接失败，避免把任意分支部署到预发或生产。

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

## App Expo Release

- `push` 到 `main`：构建 Staging APK，执行 `node scripts/use-env.js staging`，产物上传为 GitHub Actions artifact。
- `push` tag `v*.*.*`：构建 Production APK，执行 `node scripts/use-env.js production`，并创建 GitHub Release。
- 手动 `workflow_dispatch`：`stage` 只允许在 `main` / `master` 上补跑；`prod` 需要选择 `vMAJOR.MINOR.PATCH` tag，或在 `main` / `master` 上填写语义化 `version`。

## 本地验证 SSH

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

## 本地验证 registry 登录

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

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