🚀 FireMail Plus 部署指南

本指南提供多种部署方式，涵盖 Docker Compose 快速部署（推荐）、Docker CLI 部署、源码本地构建部署 以及 ARM64 架构（如甲骨文云、树莓派）专门部署事项与 FAQ。

目录

• ✨ 环境要求
• 📦 方式一：Docker Compose 快速部署（推荐）
• 🐳 方式二：Docker CLI 一键运行
• 🛠️ 方式三：源码本地构建部署 (包含 ARM64 架构)
• ⚙️ 环境变量说明
• ❓ 常见问题排查 (FAQ)

✨ 环境要求

• 操作系统：Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+ 等)
• 支持架构：x86_64 / amd64 及 aarch64 / arm64 (如甲骨文云 ARM、树莓派)
• 依赖工具：Docker 20.10+ 及 Docker Compose v2+

📦 方式一：Docker Compose 快速部署（推荐）

这是最简单、最稳妥的部署方式。不需要安装 Node.js 或 Go 环境，全过程只需 1 分钟。

1. 创建部署工作目录

mkdir -p ~/firemail && cd ~/firemail

2. 创建 docker-compose.yml 配置文件

在终端运行以下命令一键写入配置文件：

cat << 'EOF' > docker-compose.yml
services:
  firemail:
    image: luofengyuan/firemailplus:main-1b3a711
    container_name: firemail-app
    ports:
      - "15865:15865"
    volumes:
      - firemail_data:/app/data
      - firemail_logs:/app/logs
    environment:
      - HOST=0.0.0.0
      - PORT=8080
      - FRONTEND_PORT=15865
      - ENV=development
      - GIN_MODE=release
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=admin123
      - JWT_SECRET=your_jwt_secret_key_123456
      - DB_PATH=/app/data/firemail.db
      - DATABASE_URL=/app/data/firemail.db
      - ENABLE_REAL_EMAIL_SYNC=true
      - NODE_ENV=production
      - NEXT_PUBLIC_API_BASE_URL=/api/v1
    restart: unless-stopped

volumes:
  firemail_data:
    driver: local
  firemail_logs:
    driver: local

networks:
  default:
    name: firemail_network
EOF

3. 启动服务

docker-compose up -d

4. 放行服务器防火墙端口

如果使用的是甲骨文云或阿里云/腾讯云，请确保开放 15865 端口：

# Linux 系统防火墙放行
sudo iptables -I INPUT -p tcp --dport 15865 -j ACCEPT
sudo netfilter-persistent save 2>/dev/null || true

5. 访问与默认凭据

访问地址：http://<你的服务器IP>:15865

• 默认账号：admin
• 默认密码：admin123

🐳 方式二：Docker CLI 一键运行

如果你不想使用 Compose 文件，可以直接用单条 docker run 命令启动：

# 创建持久化存储卷
docker volume create firemail_data
docker volume create firemail_logs

# 运行容器
docker run -d \
  --name firemail-app \
  --restart unless-stopped \
  -p 15865:15865 \
  -v firemail_data:/app/data \
  -v firemail_logs:/app/logs \
  -e ADMIN_USERNAME=admin \
  -e ADMIN_PASSWORD=admin123 \
  -e JWT_SECRET=your_jwt_secret_key_123456 \
  -e FRONTEND_PORT=15865 \
  -e HOST=0.0.0.0 \
  -e PORT=8080 \
  -e ENV=development \
  luofengyuan/firemailplus:main-1b3a711

🛠️ 方式三：源码本地构建部署

适合开发者二次开发或自行在 ARM64 架构上进行源码编译。

1. 克隆代码仓库

git clone https://github.com/fengyuanluo/firemailplus.git
cd firemailplus

2. 补全 scripts/start.sh 脚本

mkdir -p scripts
cat << 'EOF' > scripts/start.sh
#!/bin/sh
set -e

mkdir -p /app/data /app/logs /app/data/backups
chmod -R 777 /app/data || true
chmod -R 755 /app/logs || true
chmod +x /app/backend/firemail

# 启动后端
cd /app/backend
HOST=$HOST PORT=$BACKEND_PORT /app/backend/firemail &
BACKEND_PID=$!
cd /app

sleep 2
if ! kill -0 $BACKEND_PID 2>/dev/null; then
    echo "[start.sh] ERROR: Go backend failed to start!"
    exit 1
fi

# 启动前端
cd /app/frontend
PORT=$FRONTEND_PORT HOSTNAME=0.0.0.0 NEXT_PUBLIC_API_BASE_URL=$NEXT_PUBLIC_API_BASE_URL exec node server.js
EOF
chmod +x scripts/start.sh

3. 构建并启动

docker-compose build --no-cache
docker-compose up -d

⚙️ 环境变量说明

❓ 常见问题排查 (FAQ)

Q1：登录时提示“服务器响应格式错误: 500”？

• 原因：由于历史旧数据卷残留了加密失败的密码哈希，或者生产模式（ENV=production）下使用了默认的弱密码 admin123 导致后端初始化被安全策略拦截崩溃。

• 解决办法：

  1. 彻底清理旧的数据卷：docker-compose down -v
  2. 将环境变量中的 ENV 设置为 development，重新执行 docker-compose up -d 即可。

Q2：甲骨文云 ARM 服务器部署后网页无法打开？

• 原因：甲骨文系统的安全组规则和系统自带的 iptables 防火墙默认封禁了未放行的端口。

• 解决办法：
  在终端中执行放行命令：

  sudo iptables -I INPUT -p tcp --dport 15865 -j ACCEPT
  sudo netfilter-persistent save 2>/dev/null || true

  并在甲骨文云控制台的入站规则（Inbound Rules）中添加放行 15865 端口。

Q3：如何查看日志诊断服务运行状态？

# 查看实时运行日志
docker-compose logs -f

# 查看后端容器历史日志最后50行
docker logs --tail 50 firemail-app