logo
pu.ac.cn/tempmail
Public
5
0
WeChat Login
CodeIssuesPull requestsEventsPackagesInsights
master
tempmail/README.md
天
功能: 添加用户域名catch_all模式支持与全面测试修复
9ada93b5

临时邮箱系统后端 API (TempMail Backend API)

一个功能完善的临时邮箱后端服务，提供 REST API、SMTP 邮件接收和 WebSocket 实时推送功能。专注于后端开发，可与任何前端框架集成。

⚠️ 重要安全说明

本系统是临时邮箱服务，仅用于接收邮件，禁止对外发送邮件。

🔒 安全特性

  • ✅ 只接收邮件 - SMTP 服务器只接收发送到本系统邮箱的邮件
  • ✅ 严格地址验证 - 只有系统内的邮箱/别名才能接收邮件
  • ✅ 防止邮件中继 - 拒绝所有发往外部地址的邮件（返回 550 错误）
  • ❌ 不支持对外发送 - 没有实现任何邮件发送功能
  • ❌ 不会成为垃圾邮件中继 - 通过严格的收件人验证防止滥用

适用场景：临时邮箱、一次性邮箱、邮件测试、匿名接收等

🎯 项目状态

当前版本: v0.8.3-beta 架构: 纯后端 API 服务（无前端） 开发进度: 100%（后端核心功能已全部完成，响应格式已标准化）

✅ 已完成功能

  • ✅ 完整的 REST API - 用户、邮箱、邮件管理
  • ✅ SMTP 邮件接收 - 基于 go-smtp，实时接收外部邮件
  • ✅ JWT 认证系统 - 双令牌机制（访问令牌 + 刷新令牌）
  • ✅ WebSocket 实时推送 - 新邮件即时通知
  • ✅ 管理后台 API - 用户管理、域名管理、系统统计
  • ✅ 角色权限系统 - RBAC（User/Admin/Super）三级权限
  • ✅ 自动清理机制 - 定时清理过期邮箱和邮件
  • ✅ 邮箱 Token 保护 - 游客邮箱访问控制
  • ✅ 邮件附件支持 - MIME 多部分解析、附件上传下载
  • ✅ 邮箱别名系统 - 多地址绑定、SMTP 别名路由、API 完整支持
  • ✅ 用户域名管理 - 自定义域名、DNS 验证、共享/独享/通配模式、MX 配置
  • ✅ 技术栈优化 - 使用最新成熟库，避免重复造轮子
  • ✅ 生产环境就绪 - 完整的监控、日志、健康检查系统
  • ✅ 兼容API接口 - 提供 mail.ry.edu.kg 风格API，第三方系统可直接对接

🎯 最新更新 (v0.8.3-beta)

新增：用户域名catch_all模式 + 全面测试修复

  • ✨ catch_all域名模式 - 支持通配模式，捕获所有发往该域名的邮件
    • 现支持三种模式：shared(共享)、exclusive(独享)、catch_all(通配)
  • 🐛 测试全面修复 - 38个API端点测试100%通过
    • 修复域名验证测试(email/username/tagName)
    • 修复Auth测试编译错误
    • 清理不兼容的测试文件
  • ✅ 全部功能验证 - 所有核心API端点工作正常

v0.8.2 - 兼容API完全兼容 mail.ry.edu.kg

  • ✅ 兼容API格式调整 - 所有兼容API端点使用旧格式
    • 直接返回数据对象，不包装
    • 错误响应使用 {error: "..."} 格式
    • 与 mail.ry.edu.kg 100%兼容
    • 第三方系统可无缝对接
    • 详见：API兼容层说明

v0.8.0 重大改进：统一API响应格式

  • ✅ 面向失败设计 - 采用统一的 {code, msg, data} 响应格式
    • 标准业务状态码
    • 中文错误消息
    • 更清晰的成功/失败判断
    • 详见：API响应格式说明
  • ✅ 向后兼容 - 兼容API保持旧格式不变
  • ✅ 开发体验优化 - 统一的错误处理，降低前端集成复杂度

响应示例：

{
  "code": 200,
  "msg": "成功",
  "data": {
    "id": "mailbox-123",
    "address": "test@temp.mail"
  }
}

