Debian 版 Forward Email 自托管安装指南

概述

本指南提供在 Debian 系统上安装 Forward Email 自托管解决方案的分步说明。本指南专门针对 Debian 11（Bullseye）和 Debian 12（Bookworm）系统。

先决条件

在开始安装之前，请确保您已：

Debian 服务器：版本 11（Bullseye）或 12（Bookworm）
根访问权限：您必须能够以 root 身份运行命令（sudo 访问权限）
域名：您拥有 DNS 管理访问权限的域名
清洁服务器：建议使用全新 Debian 安装
互联网连接：下载软件包和 Docker 镜像所需

系统要求

RAM：最低 2GB（生产环境建议 4GB）
贮存：最低 20GB 可用空间（生产环境建议 50GB 以上）
CPU：至少 1 个 vCPU（建议生产环境使用 2 个以上的 vCPU）
网络：可访问以下端口的公共 IP 地址：
- 22 (SSH)
- 25 (SMTP)
- 80 (HTTP)
- 443 (HTTPS)
- 465 (SMTPS)
- 993 (IMAPS)
- 995 (POP3S)

分步安装

步骤 1：初始系统设置

首先，确保您的系统是最新的，并切换到 root 用户：

# Update system packages sudo apt update && sudo apt upgrade -y Switch to root user (required for the installation)

sudo su -

步骤2：配置DNS解析器

配置您的系统以使用 Cloudflare 的 DNS 服务器来生成可靠的证书：

# Stop and disable systemd-resolved if running if systemctl is-active --quiet systemd-resolved; then rm /etc/resolv.conf systemctl stop systemd-resolved systemctl disable systemd-resolved systemctl mask systemd-resolved fi Configure Cloudflare DNS resolvers

tee /etc/resolv.conf > /dev/null <<EOF nameserver 1.1.1.1 nameserver 2606:4700:4700::1111 nameserver 1.0.0.1 nameserver 2606:4700:4700::1001 nameserver 8.8.8.8 nameserver 2001:4860:4860::8888 nameserver 8.8.4.4 nameserver 2001:4860:4860::8844 EOF

步骤3：安装系统依赖项

在 Debian 上安装转发电子邮件所需的软件包：

# Update package list
apt-get update -y
Install basic dependencies (Debian-specific package list)
apt-get install -y 

ca-certificates 

curl 

gnupg 

git 

openssl 

lsb-release 

apt-transport-https 

software-properties-common

步骤4：安装并配置Snapd

Debian 默认不包含 snapd，所以我们需要安装并配置它：

# Install snapd apt-get install -y snapd Enable and start snapd service systemctl enable snapd systemctl start snapd Create symlink for snap to work properly ln -sf /var/lib/snapd/snap /snap Wait for snapd to be ready sleep 10 Verify snapd is working

snap version

步骤5：安装Snap包

通过 snap 安装 AWS CLI 和 Certbot：

# Install AWS CLI snap install aws-cli --classic Install Certbot and DNS plugin snap install certbot --classic snap set certbot trust-plugin-with-root=ok snap install certbot-dns-cloudflare Verify installations

aws --version certbot --version

步骤6：安装Docker

在 Debian 上安装 Docker CE 和 Docker Compose：

