邮件与 OAuth2

范围

登录相关配置分两类：

• 邮件登录的静态配置
• OAuth2 provider 的 runtime 配置

OAuth2 provider 放在 runtime settings 的 oauth2.providers 里。

邮件配置

邮件配置仍然属于静态配置，主要用于 SMTP 连接和发信身份。

email:
  smtp_host: "smtp.example.com"
  smtp_port: 587
  smtp_username: "synctv@example.com"
  smtp_password_file: "/run/secrets/smtp_password"
  from_email: "synctv@example.com"
  from_name: "SyncTV"
  use_tls: true

字段	默认值	作用
email.smtp_host	""	SMTP 服务器地址。为空表示不配置发信能力
email.smtp_port	587	SMTP 端口
email.smtp_username	""	SMTP 登录用户名
email.smtp_password	""	SMTP 登录密码，支持 smtp_password_file
email.from_email	""	发件邮箱。配置 SMTP 时必须是合法邮箱地址
email.from_name	SyncTV	发件人显示名
email.use_tls	true	是否使用 TLS 连接 SMTP

邮件验证码、密码重置、邮件 MFA 都依赖这组 SMTP 配置。独立邮箱登录只服务已有账号；请求验证码接口会返回统一文案，避免泄露邮箱是否已注册。邮件注册是否开放、是否需要审核属于 runtime settings，见 运行时设置。

OAuth2 runtime 配置

oauth2.providers 是 OAuth2ProviderSettings 数组。每个元素的 instanceName 是 provider 实例名，例如 github、logto1、corp_oidc。实例名只能包含 ASCII 字母、数字、_ 和 -。

每个实例使用共享字段加一个 provider oneof 字段：

{
  "instanceName": "github",
  "enableSignup": true,
  "signupNeedReview": false,
  "github": {
    "clientId": "github-client-id",
    "clientSecret": "github-client-secret",
    "redirectUrl": "https://app.example.com/oauth2/callback"
  }
}

字段含义：

字段	作用
instanceName	provider 实例名
enableSignup	是否允许这个 provider 的首次登录自动创建本地账号
signupNeedReview	首次登录是否进入注册审核
provider oneof 字段	例如 github、google、logto、oidc、casdoor。每个对象内写 provider 私有字段

常见 provider 示例

GitHub

[
  {
    "instanceName": "github",
    "enableSignup": true,
    "signupNeedReview": false,
    "github": {
      "clientId": "github-client-id",
      "clientSecret": "github-client-secret",
      "redirectUrl": "https://app.example.com/oauth2/callback"
    }
  }
]

OIDC

[
  {
    "instanceName": "corp_oidc",
    "enableSignup": false,
    "signupNeedReview": false,
    "oidc": {
      "clientId": "synctv",
      "clientSecret": "oidc-client-secret",
      "issuer": "https://idp.example.com",
      "redirectUrl": "https://app.example.com/oauth2/callback"
    }
  }
]

默认使用 issuer 进行 OIDC discovery。只有在 IdP 没有标准 discovery 文档时才手动配置 authUrl、tokenUrl 和 jwksUrl；userinfoUrl 可选，缺失时会使用已验证的 ID Token claims。

运行时行为

• 运行时 settings 修改后，OAuth2 服务会按新配置重建 provider map。
• 缺失某个实例名，就等于这个入口不可用。
• enableSignup=false 只影响首次 OAuth2 建号，不影响已绑定账号登录。
• signupNeedReview=true 会把首次 OAuth2 注册送入审核流程。

常见问题

Redirect URL

每个 provider 实例通过 redirectUrl 配置完整回调地址。不同 provider 可以使用各自的回调路径和协议。

clientSecret 应该放哪里

放在 clientSecret，并通过 runtime settings 管理。