30 lines
2.0 KiB
Markdown
30 lines
2.0 KiB
Markdown
# PK Lab Server
|
|
|
|
`pk-lab-xhs` 与 `rice-pk-xhs` 共用的 FastAPI + PostgreSQL 后端。它保存首批七套题库、PK 决策轨迹、最终排名和用户历史，并负责把两个小红书小程序各自的 `open_id` 安全映射到内部用户。
|
|
|
|
## 核心设计
|
|
|
|
- `xhs.login()` 的一次性 `code` 只发给 `/api/v1/auth/xhs`；服务端换取 `open_id`，绝不把 `session_key` 下发。
|
|
- 小红书 `open_id` 只在单个小程序内唯一。综合版与饭类独立版通过 6 位、10 分钟有效、单次使用的绑定码合并内部用户。
|
|
- 完整 PK 决策轨迹和 Top 排名写入 PostgreSQL，可复现结果并支持后续统计。
|
|
- 固定 Compose project `pk-lab-production` 和具名卷 `pk-lab-postgres-data`。CI 只执行 `up -d` 更新，不执行 `down -v`，发布后服务与数据持续存在。
|
|
|
|
## CI 所需配置
|
|
|
|
部署前只需由仓库所有者配置 Secret `POSTGRES_PASSWORD`。用户登录采用 PostgreSQL 持久化 session，服务端只保存随机 token 的 SHA-256 哈希，不需要全局 token 签名密钥。上线真实登录前再配置两套 `XHS_*_APP_ID/SECRET`。拉取源码默认使用 Gitea 工作流自带令牌，也可用 `GITEA_TOKEN` 覆盖。后端只在 `pk-lab-public` Docker 网络内以别名 `pk-lab-api:8000` 提供服务，不映射宿主机端口；两个预览站通过同源 `/api` 反向代理访问。可选 Variables：`PUBLIC_BASE_URL`、`CORS_ORIGINS`、`TEST_AUTH_ENABLED`。
|
|
|
|
当前流水线默认 `TEST_AUTH_ENABLED=true`，让两个公网预览可以创建明确隔离的测试身份。接入真实小红书 App ID/Secret 后，必须把该变量改成 `false`，关闭 `dev:` 登录路径。
|
|
|
|
生产 API 必须使用 HTTPS，并在两个小程序后台加入 request 合法域名。首次配置 App ID/Secret 后重新运行流水线即可启用真实登录。
|
|
|
|
## 本地命令（可选）
|
|
|
|
```bash
|
|
python -m venv .venv
|
|
. .venv/bin/activate
|
|
pip install . pytest ruff
|
|
TEST_AUTH_ENABLED=true pytest -q
|
|
```
|
|
|
|
接口文档部署后位于 `/docs`，健康检查为 `/health`。
|