Synapse/Element v1.163.0 配置参数详解

目标：逐项讲透 Synapse v1.163.0 主配置 homeserver.yaml 与 Element Web 配置 config.json 的核心参数，每个关键参数组都配「修改 → 重启 → 验证生效」的实测闭环，并给出可直接套用的生产配置模板。已在 Ubuntu 22.04 + Synapse v1.163.0（部署方法见 《Synapse/Element v1.163.0 Docker Compose 部署指南》）实测通过。

一、环境信息

二、前置条件

1. 已按部署指南完成 Synapse + Element 双服务搭建并能登录（安装过程与全链路验证见部署篇）。
2. 配置文件的修改入口在宿主机目录 /opt/synapse/data/（Synapse）与 /opt/synapse/element-config/（Element）；服务内路径分别为 /data 与 /app/config.json。
3. 掌握「改配置 → 重启 → 验证」的三板斧命令（下文所有闭环都用它）：

cd /opt/synapse
docker compose restart synapse    # homeserver.yaml 生效
docker compose restart element    # config.json 生效
docker compose logs synapse --tail 20   # 启动日志（配置错误首屏即现）

⚠️ 注意：homeserver.yaml 是严格缩进的 YAML，列表元素缩进必须一致（官方配置文档开头即强调）；改完先看启动日志再验功能，避免「改了没生效其实是没启动成功」。

三、参数查看与修改方式

3.1 查看：generate 基线与官方文档

当前生效配置的「出厂基线」是 generate 生成的 homeserver.yaml（全文回显见部署篇 4.3）。参数全集与默认值以官方配置文档为准（https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html，2026-10-21 查证），本文凡引用默认值均以该文档为据。

仓库内置的 synapse.config 模块可打印其用法（v1.163.0 发行包内实测，该构建只提供配置生成类选项，未提供子命令式校验）：

docker compose exec synapse python -m synapse.config --help

usage: __main__.py [-h] [-c CONFIG_FILE] [--keys-directory DIRECTORY]
                   [--no-secrets-in-config] [-D] [--print-pidfile]
                   [--manhole PORT] [-d SQLITE_DATABASE_PATH] [-n]
                   [--enable-registration]
options:
  -h, --help            show this help message and exit
  -c, --config-path CONFIG_FILE
                        Specify config file. Can be given multiple times and
                        may specify directories containing *.yaml files.
  --keys-directory DIRECTORY
                        Where files such as certs and signing keys are stored
                        when their location is not given explicitly in the
                        config. Defaults to the directory containing the last
                        config file

3.2 修改与生效闭环（标准动作）

vi /opt/synapse/data/homeserver.yaml   # 修改参数
docker compose restart synapse          # 重启生效
docker compose logs synapse --tail 20   # 无 Error in configuration 即通过

配置错误时服务会直接拒绝启动并在日志给出原因，例如 3.5 节的注册校验报错。以下各节均以「修改内容 → 重启 → 验证回显」的完整闭环展开。

四、参数总览

homeserver.yaml 参数量数百个，按运维关注度分组如下（★ 为本文含实测闭环的参数组）：

五、核心参数分类详解

5.1 服务器身份：server_name 与 public_baseurl

server_name: "matrix.local"

• 作用：整个服务器的唯一身份，出现在每个用户 ID（@admin:matrix.local）与房间 ID 里；签名密钥文件名、日志配置文件名也由它派生。
• 默认值：generate 时由 SYNAPSE_SERVER_NAME 写入，此后不可随意更改——改了等于全服务器用户换身份证，历史数据全部失联。
• 验证：登录接口回显 home_server 字段（实测：{"user_id":"@admin:matrix.local",...,"home_server":"matrix.local",...}）。
• public_baseurl（默认不设，取 server_name）：对外公布的完整基础 URL，配置 OIDC 回调、邮箱验证链接、联邦well-known 时必须显式设置。本文内网场景以 http://192.168.146.128:8141 访问，未启用联邦故未设置；启用联邦时设为 https://matrix.<真实域名>/。

💡 技术拓展：server_name 与监听地址是「身份」与「传输」两层概念，允许不同——身份层靠 DNS SRV/.well-known 服务发现把 matrix.local 指到实际 host:port。小型部署通常两者相同；需要把服务端藏在 8448 以外端口或反代后面时，用 /.well-known/matrix/server 指路，server_name 保持纯域名。

5.2 存储：database 与媒体路径（★含切换要点）

database:
  name: sqlite3
  args:
    database: /data/homeserver.db
media_store_path: /data/media_store

• database.name：sqlite3（默认，generate 所得）或 psycopg2（PostgreSQL）。SQLite 单文件便于备份，适合几十到几百用户；官方文档明确建议规模化生产使用 PostgreSQL（官方「Using Postgres」页口径）。
• 切 PostgreSQL 的写法（官方文档标准形态，需先建库并注入连接环境变量，见部署篇第六章 POSTGRES_* 变量）：

