RetroMail OAuth 部署参数配置说明

RetroMail 是一个复古风格的邮件客户端，支持 Gmail, Hotmail, Outlook, QQ, IMAP/SMTP, Microsoft Exchange Server 多个 Provider.

此外，本客户端充分利用懒猫客户端的通知功能，可以做到不输各官方邮件客户端的收信速度。

本教程专为懒猫微服用户编写，手把手教你创建 Gmail 和 Microsoft 的 OAuth 凭据，填入懒猫安装参数，让 RetroMail 能够连接你的邮箱。
逻辑都是一样的，申请个人使用的邮箱API, 申请密钥，然后配置回调以支持懒猫无缝服务。

预计耗时：15-20 分钟。

---

概览

下面两个是独立的，按需选择（也可以都配）：

• 要用 Gmail → 去 Google 创建 OAuth 凭据
• 要用 Outlook/Hotmail → 去 Microsoft 创建 OAuth 凭据

拿到凭据后回到懒猫填入参数、连接邮箱。

📌 先记下你的回调地址（后面在 Google 和 Microsoft 控制台都要用到）：

用途	回调地址
Gmail	https://retro-mail.<你的微服名>.heiyu.space/api/v1/oauth/gmail/callback
Microsoft	https://retro-mail.<你的微服名>.heiyu.space/api/v1/oauth/microsoft/callback

⚠️ 地址必须完全一致，包括 https、域名、路径、大小写和结尾斜杠。

---

配置 Gmail（要用 Gmail 才做）

1.1 创建项目并启用 Gmail API

1. 打开 Google Cloud Console
2. 登录你的 Google 账号
3. 点击顶部项目选择器 → 新建项目

4. 项目名称填写 RetroMail 或者任意你想要的名称，点击 创建
5. 等待创建完成，确认顶部已选中 RetroMail 项目
6. 左侧菜单 → APIs & Services / API和服务 → Library / 库

7. 搜索 Gmail API，点击进入后点击 Enable / 启用
   
   

1.2 配置 OAuth 同意屏幕

1. 左侧菜单 → APIs & Services / API和服务 → OAuth consent screen / OAuth权限请求页面
   

2. 点击 Get started / 开始 App Information(应用名称) 看着填就行，注意 Audience/受众群体 需要选择 External/外部，剩下的可以看着填

3. Branding（品牌塑造）页面填写都是默认，注意 Authorized domains/已获授权的网域 需要配置一下：

   字段	填写内容
   App name	RetroMail
   User support email	选择你的 Google 邮箱
   Developer contact email	同上

4. 点击 Save / 保存

5. Audience / 目标对象 这里有两种选择

• 如果是 Testing/测试版 模式，需要在下面的 Test users / 测试用户 中加入你想要登陆的 gmail 邮箱，且这样的话，每七天会要求你重新授权
  
  

• 如果你选择 publish app, 此时不输入邮箱，也不需要每七天重新授权，但是登陆时会有安全提示（可以忽略），笔者推荐使用这种模式

6. Data Access（数据访问）页面 —— 这是关键步骤：
   • 点击 Add or Remove Scopes / 添加或移除范围
   • 搜索框输入 gmail.modify
   • 勾选出现的 https://www.googleapis.com/auth/gmail.modify
   • 点击 Update/更新 → Save and Continue 注意最下面还要 save 一下

注意下面这里还要保存一次

1.3 创建 OAuth Client

1. 左侧菜单 → APIs & Services/API和服务 → Credentials/凭证
2. 点击 + Create Credentials / 创建凭证 → OAuth client ID / OAuth客户端ID

3. 填写：

   字段	填写内容
   Application type(应用类型)	Web application / Web应用
   Name(名称)	RetroMail Web
   Authorized redirect URIs (已获授权的重定向 URI)	https://retro-mail.<你的微服名>.heiyu.space/api/v1/oauth/gmail/callback

   点击 + Add URI 添加回调地址。如有多余的 https://localhost:8080
   占位符，可以删除。

4. 点击 Create/创建

5. 弹出窗口显示 Client ID/客户端 ID 和 Client Secret/客户端密钥：

   • 立即复制保存这两个值
   • 关闭弹窗后就看不到 Client Secret 了

⚠️ 把这两个值粘贴到记事本或密码管理器中。不要截图分享。

✅ Gmail OAuth 凭据完成！ 记好你的：

• Google Client ID
• Google Client Secret

---

配置 Microsoft（要用 Outlook/Hotmail 才做）

