Continuwuity 26.9 配置参数详解

目标：讲清 Continuwuity（二进制名 conduwuit）配置文件 conduwuit.toml 的结构、四种生效方式（配置文件 / 环境变量 / 命令行覆盖 / 信号热重载）与核心参数逐项含义，并给出一套可直接套用的生产配置模板。全部示例基于 v26.9.1 官方示例配置 conduwuit-example.toml（2386 行）与本地实测，实测环境：Ubuntu 22.04.5 LTS，Continuwuity 26.9.1（046074b）。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• 组件版本：Continuwuity v26.9.1（2026-09-28 发布，CalVer 编号）
• 配置文件：/etc/conduwuit/conduwuit.toml（TOML 格式）
• 数据目录：/var/lib/conduwuit（RocksDB 嵌入式存储，无外部数据库）
• 默认监听：127.0.0.1:8008、[::1]:8008
• 官方全量配置参考：https://continuwuity.org/reference/config.html

二、前置条件

已有一台装好 Continuwuity 的服务器（安装过程见《Ubuntu 22.04 安装 Continuwuity 26.9 指南》）。本文所有命令均可在该机上独立执行。

确认配置加载路径的命令：

systemctl cat conduwuit | grep ExecStart

实测回显：

ExecStart=/usr/local/bin/conduwuit --config /etc/conduwuit/conduwuit.toml

三、参数查看与修改方式（四种，均有实测）

Continuwuity 的全部配置项都在 [global] 段（另有 [global.tls]、[global.well_known]、[global.matrix_rtc] 等少数子段）。同一个键最多有四种写法，优先级从高到低如下。

3.1 配置文件（主方式）

直接编辑 /etc/conduwuit/conduwuit.toml，键名小写下划线：

[global]
server_name = "example.com"
port = 8008

3.2 环境变量（CONTINUWUITY_ 前缀）

规则：键名转大写、加 CONTINUWUITY_ 前缀；子段的键用双下划线连接段名与键名。例如：

# 等价于 port = 8008
CONTINUWUITY_PORT=8008
# 等价于 [global.well_known] 下的 server = "matrix.example.com:443"
CONTINUWUITY_WELL_KNOWN__SERVER="matrix.example.com:443"

环境变量适合临时调整与机密注入；长期配置仍建议落配置文件。

3.3 命令行 -O 覆盖（一次性调试）

二进制支持 -O 'key=value'（TOML 语法）临时覆盖，实测回显：

conduwuit --config /etc/conduwuit/conduwuit.toml -O "port=18128"

⚠️ 注意：-O 的值按 TOML 解析，字符串必须带引号。实测 -O "database_path=/var/lib/x" 会直接报错：

Error: TOML parse error at line 1, column 15

正确写法：-O 'database_path="/var/lib/x"'。另外数据目录被运行中的实例独占锁定（实测报 While lock file: /var/lib/conduwuit/LOCK: Resource temporarily unavailable），调试时务必换 -O 指定另一个空目录。

3.4 信号热重载（免重启）

配置 config_reload_signal = true（默认开启）后，向进程发 SIGUSR1 即重读配置：

kill -USR1 $(systemctl show -p MainPID --value conduwuit)
journalctl -u conduwuit --no-pager --since "-10s"

实测回显（重载后配置检查重新执行）：

WARN conduwuit_core::config::check: No support contact information (support_email or support_mxid) is configured ...

💡 说明：若 systemd 单元定义了 ExecReload=/bin/kill -USR1 $MAINPID，则可直接 systemctl reload conduwuit。并非所有键都支持热重载（如监听地址/端口需重启），改完网络类参数建议直接 systemctl restart。

四、参数总览

v26.9.1 示例配置共 200+ 个键，按功能域归类如下（后文逐域详解标★的核心项）：

五、核心参数分类详解

5.1 身份与监听

[global]
server_name = "example.com"
address = ["127.0.0.1", "::1"]
port = 8008

• server_name（必填，无默认）：服务器在 Matrix 联邦中的域名标识，作为用户 ID 与房间别名后缀。首次启动写库后不可更改，变更等于换服务器（需清库重来）；
• address：默认 ["127.0.0.1", "::1"] 仅回环，配合本机反向代理；要裸暴露需显式改 "0.0.0.0"；
• port：默认 8008，可写数组监听多端口；
• unix_socket_path / unix_socket_perms：可改走 UNIX socket（与 TCP 监听互斥，需注释掉 address）。

5.2 存储与备份

database_path = "/var/lib/conduwuit"
database_backup_path = "/opt/continuwuity-db-backups"
database_backups_to_keep = 1

• database_path（必填）：唯一数据目录，含消息库与媒体；systemd 部署时由单元环境变量注入；
• database_backup_path：设置后启用 RocksDB 在线热备（Backup Engine API），systemd 部署需把该路径加进单元 ReadWritePaths；
• database_backups_to_keep：滚动保留备份份数，默认 1。

