部署#

                       Internet
                           │
        ┌──────────────────┼───────────────────┬──────────────┐
        │                  │                   │              │
      :25                :587/:465           :143/:993      :443
    inbound MX         submission           IMAP           HTTPS (API,
        │                  │                   │            Webmail, Admin)
        └──────────────────┴───────────────────┘              │
                           │                                  │
                  ┌────────▼──────────────────────────────────▼────────┐
                  │                  ferroma container                 │
                  │  one process: SMTP, IMAP, HTTP API, queue workers, │
                  │  sync service, event bus                          │
                  └────────┬───────────────────────────────┬──────────┘
                           │                               │
                  ┌────────▼────────┐            ┌─────────▼──────────┐
                  │ postgres:16     │            │ volume ferroma-data│
                  │ (internal only) │            │  mail/ attachments/│
                  └─────────────────┘            │  tls/ backups/     │
                                                 └────────────────────┘

$TTL 3600
$ORIGIN example.com.

; --- address ---
@               IN  A       203.0.113.10
mail            IN  A       203.0.113.10
; 只有在 IPv6 端到端确实可用时才发布 AAAA。一台宣告了 AAAA
; 却无法在其上应答的主机，会丢掉双栈发信方的邮件。
; mail          IN  AAAA    2001:db8::10

; --- mail routing ---
@               IN  MX  10  mail.example.com.

; 「null MX」表示该域不接收任何邮件。不要在已有用户的域上
; 发布它：
; @             IN  MX  0   .

; --- sender authentication ---
@               IN  TXT     "v=spf1 mx -all"

; DKIM：粘贴来自 `ferroma dkim generate` / Admin 面板的 p= 值。
default._domainkey IN TXT  "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA..."

; DMARC。先用 p=none 收集报告，再逐步收紧。
_dmarc          IN  TXT     "v=DMARC1; p=quarantine; rua=mailto:[email protected]; ruf=mailto:[email protected]; adkim=r; aspf=r; pct=100"

; --- transport security ---
_mta-sts        IN  TXT     "v=STSv1; id=20260916000000"
mta-sts         IN  CNAME   mail.example.com.
_smtp._tls      IN  TXT     "v=TLSRPTv1; rua=mailto:[email protected]"

; --- issuance control ---
@               IN  CAA     0 issue "letsencrypt.org"
@               IN  CAA     0 iodef "mailto:[email protected]"

; --- optional service hostnames (specification §42) ---
; webmail       IN  CNAME   mail.example.com.
; admin         IN  CNAME   mail.example.com.

# 全世界为你的地址看到的内容。它必须等于 FERROMA_HOSTNAME。
dig +short -x 203.0.113.10
# 预期：mail.example.com.

dig +short mail.example.com        # -> 203.0.113.10
dig +short -x 203.0.113.10         # -> mail.example.com.

@   IN  MX  10  mail.example.com.
@   IN  MX  20  mail2.example.com.

# 看看接收方会看到什么。
dig +short TXT example.com | grep spf1

_mta-sts    IN  TXT     "v=STSv1; id=20260916000000"
mta-sts     IN  CNAME   mail.example.com.

# 在 https://mta-sts.example.com/.well-known/mta-sts.txt 提供
version: STSv1
mode: enforce
mx: mail.example.com
max_age: 604800

# 一次全查。
dig +short MX  example.com
dig +short A   mail.example.com
dig +short -x  203.0.113.10
dig +short TXT example.com              | grep spf1
dig +short TXT default._domainkey.example.com
dig +short TXT _dmarc.example.com
dig +short TXT _mta-sts.example.com
curl -s https://mta-sts.example.com/.well-known/mta-sts.txt

# 问一个 DNSBL，你的 IP 是否已被列入（用一个真实的，这里只是示例）。
# 203.0.113.10 是文档保留地址，永远不会被列入。
dig +short 10.113.0.203.zen.spamhaus.org

git clone … && cd ferroma
./scripts/deploy.sh

