Cheng Zhou
74feca4467
- replace plaintext login and unlock requests with RSA-OAEP/AES-GCM encrypted payloads - add login challenge replay protection, production RSA key validation, and auth tests - wire compose to environment-driven dev/prod settings without committing local secrets - update setup-config smoke scripts and Postman docs for encrypted login - add visit schedule migrations/tests and update study/subject setup workflows
329 lines
8.5 KiB
Markdown
329 lines
8.5 KiB
Markdown
# CTMS 分支环境安装配置指南
|
||
|
||
本文定义 `dev`、`main`、`release` 三类分支对应的推荐部署环境、配置文件、初始化步骤与验证命令。分支本身不会自动切换运行模式，实际模式由后端环境变量 `ENV` 决定。
|
||
|
||
## 分支与环境映射
|
||
|
||
| 分支 | 分支定位 | 推荐环境 | 后端 `ENV` | 用途 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `dev` | 日常开发与集成 | 开发环境 | `development` | 功能开发、联调、自测、内部集成 |
|
||
| `main` | 下一版本候选 | 预发布 / 验收环境 | `production` | 回归测试、验收、发布候选验证 |
|
||
| `release` | 当前稳定生产线 | 生产环境 | `production` | 正式生产部署、生产 hotfix |
|
||
|
||
推广路径保持为：
|
||
|
||
```text
|
||
feature/* -> dev -> main -> release
|
||
```
|
||
|
||
不要把 `release` 当作日常开发分支使用。`main` 应只接收已经准备进入候选版本范围的变更。
|
||
|
||
## 公共前置条件
|
||
|
||
所有环境都需要：
|
||
|
||
- Docker 与 Docker Compose
|
||
- 可写的 `pg_data/` 数据目录
|
||
- 端口 `8888`、`8000`、`5432` 未被占用
|
||
- 后端镜像可安装 `backend/requirements.txt` 中的依赖
|
||
- 前端镜像可执行 `npm ci` 与 `npm run build`
|
||
|
||
当前 compose 服务拓扑：
|
||
|
||
```text
|
||
nginx -> backend -> db
|
||
```
|
||
|
||
对外入口：
|
||
|
||
- 前端：`http://localhost:8888`
|
||
- 后端 API：同域 `/api/v1/*`
|
||
- 健康检查：`http://localhost:8888/health`
|
||
|
||
## dev 分支：开发环境
|
||
|
||
`dev` 默认用于本地开发和内部集成，推荐使用 `ENV=development`。
|
||
|
||
### 1. 切换分支
|
||
|
||
```bash
|
||
git checkout dev
|
||
git pull --rebase origin dev
|
||
```
|
||
|
||
### 2. 配置 `.env`
|
||
|
||
根目录 `.env` 不提交到仓库。开发环境推荐：
|
||
|
||
```env
|
||
COMPOSE_PROJECT_NAME=ctms_dev
|
||
ENV=development
|
||
JWT_SECRET_KEY=dev-secret
|
||
LOGIN_RSA_KEY_ID=default
|
||
LOGIN_RSA_PRIVATE_KEY=
|
||
```
|
||
|
||
说明：
|
||
|
||
- `ENV=development` 会启用开发行为。
|
||
- 未配置 `LOGIN_RSA_PRIVATE_KEY` 时，后端启动后会生成临时 RSA 私钥。
|
||
- 后端重启后临时公钥会变化，已有登录页应刷新后重新登录。
|
||
- `JWT_SECRET_KEY=dev-secret` 只允许本地开发使用。
|
||
|
||
### 3. 启动
|
||
|
||
```bash
|
||
docker compose up -d --build backend nginx
|
||
```
|
||
|
||
如果需要首次启动完整栈：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 4. 开发模式行为
|
||
|
||
`development` 模式下：
|
||
|
||
- FastAPI `debug=True`
|
||
- 应用启动时会执行 `Base.metadata.create_all`
|
||
- 应用启动时会确保默认管理员存在
|
||
- 未配置 RSA 私钥时允许临时生成
|
||
|
||
这些行为只适合开发，不适合生产。
|
||
|
||
### 5. 验证
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose exec backend python -c "from app.core.config import settings; print(settings.ENV)"
|
||
curl -i http://127.0.0.1:8888/health
|
||
curl -i http://127.0.0.1:8888/api/v1/auth/login-key
|
||
```
|
||
|
||
预期：
|
||
|
||
```text
|
||
ENV=development
|
||
GET /health -> 200
|
||
GET /api/v1/auth/login-key -> 200, key_id=default
|
||
```
|
||
|
||
## main 分支：预发布 / 验收环境
|
||
|
||
`main` 是下一正式版本候选分支，应按生产模式运行，但不直接承载正式生产流量。
|
||
|
||
### 1. 切换分支
|
||
|
||
```bash
|
||
git checkout main
|
||
git pull --rebase origin main
|
||
```
|
||
|
||
### 2. 配置 `.env`
|
||
|
||
预发布环境应使用 `ENV=production`，并配置独立于生产的密钥：
|
||
|
||
```env
|
||
COMPOSE_PROJECT_NAME=ctms_staging
|
||
ENV=production
|
||
JWT_SECRET_KEY=<staging-strong-random-secret>
|
||
LOGIN_RSA_KEY_ID=staging-YYYYMMDD
|
||
LOGIN_RSA_PRIVATE_KEY=<staging-rsa-private-key-pem-with-\n-escaped-newlines>
|
||
```
|
||
|
||
生成密钥示例：
|
||
|
||
```bash
|
||
openssl rand -hex 32
|
||
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048
|
||
```
|
||
|
||
要求：
|
||
|
||
- `JWT_SECRET_KEY` 不得使用 `dev-secret`。
|
||
- `LOGIN_RSA_PRIVATE_KEY` 必须固定保存，不能每次部署重新生成。
|
||
- staging 私钥不得复用 production 私钥。
|
||
|
||
### 3. 初始化数据库
|
||
|
||
生产模式不会自动建表或自动补管理员。首次部署或迁移前执行：
|
||
|
||
```bash
|
||
docker compose run --rm backend-init
|
||
```
|
||
|
||
该步骤应运行 Alembic migration，并确保固定管理员账号存在。
|
||
|
||
### 4. 启动
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 5. 验证
|
||
|
||
```bash
|
||
docker compose config
|
||
docker compose ps
|
||
docker compose exec backend python -c "from app.core.config import settings; print(settings.ENV); print(settings.JWT_SECRET_KEY == 'dev-secret'); print(bool(settings.LOGIN_RSA_PRIVATE_KEY))"
|
||
curl -i http://127.0.0.1:8888/health
|
||
curl -i http://127.0.0.1:8888/api/v1/auth/login-key
|
||
```
|
||
|
||
预期：
|
||
|
||
```text
|
||
ENV=production
|
||
JWT_SECRET_KEY == dev-secret -> False
|
||
LOGIN_RSA_PRIVATE_KEY_SET -> True
|
||
GET /health -> 200
|
||
GET /api/v1/auth/login-key -> 200
|
||
```
|
||
|
||
### 6. 验收门禁
|
||
|
||
在把 `main` 推进到 `release` 前，至少执行：
|
||
|
||
```bash
|
||
docker compose run --rm -v "$PWD/backend/tests:/code/tests:ro" backend python -m pytest
|
||
cd frontend && npm run test:unit
|
||
cd frontend && npm run type-check
|
||
cd frontend && npm run build
|
||
```
|
||
|
||
## release 分支：生产环境
|
||
|
||
`release` 是正式生产稳定分支。只有正式发布和生产 hotfix 应进入该分支。
|
||
|
||
### 1. 切换分支
|
||
|
||
```bash
|
||
git checkout release
|
||
git pull --rebase origin release
|
||
```
|
||
|
||
### 2. 配置 `.env`
|
||
|
||
生产环境必须使用生产专用配置：
|
||
|
||
```env
|
||
COMPOSE_PROJECT_NAME=ctms_prod
|
||
ENV=production
|
||
JWT_SECRET_KEY=<production-strong-random-secret>
|
||
LOGIN_RSA_KEY_ID=prod-YYYYMMDD
|
||
LOGIN_RSA_PRIVATE_KEY=<production-rsa-private-key-pem-with-\n-escaped-newlines>
|
||
```
|
||
|
||
要求：
|
||
|
||
- `.env` 必须只保存在部署机器或密钥管理系统中。
|
||
- 不得提交 `.env`、私钥、JWT 密钥。
|
||
- `JWT_SECRET_KEY` 轮换会使既有 token 失效，应安排维护窗口。
|
||
- `LOGIN_RSA_PRIVATE_KEY` 轮换会影响新登录密钥获取，应同步更新 `LOGIN_RSA_KEY_ID`。
|
||
|
||
### 3. HTTPS 要求
|
||
|
||
登录加密依赖浏览器 WebCrypto。生产访问必须使用 HTTPS：
|
||
|
||
- `https://正式域名`
|
||
- 本地 `localhost` 是浏览器安全上下文例外，但不能代表生产可用性
|
||
|
||
如果生产仍通过 `http://服务器IP:8888` 访问，前端会拒绝执行登录加密。
|
||
|
||
### 4. 初始化与迁移
|
||
|
||
首次部署或每次包含 migration 的发布：
|
||
|
||
```bash
|
||
docker compose run --rm backend-init
|
||
```
|
||
|
||
确认 migration 成功后再启动或滚动重启服务。
|
||
|
||
### 5. 启动
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
### 6. 生产验证
|
||
|
||
```bash
|
||
docker compose ps
|
||
docker compose exec backend python -c "from app.core.config import settings; print(settings.ENV); print(settings.JWT_SECRET_KEY == 'dev-secret'); print(bool(settings.LOGIN_RSA_PRIVATE_KEY)); print(settings.LOGIN_RSA_KEY_ID)"
|
||
curl -i https://<production-domain>/health
|
||
curl -i https://<production-domain>/api/v1/auth/login-key
|
||
```
|
||
|
||
预期：
|
||
|
||
```text
|
||
ENV=production
|
||
JWT_SECRET_KEY == dev-secret -> False
|
||
LOGIN_RSA_PRIVATE_KEY_SET -> True
|
||
GET /health -> 200
|
||
GET /api/v1/auth/login-key -> 200
|
||
```
|
||
|
||
### 7. 多实例约束
|
||
|
||
当前登录 challenge 默认保存在后端进程内：
|
||
|
||
- 单实例、单 worker：可直接使用
|
||
- 多实例或多 worker：必须满足以下至少一项
|
||
- 使用共享缓存保存 challenge，例如 Redis
|
||
- 启用粘性会话，确保 `/login-key` 与 `/login` 命中同一后端进程
|
||
- 将后端限制为单 worker 单副本
|
||
|
||
如果不满足，上线后可能出现偶发登录失败。
|
||
|
||
## 环境变量说明
|
||
|
||
| 变量 | dev | main/staging | release/production | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `COMPOSE_PROJECT_NAME` | `ctms_dev` | `ctms_staging` | `ctms_prod` | 防止不同环境容器名、网络名冲突 |
|
||
| `ENV` | `development` | `production` | `production` | 后端运行模式 |
|
||
| `JWT_SECRET_KEY` | `dev-secret` | 强随机 | 强随机 | JWT 签名密钥 |
|
||
| `LOGIN_RSA_KEY_ID` | `default` | `staging-YYYYMMDD` | `prod-YYYYMMDD` | 登录 RSA 密钥版本 |
|
||
| `LOGIN_RSA_PRIVATE_KEY` | 空 | staging 私钥 | production 私钥 | RSA 私钥，生产模式必填 |
|
||
|
||
## 常见问题
|
||
|
||
### 登录页提示当前浏览器环境不支持安全登录加密
|
||
|
||
原因：非 HTTPS、非 localhost 的访问环境不满足 WebCrypto 安全上下文要求。
|
||
|
||
处理：
|
||
|
||
- 本地使用 `http://localhost:8888`
|
||
- staging/production 使用 HTTPS 域名
|
||
|
||
### production 模式启动失败，提示必须配置 LOGIN_RSA_PRIVATE_KEY
|
||
|
||
原因：`ENV=production` 时必须提供固定 RSA 私钥。
|
||
|
||
处理：
|
||
|
||
```bash
|
||
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048
|
||
```
|
||
|
||
将输出 PEM 写入 `.env` 的 `LOGIN_RSA_PRIVATE_KEY`，换行使用 `\n` 转义。
|
||
|
||
### 切换分支后环境不符合预期
|
||
|
||
分支不会自动修改 `.env`。切换分支后应重新确认：
|
||
|
||
```bash
|
||
docker compose config
|
||
docker compose exec backend python -c "from app.core.config import settings; print(settings.ENV)"
|
||
```
|
||
|
||
必要时修改 `.env` 并重启：
|
||
|
||
```bash
|
||
docker compose up -d --build backend nginx
|
||
```
|