用户、登录与工作区
本文档基于 Aivory v2.4.7 编写。相关界面：“用户与访问 → 用户 / 注册策略 / 登录方式 / 工作空间”。反向代理与 HTTPS 前置配置见域名、HTTPS 与 OAuth。
访问控制决定谁能进入实例、以何种方式登录、能看到哪些资源，以及管理员在异常时如何处置账号。顺序原则：先保住了至少一个可恢复的管理员登录路径，再收紧注册和登录策略；不要在未验证 OAuth 或管理员密码前关闭唯一入口。
用户生命周期
“用户与访问 → 用户”支持搜索、创建和维护账号，并可下钻查看单个用户的对话、内容库、记忆、登录历史与用量：
| 操作 | 要点 |
|---|---|
| 创建/修改账号 | 确认邮箱归属、显示名、角色和初始密码；不要通过聊天、截图或工单发送明文密码 |
| 提升管理员 | 只对受信任人员授予：管理员可读取运营数据、修改渠道、导出含明文凭据的配置 |
| 暂停或封禁 | 适合安全事件、滥用或离职处理；先记录原因、时间和负责人，封禁会终止该用户的活跃会话 |
| 重置密码 / 关闭 2FA | 先核验身份，操作后通知账号所有者并留审计记录 |
| 删除用户 | 影响数据的不可逆操作：先确认法律保留、工作区所有权、共享资料与备份；删除≠暂时禁用 |
删除用户会先登记待清理对象路径，再执行破坏性 SQL，物理删除在启动时清扫。排查“文件还在吗”这类问题时以“数据与运营 → 文件”视图为准。
注册策略
“用户与访问 → 注册策略”集中了入口开关（页面保存前会检查当前管理员自身的身份源绑定，避免把自己锁在门外）：
| 字段 | 说明 | 默认 |
|---|---|---|
| 允许邮箱密码注册 | 关闭后禁止直接注册，不影响第三方登录各自的注册开关 | 开 |
| 注册需要验证码 | 新注册需完成滑块拼图验证码 | 关 |
| 登录需要验证码 | 每次密码登录先完成滑块拼图，可延缓撞库 | 关 |
| 单 IP 每日注册上限 | 0 = 不限制 | 0 |
| 要求邮箱验证 | 新注册用户须输入 6 位邮箱验证码才能登录（验证码 10 分钟有效，错 5 次作废，需 SMTP） | 关 |
| 允许注册的邮箱域名 | 逗号分隔；留空允许所有域名 | 空 |
企业登录策略（同页）
| 字段 | 说明 | 默认 |
|---|---|---|
| 允许本站邮箱密码登录 | 关闭后只剩第三方身份源入口 | 开 |
| 未登录入口 | 显示普通登录页 / 仅显示第三方登录 / 自动跳转到身份源 | 登录页 |
| 默认身份源 | “自动跳转”模式下未登录用户直接进入该身份源的授权页 | — |
| 允许第三方登录创建新账号 | 关闭后仅已绑定账号可第三方登录 | 开 |
| 第三方账号初始密码 | 必须设置 / 可选设置 / 禁止设置 | 可选 |
“仅显示第三方登录”或“自动跳转”都要求至少存在一个已启用且配置完整的身份源；关闭密码登录时也不能同时要求第三方账号“必须设置本站密码”（页面会拒绝该组合）。务必先在另一个浏览器或无痕窗口用测试账号走通登录，再关闭原入口。
推荐的公共部署基线：初期关闭开放注册或用邮箱域名白名单收紧 → 需要开放时启用验证码 + 邮箱验证 + 合理的单 IP 限制 → 为管理员保留至少一个已验证的登录路径 → 发布前用非管理员测试账号完整走一遍注册、验证、登录、登出、刷新、重置密码和被禁用后的行为。
典型场景的开关组合
| 场景 | 建议组合 |
|---|---|
| 个人自用 | 关闭开放注册；邮箱验证与验证码全部关闭；需要他人使用时在“用户”页手工建号，初始密码通过安全渠道单独交代 |
| 邀请制内测 | 保持关闭开放注册；管理员手工建号、按批次发放；SMTP 可以在这个阶段之后再配 |
| 公开社区 | 开放注册 + 注册与登录验证码 + 邮箱验证（SMTP 就绪后）+ 合理的单 IP 每日上限；默认用户组收紧额度，并准备好封禁与申诉流程 |
| 企业内网 | 关闭邮箱密码注册与本站密码登录，仅保留通用 OIDC / OAuth2 身份源；“未登录入口”设为自动跳转并指定默认身份源；第三方自动建号按组织策略显式决定 |
任何开关组合改动后，先用无痕窗口的新账号完整走一遍注册 → 登录 → 退出，再对全员生效。
验证码与邮箱机制细节
- 滑块拼图验证码：前端从
GET /api/public/captcha领取拼图，通过后换取一次性通行令牌（POST /api/public/captcha/verify）。挑战约 2 分钟过期、通行令牌约 10 分钟且一次一用。老浏览器截图/代理缓存拼图会导致“明明滑对了仍失败”，换无痕窗口重试即可判断。 - 邮箱验证/重置：6 位数字码，10 分钟有效，错 5 次作废重发；两者都依赖 SMTP 已配置。
- 登录审计：
登录历史是不可篡改的成功登录记录（设备、IP、时间），下钻在用户详情页；它只记成功登录，爆破尝试请看应用日志与速率限制行为。
OAuth 登录方式
“用户与访问 → 登录方式”支持五个内置/通用类型：Google、GitHub、Apple、通用 OAuth 2.0、通用 OIDC。上线一个身份源的安全步骤：
- 先完成公开 HTTPS 域名与反向代理（回调地址必须是浏览器可达的正式域名）。
- 在服务商侧创建应用：
- Google：Cloud Console → 凭据 → OAuth 客户端（授权码 + PKCE）。
- GitHub：Settings → Developer settings → OAuth Apps。
- Apple：创建 Services ID 与 AuthKey（
.p8），Client Secret 由 Aivory 用.p8现场签发的 JWT 承担。 - 通用 OAuth2 / OIDC：向 IdP 要授权、令牌、（可选）用户信息端点。
- 在“登录方式”点“添加登录方式”，把表单显示的“回调地址（Redirect URI）”原样复制到服务商控制台——该地址保存后不会变化。它形如：
https://aivory.example.com/api/auth/oauth/<提供方ID>/callback
- 填回 Client ID / Client Secret 等凭据并启用，用测试账号验证：新用户创建、已有账号登录、以及在个人设置中的显式账号绑定/解绑。
- 检查邮箱匹配、自动创建、初始密码策略和用户组分配符合预期后，再向真实用户开放入口或设置自动跳转。
各类型字段（表单按类型显示所需项）：
| 字段 | 适用 | 说明 |
|---|---|---|
| 登录方式 / 按钮文字 / 图标 | 全部 | 按钮文字与图标显示在登录页 |
| Client ID / Client Secret | 全部 | Apple 此处上传 .p8 私钥；编辑时留空保留原密钥 |
| Team ID / Key ID | Apple | 签发 client-secret JWT 所需 |
| 签发者地址 (Issuer URL) / JWKS URL | OIDC | 校验 ID Token 的签发方与签名密钥 |
| 授权 / 令牌 / 用户信息地址 | 通用 OAuth2 | 按提供商文档填写 |
| Scopes | 通用 | OAuth2 按文档；OIDC 留空用 openid email profile |
| 启用（在登录页显示） | 全部 | — |
token_exchange_failed多个公开域名时，用 OAUTH_CALLBACK_BASE_URL 固定回调规范主机、OAUTH_RETURN_ORIGINS 白名单允许的返回源（跨域一次性 handoff 令牌 60 秒有效），见域名、HTTPS 与 OAuth。第三方登录出现 token_exchange_failed 时，账号绑定正常不代表服务器出网正常：检查服务器到服务商 token endpoint 的 HTTPS、DNS、代理、防火墙与系统时间（令牌交换超时约 40 秒、state 有效期 10 分钟），不要反复解绑用户账号。
两步验证与会话安全
用户在前台个人设置中启用 TOTP 两步验证（错误码连续 5 次作废本次设置）；管理员可在核验身份后为用户关闭。2FA 不能替代：强且唯一的管理员密码、对 JWT_SECRET/数据库密码/OAuth Secret 的保护、HTTPS 与 Cookie 正确配置、对被盗设备及时封禁和会话撤销。
会话机制（管理员排障需要知道的）：
| 机制 | 事实 |
|---|---|
| 令牌形态 | 短期访问令牌（默认 30 分钟，ACCESS_TTL）+ 长期刷新令牌（默认 30 天，REFRESH_TTL，轮换、逐条入库可撤销），经 HttpOnly Cookie 或 Bearer 头下发 |
| 版本化撤销 | 每个访问令牌携带 token 版本与会话族 ID；改密、管理员封禁或用户撤销会话后，下一个请求即全网失效（多副本同样生效） |
| 会话管理 | 用户在个人设置查看活动会话（设备/IP/位置/最后在线）并可逐个撤销；无“全部退出”之外的后门 |
| 请求签名 | 认证后的写操作默认要求一次性 HMAC 签名请求（防重放窗口：时间戳超前 ≤300 秒、滞后 ≤60 秒）。客户端时钟严重偏移会表现为“request signature expired”；AIVORY_REQUEST_SIGNATURES_REQUIRED=false 可关闭（降低防护，仅调试用） |
| CSRF 源 | Cookie 携带的跨站请求必须 Origin 匹配 ALLOWED_ORIGINS，否则 403“cross-site request blocked”——这是域名部署后最常见的“登录成功但一切写操作失败”的原因 |
登录与访问故障速查
| 症状 | 优先检查 |
|---|---|
| 登录后一切写操作 403“cross-site request blocked” | ALLOWED_ORIGINS 是否精确等于浏览器 Origin（无路径、无尾斜杠、逗号分隔） |
| “request signature expired” | 客户端/服务器时钟偏移（窗口：超前 ≤300s、滞后 ≤60s）；代理是否改写了 /api 前缀或查询串 |
| 刚改密/被封禁的账号仍在使用 | 理论上下一个请求即失效；确认请求命中的是同一数据库而非旧副本 |
| 第三方登录跳回后仍是未登录 | 多域名时 OAUTH_CALLBACK_BASE_URL / OAUTH_RETURN_ORIGINS 未配置，handoff 被拒（60 秒一次性令牌） |
| 收不到验证邮件但 SMTP 测试发送正常 | 发件域 SPF/DKIM 缺失进垃圾箱；或邮箱域名白名单把它拦在注册前 |
| 反复要求重新登录（本地开发） | 未设 JWT_SECRET，重启即换密钥 |
| 用户说“登录不上”但后台能查到成功记录 | 检查其是否被要求邮箱验证、或账号状态被暂停 |
TTL 调整入口在环境变量：ACCESS_TTL（默认 30m）与 REFRESH_TTL（默认 720h）。缩短访问令牌能压缩泄露窗口，刷新令牌长度则在用户便利与设备风险间权衡。
用户组与工作空间
用户组（套餐）承载一组账号的默认可见模型、额度、积分与权限，见套餐、积分与支付。建议为管理员、内部员工、试用、付费和受限用户定义清晰少量分组，不制造难以追踪的例外组合。
工作空间用于团队协作（前台创建，管理端“工作空间”页检视与删除）：
- 明确所有者与转移规则：创建者离开后谁接管。
- 成员能力是逐项授权（会话、项目、知识库、文件等粒度开关），工作空间策略还能进一步收窄允许模型、工具与 MCP、月度积分限额——只做减法。
- 邀请链接设置合理有效期与使用次数，用后即撤；历史邀请令牌不会成为旁路。
- 不同客户、法律实体或保密级别的数据放独立工作空间，不依赖口头约定隔离。
- 审计：工作空间操作留审计日志，且记录不随工作空间删除而消失；元数据不含令牌、密钥与请求体。
平台管理员保留个人空间。域锁定功能只作用于被邮箱域规则绑定的普通用户；拥有平台 admin 角色的账号仍可在个人空间与工作空间之间切换。若需要限制某个管理员，应先调整账号角色，再在域名入组与工作空间访问中配置域规则或单用户例外。
组织域名入组请查看独立的域名入组与工作空间访问页面，那里说明精确域名匹配、命中注册时强制验证、只对未来账号生效、个人空间锁定以及 /admin/workspaces 负责人流程。
变更角色、用户组或工作区成员后，用低权限测试账号实际验证访问被正确收紧或放开，不要只从管理员视图判断权限。
权限面速查
| 层级 | 控制什么 | 在哪配 |
|---|---|---|
| 账号角色 | user / admin | 用户详情页 |
| 用户组权限 | 功能开关（分享、知识库、上传、语音、记忆、绘图…）与资源目录（提示词/技能/工具/MCP 的全部/指定/无） | 用户组 → 权限 |
| 模型权限 | 模型对哪些组可用、按费用/次数限额 | 模型页权限区块 + 用户组额度 |
| 工作空间策略 | 允许模型/工具/MCP 白名单、功能开关、成员月度积分上限（只收窄） | 工作空间所有者设置 |
| 成员能力项 | 逐成员细粒度 can_* 开关 | 工作空间成员管理 |
| 全局工具禁用 | 一键从所有模型移除某工具 | 能力与集成 → 工具 |
异常事件处置顺序
- 确认影响面：登录历史、异常用量（“用量与计费”按用户维度）、该用户参与的共享资源清单。
- 止血优先于取证：封禁账号或下调用户组即可即时终止会话、冻结入口；不需要先删数据。
- 撤销凭据：若怀疑泄露，轮换涉及的管理员密码并撤销全部会话（个人设置 → 会话管理）；管理员封禁会连带终止该账号所有刷新令牌。
- 保留证据：导出前记录订单号/事件 ID/时间线；“删除用户”会让用量记录匿名化而非消失。
- 复盘收紧：把这次攻击面翻译成注册策略、验证码或 IP 限制的具体开关，写进变更日志。
安全运营检查表
- 至少保留两个独立、可恢复的管理员登录路径，并妥善保存恢复流程。
- 定期轮换 OAuth、SMTP、模型渠道和存储密钥；轮换后做真实登录与发送测试。
- 开启注册或自动创建前，明确允许的用户范围、邮箱域名和滥用处理机制。
- 定期审阅登录历史、异常地区/IP、失败登录峰值与高频注册；用多信号组合而不是单一指标判断攻击。
- 删除、封禁、导出或恢复数据前，记录操作者、原因、范围和回滚方案。