Tuwunel v1.9.3 配置参数详解
完整覆盖 Tuwunel v1.9.3 TOML 配置文件(4314 行),按功能分组详解 16 组核心参数:服务器基础、数据库缓存、注册认证、Federation、媒体存储、Application Service 等,含三档生产配置模板。
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 部署中验证生效 |
二、前置条件
- 配置文件路径:Tuwunel 启动时通过
-c /path/to/tuwunel.toml指定;如不指定,默认在当前目录查找tuwunel.toml - 必填参数(标记
YOU NEED TO EDIT THIS):server_name— 一经选定、数据库绑定、不可更改registration_token或开放注册确认标志 — 注册必需
- 环境变量优先级:环境变量 > TOML 文件 > 默认值
- 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] 缓存相关 key | 20+ |
| 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] 联邦相关 key | 15+ |
| 7. Admin Room 与管理 | [global] admin_* key | 20+ |
| 8. 媒体与存储 | [global] media_* + `[global.storage_provider.<ID>.local | s3 |
| 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/purge | 10+ |
| 14. OIDC Server 内置 | [global] oidc_* | 20+ |
| 15. 统计与日志 | [global] stats/log | 5+ |
| 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"] |
port | 8008 | ❌ | HTTP 监听端口(Federation 同端口,通过路径区分) |
unix_socket_path | — | ❌ | 可选 UNIX socket 路径(替代 TCP 监听) |
unix_socket_perms | 660 | ❌ | UNIX socket 权限 |
error_on_unknown_config_opts | false | ✅ | 遇未知配置项报错(true 用于开发严格模式) |
log_levels | info | ✅ | 日志级别:trace/debug/info/warn/error |
5.2 数据库与缓存调优
💡 技术拓展:RocksDB 缓存层次——
层次 说明 调优建议 LRU Block Cache RocksDB block 级缓存,本文各 *_cache_capacity参数即控制此层CPU 核心数自动缩放 Write Buffer memtable 内存缓冲,写满刷盘 db_write_buffer_capacity_mbRead Cache SSTable 读取缓存 db_cache_capacity_mbcache_capacity_modifier统一缩放倍数 内存充裕设 1.5–2.0,紧张设 0.5 本文/本方案实际采用
cache_capacity_modifier = 1.0(默认),理由:服务器硬件未知时保守设值。
| 参数 | 默认值 | reload | 说明 |
|---|---|---|---|
cache_capacity_modifier | 1.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_keep | 1 | ✅ | 在线备份保留数量 |
5.3 注册与用户管理
| 参数 | 默认值 | reload | 说明 |
|---|---|---|---|
allow_registration | false | ✅ | 允许新用户注册 |
yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse | false | ✅ | 无 token 开放注册的强制安全确认 |
registration_token | — | ✅ | 静态注册令牌(推荐方式) |
registration_token_file | — | ✅ | 文件路径,内容为令牌(whitespace 分隔多 token) |
registration_shared_secret | — | ✅ | Synapse admin register 端点 HMAC 密钥 |
grant_admin_to_first_user | true | ❌ | 首个注册用户自动获得 admin 权限 |
create_admin_room | true | ❌ | 启动时自动创建 admin room |
admin_room | — | ❌ | admin room 房间 ID 或 alias |
allow_guest_registration | false | ✅ | 允许 guest 用户 |
allow_guest_access | true | ✅ | guest 用户加入房间的权限 |
require_email_for_registration | false | ✅ | 注册需邮箱验证 |
registration_shared_secret_file | — | ✅ | 共享密钥文件版本 |
5.4 SMTP 邮箱配置
[global.smtp] section:
| 参数 | 默认值 | 说明 |
|---|---|---|
server | — | SMTP 服务器地址 |
port | 587 | SMTP 端口 |
username | — | SMTP 用户名 |
password | — | SMTP 密码 |
from | — | 发件人地址(如 no-reply@chat.example.com) |
helo_name | 自动 | HELO 标识 |
timeout_ms | 10000 | 连接超时 |
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 |
default | false | 是否默认选中(简化登录) |
5.7 Federation 联邦互联
| 参数 | 默认值 | reload | 说明 |
|---|---|---|---|
allow_federation | true | ✅ | 联邦总开关 |
forbidden_remote_server_names | [] | ✅ | 禁止的远端服务器名正则列表(黑名单) |
federation_max_depth | 10 | ✅ | 事件联邦最大深度(防循环) |
public_base_url | — | ❌ | 公开基 URL(用于邀请链接等) |
federate_admin_room | true | ❌ | admin room 是否联邦 |
outbound_federation_timeout_ms | 20000 | ✅ | 出站联邦超时 |
incoming_federation_timeout_ms | 30000 | ✅ | 入站联邦超时 |
5.8 Admin Room 命令系统
| 参数 | 默认值 | reload | 说明 |
|---|---|---|---|
admin_console_automatic | false | ❌ | 启动时自动激活 admin room 命令控制台 |
admin_escape_commands | true | ✅ | 允许在非 admin room 用 \!admin <cmd> 执行命令 |
admin_execute | [] | ❌ | 启动时执行的 admin 命令列表 |
admin_room_notices | true | ✅ | 注册/密码修改等事件通知到 admin room |
admin_output_threads | false | ✅ | 命令输出放 thread |
admin_output_max_events | 1 | ✅ | 单条命令输出最大 event 数 |
5.9 媒体与存储
| 参数 | 默认值 | reload | 说明 |
|---|---|---|---|
media_storage_providers | ["local"] | ✅ | 存储提供方列表 |
expire_media_days | — | ✅ | 媒体自动清理天数 |
url_preview | true | ✅ | 启用 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 |
endpoint | https://s3.amazonaws.com | S3 端点(MinIO: http://minio:9000) |
region | — | 区域 |
force_path_style | false | MinIO 必须设为 true |
Google Cloud Storage:[global.storage_provider.<ID>.gcs](v1.9.3 新增)
5.10 Blurhash 媒体缩略图
[global.blurhashing] section:
| 参数 | 默认值 | 说明 |
|---|---|---|
components_x | 4 | X 方向 blurhash 分量 |
components_y | 3 | Y 方向 blurhash 分量 |
blurhash_max_raw_size | 33554432 | 最大处理尺寸(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_limited | false | Bridge 虚拟用户是否限流 |
pause | false | 暂停此 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_user | 10 | ✅ | 单用户最大并发登录 |
max_login_attempts | 3 | ✅ | 登录失败锁定阈值 |
login_delay_ms | 100 | ✅ | 登录延迟(防暴力破解) |
allow_registration_without_token | — | ✅ | 无 token 注册(被 yes_i_am_very_very_sure 取代) |
ip_ratelimit_logins_count | 10 | ✅ | IP 级登录限流 |
ip_ratelimit_logins_duration_ms | 60000 | ✅ | IP 级登录限流窗口 |
block_non_admin_invites | false | ✅ | 禁止非 admin 发送/接收邀请 |
forbidden_usernames | [] | ✅ | 禁止注册的用户名正则列表 |
allowed_room_versions | 自动 | ✅ | 允许的 room version 列表 |
report_to_admin_notices | true | ✅ | 用户 report 发送到 admin room |
5.13 TLS 配置
[global.tls] section:
| 参数 | 默认值 | 说明 |
|---|---|---|
enabled | false | 启用内置 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_auth | false | ✅ | 启用内置 OIDC 登录页面 |
access_token_ttl | 604800 | ✅ | Access token 有效期(7 天) |
refresh_token_ttl | 2592000 | ✅ | 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 | 说明 |
|---|---|---|---|
statistics | false | ✅ | 允许匿名统计 |
log_hipchat_room_message | false | ✅ | HipChat 兼容消息日志 |
admin_log_capture | info | ✅ | 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 身份提供商 API | https://spec.matrix.org/latest/server-server-api/ |
| Federation 规范 | https://spec.matrix.org/latest/server-server-api/ |