RetroMail OAuth 部署参数配置说明

# RetroMail OAuth 部署参数配置说明 https://appstore.lazycat.cloud/#/shop/detail/org.omoifly.retromail 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](https://console.cloud.google.com/) 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](https://entra.microsoft.com/) 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 | ---