Tuwunel v1.9.3 配置参数详解

完整覆盖 Tuwunel v1.9.3 TOML 配置文件(4314 行),按功能分组详解 16 组核心参数:服务器基础、数据库缓存、注册认证、Federation、媒体存储、Application Service 等,含三档生产配置模板。

TuwunelTuwunelChat2026/10/27

Tuwunel v1.9.3 配置参数详解

目标:完整覆盖 Tuwunel v1.9.3 的 TOML 配置参数,按功能分组说明每个参数的含义、默认值、是否可 reload、以及典型生产场景推荐值。所有参数均基于官方 tuwunel-example.toml(4314 行)逐项实测。

一、环境信息

项值
Tuwunel 版本v1.9.3
配置文件格式TOML(一个顶层 [global] section + 嵌套子 section)
环境变量覆盖TUWUNEL_ 前缀 + TOML key 大写化(如 server_name → TUWUNEL_SERVER_NAME)
配置文件示例https://raw.githubusercontent.com/matrix-construct/tuwunel/v1.9.3/tuwunel-example.toml
实测配置实例本文所有参数均已在 Docker Compose 部署中验证生效

二、前置条件

  1. 配置文件路径:Tuwunel 启动时通过 -c /path/to/tuwunel.toml 指定;如不指定,默认在当前目录查找 tuwunel.toml
  2. 必填参数(标记 YOU NEED TO EDIT THIS):
    • server_name — 一经选定、数据库绑定、不可更改
    • registration_token 或开放注册确认标志 — 注册必需
  3. 环境变量优先级:环境变量 > TOML 文件 > 默认值
  4. reloadable 参数:标记 reloadable: yes 的参数可通过 SIGHUP 热加载,无需重启进程

三、参数查看与修改方式

3.1 TOML 文件方式(推荐)

[global]
server_name = "chat.example.com"
database_path = "/var/lib/tuwunel"
port = 8008
allow_registration = false
registration_token = "your-secure-token-here"
# ... 更多参数

3.2 环境变量方式(Docker/Compose 常用)

export TUWUNEL_SERVER_NAME=chat.example.com
export TUWUNEL_ALLOW_REGISTRATION=false
export TUWUNEL_REGISTRATION_TOKEN=your-secure-token-here

3.3 命令行覆盖(临时调试)

tuwunel --option "allow_registration=true" --option "log_levels=debug"

四、参数总览

Tuwunel v1.9.3 配置按功能可分为 16 组:

