# 邮件自动接收系统

**Repository Path**: zhuxbo/email

## Basic Information

- **Project Name**: 邮件自动接收系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 邮件收发系统

一个简单的邮件收发系统，支持接收所有 MX 解析过来的邮件，并可以回复。

## 功能特点

- **自动接收邮件**：只要域名 MX 解析到服务器，即可接收该域名的所有邮件
- **对话视图**：自动将往返邮件整理为对话，类似 Gmail 的对话模式
- **附件支持**：收发邮件均支持附件，自动保存和下载
- **回复邮件**：使用收件邮箱地址回复邮件，自动包含原邮件内容和 `Re:` 标题
- **搜索功能**：支持按关键词搜索邮件（主题、内容、发件人、收件人）
- **自动刷新**：前端每 30 秒自动刷新对话列表
- **分页加载**：支持加载更多，避免一次加载过多数据
- **域名黑名单**：拒绝接收指定收件域名的邮件（支持后缀匹配）
- **发件白名单**：只接收白名单中域名发来的邮件（支持后缀匹配，空白名单=不限制）
- **无主题拒收**：自动拒绝接收无主题的邮件
- **邮件上限**：每个域名最多保存 100 封邮件
- **按域名管理**：可按域名查看和批量删除邮件
- **用户认证**：支持登录认证，可修改用户名和密码
- **TLS 支持**：SMTP 服务器支持 TLS/STARTTLS 加密
- **HTTPS 支持**：Web 服务支持自签证书 HTTPS，自动生成 10 年有效期证书
- **日志系统**：支持日志级别控制，生产环境自动写入文件

## 快速开始

### 1. 部署

```bash
docker-compose up -d
```

### 2. 获取登录凭据

首次启动时，系统会自动生成随机用户名和密码，查看后端日志获取：

```bash
docker-compose logs backend | grep -A 4 "首次运行"
```

输出示例：

```plain
========================================
首次运行，已生成随机登录凭据：
用户名: a1b2c3d4
密码: x9y8z7w6
请妥善保存，此信息仅显示一次！
========================================
```

### 3. 配置域名

将域名的 MX 记录指向服务器 IP：

```plain
example.com.  MX  10  mail.example.com.
mail.example.com.  A  YOUR_SERVER_IP
```

### 4. 访问系统

打开浏览器访问 `http://YOUR_SERVER_IP:8080`，使用生成的凭据登录。

## 环境变量

支持使用 `.env` 文件配置环境变量，复制示例文件后根据需要修改：

```bash
cp .env.example .env
```

### Docker Compose

| 变量              | 默认值      | 说明                                       |
| ----------------- | ----------- | ------------------------------------------ |
| `WEB_PORT`        | `8080`      | Web 服务暴露端口                           |
| `ENABLE_HTTPS`    | `false`     | 是否启用 HTTPS                             |
| `DOMAIN`          | `localhost` | 证书域名（用于生成自签证书）               |
| `REGENERATE_CERT` | `false`     | 强制重新生成证书                           |

### 后端

| 变量                              | 默认值                    | 说明                                   |
| --------------------------------- | ------------------------- | -------------------------------------- |
| `SMTP_PORT`                       | `25`                      | SMTP 服务端口（465 需启用 TLS）        |
| `SMTP_HOSTNAME`                   | `localhost`               | SMTP 主机名（用于发件 HELO 命令）      |
| `SMTP_SECURE`                     | `false`                   | 是否启用隐式 TLS（465 端口设为 true）  |
| `SMTP_KEY_PATH`                   | -                         | TLS 私钥文件路径                       |
| `SMTP_CERT_PATH`                  | -                         | TLS 证书文件路径                       |
| `DATABASE_PATH`                   | `./data/email.db`         | 数据库文件路径                         |
| `CREDENTIALS_PATH`                | `./data/credentials.json` | 凭据文件路径                           |
| `LOG_LEVEL`                       | `info`                    | 日志级别 (error/warn/info/debug)       |
| `LOG_DIR`                         | `./logs`                  | 日志文件目录（生产环境）               |
| `MAX_EMAILS_PER_DOMAIN`           | `100`                     | 每个域名最大邮件数                     |
| `SMTP_MAX_MESSAGE_SIZE`           | `26214400`                | 邮件大小限制（字节，默认 25MB）        |
| `SMTP_MAX_ATTACHMENTS`            | `20`                      | 附件数量限制                           |
| `SMTP_MAX_ATTACHMENTS_TOTAL_SIZE` | `20971520`                | 附件总大小限制（字节，默认 20MB）      |
| `SMTP_RAW_EMAIL_MAX_STORE_SIZE`   | `1048576`                 | 原始邮件最大存储大小（字节，默认 1MB） |

