配置 SMTP 邮件与 SAML SSO
给自托管的 OpenTickly 配置发邮件（邀请、重置密码、邮箱验证）和 SAML 单点登录。
发邮件（SMTP）整个实例只配一次；单点登录（SAML 2.0）每个工作区单独配。先设置 Site URL，因为邮件里的链接和 SSO 用到的地址都是根据它生成的。
设置 Site URL
用实例管理员账号打开 实例管理 → 配置，把 Site URL 填成用户在浏览器里访问的地址，例如 https://time.example.com。
不要填 Docker 内部的主机名，也不要在后面加 /api 之类的路径。以后换了域名，要检查邮件链接是否正常，并在身份提供商那边更新 SSO 配置。
配置 SMTP 发信
在 实例管理 → 配置 → 邮件 / SMTP 填写：
| 字段 | 含义 |
|---|---|
| 发件人名称 | 邮件中展示的名称 |
| 发件人邮箱 | 邮件服务商允许你用来发信的地址 |
| SMTP 主机 | 邮件服务器主机名 |
| SMTP 端口 | 通常 587 使用 STARTTLS，465 使用隐式 TLS |
| SMTP 用户名 | SMTP 登录账号 |
| SMTP 密码 | 密码或服务商生成的应用专用密码 |
465 端口一开始就走 TLS；其他端口如果服务器支持，会自动切到 STARTTLS。
保存后，在 发送测试邮件 里填个收件地址发一封试试。失败的话会告诉你是连不上、账号密码错、收件人被拒还是超时，方便你判断该查服务商设置还是防火墙。
邀请成员、重置密码、邮箱验证都要用到 SMTP。测试邮件收到后，如果希望新用户注册时验证邮箱，就打开 邮箱验证。
别让 SMTP 密码出现在截图、Issue、git 仓库或共享的 Shell 历史里。万一泄露了，马上改掉。
配置工作区 SAML SSO
身份提供商（IdP）就是你们团队平时统一登录用的服务，比如 Okta、Microsoft Entra ID、Google Workspace、Keycloak。
用工作区管理员账号打开 工作区设置 → 单点登录。
- 填一个配置名称，以及公司的邮箱域名（例如
example.com）。 - 在 IdP 里新建一个 SAML 应用，把 OpenTickly 页面上显示的 Entity ID、ACS URL、登录 URL 和 Metadata URL 填进去。
- 回到 OpenTickly，填上 IdP 的 Metadata URL。如果 IdP 没提供，就手动填它的登录 URL、Entity ID 和 X.509 签名证书。
- 打开 SSO 之前，先点 测试配置。
- 点 测试登录，用这个邮箱域名下的账号登录一次，看看返回的邮箱、姓名等信息对不对。
- 保存，然后打开单点登录。
用户在登录页点 SSO 时，OpenTickly 会根据邮箱域名判断该进哪个工作区，所以一个域名只能给一个工作区用。IdP 必须把用户邮箱传过来，可以放在邮箱属性里，也可以直接作为 NameID。
给所有人打开之前
避免把自己锁在外面：
- 测试时，另开一个标签页保持用密码登录的管理员账号。
- 先拿一个测试账号试，别一上来就让全公司用。
- 确认 IdP 里填的 Entity ID 和 ACS URL 和 OpenTickly 显示的一字不差。
- 确认用户和 IdP 都能通过 HTTPS 访问到 OpenTickly。
- 改了 Site URL、反向代理、证书或 IdP 配置之后，再测一遍。
- 至少有另一位管理员用 SSO 登录成功之前，别关掉密码登录。
部署和反向代理见自托管，API Token 和脚本见 Toggl API 兼容接入。