database:
  name: psycopg2
  args:
    user: synapse
    password: "${POSTGRES_PASSWORD}"
    database: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

⚠️ 注意：password 一项是本节唯一的占位示例——生产真实口令请注入环境变量，不要明文入库；其余演示值全部落实际值。SQLite→PostgreSQL 的历史数据迁移用官方 synapse_port_db 工具（实测用法见 《Synapse/Element v1.163.0 Admin API 与 CLI 工具详解》），不是改配置就能搬数据。

• media_store_path：媒体（图片/文件/头像）落盘目录，默认 /data/media_store；磁盘规划按「用户数 × 日均上传量」估算，企业内网一般预留 50–100GB 起步。

5.3 监听器：listeners 与 enable_metrics（★完整闭环）

generate 生成的监听器：

listeners:
  - port: 8008
    resources:
    - compress: false
      names:
      - client
      - federation
    tls: false
    type: http
    x_forwarded: true

逐项说明：

• port：监听端口；官方镜像默认 8008（本文映射宿主机 8141）。
• resources.names：该监听器挂载的资源面，client（含 Admin API）、federation、metrics、replication 可组合；compress 控制 HTTP 压缩。
• tls：false 表示明文 HTTP（由外层反代终结 TLS，容器化部署的主流做法）；true 时 Synapse 自持证书。
• x_forwarded: true：信任反代传入的 X-Forwarded-For（限流与审计取真实 IP，前置反代时必开）。

实测闭环：新增 Prometheus 指标监听。在 listeners 下追加 metrics 监听并打开总开关：

enable_metrics: true

listeners:
  - port: 8008
    resources:
    - compress: false
      names:
      - client
      - federation
    tls: false
    type: http
    x_forwarded: true
  - port: 9000
    type: metrics
    bind_addresses:
      - '0.0.0.0'

⚠️ 排障实录：只加 listeners 段、不加 enable_metrics: true 时，重启后 9000 端口静默不监听（启动日志无任何报错，仅有 Starting metrics listener 缺席）。两处都配置后重启生效。

重启并验证（在服务网络内抓取，9000 未发布到宿主机端口故宿主机 curl 不通属预期）：

docker compose restart synapse && sleep 13
docker compose exec synapse curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://127.0.0.1:9000/_synapse/metrics
docker compose exec synapse curl -s http://127.0.0.1:9000/_synapse/metrics | wc -l

实测回显：

HTTP 200
1260

指标样例（实测头部）：

# HELP python_gc_objects_collected_total Objects collected during gc
# TYPE python_gc_objects_collected_total counter
python_gc_objects_collected_total{generation="0"} 11911.0
python_gc_objects_collected_total{generation="1"} 1182.0

💡 说明：Prometheus 抓取配置中 target 指向服务网络内的 synapse:9000（而非宿主机映射端口）；需要宿主机访问时再在 compose 的 ports 里映射 9000。

5.4 注册与共享密钥（★核心安全参数）

generate 自动写入的三个密钥参数（实测生成值，演示环境）：

registration_shared_secret: "US&am;b2mR3dCi1YrHv1D4AeU01H.Yd,wuIujYL+1,,vH:KG~X"
macaroon_secret_key: "*f^+#1n&qb5FcwESTILh^9wFx=TSo8A#Rzb28EN,fHukca,@bI"
form_secret: "t7oUJdhL7nMD&TnCZjRlv=rsdg7SDt6_otQn7sJiuBm7KRhWvO"

• registration_shared_secret：注册共享密钥。register_new_matrix_user CLI 与 Admin 注册接口（/_synapse/admin/v1/register）靠它向服务器证明「我是管理员」。泄露即可任意开户，等同半个管理员权限，生产环境必须轮换并妥善保管。
• macaroon_secret_key：access_token 的签名密钥，轮换会使所有已登录会话失效（用户需重新登录）。
• form_secret：Web 表单防伪造签名密钥，保持默认随机值即可。

注册开关组（本文实测闭环，报错原文与解决见部署篇 FAQ Q2）：

enable_registration: true
enable_registration_without_verification: true

• enable_registration（默认 false）：允许自助注册。
• enable_registration_without_verification（默认 false）：不配邮箱/验证码校验时的豁免开关。实测只开第一项时服务拒绝启动，日志原文：

Error in configuration:
  You have enabled open registration without any verification. This is a known vector for spam and abuse. If you would like to allow public registration, please consider adding email, captcha, or token-based verification. Otherwise this check can be removed by setting the `enable_registration_without_verification` config option to `true`.

