benxianyu/flymail repository overview

⁠FlyMail

FlyMail 是一个面向个人、家庭和小团队的自托管多用户邮箱聚合与管理平台。它把多个邮箱集中到一个 Web 界面中，同时保留用户数据隔离、历史邮件同步、附件与正文缓存、邮件备份和多种通知能力。

⁠主要功能

• 多用户本地登录，管理员可创建、禁用用户和重置密码；用户之间的数据相互隔离
• 支持 Gmail、Outlook、QQ、网易、iCloud、新浪以及通用 IMAP/SMTP
• 聚合收件箱、跨邮箱搜索、邮件会话、验证码识别、联系人和多签名
• 历史邮件后台同步，支持暂停、继续、重试和断点恢复
• 邮件正文、内嵌图片和普通附件缓存；普通附件按需下载
• 本地 .eml 备份、NAS 授权目录备份，以及 Bark、Telegram、企业微信、钉钉、飞书和 Webhook 通知
• PWA、移动端适配、深色模式，以及 HTML 邮件安全渲染
• 单容器内置 MySQL，适合快速部署；所有业务数据统一持久化到 /data

⁠快速开始

⁠1. 准备数据目录和环境变量

建议把持久化数据放在宿主机 /Docker/flymail/data：

sudo mkdir -p /Docker/flymail/data
mkdir -p flymail-deploy
cd flymail-deploy

创建 .env。以下值仅为示例，请务必替换管理员密码、数据库密码和会话密钥：

FLYMAIL_ADMIN_USERNAME=admin
FLYMAIL_ADMIN_PASSWORD=请替换为高强度管理员密码
FLYMAIL_SESSION_SECRET=请替换为随机长字符串
MYSQL_DATABASE=flymail
MYSQL_USER=flymail
MYSQL_PASSWORD=请替换为高强度数据库密码

# 如需代理，再填写；不需要时保持为空
FLYMAIL_HTTP_PROXY=
FLYMAIL_HTTPS_PROXY=
FLYMAIL_ALL_PROXY=
FLYMAIL_NO_PROXY=127.0.0.1,localhost

可用下面的命令生成会话密钥（不要把输出提交到 Git）：

openssl rand -hex 32

⁠2. 启动容器

docker run -d \
  --name flymail \
  --restart unless-stopped \
  --env-file .env \
  -p 36080:8080 \
  -v /Docker/flymail/data:/data \
  benxianyu/flymail:0.0.58

浏览器访问 http://服务器地址:36080。首次启动会使用 FLYMAIL_ADMIN_USERNAME 和 FLYMAIL_ADMIN_PASSWORD 初始化管理员。已有数据目录再次启动时不会覆盖已有账号；修改环境变量后如需改变管理员密码，请在 Web 界面中修改。

⁠3. 检查运行状态

docker ps --filter name=flymail
docker logs -f flymail
curl http://127.0.0.1:36080/api/health

健康检查应返回 HTTP 200，并包含应用状态和版本信息。

⁠Docker Compose 用法

也可以使用下面的 compose.yaml：

services:
  flymail:
    image: benxianyu/flymail:0.0.58
    container_name: flymail
    restart: unless-stopped
    ports:
      - "36080:8080"
    env_file:
      - .env
    environment:
      APP_HOST: 0.0.0.0
      APP_PORT: 8080
      FLYMAIL_STORAGE_ROOT: /data
      FLYMAIL_DATA_DIR: /data/flymail
      FLYMAIL_UI_DIR: /app/frontend-dist
    volumes:
      - /Docker/flymail/data:/data

启动和停止：

docker compose up -d
docker compose logs -f flymail
docker compose down

不要删除 /Docker/flymail/data；它包含 MySQL 数据库、邮箱配置、缓存、附件和备份。

⁠数据和备份

容器内唯一需要持久化的目录是 /data，建议整体映射到宿主机目录：

• /data/mysql：用户、邮箱账号、邮件缓存、设置、通知和同步任务
• /data/flymail/config：应用配置和运行时密钥文件
• /data/flymail/files：头像、邮箱图标、签名图片、邮件正文图片和附件对象
• /data/flymail/backup：邮件 .eml 备份
• /data/flymail/logs：应用日志

快照不等于备份。升级或迁移前，建议先停止写入并复制数据目录：

docker stop flymail
sudo tar -C /Docker/flymail -czf flymail-data-$(date +%F).tar.gz data
docker start flymail

如果要使用 NAS 目录，应将 NAS 路径显式挂载到容器 /data 下，并在 FlyMail 备份页面授权；不要把宿主机根目录或整个 /Docker 映射进容器。

⁠首次使用流程

1. 登录管理员账号。
2. 管理员在用户管理中创建普通用户；普通用户登录后只能管理自己的数据。
3. 在账号管理中添加邮箱，选择服务商或填写 IMAP/SMTP 参数。
4. 按需要开启历史邮件同步，进入同步管理查看进度；任务支持暂停、继续和失败重试。
5. 在设置中配置聚合收件箱、附件缓存容量、主题和通知渠道。
6. 在邮件备份页面选择邮箱和备份目录，首次使用建议执行一次手动备份。

Gmail、OAuth、SMTP 和第三方通知需要对应服务商的授权信息。请只在服务器本地 .env 或 Web 配置中填写凭据，不要写入镜像、代码仓库、工单或公开日志。

⁠升级镜像

先备份 /Docker/flymail/data，再拉取目标版本并重建容器：

docker pull benxianyu/flymail:0.0.58
docker stop flymail
docker rm flymail
# 使用原来的 --env-file、端口和 /data 挂载重新执行 docker run

若使用 Compose：

docker compose pull
docker compose up -d

升级后检查容器健康状态、/api/health、登录、收件箱读取和一封测试邮件。不要在没有备份的情况下删除旧数据目录。

⁠常见问题

容器启动后退出： 先看 docker logs flymail。首次启动必须提供 FLYMAIL_ADMIN_USERNAME、FLYMAIL_ADMIN_PASSWORD 和 FLYMAIL_SESSION_SECRET；同时确认 /data 可写。

网页打不开： 检查宿主机端口映射、防火墙和 docker ps。容器内部固定监听 8080，宿主机可使用其他未占用端口，例如 36080:8080。

邮箱无法连接： 检查 IMAP/SMTP 主机名、端口、SSL/STARTTLS 选项和凭据；如果网络需要代理，设置 FLYMAIL_HTTP_PROXY、FLYMAIL_HTTPS_PROXY 或 FLYMAIL_ALL_PROXY。

历史同步很慢： 首次同步会按文件夹拉取历史邮件，正文和内嵌图片也可能需要缓存。可在同步管理页面暂停、继续或重试，避免反复删除本地数据重新开始。

修改环境变量没有生效： Compose 修改 .env 后需要 docker compose up -d；普通 docker run 需要用相同参数重新创建容器。已有数据库中的账号和设置不会因重启自动重置。

⁠安全建议

• 生产环境使用 HTTPS 反向代理，不直接把管理端口暴露到公网。
• 使用高强度、唯一的管理员密码和数据库密码；定期备份并测试恢复。
• 不提交 .env，不在日志和截图中暴露邮箱密码、OAuth Token、SMTP 密钥或会话密钥。
• 只开放实际需要的宿主机端口，并定期更新到明确的版本标签。

⁠版本

当前镜像标签：0.0.58

镜像地址：benxianyu/flymail:0.0.58

⁠GitHub 源码

项目源码、问题反馈和最新开发进展请访问 GitHub：

https://github.com/LiangLiang723/flymail⁠