Skip to content

boloboloda/Gmail_Retrieval_And_Subject_Forwarding_System

BranchesTags

Repository files navigation

Gmail 邮件转发系统

🚀 基于 Gmail API 的智能邮件转发系统，支持关键词规则自动路由

License: MIT Go Version Gmail API

📖 项目简介

Gmail 邮件转发系统是一个智能化的邮件处理工具，通过 Gmail API 自动检索未读邮件，基于预设的关键词规则将邮件转发到指定的目标地址。系统采用 Go 语言开发，具备高性能、高可靠性的特点。

✨ 主要特性

  • 📧 Gmail API 集成 - 完整的 Gmail OAuth2 认证和邮件操作
  • 🎯 智能关键词路由 - 基于邮件主题的关键词匹配和转发规则
  • 🔄 自动化处理 - 定时任务自动检索和处理未读邮件
  • 🛡️ 安全可靠 - 完整的错误处理、事务管理和日志记录
  • 📊 完整审计 - 详细的转发日志和操作记录
  • ⚡ 高性能 - Redis 缓存 + MySQL 数据库 + 异步任务队列
  • 🐳 容器化支持 - Docker 和 Docker Compose 一键部署
  • 📈 可观测性 - OpenTelemetry 分布式链路追踪

🏗️ 系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Gmail API     │    │   Application   │    │   Storage       │
│                 │    │                 │    │                 │
│ • OAuth2 Auth   │◄──►│ • Email Proc.   │◄──►│ • MySQL DB      │
│ • Email Fetch   │    │ • Rule Engine   │    │ • Redis Cache   │
│ • Email Forward │    │ • Task Queue    │    │ • Audit Logs    │
│ • Mark as Read  │    │ • API Server    │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

邮件处理流程

  1. 定时调度 - 每 5 分钟创建邮件处理任务
  2. 邮件检索 - 通过 Gmail API 获取未读邮件（批量最多 50 封）
  3. 规则匹配 - 解析邮件主题，匹配关键词和转发目标
  4. 邮件转发 - 将符合规则的邮件转发到指定地址
  5. 状态更新 - 标记已处理邮件为已读，记录操作日志

主题格式规范

支持以下邮件主题格式：

  • [关键词] - [目标名称]
  • 关键词 - 目标名称

示例：[support] - tech_team 或 urgent - manager

🛠️ 技术栈

后端

  • Go 1.24 - 主要开发语言
  • Gin - Web 框架
  • GORM - ORM 框架
  • Asynq - 异步任务队列
  • Redis - 缓存和任务存储
  • MySQL - 主数据库
  • OpenTelemetry - 链路追踪
  • Swagger - API 文档

基础设施

  • Docker - 容器化部署
  • Gmail API - 邮件服务集成
  • OAuth2 - 安全认证

📋 环境要求

  • Go >= 1.24
  • MySQL >= 8.0
  • Redis >= 7.0
  • Gmail API 凭证 - Google Cloud Console 配置

🚀 快速开始

1. 克隆项目

git clone <repository-url>
cd Gmail_Retrieval_And_Subject_Forwarding_System

2. 配置环境

复制配置文件并编辑：

cp config.example.yaml config.yaml

编辑 config.yaml 文件，配置以下关键信息：

  • 数据库连接参数
  • Redis 连接信息
  • Gmail API 认证文件路径
  • OAuth2 设置

3. 设置 Gmail API 凭证

  1. 前往 Google Cloud Console
  2. 创建新项目或选择现有项目
  3. 启用 Gmail API
  4. 创建 OAuth2 凭证（桌面应用类型）
  5. 下载凭证文件并保存为 support-files/auth/credentials.json

4. 初始化数据库

# 创建数据库
mysql -u root -p -e "CREATE DATABASE gmail_retrieval_and_subject_forwarding_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

5. 安装依赖并启动

# 安装 Go 依赖
go mod tidy

# 生成 API 文档
make swagger

# 启动 API 服务器
go run main.go api

# 启动任务调度器（新终端）
go run main.go scheduler

# 启动工作队列（新终端）
go run main.go worker

6. 访问应用

⚙️ 配置说明

