配置 SMTP 邮件与 SAML SSO
为自托管 OpenTickly 配置 SMTP 发信、邮箱验证、邀请、密码重置，以及工作区级 SAML 2.0 单点登录。
自托管 OpenTickly 的 SMTP 是实例级配置，SAML 2.0 单点登录是工作区级配置。请先设置公网 Site URL，因为邮件链接和 SAML 服务提供方地址都依赖它。
配置公网 Site URL
使用实例管理员账号打开 实例管理 → 配置，把 Site URL 设置为用户实际访问的 HTTPS 地址，例如 https://time.example.com。
不要填写容器内部主机名，也不要附加 API 路径。公网域名变更后，需要重新核对邮件链接以及提供给身份提供商的 SAML 地址。
配置 SMTP 发信
在 实例管理 → 配置 → 邮件 / SMTP 填写：
| 字段 | 含义 |
|---|---|
| 发件人名称 | 邮件中展示的名称 |
| 发件人邮箱 | 邮件服务商允许使用的 From 地址 |
| SMTP 主机 | 邮件服务器主机名 |
| SMTP 端口 | 通常 587 使用 STARTTLS，465 使用隐式 TLS |
| SMTP 用户名 | SMTP 登录账号 |
| SMTP 密码 | 密码或服务商生成的应用专用密码 |
OpenTickly 在 465 端口使用隐式 TLS；其他端口会在服务器支持时升级到 STARTTLS。
保存后，在 发送测试邮件 中填写收件地址并执行测试。测试结果会区分连接失败、认证失败、收件人被拒绝和超时，便于检查服务商配置或防火墙。
成员邀请、密码重置和邮箱验证都依赖 SMTP。确认测试邮件到达后，如果要求新注册用户验证邮箱，再启用 邮箱验证。
不要把 SMTP 凭据放进截图、Issue、代码仓库或共享 Shell 历史。凭据一旦泄露，应立即轮换。
配置工作区 SAML SSO
使用工作区管理员账号打开 工作区设置 → 单点登录。
- 填写配置名称和应路由到该工作区的邮箱域名。
- 把页面生成的 Entity ID、ACS URL、登录 URL 和 Metadata URL 填入身份提供商的新 SAML 应用。
- 优先填写身份提供商的 Metadata URL；如果没有，再手动填写 IdP 登录 URL、Entity ID 和 X.509 签名证书。
- 启用前先运行 测试配置。
- 使用该域名的用户运行 测试登录，核对返回的邮箱、姓名、域名匹配和断言属性。
- 保存配置，然后启用单点登录。
公网 SSO 登录页面使用邮箱域名决定路由到哪个工作区。一个已启用的域名只能属于一个工作区。SAML 断言必须通过常见邮箱属性或邮箱格式的 NameID 返回用户邮箱。
安全上线检查
- 测试期间保留一个已登录的密码管理员会话。
- 先用非关键用户测试，再让整个域名使用 SSO。
- 确认 IdP 使用页面生成的完整 Entity ID 和 ACS URL。
- 确认用户和身份提供商都能通过 HTTPS 访问实例。
- 修改 Site URL、反向代理、证书或 IdP Metadata 后重新测试。
- 至少另一名管理员成功通过 SSO 前，不要关闭备用登录方式。
部署和反向代理背景见自托管，脚本与 Token 配置见 Toggl API 兼容接入。