# Add Docker's official GPG key (Debian-specific)
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | tee /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
Add Docker repository (Debian-specific)
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list
Update package index and install Docker
apt-get update -y
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Install standalone docker-compose as fallback (if plugin doesn't work)
if ! command -v docker-compose &> /dev/null; then
apt-get install -y docker-compose
fi
Verify Docker installation
docker --version
docker compose version || docker-compose --version

步骤7：配置Docker服务

确保 Docker 自动启动并运行：

# Enable and start Docker service systemctl unmask docker systemctl enable docker systemctl start docker Verify Docker is running

docker info

如果 Docker 启动失败，请尝试手动启动：

# Alternative startup method if systemctl fails
nohup dockerd >/dev/null 2>/dev/null &
sleep 5
docker info

步骤8：安装并配置UFW防火墙

Debian 最小安装可能不包含 UFW，因此请先安装它：

# Install UFW if not present if ! command -v ufw &> /dev/null; then apt-get update -y apt-get install -y ufw fi Set default policies ufw default deny incoming ufw default allow outgoing Allow SSH (important - don't lock yourself out!) ufw allow 22/tcp Allow email-related ports ufw allow 25/tcp # SMTP ufw allow 80/tcp # HTTP (for Let's Encrypt) ufw allow 443/tcp # HTTPS ufw allow 465/tcp # SMTPS ufw allow 993/tcp # IMAPS ufw allow 995/tcp # POP3S ufw allow 2993/tcp # IMAP (alternative port) ufw allow 2995/tcp # POP3 (alternative port) ufw allow 3456/tcp # Custom service port ufw allow 4000/tcp # Custom service port ufw allow 5000/tcp # Custom service port Allow local database connections ufw allow from 127.0.0.1 to any port 27017 # MongoDB ufw allow from 127.0.0.1 to any port 6379 # Redis Enable firewall echo "y" | ufw enable Check firewall status

ufw status numbered

步骤9：克隆转发电子邮件存储库

下载转发电子邮件源代码：

# Set up variables REPO_FOLDER_NAME="forwardemail.net" REPO_URL="https://github.com/forwardemail/forwardemail.net.git" ROOT_DIR="/root/$REPO_FOLDER_NAME" Clone the repository git clone "$REPO_URL" "$ROOT_DIR" cd "$ROOT_DIR" Verify the clone was successful

ls -la

步骤10：设置环境配置

准备环境配置：

# Set up directory variables SELF_HOST_DIR="$ROOT_DIR/self-hosting" ENV_FILE_DEFAULTS=".env.defaults" ENV_FILE=".env" Copy default environment file cp "$ROOT_DIR/$ENV_FILE_DEFAULTS" "$SELF_HOST_DIR/$ENV_FILE" Create SSL directory mkdir -p "$SELF_HOST_DIR/ssl" Create database directories

mkdir -p "$SELF_HOST_DIR/sqlite-data" mkdir -p "$SELF_HOST_DIR/mongo-backups" mkdir -p "$SELF_HOST_DIR/redis-backups"

步骤11：配置您的域

设置您的域名并更新环境变量：

# Replace 'yourdomain.com' with your actual domain
DOMAIN="yourdomain.com"
Function to update environment file
update_env_file() {
local key="$1"
local value="$2"
if grep -qE "^${key}=" "$SELF_HOST_DIR/$ENV_FILE"; then
sed -i -E "s|^${key}=.*|${key}=${value}|" "$SELF_HOST_DIR/$ENV_FILE"
else
echo "${key}=${value}" >> "$SELF_HOST_DIR/$ENV_FILE"
fi
}
Update domain-related environment variables
update_env_file "DOMAIN" "$DOMAIN"
update_env_file "NODE_ENV" "production"
update_env_file "HTTP_PROTOCOL" "https"
update_env_file "WEB_HOST" "$DOMAIN"
update_env_file "WEB_PORT" "443"
update_env_file "CALDAV_HOST" "caldav.$DOMAIN"
update_env_file "CARDDAV_HOST" "carddav.$DOMAIN"
update_env_file "API_HOST" "api.$DOMAIN"
update_env_file "APP_NAME" "$DOMAIN"
update_env_file "SMTP_HOST" "smtp.$DOMAIN"
update_env_file "SMTP_PORT" "465"
update_env_file "IMAP_HOST" "imap.$DOMAIN"
update_env_file "IMAP_PORT" "993"
update_env_file "POP3_HOST" "pop3.$DOMAIN"
update_env_file "POP3_PORT" "995"
update_env_file "MX_HOST" "mx.$DOMAIN"
update_env_file "SMTP_EXCHANGE_DOMAINS" "mx.$DOMAIN"
update_env_file "SELF_HOSTED" "true"
update_env_file "WEBSITE_URL" "$DOMAIN"
update_env_file "AUTH_BASIC_ENABLED" "true"

步骤12：生成SSL证书

选项 A：手动 DNS 质询（推荐大多数用户使用）

# Generate certificates using manual DNS challenge
certbot certonly \
  --manual \
  --agree-tos \
  --preferred-challenges dns \
  -d "*.$DOMAIN" \
  -d "$DOMAIN"

重要的：出现提示时，您需要在 DNS 中创建 TXT 记录。您可能会看到针对同一域名的多个质询 - 创建所有。添加第二条 TXT 记录时，请勿删除第一条 TXT 记录。

选项 B：Cloudflare DNS（如果您使用 Cloudflare）

如果您的域使用 Cloudflare 作为 DNS，您可以自动生成证书：

# Create Cloudflare credentials file cat > /root/.cloudflare.ini <<EOF dns_cloudflare_email = "your-email@example.com" dns_cloudflare_api_key = "your-cloudflare-global-api-key" EOF Set proper permissions chmod 600 /root/.cloudflare.ini Generate certificates automatically

certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.cloudflare.ini -d "$DOMAIN" -d "*.$DOMAIN" --non-interactive --agree-tos --email "your-email@example.com"

复印证书

证书生成后，将其复制到应用程序目录：

# Copy certificates to application SSL directory cp /etc/letsencrypt/live/$DOMAIN*/* "$SELF_HOST_DIR/ssl/" Verify certificates were copied

ls -la "$SELF_HOST_DIR/ssl/"

步骤13：生成加密密钥

创建安全操作所需的各种加密密钥：

# Generate helper encryption key
helper_encryption_key=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32)
update_env_file "HELPER_ENCRYPTION_KEY" "$helper_encryption_key"
Generate SRS secret for email forwarding
srs_secret=$(openssl rand -base64 32 | tr -d /=+ | cut -c -32)
update_env_file "SRS_SECRET" "$srs_secret"
Generate TXT encryption key
txt_encryption_key=$(openssl rand -hex 16)
update_env_file "TXT_ENCRYPTION_KEY" "$txt_encryption_key"
Generate DKIM private key for email signing
openssl genrsa -f4 -out "$SELF_HOST_DIR/ssl/dkim.key" 2048
update_env_file "DKIM_PRIVATE_KEY_PATH" "/app/ssl/dkim.key"
Generate webhook signature key
webhook_signature_key=$(openssl rand -hex 16)
update_env_file "WEBHOOK_SIGNATURE_KEY" "$webhook_signature_key"
Set SMTP transport password
update_env_file "SMTP_TRANSPORT_PASS" "$(openssl rand -base64 32)"
echo "✅ All encryption keys generated successfully"

