FireMail Plus 项目部署

举报
yd_229065422 发表于 2026/11/13 20:35:48 2026/11/13
【摘要】 一、功能概览类别说明多邮箱聚合同时管理多个账号,支持 Gmail、Outlook、QQ 邮箱、163 邮箱、自定义 IMAP/SMTP认证方式OAuth2(Gmail、Outlook)与自定义 IMAP/SMTP 密码;Gmail 目前仅支持应用专用密码登录实时同步基于服务器推送(SSE)的实时邮件同步搜索全文搜索与高级过滤附件附件上传、下载与预览界面响应式设计,适配桌面与移动端;支持明暗...

一、功能概览

类别 说明
多邮箱聚合 同时管理多个账号,支持 Gmail、Outlook、QQ 邮箱、163 邮箱、自定义 IMAP/SMTP
认证方式 OAuth2(Gmail、Outlook)与自定义 IMAP/SMTP 密码;Gmail 目前仅支持应用专用密码登录
实时同步 基于服务器推送(SSE)的实时邮件同步
搜索 全文搜索与高级过滤
附件 附件上传、下载与预览
界面 响应式设计,适配桌面与移动端;支持明暗主题自动切换
运维友好 内置健康检查与日志系统,具备数据库自动备份机制
多架构镜像 镜像提供 amd64 与 arm64 两种架构,树莓派等设备可用,镜像体积较小(约 86MB)

二、部署方案选择

方案 适用场景 说明
Docker Compose 长期使用、生产环境 官方推荐,克隆仓库后使用其中的 Compose 文件
Docker CLI 快速体验、测试 一条命令启动,本文第四章给出完整示例
源码运行 二次开发 需 Go 环境与 pnpm,前端默认 3000 端口,后端默认 8080 端口

本文以 Docker 为主。


三、环境要求

  • Linux 服务器或家用主机(amd64 或 arm64)
  • Docker Engine 与 Docker Compose 插件
  • 内存:512MB 以上即可;磁盘:取决于同步的邮件与附件量
  • 默认服务端口:3000
  • 服务器能够主动访问目标邮箱的 IMAP 与 SMTP 服务(常用 993、465、587 端口)。部分云厂商会限制出站的 25 端口,但 465 与 587 通常可用
  • 若使用公网域名,需要域名解析与 HTTPS 反向代理

四、Docker 部署

4.1 Docker CLI 快速启动

# 1. 拉取镜像
docker pull luofengyuan/firemailplus:latest

# 2. 创建数据卷
docker volume create firemail_data
docker volume create firemail_logs

# 3. 生成密钥
openssl rand -hex 32   # 用作 JWT_SECRET
openssl rand -hex 32   # 用作 ENCRYPTION_KEY

# 4. 运行容器
docker run -d \
  --name firemail-app \
  --restart unless-stopped \
  -p 3000:3000 \
  -v firemail_data:/app/data \
  -v firemail_logs:/app/logs \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=请替换为强密码 \
  -e JWT_SECRET=填入第一个随机值 \
  -e ENCRYPTION_KEY=填入第二个随机值 \
  luofengyuan/firemailplus:latest

# 5. 查看状态与日志
docker ps
docker logs -f firemail-app

说明:

  • 容器内数据目录为 /app/data,日志目录为 /app/logs,务必挂载为持久化卷。
  • ENCRYPTION_KEY 在官方说明中是可选项,用于加密保存的邮箱凭据。建议配置,并和 JWT_SECRET 一起长期保存。
  • 官方 README 的示例里还带有一个 EXTERNAL_OAUTH_SERVER_URL 变量,指向作者提供的第三方 OAuth 中转服务,详见本文第六章。

4.2 Docker Compose(推荐长期使用)

官方方式是克隆仓库,复制环境变量模板后启动:

git clone 仓库地址 firemailplus   # 仓库为 fengyuanluo 名下的 firemailplus
cd firemailplus
cp .env.example .env
# 编辑 .env:修改管理员密码与 JWT_SECRET,建议同时配置 ENCRYPTION_KEY
docker compose up -d
docker compose ps
docker compose logs -f

