www_site/docs/phase-2-report.md

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 已用统一保留目录结构的发布归档部署，避免逐文件传输错位。

5. 浏览器闭环验收

使用真实 Chromium 浏览器执行 Playwright 页面操作，测试环境版本为 build 7890868：

• 桌面视口：1440x900，移动视口：390x844。
• 注册页填写邮箱、密码和确认密码，提交后页面跳转登录页。
• 登录页提交后页面跳转账户中心。
• 账户中心从 API 加载真实邮箱、角色、Free 计划和 10,000 可用额度。
• 修改密码后页面显示“密码已修改，其他会话已撤销”。
• 点击退出登录后页面返回登录页并显示登录标题。
• 第二次完整运行 pageErrors=[]，未发现浏览器页面运行时错误。
• 已生成桌面注册、桌面账户和移动未登录账户截图用于验收，截图未提交 Git。

本次浏览器脚本首次发现并修复了异步表单事件引用错误，修复提交为 7890868；修复后重新构建、部署并完成闭环。

6. TTS 上游资料状态

本阶段已完成只读核查，但仍未发现真实 TTS 上游地址、接口文档、鉴权方式、音色列表、参数范围、音频返回方式或异步任务查询资料。详细请求字段见 TTS_UPSTREAM_REQUEST.md。这些资料仍是 Phase 3 入口条件。