Matrix Synapse 服务端加固实战:联邦收口

Matrix Synapse 加固的第一原则是:把「联邦」当成一个默认关闭的功能来对待。Synapse 的设计目标是让任意域名之间自由互通,这意味着一旦公网可达,全世界的 homeserver 都能向你发起请求、投递事件、拉取媒体。对内部团队使用的实例来说,这份开放性没有业务价值,却是最大的攻击面。

本文以 Synapse 1.9x 为例,从注册入口、联邦暴露面、媒体存储、管理 API、登录限速五个方面给出可复制的 homeserver.yaml 与 Nginx 配置,并说明每项配置对应的实际风险。

适用场景

  • 团队自建 Matrix 用于内部沟通,不需要与外部 homeserver 联邦
  • 实例曾被扫到 /_matrix/client/r0/register 并被批量注册机器人账号
  • 媒体目录被当成图床外链传播,磁盘与带宽被非业务流量占满
  • 需要通过 SSO 登录并关闭本地密码体系,减少口令泄露面

前置条件

  • Synapse 1.90 及以上,Python 3.11 环境,PostgreSQL 13+(生产环境不建议 SQLite)
  • 配置文件 /etc/matrix-synapse/homeserver.yaml,数据目录 /var/lib/matrix-synapse
  • 域名与证书就绪:客户端走 matrix.example.com:443,联邦走 example.com:8448
  • 日常运维账号具备 admin 权限,用于创建用户与查看房间
  • 注意:homeserver.yaml 含 registration_shared_secret 与数据库口令,文件权限应为 640 且属主为 matrix-synapse

原理说明

Synapse 的暴露面由三类监听决定:Client-Server API(默认 8008)给客户端用,Federation API(默认 8448)给其他 homeserver 用,以及管理 API(/_synapse/admin)给运维用。三者共用同一个进程,靠路径区分,所以路径级拦截必须在反向代理层做,不能指望应用自己区分。

注册链路是最常见的入侵点。默认配置虽然 enable_registration: false,但不少教程会让人打开它以方便建号,同时又没设置 registration_shared_secret 对应的验证环节,结果任何人都能注册。正确的做法是:注册永久关闭,账号一律用 register_new_matrix_user 在服务器上创建,或走 SSO 自动建号。

联邦层面,federation_domain_whitelist 是唯一的白名单机制。把它设为一个空列表意味着「谁都不许联邦」,但这并不等于对外完全静默——其他服务器仍可能向 8448 发起请求并触发密钥查询。真正要做到零联邦,最稳的做法是不在公网暴露 8448,并让 .well-known 不指向本域。

媒体存储是第二个高频问题。Synapse 会把收到的每个附件按内容哈希落盘,并保留缩略图,max_upload_size 只限制单文件,不限制总量。被当成图床后,磁盘会在几周内被填满,且这些文件的访问路径不需要登录(联邦媒体接口 /_matrix/media/v3/download 默认可匿名读取)。

操作步骤

1. 关闭注册与访客访问

sudo cp /etc/matrix-synapse/homeserver.yaml /etc/matrix-synapse/homeserver.yaml.bak

sudo python3 - <<'PY'
import re, pathlib
p = pathlib.Path("/etc/matrix-synapse/homeserver.yaml")
s = p.read_text()

def setkv(text, key, val):
    pat = re.compile(r"^%s:.*$" % re.escape(key), re.M)
    if pat.search(text):
        return pat.sub("%s: %s" % (key, val), text, count=1)
    return text + "\n%s: %s\n" % (key, val)

s = setkv(s, "enable_registration", "false")
s = setkv(s, "enable_registration_without_verification", "false")
s = setkv(s, "allow_guest_access", "false")
s = setkv(s, "report_stats", "false")
p.write_text(s)
print("done")
PY

# 强随机共享密钥(仅在需要命令行建号时使用,务必妥善保存)
python3 -c "import secrets; print(secrets.token_urlsafe(48))"

sudo systemctl restart matrix-synapse

把生成的随机串填入 registration_shared_secret,随后用官方脚本建号,日常运维不再需要打开注册开关:

sudo -u matrix-synapse register_new_matrix_user \
  -c /etc/matrix-synapse/homeserver.yaml \
  -u alice -a --no-password https://matrix.example.com

2. 联邦暴露面收口

不需要联邦的实例,直接把白名单置空并把 8448 从公网撤下:

# 白名单为空 = 拒绝任何外部 homeserver 联邦
sudo tee -a /etc/matrix-synapse/homeserver.yaml > /dev/null <<'EOF'

federation_domain_whitelist: []

trusted_key_servers:
  - server_name: "matrix.org"
EOF

# 只监听回环,联邦端口不对公网开放
sudo python3 - <<'PY'
import yaml, pathlib
p = pathlib.Path("/etc/matrix-synapse/homeserver.yaml")
cfg = yaml.safe_load(p.read_text())
for lst in cfg.get("listeners", []):
    if lst.get("port") == 8448:
        lst["bind_addresses"] = ["127.0.0.1"]
        lst["resources"] = [{"names": ["federation"], "compress": False}]
p.write_text(yaml.safe_dump(cfg, allow_unicode=True, sort_keys=False))
print("listeners patched")
PY

sudo systemctl restart matrix-synapse

若确有联邦需求,则改为按域名白名单放行,并保留 8448 的 TLS 监听;两种模式不要混用——白名单为空却仍暴露端口,等于把请求放进来到最后一步才拒绝,白白承担解析与密钥查询开销。

3. Nginx 分层反代与路径拦截