5.3 注册与账户

allow_registration = false
registration_token = "o&^uCtes4HPf0Vu@F20jQeeWE7"
suspend_on_register = false
allow_deactivation = true

• allow_registration：默认 false。开启后若未配令牌，还需编译期 openreg feature 并显式确认 yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse（名字即警告）；
• registration_token / registration_token_file：静态注册令牌/令牌文件；与管理员用 !admin token 签发的动态令牌并存不互斥；令牌文件仅在启动时读一次，热重载不重读；
• recaptcha_site_key / recaptcha_private_site_key：注册强制验证码；与令牌可同时强制；
• suspend_on_register：新注册用户自动冻结（只读），需管理员 !admin users unsuspend 解冻，适合人工审核制实例；
• new_user_displayname_suffix：新用户显示名后缀，默认 🏳️‍⚧️，设 "" 关闭；
• emergency_password：紧急后门密码，任意本地用户可用它登录（仅限救急，平时务必注释掉）。

5.4 联邦控制

allow_federation = true
trusted_servers = ["matrix.org"]
default_room_version = "12"

• allow_federation：默认 true；纯内网实例设 false 完全关闭对外联邦；
• trusted_servers：密钥公证服务器列表，默认 ["matrix.org"]，建议不超过 5 个；支持 {server_name=..., verify_keys=[...]} 严格校验写法；
• default_room_version：默认 "12"（实测 / _matrix/client/v3/capabilities 返回 "default":"12"）；
• forbidden_remote_server_names / allowed_remote_server_names：联邦黑/白名单；
• ip_range_denylist：出站请求 IP 黑名单段，防 SSRF 扫内网；
• federation_timeout（默认 60s）、federation_conn_timeout（10s）等联邦超时族，弱网互联时可调大。

5.5 在线状态 / 已读 / 输入中（性能敏感）

allow_local_presence = true
allow_incoming_presence = true
allow_outgoing_presence = false
allow_local_read_receipts = true
allow_outgoing_read_receipts = true
allow_outgoing_typing = true

• 联邦 presence 是 Matrix 性能大户：v26.x 起 allow_outgoing_presence 默认 false（出站在线状态关闭），显著降低 CPU；income/local 默认开；
• 大实例可进一步关 allow_incoming_presence、allow_outgoing_typing 换 CPU；
• presence_idle_timeout_s（300）、presence_offline_timeout_s（1800）控制状态翻转节奏。

💡 技术拓展：「在线状态（presence）」在 Matrix 各 homeserver 实现中的默认策略差异很大——

实现	联邦 presence 默认	取舍
Continuwuity	出站关、入站开	牺牲联邦在线状态新鲜度换 CPU
Synapse	全开	功能完整，资源开销大
Conduit	全开但实现精简	小规模实例可承受

Continuwuity 的默认取向是「小服务器友好」，需要完整在线状态再手动打开出站开关。

5.6 媒体与 URL 预览

• allow_legacy_media（默认 false）：旧版非鉴权媒体端点开关；freeze_legacy_media（默认 true）冻结旧媒体再编辑；
• media_startup_check（默认 true）：启动时校验媒体目录一致性；
• url_preview_* 一族：url_preview_max_spider_size（默认 256000 字节）、url_preview_domain_explicit_denylist 等，控制链接预览抓取的体积与域名边界；对外开放的实例建议收紧，防抓取放大攻击。

5.7 日志与可观测

log = "info"
log_to_journald = false

• log：tracing EnvFilter 语法，默认 info；排障可 "info,conduwuit=debug" 粒度调节；
• log_to_journald + journald_identifier：直写 systemd journal（官方单元默认开启）；
• allow_otlp / otlp_filter / otlp_protocol：OpenTelemetry 链路导出；
• sentry_* 一族：Sentry 错误上报集成（默认全关）；
• rocksdb_log_level（默认 "error"）：RocksDB 自身日志级别，独立于应用日志。

5.8 缓存与 RocksDB（性能主战场）

• cache_capacity_modifier（默认 1.0）：全站缓存容量倍率，内存紧张下调、充裕上调；
• db_cache_capacity_mb / db_write_buffer_capacity_mb：RocksDB 块缓存与写缓冲，默认按系统内存自动推算（示例配置标注 varies by system）；
• rocksdb_compression_algo：默认 "zstd"；rocksdb_compression_level / rocksdb_bottommost_compression_level 默认 32767（= 按层级自动选档）；
• rocksdb_direct_io（默认 true）、rocksdb_optimize_for_spinning_disks（机械盘 true）；
• rocksdb_recovery_mode：0 强一致 / 1 容忍尾部损坏（默认）/ 2 时间点恢复 / 3 跳过一切坏记录（官方原话：用了就失去保修），灾难恢复时临时调 2；
• db_pool_workers（32）/ db_pool_workers_limit（64）/ db_pool_queue_mult（4）：数据库线程池与排队深度。

