认证与订阅
1. 功能概述
DBridge 支持两种认证模式：OAuth 第三方认证（用户中心）和本地账号密码认证。同时提供订阅管理功能，展示当前订阅状态、权益信息和网络连接状态。
核心能力：
- OAuth 第三方认证（支持多个 Provider）
- 本地账号密码认证
- 订阅状态查看
- 权益信息查询
- 网络连接状态监控
2. 登录
2.1 登录页面
访问系统地址后，未登录用户会自动跳转到登录页面。登录页面根据系统配置显示不同的登录方式。
2.2 OAuth 登录
当系统配置了 OAuth Provider 时，登录页面显示 OAuth 标签页。
操作步骤：
- 在登录页面切换到 OAuth 登录 标签页
- 页面显示可用的 OAuth Provider 按钮（如 GitHub、Google 等）
- 点击对应的 Provider 按钮
- 浏览器跳转到 Provider 的授权页面
- 用户授权后，自动跳转回 DBridge 并完成登录
提示：如果同时配置了 OAuth 和本地登录，页面底部会提示可以切换到本地登录。
2.3 本地账号登录
当系统允许本地登录时，登录页面显示本地登录标签页。
操作步骤：
- 在登录页面切换到 本地登录 标签页
- 输入用户名和密码
- 点击 登录 按钮
说明：本地账号由 dbridge-desktop 的安全设置管理。
2.4 登录错误处理
| 错误状态 | 说明 |
|---|---|
| missing_code | OAuth 回调缺少授权码 |
| device_limit_reached | 设备数量已达上限，需要管理设备 |
| login_failed | 登录失败，请检查凭据 |
3. 认证模式配置
认证模式在系统配置文件 config.yaml 中设置：
subscription:
enabled: true
auth_mode: "usercenter" # "password" 或 "usercenter"
base_url: "http://localhost:8080"
app_id: "your_app_id"
product_id: "your_product_id"
3.1 auth_mode 说明
| 模式 | 说明 |
|---|---|
usercenter |
使用用户中心 OAuth 认证，支持多 Provider |
password |
使用本地账号密码认证 |
3.2 认证流程
OAuth 模式：
- 前端请求
/api/v1/auth/login-config获取可用 Provider - 点击 Provider 按钮，请求
/api/v1/auth/oauth/start?provider=xxx - 后端返回
authorize_url，前端跳转 - 用户授权后回调到
/auth/callback - 前端携带 code 完成后端验证和登录
本地模式：
- 前端提交用户名和密码到
/api/v1/auth/local-login - 后端验证凭据
- 返回 JWT Token
4. 订阅管理
4.1 进入订阅页面
在左侧导航栏中，点击 订阅管理 进入订阅页面。
4.2 订阅状态
页面展示当前订阅的详细信息：
| 字段 | 说明 |
|---|---|
| 状态 | 订阅状态标签 |
| 到期日期 | 订阅到期时间 |
| 有效到期 | 实际有效到期时间（含宽限期） |
| 宽限期 | 宽限期信息（如适用） |
| 只读模式 | 是否处于只读模式 |
| 网络状态 | 在线/离线状态，最后同步时间 |
4.3 订阅状态说明
| 状态 | 颜色 | 说明 |
|---|---|---|
| Active | 绿色 | 订阅有效，所有功能正常 |
| Grace | 橙色 | 订阅已过期，处于宽限期，功能受限 |
| Expired | 红色 | 订阅已过期，进入只读模式 |
| Canceled | 灰色 | 订阅已取消 |
| Refunded | 灰色 | 订阅已退款 |
4.4 权益信息
权益卡片展示当前订阅包含的权益：
- 来源：权益来源
- 产品 ID：订阅的产品标识
- 到期时间：权益到期时间
- 版本系列：适用的版本系列
4.5 刷新订阅
点击 刷新 按钮，系统会从服务器重新获取最新的订阅数据。
4.6 续费提示
当订阅状态为 expired、grace 或 canceled 时，页面会显示续费提示信息，并提供 续费 按钮。
5. 网络连接状态
系统会定期与许可服务器同步状态。
| 字段 | 说明 |
|---|---|
| 在线状态 | 与许可服务器的连接状态 |
| 最后同步时间 | 最近一次成功同步的时间 |
| 连续失败次数 | 连续同步失败的次数 |
6. 设备管理
OAuth 模式下，系统通过设备指纹识别不同的设备实例。
6.1 设备限制
当订阅达到设备数量上限时，登录会返回 device_limit_reached 错误。
6.2 管理设备
用户可以在用户中心的设备管理页面查看和移除已注册的设备。移除旧设备后，新设备即可正常登录。
7. 会话管理
登录成功后，系统会颁发 JWT Token，默认有效期为 7200 秒（2 小时）。
jwt:
expires_in: 7200
secret: change-me-in-production
Token 过期后需要重新登录。前端会自动检测 Token 过期并跳转到登录页面。
8. 安全建议
- 生产环境修改 JWT Secret：默认的
change-me-in-production不安全 - 启用 HTTPS：保护登录凭据在传输过程中的安全
- 定期更新密码：如果使用本地账号认证
- 监控设备数量：及时清理不再使用的设备
- 配置合适的 Token 有效期：根据安全需求调整
expires_in