docs: record Phase 2 authentication deployment
This commit is contained in:
parent
4e40019dce
commit
4b3e82568a
@ -1,6 +1,6 @@
|
|||||||
# 考町科技官网暨 AI 工具平台
|
# 考町科技官网暨 AI 工具平台
|
||||||
|
|
||||||
当前阶段：Phase 1 设计系统与官网骨架已完成，真实业务服务尚未接入。
|
当前阶段：Phase 2 用户认证与权益基础已完成，TTS 生成和 CMS 尚未接入。
|
||||||
|
|
||||||
- [产品与技术规划（含分阶段工作清单）](docs/V1_PLAN.md)
|
- [产品与技术规划（含分阶段工作清单）](docs/V1_PLAN.md)
|
||||||
- [Word 规划书](docs/考町科技官网暨AI工具平台_V1.1.docx)
|
- [Word 规划书](docs/考町科技官网暨AI工具平台_V1.1.docx)
|
||||||
@ -10,6 +10,7 @@
|
|||||||
- [技术决策](docs/DECISIONS.md)
|
- [技术决策](docs/DECISIONS.md)
|
||||||
- [后续执行计划](docs/EXECUTION_PLAN.md)
|
- [后续执行计划](docs/EXECUTION_PLAN.md)
|
||||||
- [Phase 1 阶段报告](docs/phase-1-report.md)
|
- [Phase 1 阶段报告](docs/phase-1-report.md)
|
||||||
|
- [Phase 2 阶段报告](docs/phase-2-report.md)
|
||||||
|
|
||||||
项目根目录：`E:\RD\Kaotings\www_site`，以本次新仓库为准。
|
项目根目录：`E:\RD\Kaotings\www_site`，以本次新仓库为准。
|
||||||
|
|
||||||
|
|||||||
@ -53,13 +53,15 @@ Phase 1 当前可在本地继续开发，也可在测试机仅部署官网骨架
|
|||||||
|
|
||||||
### Phase 2：认证与权益基础
|
### Phase 2：认证与权益基础
|
||||||
|
|
||||||
- `P2-01` 建立 User、Session、PlanPolicy、MembershipGrant、QuotaAccount、UsageRecord、VerificationChallenge 和审计迁移。
|
- `P2-01` 已完成：版本化迁移和 User、Session、PlanPolicy、MembershipGrant、QuotaAccount、UsageRecord、VerificationChallenge、审计表已建立。
|
||||||
- `P2-02` 实现真实注册、登录、退出、当前用户、改密和可撤销会话。
|
- `P2-02` 已完成：真实注册、登录、退出、当前用户、改密和可撤销会话已验证。
|
||||||
- `P2-03` 实现权限、账号禁用、CSRF、站内跳转校验和认证限流。
|
- `P2-03` 已完成：权限、账号禁用、CSRF、Origin、同源入口和认证限流已实现并测试。
|
||||||
- `P2-04` 实现有效 Plan、VIP 到期、额度周期和余额读取。
|
- `P2-04` 已完成：有效 Plan、VIP 到期、额度周期和余额读取已实现；正式额度值仍待产品确认。
|
||||||
- `P2-05` 完成账户页和真实空历史状态。
|
- `P2-05` 已完成：账户页读取真实 API，支持账户、额度、退出和改密；TTS 历史保留真实空状态。
|
||||||
- `P2-06` 实现验证服务抽象、开关、挑战过期和一次性消费；未接渠道返回未启用。
|
- `P2-06` 已完成：验证服务抽象、开关、挑战过期和一次性消费已实现；未接渠道返回未启用。
|
||||||
- `P2-07` 建立受控管理员初始化及服务层管理、会员、额度调整能力。
|
- `P2-07` 已完成：受控管理员初始化及服务层用户、会员、额度调整能力已部署并测试。
|
||||||
|
|
||||||
|
交付物：数据库迁移、认证接口、可用账户页、权益服务、测试部署和 `docs/phase-2-report.md`。TTS 生成、CMS 和完整管理界面仍分别属于 Phase 3/4。
|
||||||
|
|
||||||
### Phase 3：TTS 与额度闭环
|
### Phase 3：TTS 与额度闭环
|
||||||
|
|
||||||
|
|||||||
97
docs/phase-2-report.md
Normal file
97
docs/phase-2-report.md
Normal file
@ -0,0 +1,97 @@
|
|||||||
|
# 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 已用统一保留目录结构的发布归档部署，避免逐文件传输错位。
|
||||||
Loading…
Reference in New Issue
Block a user