./scripts/deploy.sh status              # 容器 / 健康 / 数据库
./scripts/deploy.sh logs
./scripts/deploy.sh backup              # 立刻备份一次（每夜自动跑）
./scripts/deploy.sh upgrade             # 先备份 → 重建镜像 → 重启 → 等健康
./scripts/deploy.sh restore /backups/20260916T030000Z
./scripts/deploy.sh dkim --enable       # 发布 TXT 记录之后打开签名
./scripts/deploy.sh certs               # 续期后重装证书并重启监听器（certbot deploy hook 调它）
./scripts/deploy.sh doctor
./scripts/deploy.sh down [--volumes]

./scripts/deploy.sh --yes --domain example.com --admin [email protected] \
  --db-password "$DB_PW" \
  --tls-cert /etc/letsencrypt/live/mail.example.com/fullchain.pem \
  --tls-key  /etc/letsencrypt/live/mail.example.com/privkey.pem

cp .env.example .env
# 编辑 .env：至少要改 POSTGRES_PASSWORD 和 FERROMA_JWT_SECRET。
docker compose up -d
docker compose logs -f ferroma

cp .env.example .env
# 编辑 .env 并设置每一个 REQUIRED 变量：见 §4。
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f ferroma

FERROMA_TLS_ENABLED: 'true'
FERROMA_TLS_CERT: /etc/ferroma/tls/fullchain.pem
FERROMA_TLS_KEY: /etc/ferroma/tls/privkey.pem
FERROMA__API__SECURE_COOKIES: 'true'
FERROMA__SMTP__REQUIRE_TLS_FOR_AUTH: 'true'
FERROMA__IMAP__REQUIRE_TLS_FOR_LOGIN: 'true'
# 隐式 TLS 监听默认是关的（0）。缺了这两行，compose 里发布的 465/993
# 映射到的是没人监听的端口——连接被拒绝，而不是报出任何错误。
FERROMA__SMTP__SMTPS_PORT: '465'
FERROMA__IMAP__IMAPS_PORT: '993'
FERROMA_DKIM_ENABLED: ${FERROMA_DKIM_ENABLED:-false}
FERROMA_DKIM_KEY: /etc/ferroma/dkim/${FERROMA_DKIM_SELECTOR:-default}.private

backup:
  image: postgres:16-alpine
  entrypoint: ['/bin/sh', '/usr/local/bin/backup.sh']
  # 循环，而不是跑一次就退出：一次性脚本挂在 restart: always 下会在每次重启退避后
  # 再写一份完整备份，直到磁盘写满。
  command: ['--loop']
  restart: unless-stopped
  volumes:
    - ./scripts/backup.sh:/usr/local/bin/backup.sh:ro
    - ferroma-data:/mail:ro
    - backups:/backups

# 跟一个服务的日志。
docker compose -f docker-compose.prod.yml logs -f --tail=200 ferroma

# 只重启 Ferroma（PostgreSQL 继续运行）。
docker compose -f docker-compose.prod.yml restart ferroma

# 容器内的一个 shell，以 ferroma 用户身份。
docker compose -f docker-compose.prod.yml exec ferroma sh

# 针对数据库开一个 psql 会话。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma

# 两个卷的磁盘占用。
docker system df -v | grep -E 'ferroma-data|ferroma-postgres-data'

# 停掉一切，保留卷。
docker compose -f docker-compose.prod.yml down

# 停掉一切并销毁卷。这会删除所有邮件与用户。
# docker compose -f docker-compose.prod.yml down -v

FERROMA__SMTP__PORT=2525
FERROMA__TLS__ENABLED=true
FERROMA__API__SECURE_COOKIES=true
FERROMA__SMTP__REQUIRE_TLS_FOR_AUTH=true
FERROMA__IMAP__REQUIRE_TLS_FOR_LOGIN=true
FERROMA__API__TRUST_PROXY_HEADERS=true
FERROMA__LIMITS__MAX_MESSAGE_SIZE=52428800

