概要

邮箱验证密码 邮件采集能力总结

邮箱类型	密码验证	邮件采集	说明
QQ/Foxmail	✅	✅	通过 IMAP 授权码
163/126/yeah	✅	✅	通过 IMAP 授权码
Gmail	✅	✅	通过应用专用密码（采集服务需要配置代理）
Yahoo	✅	✅	通过应用专用密码
新浪	✅	✅	通过 IMAP 授权码
Outlook/Hotmail/Live	❌	❌	微软禁用基本认证，需 OAuth 2.0

QQ邮箱

QQ邮箱IMAP授权码获取步骤：

1. 登录 mail.qq.com
2. 设置 → 账户 → POP3/IMAP/SMTP 服务
3. 开启"IMAP/SMTP服务"
4. 按提示发送短信生成16位授权码

Gmail

Gmail应用专用密码获取步骤：

1. 登录 myaccount.google.com
2. 安全性 → 开启"两步验证"（未开启需先开启）
3. 直接访问 myaccount.google.com/apppasswords
4. 输入应用名称如"IMAP客户端"，点击"创建"
5. 复制生成的16位应用专用密码
6. 将密码粘贴到此输入框

Outlook

Microsoft 从 2022 年 10 月起已弃用 Outlook.com/Hotmail/Live 邮箱的 IMAP 基本身份验证
技术实现：使用 OAuth 2.0 + Microsoft Graph API，让用户主动授权
前置条件：开始实现前需要在 Azure Portal 注册应用（内容较多，步骤放在后面）

1. 授权流程

用户点击"授权连接"
  → 后端生成授权 URL（含 PKCE code_challenge + login_hint）
  → 前端打开微软登录窗口
  → 用户登录并授权
  → 微软回调 /api/email/oauth/callback?code=xxx&state=xxx
  → 后端验证 state + 用 code+code_verifier+client_secret 换取 token
  → 加密存储 refresh_token → 更新 oauth_status=AUTHORIZED
  → 返回 HTML 页面，postMessage 通知父窗口

2. 关键配置

配置项	说明
email.outlook.oauth.client-id	Azure AD 应用 Client ID
email.outlook.oauth.client-secret	Azure AD 应用 Client Secret
email.outlook.oauth.tenant-id	consumers（个人账号）
email.outlook.oauth.scope	offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.Read
email.outlook.oauth.redirect-uri	各环境的回调地址

3. Token 管理

• access_token 缓存：Redis，key=outlook:token:{emailId}，TTL=50min
• refresh_token 存储：数据库 oauth_refresh_token 字段，AES-256-GCM 加密
• token 刷新：采集时缓存未命中则用 refresh_token 换取新 access_token
• token 轮换：微软可能在刷新时返回新的 refresh_token，需要更新数据库
• token 失效：返回 invalid_grant 时标记 oauth_status=EXPIRED

4. PKCE 支持

• code_verifier：43 字符 URL-safe 随机字符串
• code_challenge：BASE64URL(SHA256(code_verifier))
• 存储：Redis，与 state 一起存储，key=outlook:state:{state}，TTL=10min

5. 安全措施

• state 参数防 CSRF（一次性消费）
• login_hint 引导用户登录正确账号
• client_secret 通过环境变量注入
• refresh_token 加密存储

代理依赖

SOCKS 代理（IMAP 连接）

配置	说明
email.proxy.enabled	是否启用代理
email.proxy.host	代理地址（默认 127.0.0.1）
email.proxy.port	代理端口（默认 7890）

需要代理的场景：

• Gmail IMAP 连接（imap.gmail.com 被墙）
• 其他被墙的邮箱服务器

不需要代理的场景：

• QQ/163/126 等国内邮箱
• Microsoft OAuth Token Endpoint（login.microsoftonline.com 国内可直连）
• Microsoft Graph API（graph.microsoft.com 国内可直连）

Azure Portal 配置指南

1. 应用注册

1. 登录 Azure Portal
2. 进入 Microsoft Entra ID（原 Azure Active Directory）→ 应用注册 → 新注册
3. 填写：
   • 名称：项目名称即可，示例：email-verify
   • 支持的账户类型：任何组织目录中的账户和个人 Microsoft 账户（AzureADandPersonalMicrosoftAccount）
   • 重定向 URI：暂时留空（后续配置）