注意:README 中写的是 docker-compose(带连字符),新版 Docker 请使用 docker compose(带空格)。

如果想自己维护 Compose 文件,可以参考下面按 4.1 命令改写的版本:

services:
  firemail:
    image: luofengyuan/firemailplus:latest
    container_name: firemail-app
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - firemail_data:/app/data
      - firemail_logs:/app/logs
    environment:
      ADMIN_USERNAME: admin
      ADMIN_PASSWORD: ${ADMIN_PASSWORD}
      JWT_SECRET: ${JWT_SECRET}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}

volumes:
  firemail_data:
  firemail_logs:

同目录下的 .env:

ADMIN_PASSWORD=请替换为强密码
JWT_SECRET=请替换为随机值
ENCRYPTION_KEY=请替换为随机值

要点:

  • 端口绑定到 127.0.0.1,由反向代理对外提供 HTTPS,避免明文暴露。
  • .env 含有密钥,不要提交到代码仓库。
  • 变量名与容器内路径来自官方 Docker CLI 示例,若你使用的镜像版本有调整,请以仓库里的 .env.example 为准。
  • 镜像标签:latest 与带提交编号的标签(例如 main 开头的标签)都可使用。生产环境建议固定到某个具体标签,升级时再手动修改。

4.3 首次登录

访问「服务器IP地址:3000」,使用环境变量里设置的管理员账号登录。

  • 默认管理员账号是 admin,默认密码是 admin123(官方建议修改)。这是公开信息,部署时务必通过环境变量改成强密码,不要使用默认值。
  • 登录后,在账号管理中添加你的邮箱。

五、添加邮箱账号

5.1 通用 IMAP/SMTP

选择自定义邮箱,填写:

项目 说明
IMAP 服务器与端口 收信,常见为 993(SSL)
SMTP 服务器与端口 发信,常见为 465(SSL)或 587(STARTTLS)
用户名与密码 多数邮箱要求使用「授权码」或「应用专用密码」,而不是登录密码

5.2 各类邮箱提示

邮箱 提示
QQ 邮箱、163 邮箱 需要先在邮箱设置中开启 IMAP/SMTP 服务,并生成授权码,客户端填写授权码
Gmail 目前仅支持应用专用密码登录,需要账号开启两步验证后生成应用密码
Outlook 支持 OAuth2 登录;个人账号的基础认证策略可能变化,以微软当前规则为准

5.3 安全建议

  • 优先使用授权码或应用专用密码,不要把主密码交给任何第三方客户端,包括自建的。
  • 该工具会保存你的邮箱凭据(经加密),所以服务器本身与其备份都必须当作高敏感资产保护。
  • 邮件内容往往含验证码、账单、重置链接,部署在公网时更要重视访问控制。

六、关于外部 OAuth 服务

官方示例里的 EXTERNAL_OAUTH_SERVER_URL 指向作者提供的第三方 OAuth 服务,用于配合 Gmail、Outlook 的 OAuth2 授权流程。我的理解是:

  • 如果你只使用 IMAP/SMTP 授权码或应用密码方式,通常不依赖这项服务。
  • 如果要使用 OAuth2 登录,授权过程会经过该第三方服务器,你需要信任它。
  • 对隐私要求高的场景,建议先阅读仓库说明,评估是否使用,或自行申请 OAuth 应用并按项目文档配置。

这部分属于我对 README 的解读,不同版本的行为可能不同,请以仓库说明为准。


七、反向代理与 HTTPS

Caddy 示例:

mail.你的域名 {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000
}

使用 Nginx 时请注意:

  • 项目使用服务器推送(SSE)做实时同步,需要关闭对该路径的代理缓冲(proxy_buffering off),并延长读超时,否则新邮件提醒会延迟。
  • 适当调大请求体大小限制,以便上传较大的附件。
  • 保持升级头与长连接设置正常。

额外建议:

  • 在代理层或防火墙上限制访问来源,或放在 VPN 之后使用。
  • 为管理员账号使用强密码,并定期更换。

八、备份与恢复

8.1 备份内容