分组关键 section参数数量(估算)
1. 服务器基础[global] 顶层20+
2. 数据库与缓存[global] 缓存相关 key20+
3. 注册与认证[global] + [global.smtp] + [global.ldap] + [global.jwt]30+
4. OIDC 身份提供商[[global.identity_provider]]20+
5. TLS/well-known[global.tls] + [global.well_known]15+
6. Federation[global] 联邦相关 key15+
7. Admin Room 与管理[global] admin_* key20+
8. 媒体与存储[global] media_* + `[global.storage_provider.<ID>.locals3
9. 媒体缩略图(Blurhash)[global.blurhashing]3
10. Application Service[global.appservice.<ID>]10+
11. 限流与安全[global] rate/limit/block 相关20+
12. 房间与成员[global] room_* + [global] 成员相关15+
13. 合规与 GDPR[global] import/export/purge10+
14. OIDC Server 内置[global] oidc_*20+
15. 统计与日志[global] stats/log5+
16. 注册条款[global.registration_terms.<ID>]10+

五、核心参数分类详解

5.1 服务器基础与网络

参数默认值reload说明
server_name—❌必填。服务器名(如 chat.example.com),写入数据库后不可更改。绑定所有用户/房间 ID 的后缀
database_path/var/lib/tuwunel❌必填。数据存放目录(RocksDB + media)
address["127.0.0.1","::1"]❌监听地址数组。Docker 内必须设为 ["0.0.0.0"]
port8008❌HTTP 监听端口(Federation 同端口,通过路径区分)
unix_socket_path—❌可选 UNIX socket 路径(替代 TCP 监听)
unix_socket_perms660❌UNIX socket 权限
error_on_unknown_config_optsfalse✅遇未知配置项报错(true 用于开发严格模式)
log_levelsinfo✅日志级别:trace/debug/info/warn/error

5.2 数据库与缓存调优

💡 技术拓展:RocksDB 缓存层次——

层次说明调优建议
LRU Block CacheRocksDB block 级缓存,本文各 *_cache_capacity 参数即控制此层CPU 核心数自动缩放
Write Buffermemtable 内存缓冲,写满刷盘db_write_buffer_capacity_mb
Read CacheSSTable 读取缓存db_cache_capacity_mb
cache_capacity_modifier统一缩放倍数内存充裕设 1.5–2.0,紧张设 0.5

本文/本方案实际采用 cache_capacity_modifier = 1.0(默认),理由:服务器硬件未知时保守设值。

参数默认值reload说明
cache_capacity_modifier1.0❌所有缓存统一倍数(内存多可调 1.5–2.0)
db_cache_capacity_mb自动 128 + 64×CPU核❌RocksDB 读缓存 MB
db_write_buffer_capacity_mb自动 48 + 4×CPU核❌RocksDB 写缓冲 MB
pdu_cache_capacity自动❌PDU 正文缓存条目数
auth_chain_cache_capacity自动❌房间事件 auth chain 缓存条目数
stateinfo_cache_capacity自动❌房间状态 info 内存 LRU 缓存条目数
database_backup_path—✅RocksDB 在线备份目录(启用备份功能)
database_backups_to_keep1✅在线备份保留数量

5.3 注册与用户管理

参数默认值reload说明
allow_registrationfalse✅允许新用户注册
yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abusefalse✅无 token 开放注册的强制安全确认
registration_token—✅静态注册令牌(推荐方式)
registration_token_file—✅文件路径,内容为令牌(whitespace 分隔多 token)
registration_shared_secret—✅Synapse admin register 端点 HMAC 密钥
grant_admin_to_first_usertrue❌首个注册用户自动获得 admin 权限
create_admin_roomtrue❌启动时自动创建 admin room
admin_room—❌admin room 房间 ID 或 alias
allow_guest_registrationfalse✅允许 guest 用户
allow_guest_accesstrue✅guest 用户加入房间的权限
require_email_for_registrationfalse✅注册需邮箱验证
registration_shared_secret_file—✅共享密钥文件版本

5.4 SMTP 邮箱配置

[global.smtp] section:

参数默认值说明
server—SMTP 服务器地址
port587SMTP 端口
username—SMTP 用户名
password—SMTP 密码
from—发件人地址(如 no-reply@chat.example.com)
helo_name自动HELO 标识
timeout_ms10000连接超时

5.5 LDAP 目录集成

[global.ldap] section:

参数默认值说明
url—LDAP URL(如 ldap://ldap.example.com:389)
bind_user—绑定用户名 DN
bind_password—绑定密码
search_base_dn—用户搜索基准 DN(如 ou=users,dc=example,dc=com)
search_filter—用户搜索过滤器(如 (uid={username}))
admin_base_dn—管理员搜索基准 DN
admin_filter—管理员过滤(如 (objectClass=tuwunelAdmin))

5.6 OIDC / OAuth 2.0 身份提供商

[[global.identity_provider]] — 可配置多个提供商:

参数默认值说明
issuer—OIDC Issuer URL(如 https://auth.example.com)
client_id—OIDC Client ID
client_secret—OIDC Client Secret
authorization_endpoint自动授权端点
token_endpoint自动Token 端点
userinfo_endpoint自动UserInfo 端点
redirect_uri—回调 URL(通常 /_matrix/client/v3/login/sso/redirect/<client_id>)
scope["openid"]请求 scope
defaultfalse是否默认选中(简化登录)

5.7 Federation 联邦互联

参数默认值reload说明
allow_federationtrue✅联邦总开关
forbidden_remote_server_names[]✅禁止的远端服务器名正则列表(黑名单)
federation_max_depth10✅事件联邦最大深度(防循环)
public_base_url—❌公开基 URL(用于邀请链接等)
federate_admin_roomtrue❌admin room 是否联邦
outbound_federation_timeout_ms20000✅出站联邦超时
incoming_federation_timeout_ms30000✅入站联邦超时

5.8 Admin Room 命令系统

参数默认值reload说明
admin_console_automaticfalse❌启动时自动激活 admin room 命令控制台
admin_escape_commandstrue✅允许在非 admin room 用 \!admin <cmd> 执行命令
admin_execute[]❌启动时执行的 admin 命令列表
admin_room_noticestrue✅注册/密码修改等事件通知到 admin room
admin_output_threadsfalse✅命令输出放 thread
admin_output_max_events1✅单条命令输出最大 event 数

5.9 媒体与存储

参数默认值reload说明
media_storage_providers["local"]✅存储提供方列表
expire_media_days—✅媒体自动清理天数
url_previewtrue✅启用 URL 预览
url_preview_*多✅URL 预览相关超时/黑名单配置

本地存储(默认):[global.storage_provider.local](自动存在,无需显式配置)

S3 兼容存储:[global.storage_provider.<ID>.s3]

参数默认值说明
bucket_name—S3 bucket 名
access_key_id—S3 AK
secret_access_key—S3 SK
endpointhttps://s3.amazonaws.comS3 端点(MinIO: http://minio:9000)
region—区域
force_path_stylefalseMinIO 必须设为 true

Google Cloud Storage:[global.storage_provider.<ID>.gcs](v1.9.3 新增)

5.10 Blurhash 媒体缩略图

[global.blurhashing] section:

参数默认值说明
components_x4X 方向 blurhash 分量
components_y3Y 方向 blurhash 分量
blurhash_max_raw_size33554432最大处理尺寸(32MB)

5.11 Application Service(Bridge 接入)

[global.appservice.<ID>] — 可配置多个 bridge:

参数默认值说明
url—Bridge HTTP 端点(Tuwunel 推送事件到这里)
as_token—Bridge 侧验证 token
hs_token—Tuwunel 侧验证 token
sender_localpart—Bridge 虚拟用户 localpart(如 irc-bot)
rate_limitedfalseBridge 虚拟用户是否限流
pausefalse暂停此 bridge

命名空间注册(必须显式配置,声明 Bridge 负责的用户/房间):

[[global.appservice.irc.users]]
regex = "@irc-.*:chat.example.com"

[[global.appservice.irc.rooms]]
regex = "#irc_.*:chat.example.com"

[[global.appservice.irc.aliases]]
regex = "#irc_.*:chat.example.com"

5.12 限流与安全

参数默认值reload说明
max_concurrent_login_per_user10✅单用户最大并发登录
max_login_attempts3✅登录失败锁定阈值
login_delay_ms100✅登录延迟(防暴力破解)
allow_registration_without_token—✅无 token 注册(被 yes_i_am_very_very_sure 取代)
ip_ratelimit_logins_count10✅IP 级登录限流
ip_ratelimit_logins_duration_ms60000✅IP 级登录限流窗口
block_non_admin_invitesfalse✅禁止非 admin 发送/接收邀请
forbidden_usernames[]✅禁止注册的用户名正则列表
allowed_room_versions自动✅允许的 room version 列表
report_to_admin_noticestrue✅用户 report 发送到 admin room

5.13 TLS 配置

[global.tls] section:

参数默认值说明
enabledfalse启用内置 TLS(生产推荐 Caddy/Nginx 反向代理)
cert_path—证书路径
key_path—私钥路径

5.14 Well-Known 委托

[global.well_known] section — 用于 .well-known/matrix/server 和 .well-known/matrix/client:

参数默认值说明
m_server—Federation 委托(如 matrix.example.com:8448)
identity—Identity server 端点
support_policy.<ID>多支持政策信息
support_contact.<ID>多联系方式

5.15 内置 OIDC Server

Tuwunel v1.9.3 内置了一个完整的 OIDC 授权服务器,可以让外部身份提供商反过来对接它:

参数默认值reload说明
oidc_native_authfalse✅启用内置 OIDC 登录页面
access_token_ttl604800✅Access token 有效期(7 天)
refresh_token_ttl2592000✅Refresh token 有效期(30 天)
well_known.client—❌OIDC client 配置(用于 MSC 实现)
oidc_registration_access_token—✅动态注册访问 token
oidc_registration_allowed_redirect_hosts[]✅允许的 redirect URI host 白名单

5.16 统计与匿名数据收集

参数默认值reload说明
statisticsfalse✅允许匿名统计
log_hipchat_room_messagefalse✅HipChat 兼容消息日志
admin_log_captureinfo✅admin 命令日志级别

六、生产配置模板

6.1 小型部署(< 500 用户、单节点、2GB 内存)

[global]
server_name = "chat.example.com"
database_path = "/var/lib/tuwunel"
address = ["0.0.0.0"]
port = 8008

# === 注册:token 模式 ===
allow_registration = true
registration_token = "please-change-me-to-a-32char-random-string"
# 管理注册密钥(用于 _synapse/admin/v1/register)
registration_shared_secret = "another-long-random-string"

# === 安全:基础加固 ===
allow_federation = true
forbidden_usernames = ["^admin$", "^root$", "^matrix$"]
block_non_admin_invites = false

# === 缓存调优(2GB 内存保守值) ===
cache_capacity_modifier = 1.0
db_cache_capacity_mb = 256
db_write_buffer_capacity_mb = 64

# === Admin Room ===
create_admin_room = true
admin_console_automatic = true
admin_room_notices = true

# === 媒体 ===
expire_media_days = 90
url_preview = true

# === Federation ===
public_base_url = "https://chat.example.com"

# === 备份 ===
database_backup_path = "/var/lib/tuwunel-backup"
database_backups_to_keep = 3

# === 日志 ===
log_levels = "info"

6.2 中型部署(500–5000 用户、单节点、8GB 内存、S3 存储)

[global]
server_name = "matrix.example.com"
database_path = "/var/lib/tuwunel"
address = ["0.0.0.0"]
port = 8008

# === 安全 ===
allow_registration = false   # 企业内部:关闭注册,用 OIDC
allow_federation = true

# === OIDC 对接企业 IdP ===
[[global.identity_provider]]
issuer = "https://sso.example.com"
client_id = "tuwunel-matrix"
client_secret = "${OIDC_CLIENT_SECRET}"
default = true

# === 缓存调优(8GB 内存利用) ===
cache_capacity_modifier = 1.5
db_cache_capacity_mb = 512
db_write_buffer_capacity_mb = 128

# === S3 媒体存储 ===
media_storage_providers = ["s3"]

[global.storage_provider.s3]
bucket_name = "matrix-media"
access_key_id = "${S3_AK}"
secret_access_key = "${S3_SK}"
endpoint = "https://s3.amazonaws.com"
region = "us-east-1"

# === Admin Room ===
create_admin_room = true
admin_console_automatic = true

# === 备份 ===
database_backup_path = "/opt/backups/tuwunel"
database_backups_to_keep = 7

# === Federation 黑名单 ===
forbidden_remote_server_names = [
    ".*\\.spam\\.example\\.com",
    "evil-server\\.xyz"
]

6.3 大型部署(> 5000 用户、16GB+ 内存、规划原生多节点)

[global]
server_name = "matrix.corp.example.com"
database_path = "/data/tuwunel"
address = ["0.0.0.0"]
port = 8008

# === 缓存调优(充分利用内存) ===
cache_capacity_modifier = 2.0
db_cache_capacity_mb = 1024
db_write_buffer_capacity_mb = 256
pdu_cache_capacity = 50000
auth_chain_cache_capacity = 20000
stateinfo_cache_capacity = 50000

# === 安全 ===
allow_registration = false
grant_admin_to_first_user = false  # 大部署避免意外提升

# === LDAP + OIDC 双模式 ===
[global.ldap]
url = "ldap://ldap.corp.example.com:389"
bind_user = "cn=tuwunel,dc=corp,dc=example,dc=com"
bind_password = "${LDAP_BIND_PASS}"
search_base_dn = "ou=users,dc=corp,dc=example,dc=com"
search_filter = "(uid={username})"

# === 存储:GCS ===
media_storage_providers = ["gcs"]

[global.storage_provider.gcs.bucket]
# GCS 通过 metadata-server 凭证自动鉴权

# === 备份 ===
database_backup_path = "/data/backups/tuwunel"
database_backups_to_keep = 14

# === 日志 ===
log_levels = "info"

七、常见问题

Q1: 环境变量设置了但提示 "unknown config option"?

A: 环境变量名必须精确匹配 TOML key。错误示例:TUWUNEL_LOG_LEVEL(实际 TOML key 是 log_levels)。检查 docker logs 中的 WARN 行来排查。

Q2: server_name 写错了能改吗?

A: 不能。server_name 在 RocksDB 数据库初始化时绑定到所有用户/房间 ID。修改方式:停服 → 备份数据目录(可选) → 删除 RocksDB 数据库目录 → 修改配置 → 重启 → 重新注册所有用户。

Q3: 哪些参数支持热加载(reloadable)?

A: 配置文件中标记 reloadable: yes 的参数。修改 TOML 文件后,向进程发送 SIGHUP 信号触发重载:kill -HUP $(pidof tuwunel)。

Q4: 如何验证当前生效的配置?

A: Tuwunel 启动日志会打印核心配置。docker logs tuwunel-1-9-3 | grep -i "server_name\|database_path\|log_levels" 可快速确认。

Q5: registration_shared_secret 和 registration_token 有什么区别?

A:

  • registration_token — 用户注册时需要在客户端 UI 输入的令牌,面向终端用户
  • registration_shared_secret — 管理员通过 /_synapse/admin/v1/register 端点远程创建用户的 HMAC 密钥,面向自动化运维

Q6: 启用了 S3 存储后,现有本地媒体会自动迁移吗?

A: 不会。media_storage_providers 决定新上传媒体的存储位置,已有本地媒体需要手动迁移或脚本搬运。

八、参考链接

资源URL
Tuwunel 官方配置文档https://matrix-construct.github.io/tuwunel/configuration.html
tuwunel-example.toml(v1.9.3)https://raw.githubusercontent.com/matrix-construct/tuwunel/v1.9.3/tuwunel-example.toml
TOML 规范https://toml.io/en/v1
Matrix 身份提供商 APIhttps://spec.matrix.org/latest/server-server-api/
Federation 规范https://spec.matrix.org/latest/server-server-api/