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 解决口令撞库。五项配完,一个公网可达的联邦节点才收敛成一个内部可控的通信服务。