DATABASE_URL                  FERROMA_HOSTNAME        FERROMA_DATA_DIR
FERROMA_LOG_LEVEL             FERROMA_LOG_FORMAT      FERROMA_SMTP_HOST
FERROMA_SMTP_PORT             FERROMA_SMTP_SUBMISSION_PORT
FERROMA_IMAP_PORT             FERROMA_API_HOST        FERROMA_API_PORT
FERROMA_API_PUBLIC_URL        FERROMA_JWT_SECRET      FERROMA_TLS_ENABLED
FERROMA_TLS_CERT              FERROMA_TLS_KEY         FERROMA_DKIM_ENABLED
FERROMA_DKIM_KEY              FERROMA_DKIM_SELECTOR

# 生成两者，然后放进 .env。永远不要提交 .env。
openssl rand -base64 32      # POSTGRES_PASSWORD
openssl rand -base64 48      # FERROMA_JWT_SECRET

FERROMA__SMTP__SMTPS_PORT=465
FERROMA__IMAP__IMAPS_PORT=993

mkdir -p tls dkim
# 证书与私钥，无论你用什么方式取得。
ls -l tls/fullchain.pem tls/privkey.pem

# 在 .env 中
FERROMA_TLS_ENABLED=true
FERROMA_TLS_CERT=/etc/ferroma/tls/fullchain.pem
FERROMA_TLS_KEY=/etc/ferroma/tls/privkey.pem

tls.cert_path and tls.key_path must be set together (or enable self_signed_fallback)

# 添加到 docker-compose.prod.yml 的 ferroma 服务。
    ports:
      - '25:25'
      - '587:587'
      - '465:465'
      - '143:143'
      - '993:993'
      - '127.0.0.1:8080:8080'      # HTTP，绑定到回环：代理能访问它
    environment:
      FERROMA_TLS_ENABLED: 'true'  # 465 和 993 仍然需要它
      FERROMA__SMTP__SMTPS_PORT: '465'
      FERROMA__IMAP__IMAPS_PORT: '993'
      FERROMA__API__TRUST_PROXY_HEADERS: 'true'
      FERROMA__API__SECURE_COOKIES: 'true'

server {
    listen 443 ssl http2;
    server_name mail.example.com mta-sts.example.com;

    ssl_certificate     /etc/letsencrypt/live/mail.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mail.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;

    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Content-Type-Options nosniff always;
    add_header X-Frame-Options DENY always;
    add_header Referrer-Policy no-referrer always;

    client_max_body_size 30m;      # >= api.max_request_size 与 limits.max_message_size

    # MTA-STS 策略由 ferroma-api 提供，转发即可（把 mta-sts.<域名> 的 CNAME
    # 指向本机，证书也要覆盖它）。
    location /.well-known/mta-sts.txt {
        proxy_pass http://127.0.0.1:18080;
        proxy_set_header Host $host;
    }

    location / {
        proxy_pass http://127.0.0.1:18080;   # prod 栈用 8080；§3.1 的栈默认 18080
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $remote_addr;   # 覆盖，绝不追加
        proxy_set_header X-Forwarded-Proto $scheme;

        # 实时套接字需要 upgrade 握手和较长的读超时。
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600s;
    }
}

# certbot，HTTP-01。端口 80 必须可达。
sudo certbot certonly --standalone \
  -d mail.example.com -d mta-sts.example.com \
  --agree-tos -m [email protected] --no-eff-email

# 文件落在这里；把它们符号链接或复制到 ./tls/。
sudo ls -l /etc/letsencrypt/live/mail.example.com/
#   fullchain.pem  -> tls/fullchain.pem
#   privkey.pem    -> tls/privkey.pem

# 复制到挂载目录，并使用容器期望的属主
# （镜像以 uid 10001 运行）。
sudo install -o 10001 -g 10001 -m 0640 \
  /etc/letsencrypt/live/mail.example.com/fullchain.pem tls/fullchain.pem
