Ubuntu 22.04 安装 Conduit 0.10.15 指南

在 Ubuntu 22.04 上安装 Conduit 0.10.15：官方静态二进制（方案A）与官方 deb 包（方案B）双方案全流程，含 systemd 托管、注册验证、资源占用实测、方案对比、升级与卸载。

ConduitConduitMatrix自托管即时通信2026/10/25

Ubuntu 22.04 安装 Conduit 0.10.15 指南

目标：在 Ubuntu 22.04 LTS 上从零安装 Conduit 0.10.15（Matrix 轻量级 homeserver），覆盖「官方静态二进制」（方案 A）与「官方 deb 包」（方案 B）两种方案，含 systemd 托管、注册验证、方案对比、升级与卸载。全部命令与回显已在 Ubuntu 22.04（x86_64，systemd）真实环境实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64），systemd 249；
  • 软件版本：Conduit v0.10.15（tag 日期 2026-09-29，2026 年最新稳定版）；
  • 制品：静态二进制 x86_64-unknown-linux-musl（65695016 字节，约 63MB）、deb 包 x86_64-unknown-linux-musl.deb（13158336 字节，约 13MB），均来自 GitLab CI 官方制品；
  • 服务端口：6167（客户端 API 与联邦 API 共用）；
  • 数据目录：/var/lib/matrix-conduit/；配置文件：/etc/matrix-conduit/conduit.toml；
  • 演示环境信息：server_name conduit.example.com，注册令牌 q1w2e3r4-reg-token，演示管理员账号 admin / 密码 q1w2e3r4；
  • 网络情况：官方源 gitlab.com 制品直连实测可用（63MB 二进制约 24 秒、2.65 MB/s），未发生降级。

二、前置条件

  1. 一台 Ubuntu 22.04 服务器（物理机或虚拟机均可），具备 root 或 sudo 权限；
  2. 系统由 systemd 托管（Ubuntu 22.04 默认即 systemd，本指南的服务托管依赖它）；
  3. 可访问 gitlab.com（下载官方制品）；如官方源不可达，按贵司出口策略配置代理后重试；
  4. 安装基础工具（实测输出，已装则显示为最新版）：
apt-get update && apt-get install -y wget curl

Reading package lists...
Building dependency tree...
Reading state information...
curl is already the newest version (7.81.0-1ubuntu1.30).
wget is already the newest version (1.21.2-2ubuntu1.5).
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.

三、版本选型说明

本章说明「装哪个版本、选哪种制品」。

版本节奏（GitLab Tags 页实查，查询日期 2026-10-25）：v0.10.15（2026-09-29）为最新稳定版；近期版本序列为 v0.10.14（2026-09-26）、v0.10.13（2026-08-25）、v0.10.12（2026-02-12）、v0.10.11（2025-12-30）、v0.10.10（2025-12-22）。近期多个版本含安全修复，生产环境建议始终安装最新稳定版。

制品形态对照（官方部署文档《Generic deployment》口径）：

制品形态适用
静态二进制（musl）单文件 63MB，不依赖系统 glibc任意 Linux x86_64/aarch64，最通用（方案 A）
deb 包13MB，自动建用户/配置/systemd 单元Debian/Ubuntu 系，最省事（方案 B）
OCI 镜像matrixconduit/matrix-conduitCompose 形态部署（见本专栏部署篇）

💡 说明：官方文档提示其动态构建链接的是 Debian bullseye 的 glibc，老系统（如 RHEL8）可能需自行编译；而本文方案 A 用的是 musl 静态链接二进制，不依赖系统 glibc，无此限制。

四、方案 A：官方静态二进制安装（推荐，最通用）

本章按「下载 → 校验 → 建用户 → 配置 → systemd 托管 → 验证」完整走一遍。

4.1 下载二进制

从 GitLab CI 制品库下载 v0.10.15 的 x86_64 musl 静态二进制（aarch64 机器把 URL 中 x86_64-unknown-linux-musl 换成 aarch64-unknown-linux-musl）：

wget -O /usr/local/bin/matrix-conduit "https://gitlab.com/api/v4/projects/famedly%2Fconduit/jobs/artifacts/v0.10.15/raw/x86_64-unknown-linux-musl?job=artifacts"

实测下载完成回显（输出节选，实测首尾）：

 64150K .....                                                 100% 9.85T=24s

