邮件与 OAuth2

这页讲什么

这页只讲两类和登录相关的内容：

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

OAuth2 provider 不再放在配置文件、环境变量或 Helm values 中定义，而是放在 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 是一个动态对象。每个 key 是一个 provider 实例名，例如 github、logto1、corp_oidc。实例名只能包含 ASCII 字母、数字、_ 和 -。

每个实例都使用同一个外层结构：

{
  "type": "github",
  "enable_signup": true,
  "signup_need_review": false,
  "config": {
    "client_id": "github-client-id",
    "client_secret": "github-client-secret",
    "redirect_url": "https://app.example.com/oauth2/callback"
  }
}

外层字段含义：

字段	作用
type	provider 类型。当前支持的值以服务端内置 provider registry 为准
enable_signup	是否允许这个 provider 的首次登录自动创建本地账号
signup_need_review	首次登录是否进入注册审核
config	provider 私有配置。外层不枚举，由对应 provider 自己解析

常见 provider 示例

GitHub

{
  "github": {
    "type": "github",
    "enable_signup": true,
    "signup_need_review": false,
    "config": {
      "client_id": "github-client-id",
      "client_secret": "github-client-secret",
      "redirect_url": "https://app.example.com/oauth2/callback"
    }
  }
}

OIDC

{
  "corp_oidc": {
    "type": "oidc",
    "enable_signup": false,
    "signup_need_review": false,
    "config": {
      "client_id": "synctv",
      "client_secret": "oidc-client-secret",
      "issuer": "https://idp.example.com",
      "redirect_url": "https://app.example.com/oauth2/callback"
    }
  }
}

运行时行为

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

常见问题

为什么不再有 oauth2.redirect_scheme

因为 redirect URL 现在直接写在每个 provider 的 config.redirect_url 里。这样不会把协议抽成全局状态，也不会限制不同 provider 之间的回调写法。

client_secret 应该放哪里

放在 config.client_secret，并通过 runtime settings 管理。不要放进静态配置文件。