sudo install -o 10001 -g 10001 -m 0600 \
  /etc/letsencrypt/live/mail.example.com/privkey.pem   tls/privkey.pem
docker compose -f docker-compose.prod.yml restart ferroma

# 续期演练：certbot 会真的申请一次（走 staging），并触发上面的 hook。
sudo certbot renew --dry-run

docker compose -f docker-compose.prod.yml up -d
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs ferroma | tail -50

# 或者从 shell 里驱动它。
curl -s https://mail.example.com/api/v1/setup
curl -s -X POST https://mail.example.com/api/v1/setup \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"…","hostname":"mail.example.com","domain":"example.com"}'

curl -s -X POST https://mail.example.com/api/v1/domains \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"example.com","description":"primary"}'

-- 域会被转成小写；模式强制要求这一点。
INSERT INTO domains (name, description) VALUES ('example.com', 'primary')
RETURNING id, name, enabled;

# 密码由服务器用 Argon2id 哈希；永远不要手工插入哈希值。
curl -s -X POST https://mail.example.com/api/v1/users \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"…","display_name":"Alice","quota_bytes":1073741824}'

# 给该用户挂一个地址。这会创建 Maildir 与标准文件夹。
curl -s -X POST https://mail.example.com/api/v1/users/7/mailboxes \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"domain":"example.com","local_part":"alice","is_primary":true}'

# 在容器里确认磁盘上的结果。
docker compose -f docker-compose.prod.yml exec ferroma \
  ls -la /var/lib/ferroma/mail/example.com/alice/Maildir

# 手工向本地地址做本地投递。要做真实测试就用真实的 From。
printf 'EHLO test\r\nMAIL FROM:<[email protected]>\r\nRCPT TO:<[email protected]>\r\nDATA\r\nSubject: hello\r\n\r\nfirst\r\n.\r\nQUIT\r\n' \
  | nc 127.0.0.1 25

# 它落库了吗？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT id, uid, subject, sender, size_bytes, storage_path FROM messages ORDER BY id DESC LIMIT 5;"

# 首选：CLI 直接生成 2048 位密钥，写进域记录（也可以 --out 落一个文件）。
docker compose exec ferroma ferroma dkim generate --domain example.com

# 打印要发布的 TXT 记录：
docker compose exec ferroma ferroma dkim show --domain example.com

# 或者用 OpenSSL。2048 位 RSA 是接收方期望的长度；1024 太弱，4096 验证起来太慢。
openssl genrsa -out dkim/default.private 2048
openssl rsa -in dkim/default.private -pubout -out dkim/default.public

# TXT 记录的值，写在一行里：
printf 'v=DKIM1; k=rsa; p=%s\n' \
  "$(openssl rsa -in dkim/default.private -pubout 2>/dev/null \
     | grep -v '^-----' | tr -d '\n')"

# 私钥必须只对服务用户可读（uid 10001）。
sudo chown 10001:10001 dkim/default.private
chmod 0600 dkim/default.private

default._domainkey IN TXT (
    "v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA"
    "…base64 的其余部分…"
)

dig +short TXT default._domainkey.example.com
# 预期（示例）："v=DKIM1; k=rsa; p=MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A..."

# config/ferroma.toml
[dkim]
enabled = true
selector = "default"
private_key_path = "/etc/ferroma/dkim/default.private"
canonicalization = "relaxed"
verify_inbound = true
add_auth_results = true

# 或者通过环境变量，docker-compose.prod.yml 就是这么做的。
FERROMA_DKIM_ENABLED=true
FERROMA_DKIM_SELECTOR=default
FERROMA_DKIM_KEY=/etc/ferroma/dkim/default.private
docker compose -f docker-compose.prod.yml restart ferroma

# 发一封邮件给会报告 DKIM 结果的检查器。
swaks --server mail.example.com --port 587 --tls \
      --auth PLAIN --auth-user [email protected] --auth-password '…' \
      --from [email protected] --to [email protected] \
      --body "dkim test"