• 验证生效的三种实测手段：① 页面注册流程可用；② register_new_matrix_user 注册成功（回显 Success!）；③ Admin API 用户列表出现新账号（见命令篇）。
• 生产建议：关闭 without_verification，改用 registrations_require_3pid: [email]（强制邮箱验证）或注册令牌机制（registration_requires_token: true + Admin API 签发令牌）。

5.5 限流组：rc_login 等（★完整闭环）

默认限流在批量验证/自动化场景非常容易触发，实测报错：

{"errcode":"M_LIMIT_EXCEEDED","error":"Too Many Requests","retry_after_ms":85252}

放宽配置（内网/演示口径）：

rc_login:
  account:
    per_second: 5
    burst_count: 50
  address:
    per_second: 5
    burst_count: 50
  failed_attempts:
    per_second: 5
    burst_count: 50

• account：按账号限登录；address：按来源 IP 限登录；failed_attempts：按失败次数限（防爆破）。
• per_second 为持续速率，burst_count 为突发桶容量；默认值极小（官方文档默认 account 为 0.17/s、桶 3），演示环境放宽后实测连续登录不再触发限流（同一账号登录立即成功，无需等待 retry_after_ms）。
• 同族参数：rc_message（发消息频率）、rc_admin_api（Admin API 频率）、rc_registration（注册接口）；生产环境保持默认或小幅上调，failed_attempts 一组不建议放宽（防爆破价值）。

5.6 媒体参数

max_upload_size: 50M        # 默认 10M；内网传大文件常上调到 50M/100M
max_image_pixels: 32M       # 默认 32M 像素，防解压炸弹
url_preview_enabled: false  # URL 预览（外网抓取），内网建议关

• max_upload_size 调大后需同步调整前置反代的 client_max_body_size，否则反代先一步 413。
• 开启 url_preview_enabled: true 必须配 url_preview_ip_range_blacklist（官方默认给出完整黑名单），否则服务器会被诱导请求内网地址（SSRF 风险）。

5.7 联邦参数

trusted_key_servers:
  - server_name: "matrix.org"

• trusted_key_servers：联邦签名密钥的信任锚（用于校验其他服务器密钥服务的签名链），默认 matrix.org；纯内网不联邦时可删。
• federation_domain_whitelist：配置后只与白名单内服务器联邦（不配=全开放）。
• 联邦监听：标准端口 8448/TLS；部署篇默认未发布该端口，开启联邦时再映射并配置证书。内网纯单机部署可在监听器 resources 中去掉 federation 彻底关联邦。

5.8 身份服务集成位：ma1sd（官方口径，未实测联调）

Synapse 不内置邮箱/手机号目录服务，官方设计是委托给 Matrix Identity Server；自托管场景最常用 ma1sd（https://github.com/ma1uta/ma1sd，2026-10-21 查证）。集成配置位：

account_threepid_delegates:
  email: http://ma1sd:8090      # 邮箱验证/查找委托
  msisdn: http://ma1sd:8090     # 手机号验证/查找委托

• 配置后，注册时的邮箱验证码、跨服务器联系人查找都由 ma1sd 承担；这也是替代 enable_registration_without_verification 的正规姿势（邮箱验证注册）。
• 本文实验未部署 ma1sd，以上为官方配置文档口径（config_documentation「Account Data」/3PID 章节，2026-10-21 查证）；ma1sd 自身的数据库、SMTP、LDAP 对接在其官方文档。联调后的实操篇视需求另行成文。

5.9 日志配置：log_config

generate 生成的日志配置在 /opt/synapse/data/matrix.local.log.config，根级别默认 INFO。调 DEBUG 排障（改 root 段 level 后 docker compose restart synapse 生效）：

root:
  level: DEBUG      # INFO（默认）/ WARNING / DEBUG
  handlers: [file, console]

生产长期运行建议 INFO 以上；DEBUG 日志量大（含每请求行），排障后记得调回。

5.10 Element Web：config.json 关键项（config.<域名>.json 机制）

Element Web 的配置文件位于静态资源根目录；发行包默认加载 config.json，官方同时支持按访问域名分发：浏览器访问 http://服务器:8142 时可优先提供 config.<该域名>.json（例如 config.192.168.146.128.json），不存在则回落 config.json（官方 element-web 文档 docs/config.md 口径，2026-10-21 查证）。多域名接入多套 homeserver 时用此机制，单域名用 config.json 即可。

本文实测生效的配置（浏览器加载验证回显见部署篇 4.8）：

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "http://192.168.146.128:8141",
      "server_name": "matrix.local"
    }
  },
  "brand": "Element",
  "default_country_code": "CN",
  "disable_guests": true,
  "room_directory": {
    "servers": ["matrix.local"]
  }
}

