基于 gog CLI 的无头服务器 Gmail OAuth 认证方案，支持手动授权流程、Token 续期及常见问题排查。
说明：
## 核心用法
gmail-oauth 是一个面向无头服务器环境的 Gmail API 认证配置方案，通过 `gog` CLI 工具实现 OAuth 2.0 授权流程。主要场景包括：初始 Gmail 集成设置、过期 Token 续期、以及无图形界面服务器上的认证故障排查。
### 使用流程
1. **Google Cloud 配置**：创建项目、启用 Gmail API、配置 OAuth 同意屏幕（需发布应用以获得永久 Token）、创建 Desktop 应用类型凭证
2. **本地配置**：安装 `gog` CLI，配置凭证路径，选择文件型密钥环以适配无头环境
3. **授权交互**：生成授权 URL → 用户在桌面浏览器完成授权 → 提取授权码 → 快速交换为访问 Token
4. **验证**：使用 `gog gmail search` 命令验证连接
### 关键设计
– 采用 `http://localhost` 重定向替代已废弃的 `urn:ietf:wg:oauth:2.0:oob`
– 文件型密钥环解决无系统密钥环的无头服务器限制
– 交互式脚本 `gmail-auth.sh` 降低操作复杂度
## 显著优点
– **无头友好**：专门针对 SSH 服务器、CI/CD 环境等无浏览器场景设计
– **故障覆盖全面**：文档涵盖 10+ 种常见错误场景，包括 Token 过期、重定向 URI 不匹配、测试模式限制等
– **权限粒度可控**：支持 `gmail.modify`/`readonly`/`send`/`compose` 四种作用域，最小权限原则
– **成本为零**：基于 Google 标准 OAuth，无第三方服务依赖
## 局限性与风险
– **手动步骤多**：无法全自动完成，需用户参与浏览器授权流程
– **授权码时效短**：生成后需数分钟内完成交换，操作窗口有限
– **Google 审核警告**：个人应用会显示”未经验证”警告，虽安全但体验不佳
– **测试模式陷阱**：未发布应用会导致 Token 7 天过期，文档虽已强调但易被忽略
– **单用户适用**：设计面向个人/小团队，大规模部署需额外工程
## 适合人群
– 需要在 VPS/云服务器上自动化 Gmail 操作的开发者
– 使用 `gog` CLI 或同类工具进行邮件管理的效率工具用户
– 熟悉命令行、具备基础 Google Cloud 操作经验的系统管理员
## 常规风险
| 风险项 | 等级 | 说明 |
|——–|——|——|
| 凭证泄露 | 中 | `client_secret.json` 与密钥环密码需妥善保管 |
| 权限过度授权 | 低 | 默认推荐 `gmail.modify`，但用户可自选更小权限 |
| 测试模式 Token 过期 | 中 | 未发布应用导致 Token 失效，影响自动化稳定性 |
| 钓鱼授权页 | 低 | 需确认 URL 为官方 Google 域名，防范中间人攻击 |
会员专属
