Conduit 0.10.15 配置参数详解

目标：系统掌握 Conduit 0.10.15 的配置体系——配置文件加载机制、CONDUIT_* 环境变量覆盖规则（含实测）、global 全参数表、media/tls/proxy/trusted_servers/well_known 等子表详解与生产配置模板。全部内容以官方配置文档为依据，关键行为已在 Ubuntu 22.04 + Conduit v0.10.15 实测验证。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）；
• 软件版本：Conduit v0.10.15（2026-09-29，实测二进制 conduit 0.10.15 (db37763)）；
• 配置文件路径：由环境变量 CONDUIT_CONFIG 指定，惯例为 /etc/matrix-conduit/conduit.toml；
• 数据目录：/var/lib/matrix-conduit/；
• 依据文档：官方配置参考 https://famedly.gitlab.io/conduit/configuration.html （2026-10-25 实查）+ 官方示例配置 conduit-example.toml；
• 实测项：环境变量覆盖注册开关与日志级别、/capabilities 默认房间版本，均来自本环境真实回显（文中标注）。

二、前置条件

1. 已按《Ubuntu 22.04 安装 Conduit 0.10.15 指南》或《Conduit Docker Compose 部署指南》装好 Conduit；
2. 对 TOML 语法有基本了解（[table] 段、key = value、数组 ["a","b"]、表数组 [[table]]）。

三、参数查看与修改方式

本章说明配置「从哪加载、怎么改、改完如何生效」。

3.1 加载机制

Conduit 的配置文件路径完全由环境变量 CONDUIT_CONFIG 决定，没有默认搜索路径：

• 未设置 CONDUIT_CONFIG → 服务拒绝启动，直接报错退出（官方配置文档明示）；
• 修改配置文件后必须重启服务才生效（官方明示，无热加载）。

systemd 托管形态下通过单元注入（安装篇方案 A 的单元即如此）：

[Service]
Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml"

3.2 查看当前生效配置

两种方式：

1. 读配置文件 + 环境变量（人工核对）；
2. admin 房间机器人命令：在管理房间向 @conduit:<你的域名> 发送 show-config 子命令可查看当前生效的配置值（实测 v0.10.15 管理机器人命令列表中包含 show-config Show configuration values；管理房间完整命令清单见《Conduit 0.10.15 API 使用详解》）。

3.3 环境变量覆盖（实测）

除配置文件外，每个配置项都可用环境变量覆盖，规则为：

• 顶层字段：CONDUIT_{字段名大写}，如 CONDUIT_ALLOW_REGISTRATION、CONDUIT_LOG；
• 表内字段：CONDUIT_{表名大写}_{字段名大写}，如 [global.well_known] 表的 client 项 → CONDUIT_WELL_KNOWN_CLIENT="https://matrix.example.org"；
• 环境变量优先级高于配置文件。

实测一（注册开关覆盖）：配置文件 allow_registration = true，在服务运行环境中追加 CONDUIT_ALLOW_REGISTRATION=false 并重启后，注册接口实测返回：

{"errcode":"M_FORBIDDEN","error":"M_FORBIDDEN: Registration has been disabled."}

实测二（日志级别覆盖）：追加 CONDUIT_LOG=debug 并重启后，服务日志出现 DEBUG 级行（原 log = "info" 被覆盖）。

结论：临时调参、十二要素式部署都可只改环境变量，不动配置文件。

四、参数总览

Conduit 配置分为 global（主表，绝大多数参数）与 global 下的子表：media（媒体存储）、tls、proxy、well_known、old_verify_keys，另有数组型 trusted_servers、ignored_keys。官方配置文档结构即 Global / Media / Rate Limiting / TLS / Proxy 五章（Rate Limiting 当前版本文档无独立参数列出）。下文第五章逐表详解。

五、核心参数分类详解

5.1 global 主表参数（全量）

下表为官方配置文档的 global 段全量字段（* 为必填；默认值列为官方文档口径，与官方示例/实测不一致处单独标注）：