步骤14：更新配置中的SSL路径

在环境文件中配置 SSL 证书路径：

# Update SSL paths to point to the correct certificate files
sed -i -E \
  -e 's|^(.*_)?SSL_KEY_PATH=.*|\1SSL_KEY_PATH=/app/ssl/privkey.pem|' \
  -e 's|^(.*_)?SSL_CERT_PATH=.*|\1SSL_CERT_PATH=/app/ssl/fullchain.pem|' \
  -e 's|^(.*_)?SSL_CA_PATH=.*|\1SSL_CA_PATH=/app/ssl/chain.pem|' \
  "$SELF_HOST_DIR/$ENV_FILE"

步骤15：设置基本身份验证

创建临时基本身份验证凭证：

# Generate a secure random password
PASSWORD=$(openssl rand -base64 16)
Update environment file with basic auth credentials
update_env_file "AUTH_BASIC_USERNAME" "admin"
update_env_file "AUTH_BASIC_PASSWORD" "$PASSWORD"
Display credentials (save these!)
echo ""
echo "🔐 IMPORTANT: Save these login credentials!"
echo "=================================="
echo "Username: admin"
echo "Password: $PASSWORD"
echo "=================================="
echo ""
echo "You'll need these to access the web interface after installation."
echo ""

步骤 16：使用 Docker Compose 进行部署

