# 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-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web-Based Email Client

> 一个功能强大的现代化Web邮件客户端，基于 FastAPI + Layui 开发。它不仅提供多邮箱账户管理、实时推送、智能草稿等基础功能，还深度集成了高级代理、安全防护和翻译服务，旨在提供桌面级的操作体验和企业级的安全性。

## ✨ 项目亮点

- **🔐 全方位安全增强**
  - **硬件密钥登录 (WebAuthn)** - 支持无密码登录，提供顶级安全性。
  - **链接安全扫描** - 集成 VirusTotal API，自动检测邮件中的链接，防止钓鱼和恶意软件。
  - **双因素认证 (MFA)** - 支持 TOTP 动态口令，为账户提供额外保护。
  - **精细化管理员控制** - 管理员可为用户灵活开启或关闭 MFA 与 WebAuthn。

- **🚀 强大的代理与网络集成**
  - **外部代理支持** - 支持配置并使用常见外部代理。
  - **多协议支持** - 支持 socks5 / http / https 三种代理协议。
  - **配置共享** - 用户可将代理配置共享给他人，方便团队协作。

- **🌐 智能国际化支持**
  - **邮件全文翻译** - 一键翻译邮件内容，支持多种翻译引擎 (AI, DeeplX 等)。
  - **自定义翻译服务** - 用户可独立配置和管理自己的翻译API凭据。
  - **翻译配置共享** - 与代理功能类似，翻译配置也可在用户间共享。

- **🎯 卓越的用户体验**
  - **三栏式经典布局** - 清晰的账户/文件夹、邮件列表、邮件详情视图。
  - **实时推送与同步** - 基于 WebSocket 的新邮件实时通知和状态同步。
  - **智能草稿系统** - 自动防抖保存，防止内容丢失。
  - **响应式设计** - 优化了在平板和手机等不同设备上的显示效果。

## 🏗️ 项目结构

```
mail.com/
├── api/                      # 后端服务（FastAPI）
│   ├── controller/           # API 控制器
│   ├── model/                # 数据库模型
│   ├── service/              # 业务服务层
│   ├── schemas/              # 数据校验模型
│   └── utils/                # 工具函数
├── css/                      # 样式文件
├── js/                       # JavaScript 模块
├── layui/                    # UI 框架
├── images/                   # 图片资源
├── run/                      # 启动脚本
├── emails/                   # 邮件文件存储（.gitignore）
│   ├── abc1@abc.com/         # 邮箱1的eml文件，数据库邮件id命名
│   └── abc2@abc.com/         # 邮箱2的eml文件
├── runtime/                  # 运行时数据（.gitignore）
│   ├── logs/                 # 日志文件
│   ├── cache/                # 缓存文件
│   └── files/                # 临时文件
└── uploads/                  # 用户上传（.gitignore）
```

## 🚀 快速开始

### 前置条件

- **Python 3.11+** （必须）
- **systemd** （推荐，用于Linux系统服务管理）
- **Nginx** （推荐，用于Web服务和反向代理）
- **sudo 权限** （用于注册系统服务）

### 一键启动

项目提供了功能强大的自动化管理脚本 `run.sh`，极大简化了部署和维护流程。

1.  **克隆项目**
    ```bash
    git clone https://gitee.com/top-yun/usersmails.git
    cd usersmails
    ```

2.  **配置环境变量**
    ```bash
    cp .env.example .env
    # 编辑 .env 文件，至少配置 `SECRET_KEY` 和 `DATABASE_URL`
    # 如需使用高级功能，请配置 VirusTotal、翻译服务等的 API Key
    ```

3.  **运行管理脚本**
    ```bash
    chmod +x run.sh
    # 服务启动（优势：开机自启）
    ./run.sh [python3或具体路径(可选，默认自动使用python3命令行)]
    # 命令行(screen后台)启动（优势：可查看启动日志）
    ./shell.sh [python3或具体路径(可选，默认自动使用python3命令行)]
    ```