🚀 技术栈优化 (v0.7.0-beta)

  • ✅ 数据库迁移系统 - 使用 golang-migrate/migrate 专业迁移工具
    • 支持版本化数据库迁移
    • 支持回滚操作
    • 生产环境安全迁移
  • ✅ 限流系统优化 - 使用 golang.org/x/time/rate 令牌桶算法
    • 更平滑的限流控制
    • 支持突发流量处理
    • 自适应限流（根据用户等级）
  • ✅ 日志系统增强 - 支持日志轮转和结构化配置
    • 自动日志轮转
    • 日志压缩
    • 按大小和时间轮转
  • ✅ 健康检查标准化 - 使用 heptiolabs/healthcheck 标准库
    • 标准化健康检查接口
    • 支持 Kubernetes 探针
    • 多维度健康检查
  • ✅ 监控系统优化 - 使用官方 Prometheus 客户端
    • 标准化 Prometheus 指标
    • 自动指标注册
    • HTTP 指标导出端点
  • ✅ 邮件解析增强 - 使用 jhillyerd/enmime 专业 MIME 解析库
    • 更强大的 MIME 解析
    • 更好的附件处理
    • 支持复杂邮件格式
  • ✅ 兼容API接口 - 提供标准化的第三方对接API
    • 兼容 mail.ry.edu.kg 风格API格式
    • API Key认证机制
    • 支持分页查询
    • 完整的错误处理
    • 详细的接口文档

🔧 待实现功能

  • 🔄 邮件转发规则
  • 📈 高级分析报表

🏗️ 技术架构

技术栈

  • 语言: Go 1.25
  • Web 框架: Gin v1.11.0
  • SMTP: go-smtp v0.24.0
  • WebSocket: gorilla/websocket v1.5.3
  • 认证: JWT (golang-jwt/jwt/v5)
  • 密码加密: bcrypt
  • 配置管理: Viper
  • 日志: Zap
  • 存储: 内存存储（开发）/ PostgreSQL + Redis（生产）

🚀 快速开始

开发环境启动

cd backend

# 设置必需的环境变量
export TEMPMAIL_JWT_SECRET="test-secret-key-for-development-32-chars-long-at-least"

# 启动综合服务（HTTP + SMTP + WebSocket）
go run ./cmd/server

# 服务运行在:
# - HTTP API: http://localhost:8080
# - SMTP Server: localhost:25
# - WebSocket: ws://localhost:8080/v1/ws

Docker 部署

# 构建镜像
docker build -t tempmail-backend ./backend

# 运行容器
docker run -d \
  -p 8080:8080 \
  -p 25:25 \
  -e TEMPMAIL_JWT_SECRET="your-super-secret-jwt-key-at-least-32-chars" \
  tempmail-backend

📖 API 文档

认证相关

# 用户注册
POST /v1/auth/register
{
  "email": "user@example.com",
  "password": "password123",
  "username": "myname"
}

# 用户登录
POST /v1/auth/login
{
  "email": "user@example.com",
  "password": "password123"
}

# 刷新令牌
POST /v1/auth/refresh
{
  "refreshToken": "..."
}

# 获取当前用户信息
GET /v1/auth/me
Authorization: Bearer <access_token>

邮箱管理

# 创建临时邮箱（游客模式）
POST /v1/mailboxes
Response:
{
  "id": "uuid",
  "address": "random@temp.mail",
  "token": "mailbox-access-token",
  "expiresAt": "2024-01-01T00:00:00Z"
}

# 创建临时邮箱（认证用户）
POST /v1/mailboxes
Authorization: Bearer <access_token>
{
  "prefix": "custom",
  "domain": "temp.mail"
}

# 获取邮箱列表（仅认证用户）
GET /v1/mailboxes
Authorization: Bearer <access_token>

# 查看邮箱详情
GET /v1/mailboxes/:id
X-Mailbox-Token: <mailbox_token>

# 删除邮箱
DELETE /v1/mailboxes/:id
X-Mailbox-Token: <mailbox_token>

邮件管理

# 获取邮件列表
GET /v1/mailboxes/:id/messages
X-Mailbox-Token: <mailbox_token>

