# Web邮箱客户端

**Repository Path**: top-yun/usersmails

## Basic Information

- **Project Name**: Web邮箱客户端
- **Description**: Web邮箱客户端
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-06
- **Last Updated**: 2026-08-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web-Based Email Client

一个基于 FastAPI、MySQL 和 Layui 的多用户在线邮箱客户端。项目采用根目录静态前端与 `api/` 后端分离的结构，支持多邮箱账户、独立邮件同步进程、实时状态推送、草稿、邮件分组、翻译、AI 总结、代理和多种身份验证方式。

## 当前功能

### 用户与安全

- 用户注册、JWT 登录、退出和个人资料管理。
- TOTP MFA 绑定、验证、禁用及管理员控制。
- WebAuthn 硬件密钥绑定、无用户名登录、解绑及管理员控制。
- 管理员用户管理，包括创建、编辑、启停、删除和密码重置。
- 邮件链接本地规则检测，可选接入 VirusTotal；支持多个 API Key 轮换。

### 邮箱与邮件

- 绑定多个 IMAP/SMTP 邮箱账户，支持 SSL、STARTTLS 和连接验证。
- 独立同步进程负责定时同步，主服务通过缓存触发手动同步和历史同步。
- 文件夹树、未读统计、搜索、分页加载、星标、已读/未读、移动和删除。
- HTML 邮件通过 iframe 展示，支持附件预览与下载、回复、转发和富文本发送。
- 草稿自动保存、继续编辑和草稿附件管理。
- WebSocket 推送未读数、同步失败状态并执行 Token 续期。

### 智能与扩展能力

- 邮件分组：按发件人、收件人或主题配置包含/排除规则，并以虚拟文件夹展示匹配邮件。
- 邮件翻译：支持百度翻译、DeeplX 和 OpenAI 兼容 AI 接口；翻译配置可共享。
- AI 总结：通过 OpenAI 兼容接口流式生成邮件总结；总结配置可共享。
- 代理管理：支持 `socks5`、`http`、`https`，可测试、共享并绑定到邮箱账户。
- 三栏式静态前端，适配桌面、平板和手机，无需前端构建步骤。

## 项目结构

```text
mail.com/
├── api/                         # FastAPI 后端
│   ├── config/                  # 邮箱服务商等静态配置
│   ├── controller/              # APIRouter 控制器
│   ├── model/                   # SQLAlchemy ORM 模型
│   ├── schemas/                 # Pydantic 请求/响应模型
│   ├── service/                 # 邮件、同步、代理、翻译、总结等服务
│   ├── utils/                   # 日志、缓存、响应、SSL、文件夹等工具
│   ├── database.py              # MySQL 数据库连接与会话
│   ├── main.py                  # API 主服务入口，端口 9999
│   ├── sync_service.py          # 独立邮件同步进程入口
│   └── requirements.txt         # Python 依赖
├── index.html                   # 邮箱客户端主页面
├── login.html                   # 登录页面
├── register.html                # 注册页面
├── admin-users.html             # 管理员用户管理页面
├── css/                         # 公共、登录和主界面样式
├── js/                          # 前端基础与业务模块
│   ├── email/                   # 列表、详情、草稿、操作、分组等子模块
│   ├── api.js                   # API 请求与 Token 管理
│   ├── main.js                  # 应用、账户、文件夹和 WebSocket
│   ├── account.js               # 账户、个人资料和安全设置
│   ├── proxy.js                 # 代理配置
│   ├── translation.js           # 翻译配置
│   └── summary.js               # AI 总结配置
├── layui/                       # Layui 框架文件
├── images/                      # 静态图片资源
├── run/                         # 主服务、同步服务启动辅助
├── run.sh                       # systemd 管理脚本
├── shell.sh                     # Screen 管理脚本
├── emails/                      # EML 文件：<邮箱>/<邮件数据库ID>.eml
├── runtime/                     # 日志、文件缓存和临时文件
├── uploads/                     # 头像、邮件图片等上传文件
└── test/                        # 测试与临时验证内容
```

前端位于项目根目录，不存在独立的 `web/` 工程。邮件前端逻辑已经从单个 `js/email.js` 拆分到 `js/email/*.js`，`js/email.js` 主要作为兼容入口。