脚本会自动完成以下任务：
- ✅ **环境检查**：检查 Python 版本是否符合要求 (>= 3.11)。
- ✅ **依赖管理**：自动检查并安装所有必需的 Python 依赖包。
- ✅ **数据库初始化**：首次运行时自动检查并创建数据库和表结构。
- ✅ **服务管理菜单**：提供交互式菜单，统一管理所有服务。
- ✅ **系统服务化**：支持将应用注册为 systemd 服务，并配置开机自启。

**菜单功能：**
- **主程序管理**：启动、停止、重启、查看 Web 服务日志。
- **同步服务管理**：独立管理后台邮件同步进程。
- **系统服务**：注册/注销 systemd 服务、配置开机自启。
- **依赖管理**：安装或更新依赖。

### Nginx 配置

```nginx
# 阻止直接访问敏感目录
location ~* ^/(runtime|emails)/ {
    return 403;
}

# 反向代理 API 请求
location /api {
    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;
}

# WebSocket 连接支持
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
```

## ⚠️ 运行与注意事项

- **服务管理**: 强烈建议使用 `./run.sh` 脚本来管理应用生命周期。它能确保核心组件（Web服务、同步服务）都以正确的方式启动和停止。

- **环境变量**: 许多高级功能（如链接扫描、邮件翻译）依赖于第三方API。请务必在 `.env` 文件中填写正确的API密钥以激活这些功能。

- **首次运行**: 系统会自动创建管理员账户 `admin`，密码为 `admin123`。**请在首次登录后立即修改密码！**

- **数据库**: 本项目使用 SQLite，数据库文件位于 `runtime/data.db`。请不要直接修改或删除该文件，任何数据库结构变更都应通过迁移脚本完成。

- **日志系统**: 日志文件位于 `runtime/logs` 目录下，并按日期归档。遇到问题时，请首先检查 `error.log` 和 `info.log`。

- **数据清理**: 系统具备自动清理能力。例如，当一封邮件被永久删除时，其关联的 `.eml` 文件和所有翻译缓存也会被自动清除，以释放磁盘空间。

## 🔧 技术栈

### 后端
- **框架**: FastAPI (Asynchronous)
- **数据库**: SQLAlchemy, SQLite
- **代理支持**: 外部代理（socks5 / http / https）
- **实时通信**: WebSocket
- **认证**: JWT, WebAuthn, MFA (TOTP)

### 前端
- **UI框架**: Layui
- **富文本编辑**: WangEditor
- **拖拽排序**: Sortable.js

## 💻 二次开发 (Development)

如果你希望对本项目进行二次开发或贡献代码，我们提供了 `shell.sh` 脚本来简化整个开发流程。

### 1. 环境与启动

首先，完成与“快速开始”中相同的步骤：克隆仓库、创建并配置 `.env` 文件。

然后，直接运行 `shell.sh` 脚本。它会自动检查环境、管理依赖，并提供一个交互式菜单来启动所有服务：

```bash
chmod +x shell.sh
./shell.sh [python3或具体路径(可选，默认自动使用python3命令行)]
```
进入菜单后，选择 `9. 启动所有服务` 即可一键启动开发环境。

### 2. 代码开发与调试

- **后端开发**: 修改 Python 代码后，在 `shell.sh` 菜单中选择 `11. 重启所有服务` 或单独重启某个服务 (`3` 或 `7`) 来使更改生效，主程序有文件监控，程序文件文件变动时会自动重载程序，同步程序没有此功能，需要自主重启。
- **查看日志**: 调试时，使用菜单中的 `4. 查看主服务` 或 `8. 查看同步服务` 附加到服务的实时输出。按 `Ctrl+A` 然后按 `D` 可以从日志视图中分离并返回菜单。
- **前端开发**: 本项目前端是静态文件。修改 `js/`, `css/` 或 `.html` 文件后，**直接在浏览器中刷新页面**即可看到效果，无需任何编译步骤。

> **提示**: `shell.sh` 使用 `screen` 在后台管理服务。为了避免冲突，建议在开发过程中始终使用此脚本的菜单来操作服务，而不是手动执行 `python` 或 `uvicorn` 命令。

- **核心**: 原生 JavaScript (ES6+)

## 📄 许可证

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