-
Notifications
You must be signed in to change notification settings - Fork 0
Feature Accounts zh
English · Tiếng Việt · 中文
从 0.1.0 起：多账户 IMAP，外加通过 OAuth 接入 Gmail 和 Outlook。这是 SkimMail 最基础的能力——在一个统一收件箱里读取来自不同服务商的多个邮箱——这 一页就是它的参考文档。
自托管者的邮件很少只在一个地方：一个私人 Gmail、一个工作用的 Outlook、几个 你自己运营的域名上的 IMAP 邮箱。SkimMail 独立连接每一个，如果你为某个账户指 定了自己的网络路径就走那条路径（见 Connections）， 并保留一份本地的、以阅读优先的邮件头缓存（也可以选择缓存正文——见邮件正文 缓存），这样统一收件箱才能快，而不需要每个服 务商都支持同一套协议扩展。
给不止一个人用？ 阅读 Security 里按用户分权那一节—— Sync now 按钮曾在 1.10.0 到 1.17.0 的每一个版本里，都能让 operator 对别人的账户动手，已在 1.18.0 修复。
Settings ▸ Accounts。 查看账户列表对每一个已登录用户开放（viewer 及 以上）；添加、编辑、同步、重新认证和测试连接是 operator 的操作；删除一个 账户仅限所有者。各角色具体意味着什么见用户与角色。
主机、端口、安全方式（tls / starttls / none）、用户名（留空则默认为邮
箱地址）和密码，外加两个可选的按账户覆盖项：一个出口（这个账户的流量走哪个
代理、VPN 或 relay——见 Connections）和一个以天为
单位的同步深度。
添加一个账户是一次真实的连接测试，而不只是保存一个表单。 在账户被写入数 据库之前，SkimMail 会真的拨号连接服务器并列出它的邮箱——如果你选了出口，就通 过那个出口——这样一个配置错误的代理会被立刻捕获，而不是之后表现为一次悄无声 息的同步失败。验证失败就完全拒绝保存这个账户。
不确定该选哪个？应用专用密码还是 OAuth？ 用通俗的语言比较了两者。本页是选定之后的操作步骤。
使用 OAuth 而非应用专用密码，有两个理由，其中只有一个属于偏好问题：
- Outlook.com 和 Hotmail 没有别的选择。 Microsoft 不再为个人账户签发应用专用 密码，并已永久关闭基本身份验证。对这些邮箱而言，OAuth 是唯一的入口。
- Gmail 有别的选择，而且更简单。 应用专用密码只需两次点击，不需要 Cloud 项目。当 Workspace 管理员禁用了应用专用密码，或者你不愿保存一个能打开整个 Google 账户的密码时，OAuth 才值得这番配置。
SkimMail 不附带任何共用的 OAuth 客户端，这是有意为之，而不是没做完。
https://mail.google.com/ 是受限范围：Google 只授予通过独立安全评估
（CASA Tier 2）的应用，且每年需重新评估。符合条件的应用与其所有者绑定；而放在
开源仓库里的 client secret 一旦被吊销，所有安装会在同一刻全部失效。Thunderbird
自带经过验证的客户端，并在同一个源文件中写道："Don't copy these values for your
own application — register one for yourself!" Roundcube 与 Nextcloud Mail 采用
的也是与 SkimMail 相同的自带客户端模式。
所以：注册一个应用——具体在 Google 和 Microsoft 控制台上怎么做，见
Register the OAuth application——然后
把 client id 与 secret 填入 Settings ▸ About ▸ Setup health ▸ OAuth。环
境变量
（GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET、
MICROSOFT_CLIENT_ID/MICROSOFT_CLIENT_SECRET）依然有效，并且优先于数据库
中保存的值，此时输入框显示为锁定并标出需要移除的变量名。任一值缺失时，该提供商
的按钮会被拒绝（oauth_not_configured），而不是显示出来却用不了。
SkimMail 请求的范围：
| 提供商 | 范围 |
|---|---|
https://mail.google.com/、userinfo.email、openid
|
|
| Microsoft |
https://outlook.office.com/IMAP.AccessAsUser.All、offline_access、openid、email、profile
|
Microsoft 于 2026-09-18 第一次被接通——时间很近，而且并不完整。 一个个人 Outlook 账户走完了端到端流程：登录成功，列出 13 个文件夹，邮件同步正常。在那 一天之前，本项目没有人亲眼看过其中任何一环跑起来。它的第一次续期现在也被亲 眼看过了，而且干净地通过了——这一点最值得说，因为 Microsoft 每次续期都会替换 已保存的登录凭据，那里出错是永久断连，而不是断一个小时。尚未被看到的是： Microsoft 365 的工作或学校账户是否表现一致——那是另一种注册，其管理员可以 直接屏蔽此应用——以及最初几个小时之后的任何情况。Gmail 已于 2026-09-17 验证， 并且已经经历过一次续期。如果你连接了 Microsoft 邮箱——无论成功与否—— 请反馈结果；这几句话只有靠这种方式才会变短。
两者都是各自厂商为 IMAP 所记载的范围。SkimMail 的同步引擎讲 IMAP，因此授予 REST
API 的范围——Gmail 的 gmail.modify，或 Microsoft Graph 的 Mail.ReadWrite——
不会被邮件服务器接受，无论令牌看上去多么有效。不要在 Outlook 范围旁边再加
Microsoft Graph 范围：一个访问令牌只携带一个受众，混用要么直接失败，要么更糟——
悄悄签发一个只对先写出的那个资源有效的令牌。
请在同一个应用上注册下面两个重定向 URI。每个在提供商控制台里只占一行，而
Setup health ▸ OAuth 页面会把两个都显示出来并附复制按钮——手工输入是
redirect_uri_mismatch 最常见的原因。
| 重定向 URI | 用途 |
|---|---|
<BASE_URL>/api/oauth/callback |
常规方式。提供商把浏览器直接送回 SkimMail，需要公网 HTTPS 地址。 |
http://localhost:8642 |
手工方式。那里没有任何服务在监听。 |
常规方式是多数部署所用：点击 Continue with Google，授权，然后回到
SkimMail。它要求 BASE_URL 指向提供商能访问到的地址。
手工方式是为其余所有情况而生的——家庭或办公网络里的一台机器，没有公网地址、 没有域名、没有 TLS。点击 No public address? Connect by pasting the sign-in result instead，SkimMail 会把登录 URL 显示出来，旁边配一个 Copy 按钮。
复制它，然后用已经登录该账号的那个浏览器打开——这正是这里直接给出 URL 而不是 只给一个链接的原因。无头服务器通常是从另一台机器上管理的，而登录着 Google 或 Microsoft 的那个会话，往往在笔记本或手机上，并不在跑 SkimMail 的那台机器上。请 粘贴到那边。（如果你正在阅读本文的浏览器就是对的那一个，URL 旁边"或者就在这里 用新标签页打开"的链接可以省掉一趟。）
授权之后，那个浏览器会跳转到 http://localhost:8642/?code=…&state=… 并加载失败。
这个失败是设计，不是故障：那个端口上本就没有服务。把地址栏中的完整地址复制回
SkimMail，它会自行读出授权码并完成交换。
你粘贴的那一行由两把互相独立的锁保护，值得分清哪把是哪把。你的 client secret——没有它，提供商不会用那个授权码换取令牌，而它从不离开你的服务器。 PKCE——一个由你的服务器自己保管、并由提供商核对的一次性值。单是 client secret 就已经让被复制的那一行对看到它的人毫无用处；PKCE 则保证即使某个提供商 对 PKCE 处理得马虎，这一点依然成立。本次登录十五分钟后过期；超时请重新开始。
七天陷阱。 Google 同意页面若停留在 Testing 发布状态，对 name、email、 profile 之外的任何范围——其中就包括邮件范围——所签发的 refresh token 会被 Google 在七天后吊销。届时账户停止同步，需要每周重新连接一次。把应用切换到 In production 即可终止这种情况。代价是同意页面上的"应用未经验证"警告，以及 100 个用户的上限——对自托管实例来说两者都可以接受。
"未经验证"的警告是正常的。 https://mail.google.com/ 属于受限范围，在应用
通过验证之前，同意页面就会给出该警告。这是预期之内的，并不表示配置有误。不要
通过改用更窄的范围来"修复"它——更窄的范围正是让 IMAP 完全无法工作的原因。
隧道可以为局域网实例提供一个真正的公网 HTTPS 地址，从而把它变成常规情况：
Cloudflare Tunnel 与 Tailscale Funnel 都能做到且无需开放端口。随后把 BASE_URL
设为它给出的地址，使用常规方式即可。仅就 Gmail 而言，应用专用密码仍是最短路径，
并且可以规避以上全部内容。
每个字段都是独立打补丁的——请求里没有出现的字段会保持不变，绝不会被重置为默 认值。创建之后可以修改的内容：显示名称、所属的 group（见 Account groups）、重新指定出口、bind address、同步深度，以及暂 停/恢复该账户自己的同步（这也会同时清除自动停止状态，效果和一次成功的重新认 证一样）。
IMAP 账户有一个 Re-authenticate 操作，接受一个新密码，用和添加账户时 一样的方式重新验证，并且——如果这个账户的同步曾因反复失败而被自动停止（见 同步与同步健康）——立刻恢复同步。
OAuth 账户有同一个按钮，而且它做的是对的事。 对 Gmail 或 Outlook 账户， 「重新认证」会把你带回服务商的授权同意界面，而不是要你输入密码。回来之后就会 拿到新的 token，并且更新你已有的那个账户——它按服务商和邮箱地址匹配，所以 不会多出一个重复账户。
不要为了修复一个过期 token 去删除账户。 删掉会连同它的设置、已指派的出口 和已缓存的邮件一起丢掉，却换不来任何好处；上面那个按钮就是全部的修复方法。
OAuth 账户的详情面板会显示其访问令牌何时过期，旁边还有一个刷新按钮。访问 令牌大约一小时有效，并会在下一次连接时自动续期，因此时钟显示已过期是很平常的 事，它以普通文字呈现，而不是警告。刷新按钮是为了你想立刻看到时钟变化时使用—— 或者更有用的是，不必等到一次同步失败，就能知道授权是否还有效。
只有一个信号意味着需要采取行动：账户上红色的需要重新连接徽章。它只在身份 验证本身失败时出现——授权被吊销、过期，或被轮换掉——此时只有重新连接才能修复，重试 没有用。SkimMail 在第一次登录失败时就亮起它，而不是等到重试次数用尽，这样警告 到达时邮箱还在工作，而不是在它已经停止之后。
如果启用了 oauth_expiring 告警通道（见通知），同一
事件也会送到那里。
每个账户都有自己的 sync_depth_days，它一开始的数值来自实例默认值——
Settings ▸ Sync ▸ Default sync depth（如果那里没有设置，就退回到
SYNC_DEPTH_DAYS 环境变量；如果两者都没设置，就是 30 天）。在 Add Account
表单里输入一个数字，会为那个账户覆盖这个值，因为最具体的答案总是胜出。
在 1.17.0 之前，这个默认值被忽略了。 创建账户的代码把 30 天写死，所以一 个选择了 90 天——或者全部历史——的运维者，得到的账户依旧同步 30 天，日志里 什么都没有，Settings 界面还继续显示他们选过的那个数字。如果你在旧版本上设置 过那个字段，却想不通为什么什么都没变，原因就在这里。
修改默认值不会移动你已有的账户。 它只适用于修改之后新创建的账户。已有的 邮箱会在自己那一行上保留原来的数字，这是有意为之：为某个账户选定的窗口，不 应该因为实例默认值之后又变了就被改写。要改一个已有账户，编辑那个账户本身。
仅限所有者，而且它做的不只是删掉那一行：这个账户缓存的邮件正文会在同一 个事务里被标记为待清理（见邮件正文缓存）， 这样一个已删除的邮箱就不会永远继续计入你的存储用量。这只会删除 SkimMail 本 地的副本——邮件本身在服务商那边完好无损，重新添加同一个账户会从 IMAP 重新同 步一切，邮件头和所有内容，从头开始。
账户显示的顺序（统一列表和按账户查看都算）是一个保存下来的 sort_order，通
过拖放修改，用一次调用持久化——这纯粹是一个显示偏好，不影响同步或出口。
| 起始版本 | 0.1.0（IMAP），OAuth 在同一个发布周期加入 |
| 角色 | viewer 可查看列表；operator 可添加/编辑/同步/重新认证/测试；owner 可删除 |
| 层级限制 | Community 10 · Sponsor 25 · Pro 无限制——见 Plan and license |
| 计数方式 | 按实例，不按用户 |
| 支持的服务商 | 任意 IMAP 服务器；Gmail 和 Outlook 通过运维者自己的 OAuth 应用 |
- 不提供任何共享/默认的 OAuth 应用。 Gmail 和 Outlook 的连接按钮会一直 停用，直到运维者自己向服务商注册应用为止——这是一个真实存在的配置步骤，不 是缺失的功能。
- 添加账户时的验证只检查可达性，不检查投递能力。 SkimMail 拨号连接服务 器并列出邮箱；它从不发送一封测试邮件，因为 SkimMail 是一个阅读优先的产 品。
- 删除一个账户绝不会触碰服务商那边的邮件。 它只删除 SkimMail 本地缓存的 东西。
- 修改同步深度不会追溯性地找回一个更窄的窗口已经跳过的内容——它只会改变 从现在起下一次同步所使用的窗口。
- Account groups —— 组织账户，以及一个 group 能下发给 其成员的设置
- Connections —— 按账户的出口（代理、WireGuard、 relay），以及当已分配的出口被禁用或删除时会发生什么
- 同步与同步健康 —— 自动停止、状态面板，以及新账 户据以起步的「Default sync depth」
- Plan and license —— Community/Sponsor/Pro 的账户数 量限制
-
配置 —— OAuth 客户端相关的环境变量和
BASE_URL - Register the OAuth application —— 在 Google 和 Microsoft 控制台上的具体步骤
- 用户与角色 —— viewer/operator/owner 在这里各自能做 什么
SkimMail · skimmail@base101.app · 2026-09-18 · commit f525934