所有环境变量都通过 `.env` 文件配置，修改后执行 `docker-compose up -d` 即可生效。

## API 文档

所有 API 需要认证（除登录接口），请求头需携带 `Authorization: Bearer <token>`。

### 认证

| 方法 | 路径                   | 说明                                                                          |
| ---- | ---------------------- | ----------------------------------------------------------------------------- |
| POST | `/api/login`           | 登录，body: `{ "username": "", "password": "" }`                              |
| POST | `/api/logout`          | 登出                                                                          |
| POST | `/api/change-password` | 修改密码，body: `{ "oldPassword": "", "newPassword": "", "newUsername": "" }` |

### 对话

| 方法 | 路径               | 说明                                                     |
| ---- | ------------------ | -------------------------------------------------------- |
| GET  | `/api/threads`     | 获取对话列表，支持 `?domain=xxx&limit=50&offset=0` 参数  |
| GET  | `/api/threads/:id` | 获取对话详情（包含所有邮件和附件）                       |
| GET  | `/api/search`      | 搜索对话，参数 `?q=关键词&domain=xxx`（关键词至少2字符） |

### 邮件

| 方法   | 路径                    | 说明                                        |
| ------ | ----------------------- | ------------------------------------------- |
| GET    | `/api/emails`           | 获取邮件列表，可选 `?domain=xxx` 筛选       |
| GET    | `/api/emails/:id`       | 获取邮件详情（包含附件列表）                |
| DELETE | `/api/emails/:id`       | 删除邮件                                    |
| POST   | `/api/emails/:id/reply` | 回复邮件，支持 multipart/form-data 上传附件 |

### 附件

| 方法 | 路径                   | 说明                       |
| ---- | ---------------------- | -------------------------- |
| GET  | `/api/attachments/:id` | 下载附件（返回文件二进制） |

### 域名

| 方法   | 路径                          | 说明                 |
| ------ | ----------------------------- | -------------------- |
| GET    | `/api/domains`                | 获取有邮件的域名列表 |
| DELETE | `/api/domains/:domain/emails` | 删除该域名所有邮件   |

### 黑名单（收件域名）

| 方法   | 路径                     | 说明                                          |
| ------ | ------------------------ | --------------------------------------------- |
| GET    | `/api/blacklist`         | 获取黑名单                                    |
| POST   | `/api/blacklist`         | 添加到黑名单，body: `{ "domain": "xxx.com" }` |
| DELETE | `/api/blacklist/:domain` | 移除黑名单                                    |

### 白名单（发件域名）

| 方法   | 路径                     | 说明                                          |
| ------ | ------------------------ | --------------------------------------------- |
| GET    | `/api/whitelist`         | 获取白名单                                    |
| POST   | `/api/whitelist`         | 添加到白名单，body: `{ "domain": "xxx.com" }` |
| DELETE | `/api/whitelist/:domain` | 移除白名单                                    |

## 架构

```plain
┌───────────────────────────────────┐
│            Nginx (8080)           │
│  ┌─────────────┐ ┌─────────────┐  │
│  │ 静态文件     │ │ API 反向代理 │  │
│  │ (React)     │ │ (/api)      │  │
│  └─────────────┘ └──────┬──────┘  │
└───────────────────────────│───────┘
                            │
                     ┌──────▼──────┐
                     │   Backend   │
                     │  (Express)  │
                     └──────┬──────┘
                            │
                     ┌──────▼──────┐
                     │   SQLite    │
                     │  (sql.js)   │
                     └─────────────┘

┌─────────────┐
│ SMTP Server │◀──── 外部邮件
│   (端口25)   │
└─────────────┘
```

## 开发

### 本地运行