# 或者读你发给自己那封邮件里的 Authentication-Results 头字段。

docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -Atc \
  "SELECT storage_path FROM messages ORDER BY id DESC LIMIT 1"

/backups/20260916T030000Z/
├── ferroma.dump      pg_dump --format=custom --compress=6
├── schema.sql        pg_dump --schema-only：一个空但正确的结构
├── maildir.tar.gz    邮件根目录的 tar -czf
├── config.tar.gz     ferroma.toml、DKIM 密钥、TLS 材料
├── MANIFEST          version、created_at、database、postgres_version、
│                     ferroma_version、hostname
└── SHA256SUMS        sha256sum ./*，这样恢复时可以证明归档完好

backup:
  image: postgres:16-alpine
  environment:
    PGHOST: postgres
    PGUSER: ${POSTGRES_USER:-ferroma}
    PGPASSWORD: ${POSTGRES_PASSWORD}
    PGDATABASE: ${POSTGRES_DB:-ferroma}
    BACKUP_DIR: /backups
    RETENTION_DAYS: ${BACKUP_RETENTION_DAYS:-14}
    BACKUP_INTERVAL_SECONDS: ${BACKUP_INTERVAL_SECONDS:-86400}
  entrypoint: ['/bin/sh', '/usr/local/bin/backup.sh']
  command: ['--loop']
  restart: unless-stopped
  volumes:
    - ./scripts/backup.sh:/usr/local/bin/backup.sh:ro
    - ferroma-data:/mail:ro
    - backups:/backups

# 跑一遍就退出（--once 是显式的「只跑一次」）。
docker compose -f docker-compose.prod.yml run --rm backup --once

# 前台循环：每 24 小时一次，保留 14 天。
docker compose -f docker-compose.prod.yml run --rm \
  -e BACKUP_INTERVAL_SECONDS=86400 -e RETENTION_DAYS=14 \
  backup --loop

# 离机存放，这才让备份成为备份。从宿主机上运行它：
docker run --rm -v ferroma-backups:/backups -v "$PWD:/out" alpine \
  tar -czf /out/ferroma-backups-$(date -u +%Y%m%d).tar.gz -C /backups .

docker compose -f docker-compose.prod.yml stop ferroma
docker compose -f docker-compose.prod.yml run --rm backup --once
docker compose -f docker-compose.prod.yml start ferroma

# 只验证：检查校验和并打印清单，不恢复任何东西。服务可以照常运行。
./scripts/deploy.sh restore /backups/20260916T030000Z --verify-only

# 完整恢复：脚本会先停 Ferroma，恢复完再拉起来并等健康检查。
./scripts/deploy.sh restore /backups/20260916T030000Z

# 等价的原始命令（external-db 栈）。
docker compose -f docker-compose.external-db.yml stop ferroma
docker compose -f docker-compose.external-db.yml --profile tools run --rm \
  restore /backups/20260916T030000Z
docker compose -f docker-compose.external-db.yml up -d ferroma

database ferroma is not empty (19 tables). Set FORCE_RESTORE=1 to overwrite,
or restore into a fresh database.

# external-db 栈：加一个 -e FORCE_RESTORE=1 就够了。
docker compose -f docker-compose.external-db.yml stop ferroma
docker compose -f docker-compose.external-db.yml --profile tools run --rm \
  -e FORCE_RESTORE=1 restore /backups/20260916T030000Z
docker compose -f docker-compose.external-db.yml up -d ferroma

./scripts/deploy.sh restore /backups/20260916T030000Z --db-only
./scripts/deploy.sh restore /backups/20260916T030000Z --mail-only

# 1. 先做检查：没有正文的行、没有对应行的文件、计数器、uid_next。
#    查询语句与 shell 循环见 docs/storage.md §9。
docker compose -f docker-compose.prod.yml exec ferroma sh -c '
  psql "$DATABASE_URL" -Atc "SELECT COUNT(*) FROM messages WHERE expunged_at IS NULL"'

# 2. 校正那些允许漂移的计数器。
#    FoldersRepository::recount 与 MailboxesRepository::recompute_usage，
#    通过 POST /api/v1/storage/gc（需要管理员令牌）与 Admin 存储界面触发。
#    curl -s -X POST https://mail.example.com/api/v1/storage/gc \
#      -H "Authorization: Bearer $TOKEN"

# 3. 启动 Ferroma 并观察头一分钟的日志。
docker compose -f docker-compose.prod.yml up -d ferroma
docker compose -f docker-compose.prod.yml logs -f --tail=100 ferroma

# 恢复到同一台宿主机上的临时数据库，不碰生产。
docker compose -f docker-compose.prod.yml exec postgres createdb -U ferroma ferroma_drill
docker compose -f docker-compose.prod.yml exec postgres \
  pg_restore --no-owner --no-privileges --dbname=ferroma_drill /backups/…/ferroma.dump
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma_drill -c 'SELECT COUNT(*) FROM messages;'
docker compose -f docker-compose.prod.yml exec postgres dropdb -U ferroma ferroma_drill

# 1. 先备份。永远。升级是第二可能需要它的时刻。
docker compose -f docker-compose.prod.yml run --rm backup --once
# external-db 栈上一步到位：./scripts/deploy.sh upgrade（备份 → 重建 → 重启 → 等健康）

# 2. 阅读发布说明里的迁移与配置变更。
#    一个新的必填键，或一个被移除的键，会让新版本在启动时停下
#    （未知键会被拒绝）。

# 3. 更新镜像标签。Prod 从不从源码构建。
sed -i 's/^FERROMA_VERSION=.*/FERROMA_VERSION=0.2.0/' .env