2.1 注册应用

1. 打开 Microsoft Entra admin center

2. 登录你的 Microsoft 账号

   不需要 Azure 订阅，免费注册的 Microsoft 账号即可操作。

3. 左侧菜单 → Identity → Applications → App registrations

4. 点击 + New registration

5. 填写：

   字段	填写内容
   Name	RetroMail
   Supported account types	Accounts in any organizational directory and personal Microsoft accounts
   Redirect URI	留空，稍后单独配置

如果你的界面是中文的，参考如下截图

6. 点击 Register

7. 注册完成后，复制 Application (client) ID(中文是應用程式 (用戶端) 識別碼) 备用

⚠️ 复制的是 **Application (client) ID **，不是 Object ID。

2.2 配置 Web 回调地址

1. 左侧菜单 → Manage → Authentication
2. 点击 + Add a platform → Web
3. 在 Redirect URIs 中输入你的 Microsoft 回调地址（见上方概览）
4. 点击 Configure

不需要勾选页面下方的 Implicit grant 或 Hybrid flow 开关。

2.3 创建 Client Secret

1. 左侧菜单 → Manage → Certificates & secrets
2. 在 Client secrets 标签页，点击 + New client secret

📸 截图：新建 client secret 按钮

3. 填写描述 RetroMail，有效期选择 12 months

4. 点击 Add
   

5. 立即复制 Value 列显示的值

⚠️ 离开此页面后再也看不到这个值。复制的是 Value / 值（类似 abc123~xyz...），
不是 Secret ID / 祕密識別碼。

2.4 添加 API 权限

1. 左侧菜单 → Manage → API permissions
2. 点击 + Add a permission → Microsoft Graph → Delegated permissions/委派的權限

📸 截图：选择 Delegated permissions

3. 在搜索框中依次搜索并勾选以下四项：

   offline_access
   User.Read
   Mail.ReadWrite
   Mail.Send
   

   搜索一项 → 勾选 → 搜下一项，不要一次性全打进去。

4. 点击 Add permissions 确认最终会有这些权限

✅ Microsoft OAuth 凭据完成！ 记好你的：

• Microsoft Application (client) ID
• Microsoft Client Secret Value

---

填入懒猫并验证

3.1 填入安装参数

回到懒猫微服，在 RetroMail 的安装或重新配置页面找到以下参数：

参数	填入内容
Gmail OAuth Client ID	从 Google 复制的 Client ID
Gmail OAuth Client Secret	从 Google 复制的 Client Secret
Microsoft OAuth Client ID	从 Microsoft 复制的 Application (client) ID
Microsoft OAuth Client Secret	从 Microsoft 复制的 Client Secret Value
Microsoft Tenant	填入 consumers

两项 Gmail 参数必须同时填写才会启用 Gmail 连接；三项 Microsoft 参数同理。
如果你只需要其中一种邮箱，另一个留空即可。

Microsoft Tenant 怎么填？

你想连接什么账号	Tenant 填什么
个人 Outlook/Hotmail/Live	consumers
组织账号 + 个人账号	common
仅限某个组织	该组织的 Tenant ID 或域名

完成后点击保存，等待 RetroMail 重启。

3.2 连接邮箱

1. 打开 RetroMail，进入 设置 → 邮箱账户
2. 点击 连接 Gmail 或 连接 Microsoft
3. 浏览器会跳转到 Google 或 Microsoft 的官方登录页 —— 选择你要连接的邮箱账号
4. 在权限确认页点击 允许 / Accept

注意，如果是 Google 配置在 production 模式，登陆后会提示"Google hasn’t verified this app" 此时需要选择无视风险继续访问 ：）

如果是微软邮箱，应该只会提示应用未验证，道理都是一样的

5. 自动回到 RetroMail，系统开始建立同步基线
6. 进入 设置 → 运行诊断，确认账户状态和同步进度

连接多个邮箱：重复 3.2 步即可 —— 在设置页再次点击连接，选择不同账号授权。
不需要创建新的 OAuth 凭据。

---

遇到问题？

错误	常见原因	解决办法
redirect_uri_mismatch	回调地址不完全一致	逐字核对 https、域名、路径、斜杠
Gmail 7 天后要重新登录	项目处于 Testing 状态	在 Google Auth platform 发布为 Production
微软提示需管理员批准	组织租户策略限制	联系管理员批准那四项权限
Client Secret 无效	复制了 Secret ID 而非 Value	回到控制台创建新 Secret，重新复制 Value

---