115 lines
6.4 KiB
Markdown
115 lines
6.4 KiB
Markdown
# 认证控制
|
|
|
|
>`系统 -> 认证控制` 聚焦“怎么让用户登录和校验身份”, 而不是角色/权限。这里可以集中配置邮箱、短信、社交账号以及设备认证等多种方式, 并内置测试工具确保配置可立即生效。
|
|
|
|
## 模块概览
|
|
|
|
- **通信方式**: 邮箱登录与短信登录, 支持验证码流程、白名单策略以及模板维护。
|
|
- **社交账号**: 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 精确填写, 包括协议与尾部路径, 需与后台配置完全一致。
|
|
|
|
## 相关文档
|
|
|
|
- [系统配置](/zh/admin/system/config): 设置站点名称、Logo、SMTP 基本参数等。
|
|
- [支付配置](/zh/admin/system/payment): 配置业务付费前, 建议先打通认证方式。
|
|
- [广告配置](/zh/admin/system/ads): 与设备认证中的“显示广告”配合使用。
|