轻量级邮件接收聚合系统 - 统一管理多个邮箱账户，通过自动化机制与其他产品和系统集成。
重要：本项目包含敏感信息管理功能，请注意：
⚠️ 不要在代码中硬编码邮箱地址和密码⚠️ 不要提交包含真实凭证的配置文件⚠️ 使用.test-config存储测试账号（已在 .gitignore 中）- ✅ 提交前运行
./check-commit-security.sh检查安全性
详见：Git 提交安全规范
- Docker 和 Docker Compose
- Go 1.21+ (后端开发)
- Node.js 18+ (前端开发)
- lsof（端口检查工具）
# 1. 克隆项目
git clone <repository-url>
cd fusionmail
# 2. 完整启动（自动启动所有服务）
./start.sh就这么简单！脚本会自动：
- ✅ 检查并安装依赖
- ✅ 启动 PostgreSQL 和 Redis
- ✅ 构建并启动后端服务
- ✅ 安装并启动前端服务
- ✅ 自动处理端口冲突
# 显示帮助信息
./start.sh -h
# 开发模式（热重载）
./start.sh -w
# 仅启动后端
./start.sh -b
# 仅启动前端
./start.sh -f
# 清理数据后启动
./start.sh -c
# 调试模式
./start.sh -d
# 组合使用
./start.sh -w -d # 开发模式 + 调试日志详细说明请查看：启动指南
# 停止前后端服务（保留数据库）
./stop.sh
# 停止所有服务（包括 Docker）
./stop.sh -a
# 停止并清理所有数据
./stop.sh -c- 前端: http://localhost:4444
- 后端 API: http://localhost:3333/api/v1
- 健康检查: http://localhost:3333/api/v1/health
首次启动后，系统会自动创建管理员账号：
- 用户名: admin
- 密码: 保存在
backend/passwd文件中 ⚠️ 首次登录后请修改密码！
- ✅ 多邮箱账户管理（Gmail、Outlook、QQ、163、iCloud、IMAP/POP3）
- ✅ 后台自动同步（增量同步，可配置频率）
- ✅ 邮件列表查询（分页、筛选、排序）
- ✅ 邮件详情查看（包含附件）
- ✅ 全文搜索（基于 PostgreSQL tsvector）
- ✅ 邮件状态管理（已读、星标、归档、删除）
- ✅ 未读邮件统计
- ✅ 账户邮件统计
- ✅ 规则引擎（条件匹配 + 动作执行）
- ✅ 支持多种条件（发件人、主题、正文等）
- ✅ 支持多种动作（标记已读、星标、归档、删除）
- ✅ 优先级排序
- ✅ 规则执行统计
- ✅ 手动同步
- ✅ 自动定时同步
- ✅ 增量同步（避免重复）
- ✅ 同步日志记录
- Webhook 集成
- 邮件标签功能
- 邮件发送功能
- 用户认证（JWT）
- 前端界面
- 附件下载
- 邮件会话视图
curl -X POST http://localhost:3333/api/v1/accounts \
-H "Content-Type: application/json" \
-d '{
"email": "your@qq.com",
"provider": "qq",
"protocol": "imap",
"auth_type": "password",
"password": "your_authorization_code",
"sync_enabled": true,
"sync_interval": 5
}'# 替换为您的账户 UID
export ACCOUNT_UID="acc_xxx"
curl -X POST http://localhost:3333/api/v1/sync/accounts/$ACCOUNT_UID# 获取邮件列表
curl "http://localhost:3333/api/v1/emails?account_uid=$ACCOUNT_UID&page=1&page_size=10"
# 搜索邮件
curl "http://localhost:3333/api/v1/emails/search?q=通知"
# 获取未读邮件数
curl "http://localhost:3333/api/v1/emails/unread-count?account_uid=$ACCOUNT_UID"curl -X POST http://localhost:3333/api/v1/rules \
-H "Content-Type: application/json" \
-d "{
\"name\": \"自动归档通知邮件\",
\"account_uid\": \"$ACCOUNT_UID\",
\"conditions\": \"[{\\\"field\\\":\\\"subject\\\",\\\"operator\\\":\\\"contains\\\",\\\"value\\\":\\\"通知\\\"}]\",
\"actions\": \"[{\\\"type\\\":\\\"archive\\\"},{\\\"type\\\":\\\"mark_read\\\"}]\",
\"enabled\": true
}"# 自动测试所有邮件 API
ACCOUNT_UID=$ACCOUNT_UID ./scripts/test-email-api.shfusionmail/
├── backend/ # Go 后端项目
├── frontend/ # React 前端项目
├── docker-compose.dev.yml # 开发环境 Docker 配置
├── scripts/ # 开发脚本
│ ├── dev-start.sh # 启动开发环境
│ ├── dev-stop.sh # 停止开发环境
│ └── README.md # 脚本说明
├── .kiro/ # Kiro IDE 配置
│ ├── specs/ # 项目规格文档
│ └── steering/ # Kiro 指导文档
└── docs/ # 项目文档
- ✅ 多邮箱账户管理（Gmail、Outlook、iCloud、QQ、163、IMAP/POP3）
- ✅ 后台自动同步（可配置同步频率）
- ✅ 邮件存储与索引（全文搜索、高级筛选）
- ✅ 邮件查看与本地管理（只读镜像模式）
- ✅ 邮件规则引擎（自动分类、标签、触发动作）
- ✅ Webhook 集成（推送邮件事件到外部系统）
- ✅ RESTful API 接口（供第三方系统调用）
- ✅ 代理支持（HTTP/SOCKS5）
- Go 1.21+
- Gin (Web 框架)
- GORM (ORM)
- PostgreSQL 15 (数据库)
- Redis 7 (缓存 + 队列)
- React 19
- TypeScript 5.9
- Vite 7
- Tailwind CSS 4
- shadcn/ui
FusionMail 提供完整的 Swagger API 文档，方便开发和测试。
- 编辑
backend/.env文件：
SWAGGER_ENABLED=true- 启动服务后访问：
http://localhost:3333/swagger/index.html
生产环境请务必关闭 Swagger 文档：
SWAGGER_ENABLED=false # 默认值- 需求文档:
.kiro/specs/fusionmail/requirements.md - 设计文档:
.kiro/specs/fusionmail/design.md - 任务清单:
.kiro/specs/fusionmail/tasks.md - 开发环境配置:
.kiro/steering/development-setup.md - API 规范:
.kiro/steering/api-standards.md - 代码规范:
.kiro/steering/code-conventions.md
# 启动开发环境
./scripts/dev-start.sh
# 停止开发环境
./scripts/dev-stop.sh
# 查看服务状态
docker-compose -f docker-compose.dev.yml ps
# 查看日志
docker-compose -f docker-compose.dev.yml logs -f
# 进入 PostgreSQL
docker exec -it fusionmail-postgres psql -U fusionmail -d fusionmail
# 进入 Redis
docker exec -it fusionmail-redis redis-cli -a fusionmail_redis_password- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'feat: Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
FusionMail 支持多种部署方式，选择最适合你的：
| 平台 | 适用场景 | 部署时间 |
|---|---|---|
| Fly.io | 生产环境推荐 | 5 分钟 |
| HuggingFace | 快速体验 | 3 分钟 |
| Docker | 自有服务器 | 10 分钟 |
| Render | Git 自动部署 | 8 分钟 |
# 1. 安装 CLI
brew install flyctl
# 2. 登录并创建应用
flyctl auth login
flyctl apps create fusionmail
# 3. 配置环境变量
flyctl secrets set -a fusionmail \
DB_HOST=your-db-host \
DB_USER=postgres.your-project-ref \
'DB_PASSWORD=your-password' \
'JWT_SECRET=your-jwt-secret' \
ENCRYPTION_KEY=your-encryption-key
# 4. 部署
flyctl deploy -a fusionmail --remote-only- 项目主页: [GitHub Repository]
- 问题反馈: [GitHub Issues]
- 文档: [Documentation]
注意: 这是一个开发中的项目，当前处于 MVP 阶段。