Conduit 0.10.15 Docker Compose 部署指南

目标：用 Docker Compose 编排部署 Conduit 0.10.15（Rust 编写的轻量级 Matrix homeserver），覆盖镜像选型、目录规划、配置文件挂载、数据持久化验证、环境变量覆盖、等价 docker run 与日常运维命令，并附 Kubernetes 社区 Helm Chart 部署形态说明。全部命令与回显已在 Linux（x86_64）+ Docker Compose 环境实测通过。

一、环境信息

• 操作系统：Linux x86_64（Ubuntu 22.04 LTS），Docker + Docker Compose v2 插件；
• 软件版本：Conduit v0.10.15（tag 日期 2026-09-29，2026 年最新稳定版）；
• 镜像：matrixconduit/matrix-conduit:v0.10.15（官方镜像，解压后约 133MB / 压缩传输约 66.5MB）；
• Compose 项目名：conduit-0.10.15-stack；内部网络：conduit-net（10.89.70.0/24）；
• 端口映射：宿主 8128 → 服务 6167（客户端 API 与联邦 API 共用单端口；宿主 8128 为本实验环境所选端口，端口空闲时读者可直接用 6167:6167）；
• 数据目录：项目目录下 ./data（bind mount 到 /var/lib/matrix-conduit/）；
• 演示环境信息：server_name conduit.example.com，注册令牌 q1w2e3r4-reg-token，演示管理员账号 admin / 密码 q1w2e3r4。

二、镜像选型说明

Docker Hub 官方账号 matrixconduit 下的 matrix-conduit 镜像（https://hub.docker.com/r/matrixconduit/matrix-conduit ，2026-10-25 实查）：

选型结论：本文使用 matrixconduit/matrix-conduit:v0.10.15，按版本 tag 固定镜像，升级时显式改 tag。

三、前置条件

1. 已安装 Docker Engine 与 Compose v2 插件（docker compose version 能输出版本号即可）；
2. 宿主 8128 端口空闲（或改用其他空闲端口）；
3. 可访问 Docker Hub（拉取镜像）；如不可达，按贵司出口策略配置镜像加速器或代理。

四、部署步骤

本章按「建目录 → 写配置 → 写编排 → 启动 → 验证 → 注册」完整走一遍。

4.1 建立项目目录

mkdir -p ~/conduit-0.10.15-stack/data
cd ~/conduit-0.10.15-stack

4.2 编写配置文件 conduit.toml

Conduit 必须设置 CONDUIT_CONFIG 环境变量指向 TOML 配置文件才能启动。在项目目录新建 conduit.toml：

[global]
server_name = "conduit.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167
max_request_size = 20_000_000
allow_registration = true
registration_token = "q1w2e3r4-reg-token"
allow_federation = false
allow_check_for_updates = true
enable_lightning_bolt = true
trusted_servers = ["matrix.org"]
log = "info"

关键项说明：server_name 为必改项（Matrix 域名，用户 ID 后缀）；address 必须为 0.0.0.0（默认 127.0.0.1 只监听环回，宿主端口映射将转发不进来）；database_path 即镜像内约定的数据目录 /var/lib/matrix-conduit/；registration_token 生产环境请换强随机令牌；allow_federation = false 为测试口径，上联邦需改 true 并配好域名与 HTTPS 反代。

4.3 编写 docker-compose.yml

name: conduit-0.10.15-stack

services:
  conduit:
    image: matrixconduit/matrix-conduit:v0.10.15
    container_name: conduit-0.10.15-server
    restart: unless-stopped
    environment:
      CONDUIT_CONFIG: "/etc/matrix-conduit/conduit.toml"
    volumes:
      - ./conduit.toml:/etc/matrix-conduit/conduit.toml:ro
      - ./data:/var/lib/matrix-conduit/
    ports:
      - "8128:6167"
    networks:
      - conduit-net

networks:
  conduit-net:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.70.0/24

逐项说明：environment 注入 CONDUIT_CONFIG 指向挂载进容器的配置文件；第一个 volume 把配置以只读（:ro）挂载到 /etc/matrix-conduit/conduit.toml，第二个 volume 把数据目录持久化到宿主 ./data；ports 把宿主 8128 映射到服务端口 6167；自定义 bridge 网络固定子网 10.89.70.0/24，避免与既有网络段冲突。

4.4 启动

docker compose up -d
docker compose ps

docker compose ps 实测可见 conduit-0.10.15-server 处于 running。查看启动日志：

docker compose logs conduit | head -20