逐项说明（标注「实测」者均经登录/页面验证）：

⚠️ 注意：config.json 改动后必须 docker compose restart element；验证手段是 curl -s http://192.168.146.128:8142/config.json 与本地文件逐字比对（部署篇 4.8 实测回显）。

六、生产配置模板

适用场景：500 人规模企业内网、16GB 内存、NVMe SSD、PostgreSQL 独立库、前置 Nginx 反代终结 TLS、关闭联邦或仅白名单联邦。核心段模板（密钥类保持 generate 随机值）：

server_name: "matrix.example.com"
public_baseurl: "https://matrix.example.com/"
pid_file: /data/homeserver.pid

listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    resources:
      - names: [client]
        compress: false
      - names: [federation]
        compress: false
  - port: 9000
    type: metrics
    bind_addresses: ['0.0.0.0']
enable_metrics: true

database:
  name: psycopg2
  args:
    user: synapse
    password: "${POSTGRES_PASSWORD}"   # 唯一占位项：真实口令走环境变量注入
    database: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

log_config: "/data/matrix.example.com.log.config"
media_store_path: /data/media_store
max_upload_size: 100M
url_preview_enabled: false

registration_shared_secret: "<generate 随机值，妥善保管>"
macaroon_secret_key: "<generate 随机值>"
form_secret: "<generate 随机值>"
signing_key_path: "/data/matrix.example.com.signing.key"

enable_registration: true
registrations_require_3pid: [email]    # 强制邮箱验证（配 ma1sd 委托）
account_threepid_delegates:
  email: "http://ma1sd:8090"

trusted_key_servers:
  - server_name: "matrix.org"
federation_domain_whitelist:
  - partner.example.org                # 按需收紧；不配则全开放

rc_login:
  account:    { per_second: 1, burst_count: 10 }
  address:    { per_second: 2, burst_count: 20 }
  failed_attempts: { per_second: 0.17, burst_count: 3 }   # 保持默认防爆破

配套说明：500 人规模单实例（默认单进程）在 16GB 内存服务器上占用约 1–2GB；再上规模先切 PostgreSQL+worker 拆分（官方文档「Workers」章节列出了按 API 面拆分的进程类型清单），而不是纵向堆配置。模板中 rc_login 收紧回近默认值（示例演示环境的放宽值勿照搬到生产）。

七、常见问题（FAQ）

Q1：改了 homeserver.yaml 重启后像没生效？

按顺序排查：① 启动日志是否出现 Error in configuration:（配置错误直接拒启，原因在首屏）；② 是否改对了宿主机文件（/opt/synapse/data/ 下的才是挂载源，容器内改动不落盘）；③ 是否执行了 docker compose restart synapse。验证参数生效用「功能级探针」：注册开关看能否页面注册、rc_login 看连续登录是否报 M_LIMIT_EXCEEDED、listeners 看端口是否有响应（见 5.3/5.5 实测）。

Q2：server_name 能改吗？

技术上能，代价是全部用户 ID/房间 ID 失效，等同重装。确需变更域名时走官方迁移路径（新 server_name + 数据迁移 + /.well-known 兼容跳转），不要直接改配置文件。

Q3：registration_shared_secret 忘了/泄露了怎么办？

它只是配置文件里的一行字符串：换新值 → docker compose restart synapse → 新值即刻生效（旧值作废）。泄露场景轮换该值并审计近期注册的账号（Admin API users 列表核对 creation_ts）。

Q4：Element 配置改了页面不变化？

浏览器缓存优先排除（强刷）；再核对挂载：curl -s http://192.168.146.128:8142/config.json 与宿主机文件比对，不一致说明没重启 element 或挂载路径写错。若挂了 config.<域名>.json，注意 Element 按访问域名选择配置文件，域名对不上会回落 config.json。

Q5：开启注册后总被滥用？

三选一：关 enable_registration_without_verification 并配邮箱验证（registrations_require_3pid + ma1sd）；或 registration_requires_token: true 改为注册令牌制（Admin API 签发）；或干脆关页面注册全走 CLI/Admin API 开户（命令篇实测）。

八、参考链接

1. Synapse 配置文档（全量参数与默认值，2026-10-21 查证）：https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html
2. Synapse Workers 扩展文档：https://element-hq.github.io/synapse/latest/workers.html
3. ma1sd 身份服务：https://github.com/ma1uta/ma1sd
4. Element Web 配置文档（config.json/config.<域名>.json）：https://github.com/element-hq/element-web/blob/develop/docs/config.md
5. 本系列：《Synapse/Element v1.163.0 Docker Compose 部署指南》、《Synapse/Element v1.163.0 Admin API 与 CLI 工具详解》、《Synapse/Element v1.163.0 介绍与选型指南》