accounts/docs/getting-started/concepts.md

核心概念

以下概念来自当前代码与数据库结构，帮助理解账户服务的核心模型。

用户（User）

用户包含：

• username / email / password
• role 与 level：admin / operator / user
• groups / permissions
• MFA 状态（TOTP）与邮箱验证状态

会话（Session）

• 登录成功后产生会话 token
• 会话默认保存在进程内存（非持久化）
• 客户端可使用 xc_session Cookie 或 Authorization: Bearer <token>

邮件验证

• SMTP 未配置或使用 *.example.com 时自动关闭验证
• 启用后，注册需要邮箱验证码

MFA（TOTP）

• 通过 /api/auth/mfa/totp/provision 生成 TOTP 秘钥
• 通过 /api/auth/mfa/totp/verify 完成验证并启用 MFA
• 可通过 /api/auth/mfa/disable 关闭

订阅（Subscription）

• 订阅信息保存在 subscriptions 表
• 支持 upsert 与 cancel
• 用于运营侧的订阅状态统计

管理权限矩阵（Admin Settings）

• 用于模块级权限开关
• 存储在 admin_settings 表
• 通过 GET/POST /api/auth/admin/settings 读取/更新

Agent / Xray 同步

• Controller（账号服务）暴露 /api/agent-server/v1 接口
• Agent 定时拉取用户列表生成 Xray 配置
• Agent 上报健康状态供管理员查看

数据导入导出与同步

• migratectl export/import：YAML 快照导入导出
• syncctl push/pull/mirror：通过 SSH 进行跨环境同步
• sql/ 下提供 pgsync 与 pglogical 同步脚本