你是否也有这样的困扰：收件箱里塞满了促销邮件、订阅资讯和“欢迎回来”的自动通知？手动退订太费时，用网页插件又担心隐私泄露？
现在，有一个完全在你本地运行、不收集任何数据的开源工具，可以帮你一键批量退订、按发件人删除垃圾邮件，甚至将成千上万封未读邮件快速标记为已读——所有操作都在你的电脑上完成，邮件内容从不离开你的设备。
它叫 Gmail Bulk Unsubscribe & Cleanup Tool，目前完全免费、开源，支持 Windows、macOS（包括 Apple Silicon）和 Linux。
核心功能一览
| 功能 | 说明 |
|---|---|
| 批量退订 | 自动扫描邮件中的退订链接，一键发起退订请求（需手动确认） |
| 按发件人删除 | 查看发件频率最高的联系人，支持批量删除其全部邮件 |
| 批量标记已读 | 一次性将数千封未读邮件设为已读，快速清理视觉干扰 |
| 智能过滤 | 可按邮件天数、大小、分类（促销/社交/更新）筛选目标邮件 |
| 100% 本地运行 | 所有逻辑在你电脑执行，无远程服务器，无数据上传 |
| 高效处理 | 利用 Gmail API 批量操作，每次最多处理 100 封邮件 |
| 熟悉界面 | 采用类似 Gmail 的简洁 UI，上手几乎无学习成本 |
支持平台
无论你用的是 Windows、macOS（Intel 或 M 系列芯片），还是 Linux，都可以运行。提供两种部署方式：
| 平台 | Docker 支持 | 本地 Python 支持 |
|---|---|---|
| Windows (x86_64) | ✅ | ✅ |
| macOS Intel | ✅ | ✅ |
| macOS Apple Silicon (M1/M2/M3/M4) | ✅ | ✅ |
| Linux (x86_64) | ✅ | ✅ |
为什么必须自己创建 Google 凭证？
这是该工具保障隐私的关键设计：
它不内置任何 OAuth 密钥，也不依赖第三方服务器。每位用户需用自己的 Google Cloud 项目创建专属凭证，确保：
- 只有你授权的账号能访问你的邮箱；
- 工具仅请求必要权限（读取 + 修改邮件状态）；
credentials.json和token.json始终保存在本地，永不外传。
虽然多花几分钟配置，但换来的是真正的数据自主权。
快速上手指南
第一步：获取 Google OAuth 凭证
- 进入 Google Cloud Console
- 创建新项目（或选择现有项目）
- 启用 Gmail API
- 配置 OAuth 同意屏幕：
- 应用名称：如 “Gmail Cleanup”
- 用户类型：选 External
- 填写你的邮箱作为联系人
- 在“测试用户”中添加你的 Gmail 地址
- 在“凭据”页面创建新凭据：
- 如果用 本地 Python 运行 → 选“桌面应用”
- 如果用 Docker 或远程部署 → 选“Web 应用”，并填写回调地址（如
http://localhost:8767/）
- 下载 JSON 文件，重命名为
credentials.json
注意：首次使用会看到“Google 未验证此应用”的警告——这是正常现象，因为这是你自己的私有应用。点击“继续”即可。
第二步：部署工具
git clone https://github.com/Gururagavendra/gmail-cleaner.git
cd gmail-cleaner
# 将 credentials.json 放入此目录
方式一：Docker（推荐）
docker compose up -d
访问 http://localhost:8766，点击“Sign In”。
首次登录需从容器日志中复制 OAuth 链接：
docker logs $(docker ps -q --filter ancestor=ghcr.io/gururagavendra/gmail-cleaner)
方式二：本地 Python（需安装 uv）
uv sync
uv run python main.py
同样访问 http://localhost:8766 使用。
安全与隐私保障
- 零数据上传：邮件内容、发件人列表、操作记录均不离开本地；
- 开源可审计：代码托管于 GitHub，任何人都可审查；
- 最小权限原则：仅申请
gmail.readonly和gmail.modify权限； - 凭证自持：你的
credentials.json和token.json永不提交或共享。
常见问题解答
Q：能用于多个 Gmail 账号吗？
A：可以。先点击“Sign Out”，再登录其他账号。但每个账号都需提前添加为 Google 项目的“测试用户”。
Q：误删邮件能恢复吗？
A：可以。删除操作只是将邮件移入“垃圾邮件”文件夹，30 天内可手动恢复。
Q：遇到“访问被阻止”错误怎么办？
A：请检查是否在 OAuth 同意屏幕的“测试用户”中添加了当前 Gmail 地址。
Q：Docker 启动后拿不到授权链接？
A：务必先点击网页上的“Sign In”，再运行 docker logs 查看日志输出。
高级用法：远程部署或自定义域名
如需在服务器或公网使用，请：
- 创建 Web 应用类型 的 OAuth 凭证；
- 在
docker-compose.yml中添加环境变量：environment: - WEB_AUTH=true - OAUTH_HOST=your.domain.com # 仅写域名，不含协议 - 确保反向代理同时开放 8766（前端）和 8767（OAuth 回调）端口。
评论