## 快速开始

### 前置条件

- Python 3.11+
- MySQL
- Nginx，推荐用于静态文件和反向代理
- systemd 与 sudo 权限，仅在使用 `run.sh` 时需要
- Screen，仅在使用 `shell.sh` 时需要

### 1. 获取项目

```bash
git clone https://gitee.com/top-yun/usersmails.git
cd usersmails
```

### 2. 配置环境

```bash
cp .env.example .env
python3 -m pip install -r api/requirements.txt
```

至少检查并修改以下配置：

- `SECRET_KEY`：生产环境必须替换为随机强密钥。
- `DB_HOST`、`DB_PORT`、`DB_NAME`、`DB_USER`、`DB_PASSWORD`：MySQL 连接信息。
- `ADMIN_ACCOUNT`、`ADMIN_PASSWORD`：首次启动时创建的管理员账号；未配置时不会按固定默认密码创建管理员。
- `VIRUSTOTAL_API_KEY`：可选，多个 Key 使用英文逗号分隔；未配置时仍保留本地链接规则检测。
- `DEV_MODE`、`WORKERS` 等：可选的主服务运行参数。

翻译和 AI 总结凭据由用户在页面中管理，不从 `.env` 读取。

### 3. 启动服务

项目包含两个独立进程：FastAPI 主服务和邮件同步服务。只启动主服务可以访问 API，但不会持续执行后台邮件同步。

使用 systemd 管理：

```bash
chmod +x run.sh
./run.sh python3
```

`run.sh` 提供服务注册、启动、停止、重启、开机自启、日志查看、依赖安装和资源检查菜单。

使用 Screen 管理：

```bash
chmod +x shell.sh
./shell.sh python3
```

也可以直接启动全部 Screen 服务：

```bash
./shell.sh python3 start-all
```

### 4. Nginx 配置

前端为静态文件，API 应代理到 `127.0.0.1:9999`。应用使用 `root_path="/api"`，WebSocket 地址为 `/ws/sync`。

```nginx
# 禁止直接访问运行时数据和邮件原文件
location ~* ^/(runtime|emails)/ {
    return 403;
}

location /api {
    proxy_pass http://127.0.0.1:9999;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location /ws {
    proxy_pass http://127.0.0.1:9999;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_cache_bypass $http_upgrade;
}
```

配置完成后检查并重载 Nginx：

```bash
nginx -t
nginx -s reload
```

## 运行说明

- 数据库仅支持 MySQL，启动主服务时会通过 SQLAlchemy 创建缺失的数据表。
- 管理员初始化读取 `.env` 中的 `ADMIN_ACCOUNT` 和 `ADMIN_PASSWORD`，不会使用 README 中写死的公共默认密码。
- 日志位于 `runtime/logs/`，主要包括 `debug.log`、`info.log`、`error.log` 和 `sync.log`，轮转文件按日期归档。
- 邮件原文件保存在 `emails/<邮箱>/<邮件数据库ID>.eml`。
- 邮件永久删除时会同步清理关联的 EML 文件和翻译缓存。
- `runtime/`、`emails/` 和 `uploads/` 包含运行时或用户数据，Web 服务器不应开放目录浏览。

## 技术栈

### 后端

- FastAPI 0.115、Uvicorn
- SQLAlchemy 2、MySQL、PyMySQL
- IMAPClient、IMAP/SMTP
- JWT、bcrypt、TOTP MFA、WebAuthn
- Requests、BeautifulSoup、lxml、PySocks
- REST API 与 WebSocket

### 前端

- 原生 JavaScript
- Layui
- WangEditor
- Sortable.js
- 静态 HTML/CSS，无 Node.js 构建流程

## 二次开发

- 修改 `js/`、`css/` 或根目录 HTML 后，刷新浏览器即可验证。
- 修改后端代码后，根据当前启动模式重启主服务；邮件同步逻辑变更后需要单独重启同步服务。
- Screen 模式可通过 `shell.sh` 菜单查看主服务、同步服务和各类日志。
- API 文档默认通过反向代理访问 `http://localhost/api/docs`，直接访问后端时路径取决于代理和 `root_path` 配置。

## 许可证

本项目基于 [MIT License](LICENSE) 开源。