# 4. 只拉取并重建 ferroma 服务。
docker compose -f docker-compose.prod.yml pull ferroma
docker compose -f docker-compose.prod.yml up -d ferroma

# 5. 看着它起来。
docker compose -f docker-compose.prod.yml logs -f --tail=100 ferroma

# 把镜像回滚。
sed -i 's/^FERROMA_VERSION=.*/FERROMA_VERSION=0.1.0/' .env
docker compose -f docker-compose.prod.yml pull ferroma
docker compose -f docker-compose.prod.yml up -d ferroma

docker compose -f docker-compose.external-db.yml stop ferroma
docker compose -f docker-compose.external-db.yml --profile tools run --rm \
  -e FORCE_RESTORE=1 restore /backups/<pre-upgrade-stamp>
docker compose -f docker-compose.external-db.yml up -d ferroma

{
  "status": "ok",
  "version": "0.1.0",
  "protocol_version": 1,
  "uptime_secs": 84213,
  "database": { "ok": true, "server_version": "PostgreSQL 16.15",
                "pool": { "size": 4, "idle": 3, "max": 20 } },
  "smtp": { "enabled": true, "connections": 3 },
  "imap": { "enabled": true, "connections": 1 },
  "queue": { "pending": 0, "delivering": 0, "retry": 2, "failed": 1 }
}

docker compose -f docker-compose.prod.yml exec ferroma \
  ferroma healthcheck --url http://127.0.0.1:8080/api/v1/health

# 或者不用 CLI。
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'wget -qO- http://127.0.0.1:8080/api/v1/health || echo unreachable'

# 队列，按状态分组。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT status, COUNT(*) FROM mail_queue GROUP BY status ORDER BY 2 DESC;"

# 等待重试中最久的那一条。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT id, recipient, attempts, next_attempt_at, last_status_code, left(last_error,60)
     FROM mail_queue WHERE status IN ('pending','retry')
    ORDER BY next_attempt_at LIMIT 20;"