内容 说明
数据卷 firemail_data 应用数据,包括账号、设置、同步数据与数据库
JWT_SECRET 与 ENCRYPTION_KEY 必须长期保存,丢失后无法解密已保存的邮箱凭据
Compose 与 .env 部署配置
日志卷 firemail_logs 按需备份,通常不是必须

官方 README 对此有明确警告:JWT_SECRET 要长期保存;如果配置了 ENCRYPTION_KEY 也必须保存,否则历史邮箱凭据无法解密。

8.2 备份方法

在容器停止或低峰时执行,使用临时容器打包数据卷:

docker run --rm \
  -v firemail_data:/data:ro \
  -v "$PWD":/backup \
  alpine tar czf /backup/firemail-data-$(date +%F).tar.gz -C /data .

注意:

  • 项目自身有数据库自动备份机制,但那些备份也在同一台服务器上,不能替代异地备份。
  • 备份文件包含凭据密文,请加密保存并同步到异地,遵循 3-2-1 原则:3 份副本、2 种介质、1 份异地。
  • 邮件本身仍保存在你的邮箱服务商处,这里备份的是客户端的配置与同步数据,两者要区分。

8.3 恢复

  1. 部署相同或兼容版本的镜像。
  2. 把备份解压回数据卷。
  3. 使用原来的 JWT_SECRET 与 ENCRYPTION_KEY 启动。
  4. 登录后检查邮箱账号是否能正常连接。

九、升级与维护

# Docker Compose
cd firemailplus
docker compose pull
docker compose up -d
docker image prune

# Docker CLI
docker pull luofengyuan/firemailplus:latest
docker stop firemail-app && docker rm firemail-app
# 然后用原来的 docker run 命令(含数据卷和环境变量)重新启动

建议:

  • 升级前先备份数据卷,并留意仓库的更新说明。
  • 查看项目与镜像的更新频率。作为个人项目,更新节奏可能不固定,选用前应确认它仍在维护,并关注安全修复。
  • 固定镜像标签,避免意外升级带来行为变化。
  • 定期查看日志与健康状态,确认邮箱同步正常。

十、安全检查清单

  1. 管理员密码是否已改掉默认值?
  2. JWT_SECRET 与 ENCRYPTION_KEY 是否为随机强值,并已备份到安全位置?
  3. 服务是否只通过 HTTPS 对外提供,3000 端口是否只绑定本机?
  4. 邮箱是否使用授权码或应用专用密码,而不是主密码?
  5. 是否评估并决定了是否使用第三方 OAuth 中转服务?
  6. 数据卷与备份是否加密保存?
  7. 是否限制了访问来源,或放在 VPN 之后?

十一、常见问题排查

现象 可能原因 处理办法
无法访问页面 端口未放行或容器未启动 检查端口映射、防火墙与容器日志
默认账号登录失败 已通过环境变量改了账号密码 使用你设置的用户名与密码
邮箱连接失败 服务器不能访问 IMAP/SMTP 端口,或使用了登录密码 检查出站网络,改用授权码或应用密码
QQ 或 163 邮箱登录失败 未开启 IMAP/SMTP 服务或授权码错误 在邮箱设置中开启服务并重新生成授权码
Gmail 登录失败 未开启两步验证或未使用应用密码 开启两步验证并生成应用专用密码
新邮件延迟出现 反向代理缓冲了 SSE 关闭缓冲并延长超时
重启后账号凭据全部失效 密钥变化 使用原来的 JWT_SECRET 与 ENCRYPTION_KEY
数据丢失 没有挂载数据卷 确认 /app/data 已持久化
附件上传失败 反向代理请求体限制 调大限制
OAuth 登录失败 外部授权服务不可用或配置不匹配 改用授权码方式,或检查相关配置

十二、命令速查

# 启动 / 停止 / 重启(Compose)
docker compose up -d
docker compose down
docker compose restart

# 查看日志
docker logs -f firemail-app

# 生成随机密钥
openssl rand -hex 32

# 升级(Compose)
docker compose pull && docker compose up -d

# 备份数据卷
docker run --rm -v firemail_data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/firemail-data-$(date +%F).tar.gz -C /data .

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。