启动所有转发电子邮件服务：

# Set Docker Compose file path DOCKER_COMPOSE_FILE="$SELF_HOST_DIR/docker-compose-self-hosted.yml" Stop any existing containers if command -v docker-compose &> /dev/null; then docker-compose -f "$DOCKER_COMPOSE_FILE" down else docker compose -f "$DOCKER_COMPOSE_FILE" down fi Pull the latest images if command -v docker-compose &> /dev/null; then docker-compose -f "$DOCKER_COMPOSE_FILE" pull else docker compose -f "$DOCKER_COMPOSE_FILE" pull fi Start all services in detached mode if command -v docker-compose &> /dev/null; then docker-compose -f "$DOCKER_COMPOSE_FILE" up -d else docker compose -f "$DOCKER_COMPOSE_FILE" up -d fi Wait a moment for services to start sleep 10 Check service status

if command -v docker-compose &> /dev/null; then docker-compose -f "$DOCKER_COMPOSE_FILE" ps else docker compose -f "$DOCKER_COMPOSE_FILE" ps fi

步骤17：验证安装

检查所有服务是否正常运行：

# Check Docker containers
docker ps
Check service logs for any errors
if command -v docker-compose &> /dev/null; then
docker-compose -f "$DOCKER_COMPOSE_FILE" logs --tail=50
else
docker compose -f "$DOCKER_COMPOSE_FILE" logs --tail=50
fi
Test web interface connectivity
curl -I https://$DOMAIN
Check if ports are listening
ss -tlnp | grep -E ':(25|80|443|465|587|993|995)'

安装后配置

DNS 记录设置

您需要为您的域配置以下 DNS 记录：

MX记录

@ MX 10 mx.yourdomain.com

A 记录

@ A YOUR_SERVER_IP
mx A YOUR_SERVER_IP
smtp A YOUR_SERVER_IP
imap A YOUR_SERVER_IP
pop3 A YOUR_SERVER_IP
api A YOUR_SERVER_IP
caldav A YOUR_SERVER_IP
carddav A YOUR_SERVER_IP

SPF 记录

@ TXT "v=spf1 mx ~all"

DKIM记录

获取您的 DKIM 公钥：

# Extract DKIM public key
openssl rsa -in "$SELF_HOST_DIR/ssl/dkim.key" -pubout -outform DER | openssl base64 -A

创建 DKIM DNS 记录：

default._domainkey TXT "v=DKIM1; k=rsa; p=YOUR_DKIM_PUBLIC_KEY"

DMARC 记录

_dmarc TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"

打开您的网络浏览器并导航至 https://yourdomain.com
输入您之前保存的基本身份验证凭据
完成初始设置向导
创建您的第一个电子邮件帐户

备份配置

设置与 S3 兼容的备份

配置自动备份到 S3 兼容存储：

