69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
# PK Lab 上线架构
|
||
|
||
## 三仓关系
|
||
|
||
```text
|
||
pk-lab-xhs (:3000 公网预览 + Nginx /api 代理) ─┐
|
||
├─ pk-lab-public Docker 网络 ─ pk-lab-api:8000 ─ PostgreSQL 16
|
||
rice-pk-xhs (:3002 公网预览 + Nginx /api 代理) ──┘
|
||
```
|
||
|
||
小程序源码不是由 Nginx 托管的 H5。两个前端容器是功能一致的浏览器验收入口；正式小程序仍由小红书开发者工具或后续接入 `xhs-mp-cli` 上传。
|
||
|
||
## 身份
|
||
|
||
1. 前端调用 `xhs.login()`，把一次性 `code` 发到服务端。
|
||
2. 服务端获取应用调用凭证并调用 `code2Session`，只在服务端使用 `session_key`，数据库保存 `(app_key, open_id) -> internal_user_id`。
|
||
3. `open_id` 仅在一个小程序内唯一。综合版用户生成 6 位绑定码，独立版用户主动输入确认；服务端检查两个用户没有同 app 身份后，以事务方式迁移身份和历史。
|
||
4. 公网预览只在 `TEST_AUTH_ENABLED=true` 时接受 `dev:` code。真实 App ID/Secret 生效后必须关闭。
|
||
|
||
## 数据模型
|
||
|
||
- `users`：内部用户，不保存小红书密码或 session key。
|
||
- `app_identities`：两套小程序各自的 `open_id` 映射。
|
||
- `auth_sessions`：随机 session token 的 SHA-256 哈希、所属用户和 app、有效期及撤销时间；原始 token 只返回给客户端。
|
||
- `tests` / `candidates`：题库和候选项；首批 7 套、288 项。
|
||
- `test_runs`：冠军、亚军、Top 排名、每轮左右选项与胜者、来源 app。
|
||
- `link_codes`：SHA-256 后的一次性绑定码、10 分钟过期时间与使用时间。
|
||
|
||
## 第一次 CI 配置
|
||
|
||
### `pk-lab-server`
|
||
|
||
Secrets：
|
||
|
||
- `POSTGRES_PASSWORD`：长随机密码，首次部署后不要随意更换。
|
||
- `XHS_HUB_APP_ID` / `XHS_HUB_APP_SECRET`：综合版，创建小程序应用后再配置。
|
||
- `XHS_RICE_APP_ID` / `XHS_RICE_APP_SECRET`：饭类独立版，创建小程序应用后再配置。
|
||
|
||
首次测试部署只要求 `POSTGRES_PASSWORD`；源码下载使用工作流内置的 Gitea job token。
|
||
|
||
Variables：
|
||
|
||
- `PUBLIC_BASE_URL`：可选，配置未来的正式 API 域名。
|
||
- `CORS_ORIGINS`：可选，仅跨域访问 API 时配置。
|
||
- `TEST_AUTH_ENABLED=true`（公网预览阶段）；小程序真实登录验收后改为 `false`。
|
||
|
||
### 两个前端
|
||
|
||
综合版默认 `DEPLOY_PORT=3000`，独立版默认 `DEPLOY_PORT=3002`。预览固定使用同源 `/api`，不需要 `API_BASE_URL` 或 CORS 配置。
|
||
|
||
## 永久运行保证
|
||
|
||
- API 与 PostgreSQL 均为 `restart: unless-stopped`。
|
||
- PostgreSQL 使用固定具名卷 `pk-lab-postgres-data`。
|
||
- 后端部署固定 Compose project 为 `pk-lab-production`，只执行 `docker compose up -d --wait`。
|
||
- 三个服务共享外部 Docker 网络 `pk-lab-public`；后端使用固定网络别名 `pk-lab-api`，前端 Nginx 通过容器 DNS 发现后端。
|
||
- 后端 API 不映射宿主机端口，公网只开放两个前端入口。
|
||
- 前端以固定容器名更新并设置重启策略；CI 结束不会删除新容器。
|
||
- PostgreSQL 不映射公网端口，只有 API 容器能访问。
|
||
|
||
## 上小红书前
|
||
|
||
- 为 API 配置可信 HTTPS 证书；小程序 `xhs.request` 必须使用 HTTPS。
|
||
- 在两套小程序后台分别加入 request 合法域名。
|
||
- 把两个 `app.js` 的 `apiBase` 改为最终 HTTPS 域名。
|
||
- 配置 App ID/Secret，确认真实 `xhs.login -> code2Session` 后关闭测试登录。
|
||
- 在开发者工具和真机检查 Canvas 海报、相册权限、长名称、轮空赛程与网络失败重试。
|
||
- 根据平台审核要求补齐隐私政策、用户数据删除入口和客服联系方式。
|