# 查看邮件详情
GET /v1/mailboxes/:id/messages/:messageId
X-Mailbox-Token: <mailbox_token>

# 标记邮件为已读
POST /v1/mailboxes/:id/messages/:messageId/read
X-Mailbox-Token: <mailbox_token>

# 下载邮件附件
GET /v1/mailboxes/:id/messages/:messageId/attachments/:attachmentId
X-Mailbox-Token: <mailbox_token>

邮箱别名管理

# 创建邮箱别名
POST /v1/mailboxes/:id/aliases
X-Mailbox-Token: <mailbox_token>
{
  "address": "alias@temp.mail"
}

# 列出邮箱别名
GET /v1/mailboxes/:id/aliases
X-Mailbox-Token: <mailbox_token>

# 获取别名详情
GET /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>

# 切换别名状态（启用/禁用）
PATCH /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>
{
  "isActive": false
}

# 删除别名
DELETE /v1/mailboxes/:id/aliases/:aliasId
X-Mailbox-Token: <mailbox_token>

用户域名管理

# 添加自定义域名
POST /v1/user-domains
Authorization: Bearer <access_token>
{
  "domain": "yourdomain.com",
  "mode": "shared"  # shared 或 exclusive
}

# 列出我的域名
GET /v1/user-domains
Authorization: Bearer <access_token>

# 获取域名详情
GET /v1/user-domains/:id
Authorization: Bearer <access_token>

# 验证域名所有权（DNS TXT 记录）
POST /v1/user-domains/:id/verify
Authorization: Bearer <access_token>

# 获取 MX 配置说明
GET /v1/user-domains/:id/setup
Authorization: Bearer <access_token>

# 切换域名模式（共享/独享）
PUT /v1/user-domains/:id/mode
Authorization: Bearer <access_token>
{
  "mode": "exclusive"
}

# 删除域名
DELETE /v1/user-domains/:id
Authorization: Bearer <access_token>

WebSocket 实时推送

// 连接 WebSocket
const ws = new WebSocket('ws://localhost:8080/v1/ws');

// 订阅邮箱
ws.send(JSON.stringify({
  type: 'subscribe',
  mailboxId: 'mailbox-uuid',
  token: 'mailbox-token'
}));

// 接收新邮件通知
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'new_mail') {
    console.log('New mail received:', data);
  }
};

管理 API（需要管理员权限）

# 用户管理
GET    /v1/admin/users              # 列出用户（Admin权限）
GET    /v1/admin/users/:id          # 获取用户详情（Admin权限）
PATCH  /v1/admin/users/:id          # 更新用户（Admin权限）
DELETE /v1/admin/users/:id          # 删除用户（Super权限）

# 配额管理
GET    /v1/admin/users/:id/quota    # 获取配额（Admin权限）
PUT    /v1/admin/users/:id/quota    # 更新配额（Admin权限）

# 域名管理
GET    /v1/admin/domains            # 列出域名（Admin权限）
POST   /v1/admin/domains            # 添加域名（Super权限）
DELETE /v1/admin/domains/:domain    # 删除域名（Super权限）

# 系统统计
GET    /v1/admin/statistics         # 系统统计（Admin权限）

兼容API（第三方对接）

本系统提供 mail.ry.edu.kg 风格的API接口，第三方系统可直接对接使用。

# 获取系统配置
GET /api/config
X-API-Key: YOUR_API_KEY

# 生成临时邮箱
POST /api/emails/generate
X-API-Key: YOUR_API_KEY
{
  "name": "test",
  "expiryTime": 3600000,  # 1小时，单位毫秒
  "domain": "temp.mail"
}

# 获取邮箱列表
GET /api/emails?cursor=0&limit=20
X-API-Key: YOUR_API_KEY

# 获取邮件列表
GET /api/emails/{emailId}?cursor=0&limit=20
X-API-Key: YOUR_API_KEY

# 获取单封邮件
GET /api/emails/{emailId}/{messageId}
X-API-Key: YOUR_API_KEY

对接优势:

  • ✅ 标准化API格式，易于集成
  • ✅ 完整的API文档
  • ✅ API Key认证
  • ✅ 支持分页查询
  • ✅ 开源免费，数据私有