实测启动日志（输出节选，实测首尾；RocksDB 加载成功即数据库就绪）：

2026-10-25T03:33:18.791819Z  INFO conduit: Loading database
2026-10-25T03:33:18.937595Z  INFO conduit::database: Loaded rocksdb database with version 18
2026-10-25T03:33:18.937951Z  INFO conduit: Starting server
2026-10-25T03:33:18.939145Z  INFO conduit::service::media: Checking if any media should be deleted due to time-based retention policies
2026-10-25T03:33:18.939191Z  INFO conduit::service::media: Found 0 media files to delete

4.5 协议级验证

curl -s http://127.0.0.1:8128/_matrix/client/versions

实测响应（支持 Matrix Client-Server API r0.5.0～v1.12）：

{"versions":["r0.5.0","r0.6.0","v1.1","v1.2","v1.3","v1.4","v1.5","v1.6","v1.7","v1.8","v1.9","v1.10","v1.11","v1.12"],"unstable_features":{"org.matrix.e2e_cross_signing":true,"org.matrix.msc3916.stable":true,"org.matrix.simplified_msc3575":true}}

4.6 注册管理员账号（UIAA 两步）

开启注册令牌后注册需两步。第一步：

curl -s -X POST http://127.0.0.1:8128/_matrix/client/v3/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测响应（401 态返回所需流程与会话标识）：

{"flows":[{"stages":["m.login.registration_token"]}],"session":"wCtiQwV7ZbS0TNP25tTFcJX8wqv7JyqA"}

第二步携带令牌与上一步 session：

curl -s -X POST http://127.0.0.1:8128/_matrix/client/v3/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4","auth":{"type":"m.login.registration_token","token":"q1w2e3r4-reg-token","session":"wCtiQwV7ZbS0TNP25tTFcJX8wqv7JyqA"}}'

实测注册成功响应：

{"access_token":"OOh9cF5DTMCcts5qHYDGtwmIMsAzq1Ub","user_id":"@admin:conduit.example.com","device_id":"bpPzcaktvK"}

access_token 即后续 API 调用的 Bearer 令牌；首个注册用户会被自动拉入管理房间（@conduit 机器人会话），管理命令用法见《Conduit 0.10.15 API 使用详解》。

五、数据持久化说明

数据全部落在服务内 /var/lib/matrix-conduit/（RocksDB 数据与媒体同目录），本指南以 bind mount 持久化到宿主项目目录 ./data：账号、房间、消息、媒体、密钥都在其中，备份即拷贝该目录（建议停机后拷贝，保证 RocksDB 一致性）。

持久化实测验证：执行 docker compose down && docker compose up -d 整体重建服务后，用重建前签发的 admin 访问令牌调 whoami：

curl -s -H "Authorization: Bearer <重建前签发的令牌>" http://127.0.0.1:8128/_matrix/client/v3/account/whoami

实测响应（旧令牌仍然有效，即账号与会话数据完整落盘）：

{"user_id":"@admin:conduit.example.com","device_id":"lrPc8TgOqe"}

六、环境变量表

Conduit 支持「配置文件之外」用环境变量逐项覆盖：字段对应 CONDUIT_{字段名}（大写），表内字段对应 CONDUIT_{表名}_{字段名}（如 well_known 表的 client 项即 CONDUIT_WELL_KNOWN_CLIENT）。环境变量优先级高于配置文件，改环境变量无需动配置文件，重建服务即生效。常用项：

覆盖实测（本环境真实验证）：在 environment: 追加 CONDUIT_ALLOW_REGISTRATION: "false" 并 docker compose up -d 重建后，注册接口直接返回 {"errcode":"M_FORBIDDEN","error":"M_FORBIDDEN: Registration has been disabled."}；追加 CONDUIT_LOG: "debug" 后日志出现 DEBUG 级行——覆盖无需修改 conduit.toml，即改即生效。

七、配置参数说明

compose 形态的配置全部通过 4.2 节的 conduit.toml 承载（[global] 段），常用键与默认值：

完整参数表（media 媒体存储/S3/保留策略、tls、proxy、well_known 委派等）见《Conduit 0.10.15 配置参数详解》。

八、配置文件挂载

本指南把 conduit.toml 以只读方式挂载到 /etc/matrix-conduit/conduit.toml：