默认房间版本实测（GET /_matrix/client/v3/capabilities，v0.10.15）：

{"capabilities":{"m.room_versions":{"default":"12","available":{"10":"stable","11":"stable","12":"stable","3":"unstable","4":"unstable","5":"unstable","6":"stable","7":"stable","8":"stable","9":"stable"}}}}

即 v0.10.15 实际默认房间版本为 12、可用 6–12（stable）与 3–5（unstable）；官方文档表格的 "6"-"10" / 默认 "10" 已滞后，以实测为准。

5.2 media 媒体存储表

[global.media] 配置媒体存储后端与保留策略。当前唯一稳定后端为 filesystem（默认，媒体存在 database_path 下的 media/ 子目录）：

[global.media]
backend = "filesystem"
path = "/srv/matrix-media"        # 可选，默认为 database_path 下的 media/ 子目录

[global.media.directory_structure] # 可选：子目录分散策略
depth = 4                          # 子目录层数（默认 2）
length = 2                         # 每层目录名长度（默认 2）

媒体文件以其内容 SHA256 摘要命名，按 depth/length 分散到子目录（如 98/ea/6e4f…）；把 directory_structure 置空表则全部平铺在根目录。

S3 后端（官方文档列出，适合媒体量大的场景）：

[global.media]
backend = "s3"
endpoint = "http://minio:9000"
bucket = "test"                    # 桶须已存在且凭据有权限
region = "minio"
key = "<s3_key>"                   # 系统级密钥：生产用环境变量注入
secret = "<s3_secret>"
duration = 15                      # 签名 URL 有效秒数（默认 30）
bucket_use_path = false            # 路径风格开关

保留策略（retention）：按范围自动清理媒体，表数组写法 [[global.media.retention]]：

[[global.media.retention]]           # 所有媒体总量上限 40GB
space = "40G"

[[global.media.retention]]           # 远端媒体：30 天未访问或超 90 天即删
scope = "remote"
accessed = "30d"
created = "90days"

[[global.media.retention]]           # 本地媒体：1 年未访问即删
scope = "local"
accessed = "1y"

[[global.media.retention]]           # 缩略图总量上限 1GB
scope = "thumbnail"
space = "1GB"

要点：scope 可取 local / remote / thumbnail（不填为兜底默认）；accessed/created 时长用 humantime 语法（240h、30d、2months），space 用 ByteSize 语法（10000MB、15GiB）；媒体须同时满足适用范围内的全部条件才会保留，清理周期为最短保留时长的 1/10（下限 1 分钟、上限 24 小时）。

5.3 tls 表

[global.tls] 让 Conduit 直接提供 HTTPS（生产更常见的做法是反代终结 TLS，此表可不用）：

[global.tls]
certs = "/path/to/cert.pem"        # PEM 证书链
key = "/path/to/key.pem"           # PEM 私钥（系统级敏感文件，权限 600）

5.4 proxy 出向代理表

[global.proxy] 控制 Conduit 外发请求（联邦、推送等）的代理：全局代理一张表，或按域名分流（glob 匹配，exclude 优先于 include）：

[global.proxy.global]
url = "https://example.com"        # 全部出向请求走该代理

[[global.proxy.by_domain]]         # 按域名分流示例（官方示例）
url = "socks5://localhost:9050"
include = ["*.onion", "matrix.secretly-an-onion-domain.xyz"]
exclude = ["*.clearnet.onion"]

5.5 trusted_servers 公证服务器

trusted_servers 指定「获取其他服务器公钥」的公证服务器：当目标服务器不可达、或本服务器尚未加入目标房间时，从公证服取钥匙。⚠️ 这是高信任位置——公证服理论上可伪造任意服务器的事件，务必只填完全信任的对象（官方建议直接抄 ["matrix.org"]，且当前 Conduit 不支持批量取钥匙，列表里应只放 Synapse 服务器）。v0.10.15 起支持预置期望公钥（带外协商钥匙的强化威胁模型）：