```bash
# 后端
cd backend
npm install
npm run dev

# 前端
cd frontend
npm install
npm run dev
```

### 构建

```bash
docker-compose build
```

## 更新系统

### 开发环境

```bash
git pull
docker-compose up -d --build
```

### 生产环境

生产环境更新建议按以下步骤操作：

```bash
# 1. 备份数据库（重要！）
cp data/email.db data/email.db.backup.$(date +%Y%m%d%H%M%S)

# 2. 拉取最新代码（data 目录已被 git 忽略，不会冲突）
git pull

# 3. 重新构建并启动服务
docker-compose up -d --build

# 4. 验证服务正常运行
docker-compose ps
docker-compose logs --tail=50
```

**回滚方法**（如果更新后出现问题）：

```bash
# 恢复数据库备份
cp data/email.db.backup.xxx data/email.db

# 重启服务
docker-compose restart backend
```

**说明**：

- 数据库文件 `data/email.db` 是唯一需要备份的数据
- 认证信息 `data/credentials.json` 和证书 `data/cert/` 在更新时会保留
- 如果只更新了前端，可以只重建 nginx：`docker-compose build nginx`
- 如果只更新了后端，可以只重建后端：`docker-compose build backend`

## HTTPS 配置

系统支持自签证书 HTTPS，首次启动时会自动生成 10 年有效期的证书。

### 启用 HTTPS

1. 复制环境变量示例文件：

    ```bash
    cp .env.example .env
    ```

2. 编辑 `.env` 文件，设置以下变量：

    ```bash
    ENABLE_HTTPS=true
    DOMAIN=mail.example.com
    WEB_PORT=8080
    ```

3. 启动服务：

    ```bash
    docker-compose up -d
    ```

### 导入根证书

由于使用自签证书，需要将根证书导入到浏览器或操作系统信任存储中，否则浏览器会提示不安全。

证书文件位置：`data/cert/ca.crt`

#### macOS

```bash
# 导入到系统钥匙串
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain data/cert/ca.crt
```

#### Windows

1. 双击 `data/cert/ca.crt` 文件
2. 点击"安装证书"
3. 选择"本地计算机"
4. 选择"将所有证书放入下列存储" → "受信任的根证书颁发机构"
5. 完成安装

#### Linux (Chrome/Chromium)

```bash
# 安装到用户证书存储
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "Email Server CA" -i data/cert/ca.crt
```

#### Firefox

1. 打开 Firefox 设置 → 隐私与安全 → 证书 → 查看证书
2. 点击"导入"，选择 `data/cert/ca.crt`
3. 勾选"信任此 CA 标识网站"

### 重新生成证书

如需重新生成自签证书（例如更换域名），在 `.env` 文件中设置：

```bash
REGENERATE_CERT=true
DOMAIN=new-domain.example.com
```

然后重启服务：

```bash
docker-compose up -d
```

**注意**：

- 重新生成证书后，需要重新导入新的根证书
- 生成完成后建议将 `REGENERATE_CERT` 改回 `false`，避免每次启动都重新生成

### 使用自定义证书

如果您有自己的 SSL 证书，可以替换自签证书：

```bash
# 复制证书和私钥（文件名必须为 server.crt 和 server.key）
cp your-certificate.crt data/cert/server.crt
cp your-private-key.key data/cert/server.key

# 确保文件权限正确
chmod 644 data/cert/server.crt
chmod 600 data/cert/server.key

# 重载 Nginx 配置（无需重启容器）：

docker compose exec nginx nginx -s reload
```

**说明**：

- 证书文件通过 Docker volume 挂载，主机和容器共享同一目录
- 使用 `nginx -s reload` 可以无缝切换证书，不会中断服务
- 如果使用 CA 签发的证书，无需导入根证书到客户端

### 证书文件说明

| 文件                   | 说明                             |
| ---------------------- | -------------------------------- |
| `data/cert/ca.crt`     | 根证书（需导入到客户端信任存储） |
| `data/cert/server.crt` | 服务器证书                       |
| `data/cert/server.key` | 服务器私钥                       |

**安全说明**：根证书私钥（`ca.key`）在生成域名证书后会立即删除，无法再用于签发新证书，这是一项安全措施。

## 许可证

MIT