认证控制

系统 -> 认证控制 聚焦“怎么让用户登录和校验身份”, 而不是角色/权限。这里可以集中配置邮箱、短信、社交账号以及设备认证等多种方式, 并内置测试工具确保配置可立即生效。

模块概览

• 通信方式: 邮箱登录与短信登录, 支持验证码流程、白名单策略以及模板维护。
• 社交账号: Apple、Google、Facebook、GitHub、Telegram 五种主流 OAuth/机器人方案, 均可独立开启/关闭。
• 设备认证: 针对客户端设备的登录策略, 支持虚拟机拦截及通信密钥。

下面内容与后台页面的分区保持一致, 建议依次配置、测试并保存。

通信方式

邮箱认证

1. 基础开关

   • 启用邮箱登录: 控制是否在用户端展示邮箱登录入口。
   • 邮箱验证: 要求新用户或敏感操作必须先完成验证码校验。
   • 域名白名单: 仅允许特定后缀(如 gmail.com)注册/登录, 可在下方列表一行一个填入。

2. SMTP 平台配置

   • 服务器地址 与 端口: 对应 SMTP Host/Port, 常用端口 25/465/587。
   • SSL/TLS 开关: 与邮件服务提供商支持的加密方式保持一致。
   • 账号/密码: SMTP 鉴权凭证, 通常为邮箱与应用专用密码。
   • 发件地址 From: 用户看到的发件邮箱, 需与 SMTP 账号匹配。
   • 发送测试邮件: 在配置下方输入收件邮箱即可发送, 立刻验证能否投递成功。

3. 模板管理 (位于页签 验证邮件 / 到期提醒 / 维护公告 / 流量超限)

   • 模板支持 HTML 并带有变量, 常用变量如下:
     • {{.Type}}: 邮件类型 (1 注册, 2 重置密码), 可结合 {{if eq .Type 1}} 编写条件。
     • {{.SiteLogo}} / {{.SiteName}}: 站点 Logo 与名称。
     • {{.Expire}}: 验证码过期时间; {{.ExpireDate}}: 订阅到期日。
     • {{.Code}}: 验证码内容。
     • {{.MaintenanceDate}}、{{.MaintenanceTime}}: 维护公告专用。
   • 所有模板使用统一的所见即所得编辑器, 保存后立即作用于新发邮件。

手机(短信)认证

1. 登录策略

   • 启用短信登录: 控制手机号验证码入口。
   • 区号白名单: 打开后仅允许填写白名单区号, 列表通过输入框逐个添加, 例如 1, 852, 886。

2. 平台选择与动态字段

   • 下拉选择 SMS 平台后, 系统会自动展示该平台所需字段并提供"去申请"链接。
   • 常见字段: Access Key / Secret Key / Endpoint / Template Code / Sign Name / 专用手机号。
   • 如果平台支持自定义模板, 需要在文本框内填入包含 {{code}}(或供应商自定义变量)的正文。

3. 测试短信

   • 右下角可选择区号 + 填写手机号, 点击“测试短信”直接调用短信网关。
   • 发送失败通常与 AccessKey、签名或模板审核状态有关, 建议先在供应商控制台验证。

社交认证

每个社交方式都使用统一的抽屉式设置, 包含「启用开关」与所需凭证字段。所有凭证填写完成后点击“保存”即可立即在登录页展示相应按钮。

Apple Sign-In

• Team ID / Key ID: 来自 Apple Developer 账户。
• Service ID (Client ID): 在 Apple Developer -> Identifiers 中创建。
• Private Key: .p8 文件内容, 需要完整包含 BEGIN/END。
• Redirect URL: 登录完成后跳转回后台的 API 地址, 不要以 / 结尾。

Google Sign-In

• Client ID 与 Client Secret: 在 Google Cloud Console 的 OAuth 同意屏幕中创建, 类型选择 Web 应用。
• 需要在 Google 控制台中为 Redirect URI 配置管理员站点的 /api/auth/google/callback(示例)。

Facebook 登录

• App ID / App Secret: 来源于 Facebook Developer 平台。确保将站点域名加入“有效 OAuth 重定向 URI”。

GitHub 登录

• Client ID / Client Secret: 在 GitHub Developer Settings -> OAuth Apps 生成。
• 请将回调地址设为 https://your-domain.com/api/auth/github/callback 并允许 HTTPS 访问。

Telegram 登录

• Bot ID / Bot Token: 通过 @BotFather 获取, 记得开启“Login Widget”权限。
• Telegram 登录依赖机器人对话, 配置完成后即可在用户端调起官方授权弹窗。

设备认证

适用于需要在客户端或 Set-Top-Box 上做一次性配对登录的场景。

• 启用设备登录: 开关后终端可以通过设备码/二维码方式登录。
• 显示广告: 控制设备端是否展示广告位(用于商业化)。
• 阻止虚拟机: 启用后检测到虚拟机或模拟器将拒绝登录。
• 启用通信安全: 强制客户端每个请求都携带通信密钥。
• 通信密钥: 管理员可以手动粘贴或使用骰子按钮自动生成 32 位 GUID, 建议每个渠道独立密钥并妥善保管。

操作建议

• 切换邮件/SMS 服务商前先复制旧配置, 保存为版本记录。
• 每次修改完 SMTP 或模板都使用“发送测试邮件”验证, 避免正式用户收不到通知。
• SMS 平台字段因供应商不同而改变, 如果列表中没有需要的字段, 需要在供应商配置里通过自定义模板变量兼容。
• 对于 Apple/Google 等 OAuth, 建议先在沙箱或测试账号演练一遍授权流程, 确认 Redirect URI 正确。
• 通信密钥 属于敏感凭证, 只对接入客户端公开, 禁止写入前端代码仓库。

常见问题

邮件可以发送, 用户仍提示“验证码发送失败”？

• 检查是否开启邮箱后缀白名单, 与用户输入的邮箱域一致。
• 如果使用企业 SMTP, 需确认发件地址与 SMTP 账号一致, 否则服务商可能拦截。

短信发送失败

• 平台模板是否审核通过; 模板参数名是否与平台 {{code}}(或其别名)一致。
• 区号白名单是否包含目标国家/地区。
• 若仍失败, 打开浏览器调试台查看 API 返回的错误码, 对照短信服务商文档定位。

OAuth 登录跳回站点后出现 redirect_uri_mismatch

• Facebook/Google/GitHub 都要求将回调 URL 精确填写, 包括协议与尾部路径, 需与后台配置完全一致。

相关文档

• 系统配置: 设置站点名称、Logo、SMTP 基本参数等。
• 支付配置: 配置业务付费前, 建议先打通认证方式。
• 广告配置: 与设备认证中的“显示广告”配合使用。