💡 技术拓展：RocksDB 压缩算法常见选项对比——

算法	压缩率	速度	适用
none	无	最快	极致低延迟
lz4	低	快	热数据层
zstd	高	中	默认均衡选择
zlib	高	慢	冷数据归档

Continuwuity 默认全库 zstd、WAL 也 zstd（rocksdb_wal_compression），保持默认即可。

5.9 管理行为

• admin_escape_commands（默认 true）：允许在普通房间用 \!admin 转义形式执行管理命令；安全加固后可关；
• admin_room_notices（默认 true）：管理房间公告；
• admin_execute / admin_signal_execute：启动后/收到信号后自动执行的管理命令列表；
• admins_list / admins_from_room（默认 true）：显式管理员名单 / 从管理房间成员推断管理员；
• admin_log_capture（默认 "info"）：管理命令执行的日志捕获级别。

5.10 子段：TLS、well-known、MatrixRTC

[global.tls]
certs = "/etc/continuwuity/fullchain.pem"
key = "/etc/continuwuity/privkey.pem"
# dual_protocol = false

[global.well_known]
client = "https://matrix.example.com"
server = "matrix.example.com:443"
support_email = "admin@example.com"

• [global.tls]：让 conduwuit 自己终结 TLS（生产更推荐前置 Caddy/Nginx，本段留空）；dual_protocol 允许同端口 HTTP+HTTPS 混合（不安全，默认 false）；
• [global.well_known]：.well-known/matrix/client|server 委派应答内容，用于「域名在 example.com、服务跑在 matrix 子域/非 8448 端口」的委派部署；support_* 一族对应 MSC1929 服务器支持信息端点；
• [global.matrix_rtc]：foci 等配置 MatrixRTC（音视频通话）焦点服务器。

六、生产配置模板

适用场景：4GB 内存、NVMe SSD、50 用户以内的小型团队实例，前置 Caddy 反代、开放联邦、令牌注册制：

[global]
server_name = "example.com"
database_path = "/var/lib/conduwuit"
address = ["127.0.0.1", "::1"]
port = 8008

# 注册：关自由注册，走管理员签发令牌
allow_registration = true
registration_token = "o&^uCtes4HPf0Vu@F20jQeeWE7"
suspend_on_register = true

# 联邦：开启但收紧
allow_federation = true
trusted_servers = ["matrix.org"]
allow_public_room_directory_over_federation = false

# 性能：关闭出站 presence，缓存按 4GB 内存适度收缩
allow_outgoing_presence = false
cache_capacity_modifier = 0.8

# 备份：在线热备 3 份
database_backup_path = "/opt/continuwuity-db-backups"
database_backups_to_keep = 3

# 日志
log = "info"
log_to_journald = true
journald_identifier = "conduwuit"

[global.well_known]
support_email = "admin@example.com"

逐项解读：suspend_on_register=true 实现「注册后人工解冻」防滥用；allow_public_room_directory_over_federation=false 避免房间目录被联邦任意拉取；cache_capacity_modifier=0.8 给其他进程预留内存；其余保持默认即官方推荐值。

七、常见问题（FAQ)

Q1：改了 port 热重载不生效？ 监听类参数（address/port/unix_socket_path）不参与热重载，systemctl restart conduwuit 重启生效。

Q2：环境变量和配置文件都写了同一键，以谁为准？ 实测环境变量优先于配置文件（这也是官方镜像完全靠 CONTINUWUITY_* 注入配置的原理）；-O 又优先于环境变量。

Q3：registration_token_file 改了文件怎么不生效？ 该文件仅启动时读取一次（官方配置注释明确），热重载不重读；改文件后需重启进程。

Q4：如何确认当前生效的端口？ ss -ltnp | grep conduwuit，实测回显：

LISTEN 0 128 127.0.0.1:8008 0.0.0.0:* users:(("conduwuit",pid=4031,fd=61))
LISTEN 0 128     [::1]:8008    [::]:* users:(("conduwuit",pid=4031,fd=59))

Q5：server_name 填错了能改吗？ 不能。它已写入数据库并作为全部用户/房间 ID 后缀；只能停服后清空 database_path 重新初始化。

八、参考链接

• 官方配置参考（全量示例配置）：https://continuwuity.org/reference/config.html
• 官方配置说明页：https://continuwuity.org/configuration.html
• 官方维护手册（备份等）：https://continuwuity.org/maintenance.html
• 站内相关：《Continuwuity 介绍与选型指南》、《Ubuntu 22.04 安装 Continuwuity 26.9 指南》