server {
    listen 443 ssl;
    http2 on;
    server_name matrix.example.com;

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

    add_header Strict-Transport-Security "max-age=31536000" always;
    add_header X-Content-Type-Options "nosniff" always;

    client_max_body_size 50m;

    # 管理 API 只允许内网
    location /_synapse/admin {
        allow 10.0.0.0/8;
        allow 127.0.0.1;
        deny  all;
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
    }

    # 注册接口直接拒绝,即使误开注册也进不来
    location ~ ^/_matrix/client/(r0|v3)/register {
        return 403;
    }

    location /_matrix {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 300s;
    }

    location / {
        proxy_pass http://127.0.0.1:8008;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4. 媒体存储与上传限制

sudo tee -a /etc/matrix-synapse/homeserver.yaml > /dev/null <<'EOF'

media_store_path: "/var/lib/matrix-synapse/media"
max_upload_size: "20M"
max_image_pixels: "16M"
media_retention:
  local_media_lifetime: 90d
  remote_media_lifetime: 14d
EOF

sudo chown -R matrix-synapse:matrix-synapse /var/lib/matrix-synapse/media
sudo chmod 750 /var/lib/matrix-synapse/media
sudo systemctl restart matrix-synapse

media_retention 让过期媒体被后台任务定期清理,本地媒体 90 天、联邦媒体 14 天是内部团队的常用值。若历史存量已经很大,先用 du -sh 确认目录体积,再手动触发一次清理,避免直接删目录导致数据库引用断裂。

5. 登录限速与口令策略

Synapse 的限速按 rc_* 前缀分接口族配置,rc_login 是防撞库的核心项,per_second 表示每秒允许的请求数,burst_count 是突发桶容量:

sudo tee -a /etc/matrix-synapse/homeserver.yaml > /dev/null <<'EOF'

rc_login:
  address:
    per_second: 0.17
    burst_count: 3
  account:
    per_second: 0.17
    burst_count: 3
  failed_attempts:
    per_second: 0.17
    burst_count: 3

rc_registration:
  per_second: 0.01
  burst_count: 1

rc_message:
  per_second: 5
  burst_count: 20

password_config:
  enabled: true
  localdb:
    enabled: false
EOF

sudo systemctl restart matrix-synapse

localdb.enabled=false 会关闭本地密码校验,只允许 SSO/OIDC 登录。这项改动不可逆地影响所有本地账号,切换前必须确认 OIDC 提供方(如 Keycloak、Authentik)已可用,并保留一个管理员账号的应急口令。

6. 数据库与文件权限

sudo -u postgres psql <<'SQL'
CREATE ROLE synapse LOGIN PASSWORD '强随机口令';
CREATE DATABASE synapse OWNER synapse ENCODING 'UTF8';
REVOKE ALL ON DATABASE synapse FROM PUBLIC;
GRANT CONNECT ON DATABASE synapse TO synapse;
SQL

# 配置文件含密钥,收紧到仅服务账号可读
sudo chown matrix-synapse:matrix-synapse /etc/matrix-synapse/homeserver.yaml
sudo chmod 640 /etc/matrix-synapse/homeserver.yaml
sudo ss -tlnp | grep -E '8008|8448'

配置验证

# 1) 客户端版本接口应 200,且不含 federation 相关信息外泄
curl -s https://matrix.example.com/_matrix/client/versions | head -c 300

# 2) 注册接口必须 403
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  -H "Content-Type: application/json" \
  -d '{"username":"probe","password":"x","auth":{"type":"m.login.dummy"}}' \
  https://matrix.example.com/_matrix/client/v3/register

# 3) 管理 API 从公网访问应 403
curl -s -o /dev/null -w '%{http_code}\n' https://matrix.example.com/_synapse/admin/v1/users

# 4) 8448 不应在公网网卡监听
ss -tlnp | grep 8448

# 5) 联邦关闭后,外部探测应失败
curl -s -o /dev/null -w '%{http_code}\n' https://matrix.example.com/_matrix/federation/v1/version

预期:版本接口 200 并返回协议版本列表;注册返回 403;管理 API 返回 403;8448 只出现在 127.0.0.1;联邦版本接口返回 404 或 403。

常见问题

FAQ 1:关闭联邦后,客户端提示「无法获取服务器密钥」怎么办?

客户端启动时会请求 /_matrix/key/v2/server 获取本域签名密钥,这与联邦无关,属于本地密钥查询。若该接口 404,通常是 Nginx 的 location /_matrix 匹配顺序被更精确的规则抢先。把 /_matrix/key 单独放行到 8008 即可,不要与 /_matrix/federation 一起拦截。

FAQ 2:把 localdb 关掉后管理员账号登不进去了?

先确认 OIDC 提供方可用,再临时把 localdb.enabled 改回 true 重启,用管理员账号登录后为该账号绑定 SSO 身份,随后再关闭。生产环境建议先新增一个 SSO 管理员并验证其能访问 /_synapse/admin,确认无误后再关闭本地口令,避免把自己锁在门外。

FAQ 3:媒体目录清理后,历史图片变成灰色占位?

这是 retention 策略的预期结果:超过 local_media_lifetime 的本地媒体会被删除,房间中对应的事件仍存在,但媒体已不可取回。若需要长期留存,应把生命周期设为 0 或更大值,并将媒体目录纳入独立备份,不要与数据库备份混在同一策略里。

总结

Synapse 的加固逻辑与普通 Web 应用相反:它的默认行为是「尽可能开放地与他人通信」,所以每一项都需要主动关掉。enable_registration 关掉解决批量注册,federation_domain_whitelist 置空加撤下 8448 解决外部投递,Nginx 层 403 掉 /register 与 /_synapse/admin 解决误配兜底,media_retention 加 max_upload_size 解决存储滥用,rc_login 加 localdb.enabled=false 解决口令撞库。五项配完,一个公网可达的联邦节点才收敛成一个内部可控的通信服务。