[skip eval] feat: 游客身份（免登录使用第一步）

[HyxiaoGe]

背景

免登录使用的第一步：未登录用户可以领取一个游客身份，像登录用户一样以 Bearer 令牌访问，会话照常保存在服务端，刷新或重开页面都还在。登录变成功能门槛，而不是使用门槛。额度与权益在 PR 2，前端在 PR 3。

改动

• 游客身份：

  • users 表新增 is_guest 字段（Alembic b7d2e4f6a813，ADD COLUMN ... DEFAULT false NOT NULL）。
  • 新增 POST /api/auth/guest，创建一个游客用户，返回 Fusion 自己签发的 HS256 令牌，有效期 365 天，签发方为 fusion-guest，与统一认证服务的 RS256 令牌互不混用。

• 认证：get_current_user 先按签发方分流。游客令牌用独立密钥验签，只能解析到 is_guest=True 的用户，不能冒充登录用户；游客不走统一认证服务的资料同步和单点登出检查。

• 登录门槛：新增 require_registered_user 依赖，挂到以下写操作上，游客请求返回 403 LOGIN_REQUIRED：

  • 文件：上传、删除。
  • 知识库：创建、修改、删除、上传文档、检索。
  • 个人设置：PATCH /me。

  读取接口不拦，游客读到的是空列表，界面不会出现 403 报错。

• 防刷：同一 IP 每天（北京时间）最多新建 5 个游客身份，超过返回 429。

  • IP 来源：依次取 CF-Connecting-IP、X-Real-IP、X-Forwarded-For 的第一个地址、直连地址。
  • 存储：Redis 键和日志只记录 IP 的 SHA-256 摘要。Redis 不可用时拒绝新建游客，返回 503，登录用户不受影响。

• 开关与密钥：

  • 新增 GUEST_MODE_ENABLED（GitHub 变量，默认 false）和 GUEST_TOKEN_SECRET（GitHub Secret，已用随机值创建）。部署脚本和回滚脚本都会传入这两项。
  • 开关打开但密钥未配置时，部署直接失败。开关关闭时，签发和验证游客令牌都会被拒绝，可作为总开关。
  • 游客令牌不使用 SECRET_KEY：dev 没有配置它，目前用的是代码里的默认值。

上线影响

GUEST_MODE_ENABLED 保持 false，本 PR 上线后行为不变。PR 2 的额度限制上线前不会打开。

验证

• 新增 test_guest_identity.py（13 项），覆盖：
  • 令牌：签发与验签往返；默认密钥伪造的令牌被拒；过期令牌被拒；开关关闭时有效令牌也被拒；统一认证服务的令牌不会被当成游客令牌。
  • 认证：游客令牌不调用统一认证服务的校验；游客令牌指向登录用户时返回 401；require_registered_user 拒绝游客。
  • 限额与 IP：同一 IP 第 6 次新建被拒，换一个 IP 不受影响；IP 来源的优先级正确。
  • 接口：成功返回的令牌能验证出新建的用户；开关关闭返回 403，超限返回 429，Redis 故障返回 503。
  • 拦截：游客调用 PATCH /me、文件上传、新建知识库都返回 403 LOGIN_REQUIRED。
• 以下测试共 78 项通过：test_guest_identity、test_security、test_knowledge_bases、test_core_surface、test_deploy_auth_config。另外 3 个测试文件（test_response、test_agent_trajectory_migration、test_ci_cd_permission_boundary）共 51 项通过。
• 迁移：离线生成的 PostgreSQL SQL 只有 ALTER TABLE users ADD COLUMN is_guest BOOLEAN DEFAULT false NOT NULL。本地 SQLite 跑不了完整的迁移链（已有迁移用到 JSONB），所以没有在本地实际执行。部署时会自动执行 upgrade。
• 没有验证：经过 Cloudflare 和 Next 代理后，CF-Connecting-IP 能否到达后端。这要等 PR 2 上线后，在 dev 打开开关时实测。

🤖 Generated with Claude Code