• 只读（:ro）：防止服务进程或误操作在容器内改写配置，配置变更只能在宿主侧进行，与 IaC 习惯一致；
• 改配置必须重启生效：Conduit 只在启动时加载配置，修改 conduit.toml 后执行 docker compose restart conduit（或改 environment: 后 docker compose up -d 重建）；
• 路径可自定义：CONDUIT_CONFIG 与挂载目标保持一致即可，例如挂到 /conduit.toml 则 CONDUIT_CONFIG=/conduit.toml。

九、等价 docker run

不用 compose 时的等价单命令（参数与 4.3 节一一对应）：

docker run -d \
  --name conduit-0.10.15-server \
  --restart unless-stopped \
  -e CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml \
  -v ~/conduit-0.10.15-stack/conduit.toml:/etc/matrix-conduit/conduit.toml:ro \
  -v ~/conduit-0.10.15-stack/data:/var/lib/matrix-conduit/ \
  -p 8128:6167 \
  matrixconduit/matrix-conduit:v0.10.15

十、常用运维命令

docker compose ps                    # 查看服务状态
docker compose logs -f conduit       # 跟踪日志
docker compose restart conduit       # 重启（改配置后必做）
docker compose pull                  # 拉取镜像（配合改 tag 升级）
docker compose up -d                 # 应用编排变更/升级后重建
docker compose down                  # 停止并删除服务（数据保留在 ./data）

升级流程：改 docker-compose.yml 的 image: tag（如 v0.10.16）→ docker compose pull → docker compose up -d → docker compose logs -f conduit 观察 RocksDB 加载与启动日志。回滚：把 tag 改回旧版本再 up -d 即可（数据目录未动）。

⚠️ 注意：该官方镜像为精简运行时，服务内不带 curl/shell 等调试工具，健康检查与 API 调用一律在宿主侧执行（本文全部 curl 均为宿主侧实测）。

十一、附节：Kubernetes 部署形态

Conduit 官方没有提供 Helm Chart 或 k8s 清单（matrixdocs 对比表口径，2026-10-25 实查）。社区侧可选用 wrenix/conduit Helm Chart（Artifact Hub 可查，chart 版本 1.0.26、应用版本 0.10.15，与本文版本一致），OCI 方式安装：

helm install conduit oci://codeberg.org/wrenix/helm-charts/conduit --values values.yaml

values.yaml 最小要点：conduit.server_name（域名）、persistence（PVC 承载 /var/lib/matrix-conduit）、service/ingress（暴露 6167，客户端与联邦共用）。Conduit 为单实例形态，副本数保持 1。

💡 说明：本附节为社区 Chart 的信息性指引（源：Artifact Hub，查询日期 2026-10-25）；本专栏的 Kubernetes 集群实测篇章将在后续批次补充，届时以实测为准。

十二、常见问题（FAQ）

Q1：启动失败，日志提示配置缺失？ CONDUIT_CONFIG 未设置或挂载路径不一致。确认 environment: 与 volume 挂载目标一致，且宿主侧 conduit.toml 存在。

Q2：宿主 curl 8128 拒绝连接？ 配置里 address 必须是 0.0.0.0（官方示例默认 127.0.0.1 只监听环回，端口映射转发不进去）；改完 docker compose restart conduit。

Q3：注册返回 M_FORBIDDEN: Registration has been disabled？ allow_registration 为 false（注意第六章：环境变量 CONDUIT_ALLOW_REGISTRATION 会覆盖配置文件）。改为 true 并重启。

Q4：数据会丢吗？ 不会，只要 ./data bind mount 存在。实测 down + up -d 重建后旧令牌 whoami 仍返回 200。切忌把数据放在匿名卷或层内。

Q5：如何上联邦？ allow_federation = true，并为 server_name 域名配好 HTTPS 反代（443 客户端 + 8448 联邦，或用 well_known 委派），TLS 终止在反代侧；反代把 /_matrix/* 与 /.well-known/matrix/* 转发到宿主 8128。

十三、参考链接

• Docker Hub 官方镜像：https://hub.docker.com/r/matrixconduit/matrix-conduit
• Conduit 官方部署文档：https://famedly.gitlab.io/conduit/deploying.html
• Conduit 官方配置文档：https://famedly.gitlab.io/conduit/configuration.html
• wrenix/conduit 社区 Helm Chart（Artifact Hub）：https://artifacthub.io/packages/helm/wrenix/conduit
• 本专栏介绍篇：《Conduit 介绍与选型指南》
• 本专栏安装篇：《Ubuntu 22.04 安装 Conduit 0.10.15 指南》
• 本专栏配置篇：《Conduit 0.10.15 配置参数详解》
• 本专栏 API 篇：《Conduit 0.10.15 API 使用详解》