主要配置项

配置项 说明 默认值
app.addr 服务监听地址 :8000
database.host MySQL 数据库地址 127.0.0.1
redis.host Redis 服务器地址 127.0.0.1
gmail.credentials_file Gmail API 凭证文件 credentials.json
schedule.email_processing_forward_mail_cron 邮件处理定时任务 */5 * * * *
worker.concurrency 工作队列并发数 50

详细配置说明请参考 config.example.yaml 文件。

🔧 开发指南

常用命令

# 运行不同模式
go run main.go api        # API 服务器
go run main.go scheduler  # 任务调度器
go run main.go worker     # 工作队列处理器

# 开发工具
make swagger             # 生成 API 文档
make tidy               # 整理依赖
make pre_commit         # 提交前检查（格式化 + 文档生成）

# 测试
go test ./...           # 运行测试

数据库管理

系统使用以下核心数据表：

  • keywords - 关键词配置表
  • forward_targets - 转发目标配置表
  • forward_logs - 转发操作日志表

应用启动时会自动执行数据库迁移。

API 开发

所有 API 端点都需要：

  • 完整的 Swagger 文档注释
  • 统一的响应格式：{"error_msg": "", "data": {}}
  • 适当的错误处理和日志记录

📚 API 文档

API 文档通过 Swagger 自动生成，启动服务后访问：

http://localhost:8000/swagger/index.html

主要 API 端点

  • GET /api/health - 系统健康检查
  • GET /api/v1/keywords - 获取关键词列表
  • POST /api/v1/keywords - 创建新关键词
  • GET /api/v1/targets - 获取转发目标列表
  • POST /api/v1/targets - 创建新转发目标

🐳 Docker 部署

使用 Docker Compose（推荐）

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f gmail-system

手动 Docker 部署

# 构建镜像
docker build -t gmail-system .

# 运行容器
docker run -d \
  --name gmail-system \
  -p 8000:8000 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -v $(pwd)/support-files:/app/support-files \
  gmail-system

🔐 安全注意事项

  • Gmail API 凭证文件权限设置为 600
  • 令牌文件自动加密存储
  • 数据库连接使用安全的连接参数
  • 所有敏感配置通过环境变量或配置文件管理
  • 定期轮换 OAuth2 令牌

🧪 测试

# 运行所有测试
go test ./...

# 运行特定包的测试
go test ./internal/services/...

# 生成测试覆盖率报告
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

📊 监控和日志

日志配置

  • 支持 JSON 和文本格式
  • 可配置日志级别（debug/info/warn/error）
  • 自动日志轮转和压缩

链路追踪

  • 集成 OpenTelemetry
  • 支持分布式链路追踪
  • 可配置导出到不同的后端系统

健康检查

  • HTTP 健康检查端点
  • 数据库连接状态检查
  • Redis 连接状态检查

🤝 贡献指南

欢迎贡献代码！请遵循以下流程：

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/your-feature)
  3. 运行 make pre_commit 确保代码质量
  4. 提交更改 (git commit -am 'Add your feature')
  5. 推送到分支 (git push origin feature/your-feature)
  6. 创建 Pull Request

代码规范

  • 使用简体中文编写注释和文档
  • 遵循 Go 语言标准格式
  • 所有 API 需要完整的 Swagger 文档
  • 数据库字段使用 snake_case 命名

📄 许可证

本项目基于 MIT 许可证 开源。

🔗 相关链接

❓ 常见问题

如何获取 Gmail API 凭证？

  1. 访问 Google Cloud Console
  2. 创建或选择项目
  3. 启用 Gmail API
  4. 创建 OAuth2 凭证（桌面应用）
  5. 下载 JSON 文件并放置到指定位置

邮件没有被转发怎么办？

  1. 检查邮件主题格式是否正确
  2. 确认关键词和目标在数据库中已启用
  3. 查看应用日志了解具体错误
  4. 验证 Gmail API 凭证是否有效

如何修改邮件检查频率？

修改 config.yaml 中的 schedule.email_processing_forward_mail_cron 配置项。

❤️ 致谢

感谢所有为本项目做出贡献的开发者！

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages