Initial commit for mail-sr

README.md

@@ -0,0 +1,335 @@
+# 多邮箱帐号收发系统
+
+一个基于 Node.js + Express + SQLite 的多邮箱工作台，支持在网页中统一管理多个邮箱渠道与邮箱帐号，进行收信、查看邮件、发信，以及通过 API 调用邮件能力。
+
+## 功能特性
+
+- 支持配置多个邮箱渠道，如 QQ 邮箱、163 邮箱和自定义 IMAP/SMTP 渠道
+- 支持导入邮箱帐号与授权码
+- 三栏式 Web 界面：邮箱帐号、邮件列表、邮件详情
+- 支持网页写邮件、发邮件、查看邮件详情
+- 支持拉取多文件夹邮件，不限于 `INBOX`
+- 支持按需补拉单封邮件正文，避免全量同步过慢
+- 支持批量导入导出邮箱信息
+- 提供 API 用于发邮件、获取邮件列表、获取最新一封邮件
+
+## 技术栈
+
+- Node.js
+- Express
+- SQLite `better-sqlite3`
+- SMTP `nodemailer`
+- IMAP `imapflow`
+- 前端：原生 HTML / CSS / JavaScript
+
+## 目录结构
+
+```text
+mail-sr/
+├── public/
+│   ├── index.html
+│   ├── styles.css
+│   └── app.js
+├── db.js
+├── mailService.js
+├── server.js
+├── Dockerfile
+├── docker-compose.yml
+└── README.md
+```
+
+## 本地启动
+
+### 1. 安装依赖
+
+```bash
+npm install
+```
+
+### 2. 配置环境变量
+
+```bash
+cp .env.example .env
+```
+
+默认环境变量：
+
+```env
+PORT=3000
+DB_PATH=./mail.db
+```
+
+### 3. 启动服务
+
+```bash
+npm start
+```
+
+访问地址：`http://localhost:3000`
+
+## Docker 部署
+
+项目已经提供 `Dockerfile` 和 `docker-compose.yml`，可以直接用 Docker Compose 部署。
+
+### 1. 准备环境变量
+
+```bash
+cp .env.example .env
+```
+
+如果你不需要额外环境变量，默认配置即可。
+
+### 2. 构建并启动
+
+```bash
+docker compose up -d --build
+```
+
+启动后访问：`http://localhost:3000`
+
+### 3. 停止服务
+
+```bash
+docker compose down
+```
+
+### 4. 查看日志
+
+```bash
+docker compose logs -f
+```
+
+### 5. 数据持久化
+
+Docker Compose 默认使用命名卷 `mail-sr-data` 持久化 SQLite 数据库，容器重建后数据不会丢失。
+
+容器内数据库路径：
+
+```text
+/data/mail.db
+```
+
+## 内置邮箱渠道
+
+系统默认会初始化以下渠道：
+
+- QQ邮箱
+  - IMAP: `imap.qq.com:993`
+  - SMTP: `smtp.qq.com:465`
+- 163邮箱
+  - IMAP: `imap.163.com:993`
+  - SMTP: `smtp.163.com:465`
+
+说明：通常需要在邮箱后台开启 IMAP/SMTP，并使用授权码，而不是邮箱登录密码。
+
+## Web 使用说明
+
+### 1. 渠道管理
+
+在设置弹窗中可以新增渠道，填写：
+
+- 渠道名称
+- 渠道标识 code
+- IMAP 主机、端口、是否 SSL
+- SMTP 主机、端口、是否 SSL
+
+### 2. 单个邮箱帐号导入
+
+在设置弹窗中填写：
+
+- 渠道
+- 邮箱帐号
+- 授权码
+- 发件人名称，可选
+
+### 3. 批量导入导出
+
+支持以下格式，每行一条：
+
+```text
+渠道名----帐号----授权码
+```
+
+例如：
+
+```text
+QQ邮箱----demo@qq.com----abcd1234
+163邮箱----demo@163.com----efgh5678
+```
+
+说明：
+
+- 导入时按“渠道名”匹配已有渠道
+- 如果渠道不存在，会直接报错
+- 如果同一渠道下邮箱已存在，则更新授权码
+- 导出会导出全部帐号，格式同上
+
+### 4. 收信
+
+点击左侧邮箱帐号后会：
+
+- 复制邮箱号到剪贴板
+- 立即触发收信
+- 拉取全部可读文件夹中的最近邮件
+- 在中间栏展示邮件列表
+- 在右侧显示邮件详情
+
+为了避免 IMAP 全量拉取过慢，系统使用“两阶段策略”：
+
+- 先同步邮件列表与头信息
+- 打开某封邮件时再按需拉取正文详情
+
+### 5. 发信
+
+点击左上角“写邮件”按钮，选择当前邮箱帐号后即可发信。
+
+## API 文档
+
+### 健康检查
+
+```bash
+curl http://localhost:3000/api/health
+```
+
+### 查询渠道
+
+```bash
+curl http://localhost:3000/api/channels
+```
+
+### 新增渠道
+
+```bash
+curl -X POST http://localhost:3000/api/channels \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "企业邮箱",
+    "code": "corp",
+    "imap_host": "imap.example.com",
+    "imap_port": 993,
+    "imap_secure": true,
+    "smtp_host": "smtp.example.com",
+    "smtp_port": 465,
+    "smtp_secure": true
+  }'
+```
+
+### 查询帐号列表
+
+```bash
+curl http://localhost:3000/api/accounts
+```
+
+### 新增邮箱帐号
+
+```bash
+curl -X POST http://localhost:3000/api/accounts \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "channel_id": 1,
+    "email": "your-account@qq.com",
+    "auth_code": "邮箱授权码",
+    "display_name": "业务邮箱"
+  }'
+```
+
+### 删除邮箱帐号
+
+```bash
+curl -X DELETE http://localhost:3000/api/accounts/1
+```
+
+### 批量导出帐号
+
+```bash
+curl http://localhost:3000/api/accounts/export
+```
+
+### 批量导入帐号
+
+```bash
+curl -X POST http://localhost:3000/api/accounts/import \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "content": "QQ邮箱----demo@qq.com----abcd1234\n163邮箱----demo@163.com----efgh5678"
+  }'
+```
+
+### 发送邮件
+
+```bash
+curl -X POST http://localhost:3000/api/send \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "accountId": 1,
+    "to": "target@example.com",
+    "subject": "测试邮件",
+    "text": "这是一封来自 API 的测试邮件"
+  }'
+```
+
+### 获取邮件列表
+
+首次建议带 `refresh=true`，从远程 IMAP 同步最新邮件。
+
+```bash
+curl "http://localhost:3000/api/messages?accountId=1&limit=20&refresh=true"
+```
+
+### 获取最新一封邮件
+
+```bash
+curl "http://localhost:3000/api/messages/latest?accountId=1&refresh=true"
+```
+
+### 获取单封邮件详情
+
+```bash
+curl "http://localhost:3000/api/accounts/1/messages/INBOX%3A123?refresh=true"
+```
+
+说明：`uid` 需要使用 URL 编码。
+
+## 数据说明
+
+- `channels`：邮箱渠道配置
+- `accounts`：邮箱帐号和授权码
+- `mail_cache`：同步后的邮件缓存
+
+默认本地数据库文件为：
+
+```text
+./mail.db
+```
+
+如果通过 Docker 运行，则默认为：
+
+```text
+/data/mail.db
+```
+
+## 部署建议
+
+- 生产环境建议使用反向代理，如 Nginx 或 Traefik
+- 建议通过 HTTPS 暴露服务
+- 当前授权码存储在 SQLite 中，生产环境建议改为加密存储
+- 建议增加访问控制与登录认证，避免未授权访问
+
+## 当前实现边界
+
+- 当前未实现附件上传与下载
+- 当前未实现用户登录、权限和多租户隔离
+- 当前邮件缓存为本地 SQLite，不适合超大规模并发
+- 当前 HTML 邮件正文做了基础清理，但不是完整沙箱渲染
+
+## 后续建议
+
+如果准备继续往生产方向演进，建议优先补以下能力：
+
+1. 用户登录与权限管理
+2. 授权码加密存储
+3. 附件收发
+4. 邮件标签、已读未读、分页
+5. 定时自动拉取邮件
+6. 发信模板和批量发信
+7. 更完整的 HTML 邮件安全隔离策略