详细文档请查看：API兼容层说明

📁 项目结构

tempmail/
├── backend/
│   ├── cmd/
│   │   ├── server/         # 综合服务入口（HTTP + SMTP + WebSocket）
│   │   └── api/            # 仅 HTTP API 服务
│   ├── internal/
│   │   ├── auth/           # 认证服务和 JWT
│   │   ├── config/         # 配置管理（Viper）
│   │   ├── domain/         # 领域模型和接口
│   │   ├── logger/         # 日志系统（Zap）
│   │   ├── middleware/     # HTTP 中间件
│   │   ├── service/        # 业务逻辑层
│   │   ├── smtp/           # SMTP 服务器
│   │   ├── storage/        # 存储实现
│   │   │   ├── memory/     # 内存存储（开发）
│   │   │   └── hybrid/     # 混合存储（生产预留）
│   │   ├── transport/      # 传输层（HTTP）
│   │   └── websocket/      # WebSocket 实时推送
│   └── migrations/         # 数据库迁移脚本
├── docs/                   # 项目文档
├── deploy/                 # 部署配置
└── CLAUDE.md              # Claude Code 工作指南

🔧 配置说明

环境变量

# JWT 密钥（生产环境必须修改，至少32字符）
TEMPMAIL_JWT_SECRET=your-super-secret-jwt-key-at-least-32-chars

# HTTP 服务器
TEMPMAIL_SERVER_HOST=0.0.0.0
TEMPMAIL_SERVER_PORT=8080

# SMTP 服务
TEMPMAIL_SMTP_BIND_ADDR=:25
TEMPMAIL_SMTP_DOMAIN=temp.mail

# 邮箱配置
TEMPMAIL_MAILBOX_ALLOWED_DOMAINS=temp.mail,tempmail.dev
TEMPMAIL_MAILBOX_DEFAULT_TTL=24h

# CORS（可选，用于前端接入）
TEMPMAIL_CORS_ALLOWED_ORIGINS=http://localhost:3000

# 日志
TEMPMAIL_LOG_LEVEL=info
TEMPMAIL_LOG_DEVELOPMENT=false

# 数据库（生产环境）
TEMPMAIL_DATABASE_DSN=postgres://user:pass@host:5432/dbname

# Redis（生产环境）
TEMPMAIL_REDIS_ADDRESS=redis:6379
TEMPMAIL_REDIS_PASSWORD=your-redis-password

🧪 开发指南

后端开发

cd backend

# 安装依赖
go mod download

# 运行服务（仅 HTTP）
go run ./cmd/api

# 运行服务（HTTP + SMTP + WebSocket）
go run ./cmd/server

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

# 构建生产版本
go build -o server ./cmd/server

测试 SMTP

# 使用 swaks 测试
swaks --to test@temp.mail --server localhost:25 --ehlo localhost

# 使用 telnet
telnet localhost 25
HELO localhost
MAIL FROM:<sender@example.com>
RCPT TO:<test@temp.mail>
DATA
Subject: Test
This is a test email.
.
QUIT

测试 API

# 健康检查
curl http://localhost:8080/health

# 创建邮箱
curl -X POST http://localhost:8080/v1/mailboxes

# 使用返回的 token 查看邮箱
curl -H "X-Mailbox-Token: <token>" \
     http://localhost:8080/v1/mailboxes/<id>/messages

🔐 安全建议

  1. ⚠️ JWT 密钥 - 生产环境必须使用强密钥（至少32字符）
  2. 🔑 密码策略 - 实施强密码要求
  3. 🔒 HTTPS - 生产环境必须使用 SSL/TLS
  4. 🚫 端口限制 - 不要暴露 SMTP 端口到公网（使用防火墙）
  5. 💾 数据加密 - 敏感数据应加密存储
  6. 📝 审计日志 - 记录所有管理操作
  7. 🔄 定期更新 - 及时更新依赖包

📚 文档

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

  1. Fork 本仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m 'Add amazing feature')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 创建 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🙏 致谢

⭐ 如果觉得这个项目有帮助，请给个 Star！

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号