98 lines
5.1 KiB
Markdown
98 lines
5.1 KiB
Markdown
|
# Phase 2 用户认证与权益基础报告
|
|||
|
|
|
|||
|
|
日期：2026-09-08
|
|||
|
|
范围：P2-01 至 P2-07
|
|||
|
|
状态：核心认证、会话、权益、额度基础和受控管理员能力已完成并部署测试环境；真实邮箱/短信渠道和 TTS 未接入。
|
|||
|
|
|
|||
|
|
## 1. 实现内容
|
|||
|
|
|
|||
|
|
### P2-01 数据模型和迁移
|
|||
|
|
|
|||
|
|
- `services/api/migrations/001_initial.sql` 建立版本化初始化脚本。
|
|||
|
|
- 已创建 `users`、`sessions`、`plan_policies`、`membership_grants`、`quota_accounts`、`usage_records`、`verification_challenges`、`admin_audit_logs` 和 `schema_migrations`。
|
|||
|
|
- PostgreSQL 使用 UUID、UTC 时间、唯一约束、Role/Plan 检查约束和审计字段。
|
|||
|
|
- 当前无旧数据库，未执行数据迁移。
|
|||
|
|
|
|||
|
|
### P2-02 认证与会话
|
|||
|
|
|
|||
|
|
- 邮箱密码注册、登录、退出、当前用户和密码修改已实现。
|
|||
|
|
- 密码使用 Argon2id 哈希；密码原文、哈希、会话令牌和验证码不进入响应或日志。
|
|||
|
|
- 会话使用服务端可撤销不透明 Cookie，Cookie 配置 `HttpOnly`、`SameSite=Lax`、HTTPS 环境 `Secure`。
|
|||
|
|
- 改密后撤销其他会话；禁用账户不能新登录。
|
|||
|
|
|
|||
|
|
### P2-03 权限和防护
|
|||
|
|
|
|||
|
|
- `role=user/admin` 与 `plan=free/vip` 分离，注册请求不能写入角色、套餐或状态。
|
|||
|
|
- Origin 校验、CSRF Cookie/Header 校验和服务端资源权限检查已实现。
|
|||
|
|
- 登录和注册具备当前 API 进程内限流；多进程/多节点限流待 Redis 阶段替换。
|
|||
|
|
- 普通用户访问管理接口返回 `403`。
|
|||
|
|
|
|||
|
|
### P2-04 会员和额度基础
|
|||
|
|
|
|||
|
|
- 有效 VIP 由未撤销且在有效期内的 `MembershipGrant` 判断；过期后权益计算回到 free，不依赖重新登录。
|
|||
|
|
- 额度账户按 UTC 自然月建立，返回周期、上限、调整、已用、冻结和可用额度。
|
|||
|
|
- 当前环境策略默认值为 free `10000`、vip `100000` 周期单位，仅用于测试基础，不代表正式产品定值。
|
|||
|
|
- TTS 生成、消费、冻结和释放仍留在 Phase 3，本阶段不实现生成业务。
|
|||
|
|
|
|||
|
|
### P2-05 账户中心
|
|||
|
|
|
|||
|
|
- `/account` 已改为读取真实 `/api/v1/auth/me` 和 `/api/v1/account/usage`。
|
|||
|
|
- 支持显示邮箱、角色、计划、验证状态、额度周期、已用、冻结和可用额度。
|
|||
|
|
- 支持退出和修改密码；未登录、加载和错误状态有明确提示。
|
|||
|
|
|
|||
|
|
### P2-06 验证流程预留
|
|||
|
|
|
|||
|
|
- `VerificationChallenge`、用途、渠道、过期、尝试次数、摘要和一次性消费结构已建立。
|
|||
|
|
- 验证确认成功会更新对应 `email_verified` 或 `phone_verified`，挑战过期/重复/错误会拒绝。
|
|||
|
|
- 邮件和短信开关默认关闭；当前发送接口明确返回 `503 VERIFICATION_NOT_ENABLED`，没有伪造发送成功。
|
|||
|
|
|
|||
|
|
### P2-07 受控管理员初始化
|
|||
|
|
|
|||
|
|
- `services/api/app/init_admin.py` 只接受进程环境中的 `ADMIN_EMAIL`、`ADMIN_PASSWORD`，拒绝覆盖已有邮箱。
|
|||
|
|
- 测试管理员已受控初始化，邮箱为 `mu.blank@gmail.com`；密码原文未写入仓库、配置文件或日志。
|
|||
|
|
- 管理服务接口支持用户查询、VIP/Plan 授予、额度调整、禁用/恢复和审计记录。
|
|||
|
|
- 最后一个可用管理员不能被禁用。
|
|||
|
|
|
|||
|
|
## 2. 测试结果
|
|||
|
|
|
|||
|
|
测试入口：`https://192.168.199.22/`。测试使用临时账户，密码未记录。
|
|||
|
|
|
|||
|
|
| 测试 | 结果 |
|
|||
|
|
| --- | --- |
|
|||
|
|
| PostgreSQL 迁移 | 通过，`001_initial.sql` 已应用 |
|
|||
|
|
| API 健康检查 | 通过，数据库状态 `ok` |
|
|||
|
|
| 注册 | `201` |
|
|||
|
|
| 登录并设置 Cookie | `200` |
|
|||
|
|
| 当前用户 | `200` |
|
|||
|
|
| 额度读取 | `200` |
|
|||
|
|
| 修改密码 | `200` |
|
|||
|
|
| 验证发送未启用 | `503` |
|
|||
|
|
| 退出 | `204` |
|
|||
|
|
| 退出后访问当前用户 | `401` |
|
|||
|
|
| 普通用户访问管理接口 | `403` |
|
|||
|
|
| 管理员查询用户 | `200` |
|
|||
|
|
| 管理员授予 VIP | `200` |
|
|||
|
|
| 管理员额度调整 | `200` |
|
|||
|
|
| 管理员禁用用户 | `200` |
|
|||
|
|
| 被禁用用户登录 | `403` |
|
|||
|
|
| 管理员恢复用户 | `200` |
|
|||
|
|
|
|||
|
|
## 3. 测试环境部署
|
|||
|
|
|
|||
|
|
- PostgreSQL `16.15`：业务数据库 `kaotings`，业务账号 `kaotings_app`，仅监听 `127.0.0.1:5432`。
|
|||
|
|
- API：FastAPI/Uvicorn，systemd 服务 `kaotings-api`，仅监听 `127.0.0.1:8000`。
|
|||
|
|
- Web：Next.js，systemd 服务 `kaotings-web`，仅监听 `127.0.0.1:3000`。
|
|||
|
|
- HTTPS：Caddy `2.6.2`，systemd 服务 `caddy`，监听 TCP `80/443`，使用 `tls internal`，`/api/*` 反代 API，其余请求反代 Web。
|
|||
|
|
- 自动重启：API、Web、Caddy 均由 systemd 管理并设置 `Restart=always`；PostgreSQL 使用系统服务。
|
|||
|
|
- 测试 HTTPS 根证书已导入当前开发机用户受信任根证书存储；根证书和私钥不进入 Git。
|
|||
|
|
- Redis、TTS、CMS、对象存储未安装或启动，符合本阶段范围。
|
|||
|
|
- 发布包保留完整目录结构；当前构建版本为 `4e40019`。
|
|||
|
|
|
|||
|
|
## 4. 安全和待办
|
|||
|
|
|
|||
|
|
- `/etc/kaotings/api.env` 为 root-only `0600`，包含数据库密码和 CSRF 密钥，不在仓库。
|
|||
|
|
- 当前测试策略值、管理员密码和临时测试账户不作为生产配置。
|
|||
|
|
- 邮件/SMS 真实服务、找回密码和强制验证仍待后续渠道接入。
|
|||
|
|
- Cookie、HTTPS 和认证已验证；完整生产限流、备份恢复和外部安全复测属于后续验收。
|
|||
|
|
- API 与 Web 已用统一保留目录结构的发布归档部署，避免逐文件传输错位。
|