# 存储。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT pg_size_pretty(pg_database_size('ferroma')) AS db,
          (SELECT COUNT(*) FROM messages WHERE expunged_at IS NULL) AS live_messages,
          (SELECT COUNT(*) FROM users) AS users,
          (SELECT COUNT(*) FROM domains) AS domains;"
du -sh "$(docker volume inspect -f '{{.Mountpoint}}' ferroma-data)"

# 过去一天的登录失败。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT email, ip, COUNT(*) FROM login_attempts
    WHERE NOT success AND created_at > NOW() - INTERVAL '1 day'
    GROUP BY email, ip ORDER BY 3 DESC LIMIT 20;"

# 只看错误。
docker compose -f docker-compose.prod.yml logs ferroma | grep -i '"level":"ERROR"'

# 关于某个 message id 的一切。
docker compose -f docker-compose.prod.yml logs ferroma | grep '4821'

# 一次失败的投递。
docker compose -f docker-compose.prod.yml logs ferroma | grep -i 'delivery'

# 实时到来的新日志行，已过滤。
docker compose -f docker-compose.prod.yml logs -f ferroma | grep -E 'WARN|ERROR'

# 1. PTR 与 FERROMA_HOSTNAME 一致吗，它指回来吗？
dig +short -x 203.0.113.10            # 必须等于 FERROMA_HOSTNAME
dig +short mail.example.com           # 必须是同一个地址
grep FERROMA_HOSTNAME .env

# 2. SPF 存在吗，是唯一一条吗，以 -all 结尾吗？
dig +short TXT example.com | grep spf1

# 3. DKIM 记录发布了吗，与你用来签名的密钥匹配吗？
dig +short TXT default._domainkey.example.com
openssl rsa -in dkim/default.private -pubout 2>/dev/null | grep -v '^-----' | tr -d '\n'

# 4. DMARC 存在吗？
dig +short TXT _dmarc.example.com

# 5. 这个 IP 在黑名单上吗？
dig +short 10.113.0.203.zen.spamhaus.org

# 6. 队列在报告带远端状态码的失败吗？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT recipient, last_status_code, last_status_text FROM mail_queue
    WHERE status = 'failed' ORDER BY updated_at DESC LIMIT 10;"

# 1. 来自互联网的连接到底有没有到达端口 25？
#    从你网络之外的一台机器上：
nc -vz mail.example.com 25

# 2. MX 记录能解析吗，是你以为的那台主机吗？
dig +short MX example.com
dig +short A mail.example.com

# 3. Ferroma 在容器内监听 25 吗？
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'netstat -tlnp 2>/dev/null || ss -tlnp'

# 4. 连接到底有没有到？如果一行日志都没有，它就从未到达这里。
docker compose -f docker-compose.prod.yml logs ferroma | grep -i 'connection\|reject\|550\|554'

# 5. 从外部看证书有效吗？
openssl s_client -starttls smtp -connect mail.example.com:25 -crlf < /dev/null 2>&1 | head -30

# 6. 问候名与 PTR 一致吗？
printf 'EHLO test\r\nQUIT\r\n' | nc mail.example.com 25

# 1. 队列真的在增长吗，第一次尝试是最近的吗？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT status, COUNT(*), MIN(next_attempt_at), MAX(created_at)
     FROM mail_queue GROUP BY status;"

# 2. 主要的失败都说了什么？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT recipient, attempts, last_status_code, last_error
     FROM mail_queue WHERE status IN ('retry','failed')
    ORDER BY attempts DESC LIMIT 20;"

# 3. 一次卡住的投递的尝试历史。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT a.attempt, a.remote_mx, a.status_code, a.status_text, a.duration_ms, a.created_at
     FROM delivery_attempts a JOIN mail_queue q ON q.id = a.queue_id
    WHERE q.id = 1234 ORDER BY a.attempt;"

# 4. 这台主机到底能不能在端口 25 上连到远端的 MX？
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'nc -vz gmail-smtp-in.l.google.com 25'

# 5. 出站 25 被供应商封了吗？从宿主机上测。
nc -vz alt1.gmail-smtp-in.l.google.com 25