[global]
trusted_servers = [
  "matrix.org",                    # 普通公证服（经 /keys 接口取钥匙）
  { server = "example.org", keys = { "ed25519:1" = "thisisanexamplebase64publickey" } },  # 预置期望公钥
]

5.6 old_verify_keys 与 well_known

old_verify_keys：若该域名此前跑过其他 homeserver 实现（或旧数据库），旧签名钥匙需登记在此，否则历史事件验签失败。表键为钥匙 ID，值含 key（base64 公钥）与 expired_ts（过期时间戳，之后的事件不再接受该钥匙）：

[global.old_verify_keys]
"ed25519:1" = {key = "thisisanexamplebase64publickey", expired_ts = "2018-02-14T00:28:07Z"}

well_known 委派：Conduit 内置 /.well-known/matrix/* 端点。默认客户端与联邦都按 server_name + 443 访问；当服务实际位于其他主机/端口时用委派改写：

[global.well_known]
server = "your.server.name:443"    # 联邦委派（m.server）
client = "https://your.server.name" # 客户端委派（m.client）

六、生产配置模板

适用场景：2C4G VPS、小团队（数十至数百用户）、开启联邦、反代终结 TLS。/etc/matrix-conduit/conduit.toml：

[global]
server_name = "matrix.example.com"          # 必改：真实域名
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "127.0.0.1"                        # 只监听环回，由反代转发
port = 6167
max_request_size = 20_000_000
allow_registration = true                    # 开放注册 + 令牌管控
registration_token = "q1w2e3r4-reg-token"    # 必改：换强随机令牌；成员拉新后亦可关注册
allow_federation = true
allow_check_for_updates = true
enable_lightning_bolt = true
trusted_servers = ["matrix.org"]
db_cache_capacity_mb = 300.0                 # 4GB 内存机器保持默认即可
log = "info"

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

[[global.media.retention]]                   # 远端媒体 30 天未访问即清
scope = "remote"
accessed = "30d"

配套要点：反代（Caddy/Nginx）把 https://matrix.example.com 的 /_matrix/* 与 /.well-known/matrix/* 转发到 127.0.0.1:6167；防火墙放行 443（联邦也可走 443 委派，无需单独开 8448）。

七、常见问题（FAQ）

Q1：改完配置不生效？ Conduit 无热加载，改配置必须重启服务；同时检查是否有同名 CONDUIT_* 环境变量覆盖了你的修改（环境变量优先，见 3.3 实测）。

Q2：default_room_version 填多少？ v0.10.15 实测默认 "12"、可用 6–12，日常无需设置；官方文档表格的默认 "10" 已滞后（见 5.1 实测 JSON）。

Q3：log 参数怎么写？ 用 tracing EnvFilter 指令语法：warn（默认）/ info / debug / trace，也可按模块定向如 conduit=debug。实测 CONDUIT_LOG=debug 环境变量覆盖后日志立即出现 DEBUG 行。

Q4：想关注册又怕管理员账号丢失？ allow_registration = false 后仍可由管理房间机器人 create-user 创建用户；另可设 emergency_password 作为 @conduit 系统用户的紧急登录口令。

Q5：S3 的 key/secret 不想写进配置文件？ 它们属于系统级真实密钥，用环境变量注入：CONDUIT_MEDIA_KEY / CONDUIT_MEDIA_SECRET（表内字段覆盖规则，见 3.3），systemd 形态写在单元的 Environment= 行或 EnvironmentFile= 中。

八、参考链接

• Conduit 官方配置文档：https://famedly.gitlab.io/conduit/configuration.html
• 官方示例配置（conduit-example.toml）：https://gitlab.com/famedly/conduit/-/blob/next/conduit-example.toml
• tracing EnvFilter 语法：https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html
• 本专栏介绍篇：《Conduit 介绍与选型指南》
• 本专栏安装篇：《Ubuntu 22.04 安装 Conduit 0.10.15 指南》
• 本专栏部署篇：《Conduit Docker Compose 部署指南》
• 本专栏 API 篇：《Conduit 0.10.15 API 使用详解》