2026-10-25 11:42:55 (2.65 MB/s) - ‘matrix-conduit’ saved [65695016/65695016]

4.2 校验与赋权

sha256sum /usr/local/bin/matrix-conduit
chmod +x /usr/local/bin/matrix-conduit
matrix-conduit --version

实测输出：

670c13848dd8040888d12d9ad188d8a2d0035e5883dac861988eca204f1ee778  /usr/local/bin/matrix-conduit
conduit 0.10.15 (db37763)

sha256 与本文一致即下载完整；--version 打印 conduit 0.10.15 (db37763) 说明二进制可正常执行。Conduit 无子命令体系，--help 实测输出如下（只有帮助与版本两个选项）：

A Matrix homeserver written in Rust

Usage: matrix-conduit

Options:
  -h, --help     Print help
  -V, --version  Print version

4.3 创建专用运行用户

用专用系统用户运行服务（最小权限），官方文档推荐命令：

adduser --system conduit --group --disabled-login --no-create-home

实测输出：

Adding system user `conduit' (UID 106) ...
Adding new group `conduit' (GID 107) ...
Adding new user `conduit' (UID 106) with group `conduit' ...
Not creating home directory `/home/conduit'.

4.4 编写配置文件

Conduit 必须通过环境变量 CONDUIT_CONFIG 指定配置文件路径才能启动（未设置会直接报错退出）。创建配置目录与配置文件：

mkdir -p /etc/matrix-conduit

写入 /etc/matrix-conduit/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（@admin:conduit.example.com）与房间 ID 后缀；生产环境填真实域名并配好 HTTPS 反代；
  • database_backend = "rocksdb"：嵌入式 KV 存储（官方推荐），数据全部落在 database_path；
  • address = "0.0.0.0"：监听所有网卡（便于测试）；生产放反代后时应改 127.0.0.1 只让反代转发；
  • port = 6167：客户端与联邦共用端口；
  • allow_registration = true + registration_token：开放注册但需提供令牌，防止任何人随意注册；生产环境请换成强随机令牌；
  • allow_federation = false：本测试环境关闭联邦（无外网域名）；要加入 Matrix 联邦网络需改为 true 并保证 443/8448 可达；
  • enable_lightning_bolt = true：注册用户名自动追加 ⚡️ 后缀（Conduit 特色，实测注册 admin 后显示名为 admin ⚡️）。

4.5 数据目录与权限

mkdir -p /var/lib/matrix-conduit/
chown -R conduit:conduit /var/lib/matrix-conduit/
chmod 700 /var/lib/matrix-conduit/
chown -R root:root /etc/matrix-conduit
chmod 755 /etc/matrix-conduit

数据目录归 conduit 用户且仅其可读写（700）；配置目录归 root、全员可读（服务进程以 conduit 身份读取配置）。

4.6 systemd 托管

创建 /etc/systemd/system/conduit.service（官方文档推荐单元）：

[Unit]
Description=Conduit Matrix Server
After=network.target

[Service]
Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml"
User=conduit
Group=conduit
Restart=always
ExecStart=/usr/local/bin/matrix-conduit

[Install]
WantedBy=multi-user.target

要点：Environment= 行把 CONDUIT_CONFIG 注入服务进程；Restart=always 保证崩溃自愈；User=conduit 降权运行。加载、开机自启、启动（每行仅操作一个单元）：

systemctl daemon-reload
systemctl enable conduit
systemctl start conduit

4.7 验证

查看服务状态：

systemctl status conduit

实测输出（active (running) 即托管成功）：

● conduit.service - Conduit Matrix Server
     Loaded: loaded (/etc/systemd/system/conduit.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 03:30:17 UTC; 1min 26s ago
   Main PID: 2676 (matrix-conduit)
      Tasks: 15 (limit: 3612)
     Memory: 9.8M
        CPU: 1.623s

协议级健康检查：

curl -s http://127.0.0.1:6167/_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.8 注册管理员账号（UIAA 两步）

开启注册令牌后，注册需走 UIAA（用户交互认证）两步。第一步不带认证信息发起注册，服务端返回 401 与所需流程：

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

实测响应（flows 声明需要 m.login.registration_token 阶段，session 为本次会话标识）：

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

第二步携带令牌与上一步的 session 完成注册：

curl -s -X POST http://127.0.0.1:6167/_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":"Q970Uhdm5AZwkyCQsrOPZ7GnwFJH5GjN"}}'

成功响应返回 access_token / user_id / device_id 三要素（完整字段说明见《Conduit 0.10.15 API 使用详解》）。注册成功后用账号密码登录验证：

curl -s -X POST http://127.0.0.1:6167/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d '{"type":"m.login.password","identifier":{"type":"m.id.user","user":"admin"},"password":"q1w2e3r4"}'

实测响应：

{"user_id":"@admin:conduit.example.com","access_token":"hYqT8wpBmzFTbGcvdS94Dv559UyqRCEd","home_server":"conduit.example.com","device_id":"c5FLuXOPmF"}

拿到 access_token 即全流程跑通。

4.9 资源占用实测

完成注册后的稳态占用：

du -sh /var/lib/matrix-conduit/
ps -o rss= -p "$(systemctl show -p MainPID --value conduit)"

实测输出：

76M	/var/lib/matrix-conduit/
37072

即数据目录约 76MB（RocksDB 初始数据 + 联邦缓存），进程常驻内存约 37MB——印证了 Conduit 的「轻量」定位。

五、方案 B：官方 deb 包安装（Debian/Ubuntu 最省事）

deb 包会自动完成建用户、写配置、装 systemd 单元，适合 Debian/Ubuntu 系快速装机。

5.1 下载 deb 包

wget -O /tmp/matrix-conduit.deb "https://gitlab.com/api/v4/projects/famedly%2Fconduit/jobs/artifacts/v0.10.15/raw/x86_64-unknown-linux-musl.deb?job=artifacts"

实测下载完成回显（输出节选，实测首尾）：

 12800K .......... .......... .......... ......... 100% 6.41M=6.9s

2026-10-25 11:43:04 (1.81 MB/s) - ‘matrix-conduit.deb’ saved [13158336/13158336]

5.2 安装

dpkg -i /tmp/matrix-conduit.deb

实测输出（自动创建系统用户 _matrix-conduit 并注册 matrix-conduit.service 开机自启）：

(Reading database ... 7102 files and directories currently installed.)
Preparing to unpack /tmp/matrix-conduit.deb ...
Unpacking matrix-conduit (0.10.15-1) ...
Setting up matrix-conduit (0.10.15-1) ...
Adding system user for the Conduit Matrix homeserver
Created symlink /etc/systemd/system/multi-user.target.wants/matrix-conduit.service → /lib/systemd/system/matrix-conduit.service.

验证包已安装：

dpkg -l matrix-conduit | tail -1

实测输出：

ii  matrix-conduit              0.10.15-1                               amd64        A Matrix homeserver written in Rust

5.3 修改配置

deb 包的配置文件同样位于 /etc/matrix-conduit/conduit.toml（内容为带完整注释的官方示例，默认 address = "127.0.0.1"、port = 6167）。必改 server_name：

sed -i 's/^#server_name = "your.server.name"/server_name = "conduit.example.com"/' /etc/matrix-conduit/conduit.toml
grep '^server_name' /etc/matrix-conduit/conduit.toml

实测输出：

server_name = "conduit.example.com"

⚠️ 注意：deb 包默认配置未设置 registration_token，且 allow_registration = true——需要注册令牌管控时在 [global] 段追加 registration_token = "q1w2e3r4-reg-token" 即可，改完重启服务生效。

5.4 启动与验证

deb 的 systemd 单元名为 matrix-conduit.service（与方案 A 的 conduit.service 不同），二进制位于 /usr/sbin/matrix-conduit，以动态用户 _matrix-conduit 运行（单元内 DynamicUser=yes，数据目录实为 /var/lib/private/matrix-conduit，/var/lib/matrix-conduit 是指向它的符号链接），并预置了 ProtectSystem=strict 等一整套安全沙箱项。启动并查看状态：

systemctl start matrix-conduit
systemctl status matrix-conduit

实测输出：

● matrix-conduit.service - Conduit Matrix homeserver
     Loaded: loaded (/lib/systemd/system/matrix-conduit.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 03:32:54 UTC; 12s ago
   Main PID: 2665 (matrix-conduit)
      Tasks: 15 (limit: 3612)
     Memory: 10.3M

协议与版本双重验证：

curl -s http://127.0.0.1:6167/_matrix/client/versions
matrix-conduit --version

实测输出：

{"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}}

conduit 0.10.15 (db37763)

六、方案对比与选择建议

维度方案 A：静态二进制方案 B：deb 包
制品大小63MB（65695016 字节）13MB（13158336 字节）
二进制位置/usr/local/bin/matrix-conduit/usr/sbin/matrix-conduit
systemd 单元手写 conduit.service包自带 matrix-conduit.service（含沙箱加固）
运行用户手建 conduit包自建 _matrix-conduit（DynamicUser）
配置文件自建 /etc/matrix-conduit/conduit.toml包自带注释完整示例，仅需改 server_name
跨发行版任意 Linux（musl 静态）仅 Debian/Ubuntu 系
升级方式换二进制 + restart装新版 deb
适用通用、可控性最强Debian/Ubuntu 快速装机、最省事

选择建议：Ubuntu/Debian 服务器求省事选方案 B（包管理可追踪、自带加固单元）；其他发行版、或要严格控制二进制位置与单元内容的场景选方案 A。两方案不可混装于同一机器（端口与数据目录相同，会冲突）。

七、配置说明

两方案共用同一份 conduit.toml（[global] 段）。常用键速查（完整参数表与环境变量覆盖见《Conduit 0.10.15 配置参数详解》）：

键默认说明
server_name无（必填）Matrix 域名，用户/房间 ID 后缀
database_backend无（必填）rocksdb（推荐）或 sqlite
database_path无（必填）数据目录，RocksDB 与媒体同目录
address / port127.0.0.1 / 8000监听地址与端口；官方示例约定 6167
max_request_size20MiB上传体积上限（字节）
allow_registrationfalse是否开放注册
registration_token无静态注册令牌，设置后注册必须携带
allow_federationfalse是否加入联邦网络
trusted_servers["matrix.org"]获取他服公钥的公证服务器列表
logwarn日志级别（tracing EnvFilter 语法）

⚠️ 注意：官方配置文档的参数表写 port 默认 8000、default_room_version 默认 "10"，而官方示例配置与 deb 包默认用 6167，v0.10.15 实测默认房间版本为 12——以实测与官方示例为准。

八、常见问题（FAQ）

Q1：启动即退出，日志报配置错误？ Conduit 必须设置 CONDUIT_CONFIG 环境变量指向配置文件，未设置会拒绝启动。手工调试时用 CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml matrix-conduit；systemd 托管时确认单元里有 Environment="CONDUIT_CONFIG=/etc/matrix-conduit/conduit.toml" 行并已 daemon-reload。

Q2：注册返回 M_FORBIDDEN: Registration has been disabled？ allow_registration 为 false。改为 true 并重启；若已设 registration_token，注册请求必须走 4.8 节的 UIAA 两步并携带令牌。

Q3：图形客户端注册时找不到填令牌的地方？ 官方 README 点名支持注册令牌的客户端为 Element web、Nheko、SchildiChat web；其他客户端可改用 4.8 节的 curl 两步注册完成账号创建后再登录。

Q4：curl 6167 端口拒绝连接？ 依次排查：systemctl status conduit 是否 active；配置 address 是否为 0.0.0.0（默认 127.0.0.1 仅本机可达）；ss -tlnp | grep 6167 确认监听；防火墙放行。

Q5：老系统（RHEL8 等老 glibc）能跑吗？ 方案 A 为 musl 静态链接，不依赖系统 glibc，可直接运行；官方提示其动态构建制品链接 Debian bullseye 的 glibc，老系统才需自行编译。

九、卸载与清理

方案 A 卸载（每行仅操作一个单元）：

systemctl stop conduit
systemctl disable conduit
rm /etc/systemd/system/conduit.service
systemctl daemon-reload
rm /usr/local/bin/matrix-conduit
rm -rf /etc/matrix-conduit /var/lib/matrix-conduit
userdel conduit

方案 B 卸载（purge 连带删除配置；数据目录按需手动清理）：

systemctl stop matrix-conduit
dpkg -P matrix-conduit
rm -rf /etc/matrix-conduit /var/lib/matrix-conduit

⚠️ 注意：rm -rf /var/lib/matrix-conduit 会删除全部账号、房间与消息数据（RocksDB 库），执行前确认已备份或确属测试环境。

十、参考链接