# 6. 调度程序到底在跑吗？
docker compose -f docker-compose.prod.yml logs ferroma | grep -i 'queue\|dispatch'
grep -A6 '^\[queue\]' config/ferroma.toml

-- 谁发得最多？
SELECT user_id, COUNT(*) FROM mail_queue
 WHERE created_at > NOW() - INTERVAL '1 hour'
 GROUP BY user_id ORDER BY 2 DESC LIMIT 10;

# 1. IMAP 在监听吗？
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'netstat -tlnp 2>/dev/null | grep -E "143|993"'

# 2. 问候语与能力列表说了什么？
openssl s_client -crlf -connect mail.example.com:143 < /dev/null 2>&1 | head -20
# 隐式 TLS：
openssl s_client -connect mail.example.com:993 < /dev/null 2>&1 | head -20

# 3. 试一次真实登录。
printf 'a LOGIN [email protected] "…"\r\nb LOGOUT\r\n' | \
  openssl s_client -quiet -crlf -connect mail.example.com:143

# 4. 是否要求 TLS，你的客户端在做吗？
grep -E 'require_tls_for_login|imaps_port' config/ferroma.toml
grep FERROMA__IMAP__REQUIRE_TLS_FOR_LOGIN .env

# 5. 账号被登录限流锁了吗？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT id, email, enabled, failed_logins, locked_until FROM users WHERE email='[email protected]';"

# 6. 最近的尝试说了什么？
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT email, ip, success, created_at FROM login_attempts
    ORDER BY created_at DESC LIMIT 20;"

# 7. 服务器对这次失败的看法。
docker compose -f docker-compose.prod.yml logs ferroma | grep -i 'imap\|login'

# 1. 健康检查，从容器内部发起。
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'wget -qO- http://127.0.0.1:8080/api/v1/health || echo unreachable'

# 2. 容器健康吗？
docker compose -f docker-compose.prod.yml ps
docker inspect -f '{{.State.Health.Status}} restarts={{.RestartCount}}' ferroma

# 3. 它为什么退出？
docker compose -f docker-compose.prod.yml logs --tail=200 ferroma | grep -iE 'error|panic|config'

# 4. 一个配置拼写错误会让服务器在启动时停下。这是有意设计的。
docker compose -f docker-compose.prod.yml run --rm ferroma \
  ferroma serve --config /etc/ferroma/ferroma.toml

# 数据库相信的情况。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT m.id, d.name||'@'||m.local_part AS addr, u.used_bytes, u.quota_bytes
     FROM mailboxes m JOIN domains d ON d.id=m.domain_id JOIN users u ON u.id=m.user_id
    ORDER BY u.used_bytes DESC LIMIT 10;"

# 磁盘上实际的情况。
docker compose -f docker-compose.prod.yml exec ferroma \
  du -sb /var/lib/ferroma/mail/example.com/alice

# 构成总数的那些文件。
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'find /var/lib/ferroma/mail/example.com/alice -type f -printf "%s %p\n" | sort -rn | head -20'

# 在哪。
du -sh /var/lib/docker/volumes/ferroma-data/_data/*
du -sh /var/lib/docker/volumes/ferroma-data/_data/mail/*

# 中断写入留下的垃圾。
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'find /var/lib/ferroma/mail -type d -name tmp -exec du -sh {} +'

# 未被引用的附件二进制对象。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -Atc 'SELECT DISTINCT storage_path FROM attachments' | wc -l
docker compose -f docker-compose.prod.yml exec ferroma \
  sh -c 'find /var/lib/ferroma/attachments -type f ! -name "*.tmp" | wc -l'

# 已清除但仍占着文件的邮件。
docker compose -f docker-compose.prod.yml exec postgres \
  psql -U ferroma -d ferroma -c \
  "SELECT COUNT(*), pg_size_pretty(SUM(size_bytes)) FROM messages WHERE expunged_at IS NOT NULL;"