4. 点击"注册"，记录生成的 Application (client) ID

2. 配置身份验证（Authentication）

1. 左侧菜单 → Authentication (Preview)
2. 点击 “+ 添加重定向 URI” 或 “添加平台” → 选择 Web
3. 添加所有环境的重定向 URI（根据实际项目填写即可）：

http://localhost:XXXXXX/api/email/oauth/callback          （开发环境）
https://XXXXXX/api/email/oauth/callback  （测试环境）
https://XXXXXX/api/email/oauth/callback      （生产环境）

4. 不勾选"隐式授权和混合流"中的任何复选框（使用标准 Authorization Code Flow）
5. 点击"配置"保存
   

3. 配置客户端密码（Certificates & secrets）

1. 左侧菜单 → 证书和密码
2. 点击 “新客户端密码”
3. 填写描述：email-oauth，过期时间选 24 个月
4. 点击"添加"
5. 立即复制生成的密码值（只显示一次！）
6. 记录：
   • 值（Value）：即 client-secret，配置到 OUTLOOK_OAUTH_CLIENT_SECRET 环境变量
   • 机密 ID：仅用于标识，不需要配置到代码中
     

4. 配置 API 权限

1. 左侧菜单 → API 权限
2. 点击 “添加权限” → 选择 Microsoft Graph → 委托的权限
3. 搜索并勾选以下权限：
   • IMAP.AccessAsUser.All — 邮箱 IMAP 读写访问
   • Mail.ReadWrite — 邮件读写（Graph API 邮件采集使用）
   • offline_access — 获取 refresh_token
   • User.Read — 读取用户基本信息（默认已有）
4. 点击"添加权限"

注意：IMAP.AccessAsUser.All 和 Mail.ReadWrite 都添加，确保兼容性。实际采集使用 Mail.ReadWrite（Graph API）。

5. 配置支持的账户类型（Manifest）

1. 左侧菜单 → 清单（Manifest）
2. 确认以下字段值：

{
  "signInAudience": "AzureADandPersonalMicrosoftAccount",
  "isFallbackPublicClient": true
}

3. 如果 signInAudience 不是 AzureADandPersonalMicrosoftAccount，需要修改并保存
   

6. 当前应用信息

项目	值
应用名称	email-verify
Application (client) ID	xxxx-xxxx-xxxx-xxxx-xxxx`
Directory (tenant) ID	使用 consumers（个人账号）
Client Secret 描述	email-oauth
Client Secret 过期	2028/5/11

7. 新环境部署检查清单

部署到新环境时，需要完成以下步骤：

• 在 Azure Portal Authentication 中添加新环境的 redirect_uri
• 确认 redirect_uri 使用 HTTPS（生产环境必须）
• 确认 redirect_uri 路径与后端 context-path 一致
• 通过环境变量注入 OUTLOOK_OAUTH_CLIENT_ID
• 通过环境变量注入 OUTLOOK_OAUTH_CLIENT_SECRET（敏感信息）
• 通过环境变量注入 OUTLOOK_OAUTH_REDIRECT_URI
• 确认 Redis 可用（state 存储 + token 缓存）
• 确认数据库已执行迁移脚本（OAuth 字段）
• 确认网络能访问 login.microsoftonline.com 和 graph.microsoft.com

8. 常见问题

错误	原因	解决方案
invalid_request: redirect_uri is not valid	redirect_uri 未在 Azure Portal 注册	在 Authentication 中添加
AADSTS70002: must include client_secret	应用需要 client_secret	在"证书和密码"中生成并配置
AADSTS70011: invalid_scope	scope 格式错误或权限未添加	在 API 权限中添加对应权限
AADSTS9001023: grant type not supported	ROPC 不支持 /common endpoint	tenant-id 使用 consumers
unsupported_grant_type	个人账号不支持 ROPC	正常行为，引导用户使用 OAuth 授权
401 body 为空	Java HttpURLConnection streaming 问题	代码已使用原生 HttpsURLConnection 绕过