# Create AWS credentials directory
mkdir -p ~/.aws
Configure AWS credentials
cat > ~/.aws/credentials <<EOF
[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY
EOF
Configure AWS settings
cat > ~/.aws/config <<EOF
[default]
region = auto
output = json
EOF
For non-AWS S3 (like Cloudflare R2), add endpoint URL
echo "endpoint_url = YOUR_S3_ENDPOINT_URL" >> ~/.aws/config

设置备份 Cron 作业

# Make backup scripts executable
chmod +x "$ROOT_DIR/self-hosting/scripts/backup-mongo.sh"
chmod +x "$ROOT_DIR/self-hosting/scripts/backup-redis.sh"
Add MongoDB backup cron job (runs daily at midnight)
(crontab -l 2>/dev/null; echo "0 0 * * * $ROOT_DIR/self-hosting/scripts/backup-mongo.sh >> /var/log/mongo-backup.log 2>&1") | crontab -
Add Redis backup cron job (runs daily at midnight)
(crontab -l 2>/dev/null; echo "0 0 * * * $ROOT_DIR/self-hosting/scripts/backup-redis.sh >> /var/log/redis-backup.log 2>&1") | crontab -
Verify cron jobs were added
crontab -l

自动更新配置

为您的转发电子邮件安装设置自动更新：

# Create auto-update command (use appropriate docker compose command)
if command -v docker-compose &> /dev/null; then
    DOCKER_UPDATE_CMD="docker-compose -f $DOCKER_COMPOSE_FILE pull && docker-compose -f $DOCKER_COMPOSE_FILE up -d"
else
    DOCKER_UPDATE_CMD="docker compose -f $DOCKER_COMPOSE_FILE pull && docker compose -f $DOCKER_COMPOSE_FILE up -d"
fi
Add auto-update cron job (runs daily at 1 AM)
(crontab -l 2>/dev/null; echo "0 1 * * * $DOCKER_UPDATE_CMD >> /var/log/autoupdate.log 2>&1") | crontab -
Verify the cron job was added
crontab -l

Debian 特定的注意事项

包管理差异

Snapd：Debian 上默认不安装，需要手动安装
Docker：使用 Debian 特定的存储库和 GPG 密钥
UFW：可能不包含在最小 Debian 安装中
系统：行为可能与 Ubuntu 略有不同

服务管理

# Check service status (Debian-specific commands) systemctl status snapd systemctl status docker systemctl status ufw Restart services if needed

systemctl restart snapd systemctl restart docker

网络配置

Debian 可能有不同的网络接口名称或配置：

# Check network interfaces ip addr show Check routing ip route show Check DNS resolution

nslookup google.com

维护和监控

日志位置

Docker Compose 日志：根据安装情况使用适当的docker compose命令
系统日志: /var/log/syslog
备份日志: /var/log/mongo-backup.log, /var/log/redis-backup.log
自动更新日志: /var/log/autoupdate.log
Snapd 日志: journalctl -u snapd

定期维护任务

监控磁盘空间: df -h
检查服务状态：使用适当的 docker compose 命令
审查日志：检查应用程序和系统日志
更新系统包: apt update && apt upgrade
监控快照: snap list 和 snap refresh

证书续订

证书应该自动更新，但您可以根据需要手动更新：

# Manual certificate renewal certbot renew Copy renewed certificates cp /etc/letsencrypt/live/$DOMAIN*/* "$SELF_HOST_DIR/ssl/" Restart services to use new certificates

if command -v docker-compose &> /dev/null; then docker-compose -f "$DOCKER_COMPOSE_FILE" restart else docker compose -f "$DOCKER_COMPOSE_FILE" restart fi

故障排除

Debian 特定问题

1. Snapd 无法正常工作

# Check snapd status
systemctl status snapd
Restart snapd
systemctl restart snapd
Check snap path
echo $PATH | grep snap
Add snap to PATH if missing
echo 'export PATH=$PATH:/snap/bin' >> ~/.bashrc
source ~/.bashrc

2. 未找到 Docker Compose 命令

# Check which docker compose command is available command -v docker-compose command -v docker Use the appropriate command in scripts

if command -v docker-compose &> /dev/null; then echo "Using docker-compose" else echo "Using docker compose" fi

3. 软件包安装问题

# Update package cache
apt update
Fix broken packages
apt --fix-broken install
Check for held packages
apt-mark showhold

常见问题

1. Docker 服务无法启动

# Check Docker status systemctl status docker Check Docker logs journalctl -u docker Try alternative startup

nohup dockerd >/dev/null 2>/dev/null &

2. 证书生成失败

确保端口 80 和 443 可访问
验证 DNS 记录指向您的服务器
使用以下方式检查防火墙设置 ufw status

3.电子邮件传递问题

验证 MX 记录是否正确
检查 SPF、DKIM 和 DMARC 记录
确保端口 25 未被托管服务提供商阻止

获取帮助

文档: https://forwardemail.net/self-hosted
GitHub 问题: https://github.com/forwardemail/forwardemail.net/issues
Debian 文档: https://www.debian.org/doc/

安全最佳实践

保持系统更新：定期更新 Debian 和软件包
监控日志：设置日志监控和警报
定期备份：测试备份和恢复程序
使用强密码：为所有帐户生成强密码
启用 Fail2Ban：考虑安装 fail2ban 以获得额外的安全性
定期安全审计：定期检查您的配置
监控快照：使用以下方式保持 snap 包更新 snap refresh

结论

您的 Forward Email 自托管安装现已完成，并在 Debian 上运行。请记住：

正确配置您的 DNS 记录
测试电子邮件发送和接收
设置定期备份
定期监控您的系统
保持安装更新
监控 snapd 和 snap 包

与 Ubuntu 的主要区别在于 snapd 安装和 Docker 仓库配置。正确设置后，“转发电子邮件”应用程序在两个系统上的运行方式完全相同。

有关其他配置选项和高级功能，请参阅转发电子邮件官方文档 https://forwardemail.net/self-hosted#configuration.

Debian 版 Forward Email 自托管安装指南

步骤 1：初始系统设置

Switch to root user (required for the installation)

步骤2：配置DNS解析器

Configure Cloudflare DNS resolvers

步骤3：安装系统依赖项

Install basic dependencies (Debian-specific package list)

步骤4：安装并配置Snapd

Enable and start snapd service

Create symlink for snap to work properly

Wait for snapd to be ready

Verify snapd is working

步骤5：安装Snap包

Install Certbot and DNS plugin

Verify installations

步骤6：安装Docker

Add Docker repository (Debian-specific)

Update package index and install Docker

Install standalone docker-compose as fallback (if plugin doesn't work)

Verify Docker installation

步骤7：配置Docker服务

Verify Docker is running

步骤8：安装并配置UFW防火墙

Set default policies

Allow SSH (important - don't lock yourself out!)

Allow email-related ports

Allow local database connections

Enable firewall

Check firewall status

步骤9：克隆转发电子邮件存储库

Clone the repository

Verify the clone was successful

步骤10：设置环境配置

Copy default environment file

Create SSL directory

Create database directories

步骤11：配置您的域

Function to update environment file

Update domain-related environment variables

步骤12：生成SSL证书

选项 A：手动 DNS 质询（推荐大多数用户使用）

选项 B：Cloudflare DNS（如果您使用 Cloudflare）

Set proper permissions

Generate certificates automatically

复印证书

Verify certificates were copied

步骤13：生成加密密钥

Generate SRS secret for email forwarding

Generate TXT encryption key

Generate DKIM private key for email signing

Generate webhook signature key

Set SMTP transport password

步骤14：更新配置中的SSL路径

步骤15：设置基本身份验证

Update environment file with basic auth credentials

Display credentials (save these!)

步骤 16：使用 Docker Compose 进行部署

Stop any existing containers

Pull the latest images

Start all services in detached mode

Wait a moment for services to start

Check service status

步骤17：验证安装

Check service logs for any errors

Test web interface connectivity

Check if ports are listening

DNS 记录设置

MX记录

A 记录

SPF 记录

DKIM记录

DMARC 记录

首次登录

设置与 S3 兼容的备份

Configure AWS credentials

Configure AWS settings

For non-AWS S3 (like Cloudflare R2), add endpoint URL

设置备份 Cron 作业

Add MongoDB backup cron job (runs daily at midnight)

Add Redis backup cron job (runs daily at midnight)