Ubuntu 22.04 安装 Continuwuity 26.9 指南

目标：在 Ubuntu 22.04 真实服务器上从零安装 Continuwuity（社区后继的轻量级 Matrix homeserver，二进制名 conduwuit），跑通「下载 → 安装 → 配置 → systemd 托管 → 注册首个管理员」全流程。本文两种方案（官方预编译静态二进制 v26.9.1、官方 APT 仓库 deb 包）均已在 Ubuntu 22.04.5 LTS（x86_64）实测通过，全部命令与回显逐行照抄。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（Jammy），x86_64，内核 5.15+（需支持 io_uring）
组件版本：Continuwuity v26.9.1（2026-09-28 发布，commit 046074b；CalVer 版本号，格式 年.月.序号）
关键命名：二进制文件名 conduwuit、配置文件 conduwuit.toml、systemd 单元 conduwuit.service、默认数据目录 /var/lib/conduwuit
默认监听：127.0.0.1:8008 与 [::1]:8008（仅回环，设计上由反向代理对外暴露 443/8448）
运行账户：conduwuit 系统账户（非 root 降权运行）
演示账号：admin + 密码 q1w2e3r4（示例口令，生产请替换）

二、前置条件

一台已联网的 Ubuntu 22.04 服务器，root 或 sudo 权限；
已安装 curl、ca-certificates、lsb-release：

apt-get update -qq
apt-get install -y curl ca-certificates lsb-release

实测回显（节选）：

curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 ...

确认机器架构，决定下载哪个二进制：

uname -m

实测回显：

x86_64

x86_64 对应 amd64 资产；ARM 服务器（aarch64）对应 arm64 资产，替换下文文件名即可。

三、版本选型说明

Continuwuity 使用 CalVer（日历版本） 编号：v26.9.1 表示 2026 年 9 月的第 1 个稳定版。截至本文实测日（2026-10-25），各渠道可拿到的版本如下：

渠道	实测可得版本	说明
Forgejo Releases 静态二进制	v26.9.1	最新稳定版，含关键联邦安全修复（SEC8），官方发布页逐版本提供
官方 APT 仓库（stable 组件）	26.7.1	实测 `apt-cache policy` 候选为 26.7.1，滞后于最新稳定版两个版本
源码编译（main 分支）	滚动	官方鼓励跟进 main，但需要 Rust 工具链，本文不展开

⚠️ 注意：v26.9.1 的 Release Notes 明确提示其修复了一个影响所有联邦部署的关键级别漏洞；APT 仓库 stable 组件实测仍停在 26.7.1，对安全敏感的公网联邦实例建议优先用方案 A（静态二进制）拿最新版。

💡 技术拓展：Matrix homeserver 的存储后端有多种实现路线。常见选项对比——

存储引擎特点适用场景
RocksDB（嵌入式 LSM KV）单文件进程内嵌、写放大低、无外部依赖 Continuwuity / conduwuit 唯一后端
SQLite（嵌入式关系库）零依赖、读多写少场景佳 Conduit 早期后端之一
PostgreSQL（外部关系库）功能强、可运维性好、需独立部署 Synapse 生产标配

Continuwuity 固定使用 RocksDB 嵌入式存储，因此安装过程无需准备任何外部数据库——这是它与 Synapse 最大的部署差异之一。

存储引擎	特点	适用场景
RocksDB（嵌入式 LSM KV）	单文件进程内嵌、写放大低、无外部依赖	Continuwuity / conduwuit 唯一后端
SQLite（嵌入式关系库）	零依赖、读多写少场景佳	Conduit 早期后端之一
PostgreSQL（外部关系库）	功能强、可运维性好、需独立部署	Synapse 生产标配

四、预编译静态二进制安装方案（A：官方 Releases，推荐）

4.1 方案说明

官方在 Forgejo Releases 页为每个版本提供预编译二进制，x86_64 下有四类资产（以 v26.9.1 为例）：

资产名	链接方式	适用
`conduwuit-linux-static-amd64`	静态链接	任意 glibc 发行版，不依赖宿主 liburing 库，推荐
`conduwuit-linux-amd64`	动态链接	需宿主安装 liburing 等动态库
`conduwuit-haswell-linux-amd64-maxperf`	动态链接 + LTO	Haswell 及以后 CPU 的性能优化版
`conduwuit-haswell-linux-static-amd64-maxperf`	静态链接 + LTO	同上，免依赖

💡 说明：静态二进制体积约 106 MiB，包含 RocksDB、jemalloc 等全部依赖；运行时仍要求内核支持 io_uring（Linux 5.1+，Ubuntu 22.04 的 5.15 内核满足）。

4.2 下载官方二进制

curl -fSL -o /usr/local/bin/conduwuit \
  https://forgejo.ellis.link/continuwuation/continuwuity/releases/download/v26.9.1/conduwuit-linux-static-amd64

实测回显（节选）：

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
100  106M  100  106M    0     0  11.5M      0:00:09  0:00:09 --:--:-- 15.5M

实测官方源直连 9 秒下完，未发生降级；若你的网络访问 Forgejo 缓慢，可改用镜像站或代理渠道下载同一 URL。

赋可执行权限并核对版本：

chmod +x /usr/local/bin/conduwuit
conduwuit --version

实测回显：

continuwuity 26.9.1 (046074b)

4.3 创建运行账户与目录

useradd -r -s /usr/sbin/nologin -d /var/lib/conduwuit -M conduwuit
mkdir -p /etc/conduwuit /var/lib/conduwuit
chown -R conduwuit:conduwuit /var/lib/conduwuit
chmod 700 /var/lib/conduwuit

4.4 最小化配置

写入 /etc/conduwuit/conduwuit.toml（此处先给最小可运行配置；全量参数逐项说明见《Continuwuity 26.9 配置参数详解》）：

[global]
server_name = "example.com"
database_path = "/var/lib/conduwuit"

chmod 755 /etc/conduwuit
chmod 644 /etc/conduwuit/conduwuit.toml

逐项说明：

server_name：本服务器在 Matrix 联邦中的域名标识，是用户 ID（@admin:example.com）与房间别名的后缀。设置后不可更改，除非清空数据库重来，务必填真实域名；
database_path：RocksDB 数据目录，与上文创建的属主一致；
address/port 未写时使用默认值：监听回环地址 127.0.0.1/::1 的 8008 端口，正好配合本机反向代理。

4.5 systemd 托管

写入单元文件 /etc/systemd/system/conduwuit.service：

[Unit]
Description=Continuwuity - Matrix homeserver
Documentation=https://continuwuity.org/
Wants=network-online.target
After=network-online.target

[Service]
Type=notify
User=conduwuit
Group=conduwuit
ExecStart=/usr/local/bin/conduwuit --config /etc/conduwuit/conduwuit.toml
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes
ProtectSystem=full
ProtectHome=yes
PrivateTmp=yes
SystemCallFilter=@system-service @resources io_uring_setup io_uring_enter io_uring_register

[Install]
WantedBy=multi-user.target

关键项说明：

Type=notify：conduwuit 启动就绪后通过 sd_notify 上报，systemd 可精确判断 active；
SystemCallFilter：放行 @system-service、@resources 两组之外，必须额外放行 io_uring_* 三个系统调用，否则 conduwuit 启动即报 Permission denied (os error 13)（实测见「八、常见问题」Q2）；
若希望支持 systemctl reload 热更配置，可补一行 ExecReload=/bin/kill -USR1 $MAINPID（SIGUSR1 触发热重载已实测生效）。

加载并启动：

systemctl daemon-reload
systemctl enable conduwuit
systemctl start conduwuit

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/conduwuit.service → /etc/systemd/system/conduwuit.service.

4.6 验证与注册首个管理员

查服务状态：

systemctl status conduwuit --no-pager

实测回显（节选）：

● conduwuit.service - Continuwuity - Matrix homeserver
     Loaded: loaded (/etc/systemd/system/conduwuit.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 03:37:49 UTC; 56s ago
   Main PID: 4031 (conduwuit)
      Tasks: 47 (limit: 3612)
     Memory: 24.4M

首次启动日志会打印一次性注册令牌（只有用它注册的第一个账户存在，之后注册自动关闭）：

journalctl -u conduwuit --no-pager | grep -E "Welcome|Listening|registration token"

实测回显：

INFO main:start: conduwuit_service::migrations: Created new database with version 19
INFO conduwuit_router::serve::plain: Listening on [127.0.0.1:8008, [::1]:8008]
Welcome to Continuwuity 26.9.1 (046074b)!
In order to use your new homeserver, you need to create its first user account.
Open your Matrix client of choice and register an account on example.com using the registration token gAWe3W8yURiiL5iM . Pick your own username and password!

先验证 HTTP 接口存活：

curl -s http://127.0.0.1:8008/_continuwuity/server_version

实测回显：

{"name":"continuwuity","version":"26.9.1 (046074b)"}

再用注册令牌注册管理员（admin / q1w2e3r4）：

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

实测回显：

{"access_token":"QfZZubDn1M0QpxY3kZa1dmB9","user_id":"@admin:example.com","device_id":"nubPe0EU0d"}

拿到 access_token 即说明注册成功，该账户自动成为服务器管理员并被拉入 #admin:example.com 管理房间。此时再试图无令牌注册会被拒绝：

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

实测回显：

{"errcode":"M_FORBIDDEN","error":"This server is not accepting registrations at this time."}

数据目录落盘核对：

ls /var/lib/conduwuit/

实测回显：

000004.log
CURRENT
IDENTITY
LOCK
MANIFEST-000005
OPTIONS-000007
archive
media

五、官方 APT 仓库安装方案（B：deb 包）

5.1 方案说明

官方维护方 continuwuation 在 Forgejo 上托管了 APT 仓库（同仓库另有 Fedora RPM 包），提供 continuwuity deb 包：自动创建用户、放置配置模板与 systemd 单元，apt upgrade 即可跟进更新。实测该仓库 stable 组件当前候选版本为 26.7.1，滞后于最新稳定版 v26.9.1，适合追求「包管理器托管」而非最新版的场景。

5.2 添加 APT 仓库

mkdir -p /etc/apt/keyrings
curl -fsSL https://forgejo.ellis.link/api/packages/continuwuation/debian/repository.key \
  -o /etc/apt/keyrings/forgejo-continuwuation.asc
echo "deb [signed-by=/etc/apt/keyrings/forgejo-continuwuation.asc] https://forgejo.ellis.link/api/packages/continuwuation/debian $(lsb_release -sc) stable" \
  > /etc/apt/sources.list.d/continuwuation.list
apt-get update

实测回显（节选）：

Get:6 https://forgejo.ellis.link/api/packages/continuwuation/debian jammy/stable amd64 Packages [3434 B]
Fetched 20.1 kB in 1s (15.8 kB/s)

查看候选版本：

apt-cache policy continuwuity

实测回显（节选）：

continuwuity:
  Installed: (none)
  Candidate: 26.7.1
  Version table:
     26.7.1 500
        500 https://forgejo.ellis.link/api/packages/continuwuation/debian jammy/stable amd64 Packages
     26.6.2 500
     ...
     0.5.10 500

5.3 安装

apt-get install -y continuwuity

实测回显（节选）：

Make sure you edit the example config at /etc/conduwuit/conduwuit.toml before starting!
To start the server, run: systemctl start conduwuit.service
Created symlink /etc/systemd/system/multi-user.target.wants/conduwuit.service → /lib/systemd/system/conduwuit.service.

包内文件布局：

dpkg -L continuwuity | grep -vE "/usr/share/doc"

实测回显（节选）：

/etc/conduwuit
/etc/conduwuit/conduwuit.toml
/usr/lib/systemd/system
/usr/lib/systemd/system/conduwuit.service
/usr/bin
/usr/bin/conduwuit

conduwuit --version

实测回显：

continuwuity 26.7.1 (83cf15bcc)

5.4 配置

编辑 /etc/conduwuit/conduwuit.toml，至少设置两项（找到对应注释行去掉 # 并填值）：

[global]
server_name = "example.com"
database_path = "/var/lib/conduwuit"

⚠️ 注意：deb 包把配置模板权限设为 640 root:root，而服务以动态用户 conduwuit 运行，必须放开为可读取，否则启动报 Permission denied：

chmod 644 /etc/conduwuit/conduwuit.toml

5.5 Ubuntu 22.04 的 systemd 兼容性处置（实测必做）

deb 包自带的 /usr/lib/systemd/system/conduwuit.service 面向更新版本 systemd 编写，在 Ubuntu 22.04（systemd 249）上直接 systemctl start 会失败，journalctl -u conduwuit 可见三类告警/报错：

/lib/systemd/system/conduwuit.service:12: Failed to parse service type, ignoring: notify-reload
/lib/systemd/system/conduwuit.service:13: Unknown key name 'ReloadSignal' in section 'Service', ignoring.
/lib/systemd/system/conduwuit.service:21: Unknown key name 'RefreshOnReload' in section 'Service', ignoring.
conduwuit[2982]: Error: There was a problem with your configuration file: missing field `server_name`

原因链（已逐条实测定位）：

Type=notify-reload、ReloadSignal、RefreshOnReload 均为 systemd 253+ 新指令，249 不识别（仅告警，可忽略）；
单元用 LoadCredential=conduwuit.toml:... 注入配置，但 systemd 249 实测凭据目录注入后为空，conduwuit 读不到配置才报 missing field server_name；
即使绕开凭据直读配置，单元内 SystemCallFilter 未放行 io_uring，启动报 Permission denied (os error 13)。

处置：写 override 覆盖这三点——

mkdir -p /etc/systemd/system/conduwuit.service.d
cat > /etc/systemd/system/conduwuit.service.d/override.conf <<'EOF'
[Service]
Type=notify
ExecStart=
ExecStart=/usr/bin/conduwuit --config /etc/conduwuit/conduwuit.toml
ReadOnlyPaths=/etc/conduwuit
SystemCallFilter=@system-service @resources io_uring_setup io_uring_enter io_uring_register
SystemCallFilter=~@clock @debug @module @mount @reboot @swap @cpu-emulation @obsolete @timer @chown @setuid @privileged @keyring @ipc
EOF
systemctl daemon-reload

5.6 启动与验证

systemctl start conduwuit
systemctl is-active conduwuit

实测回显：

active

journalctl -u conduwuit --no-pager | grep "registration token" | tail -1
curl -s http://127.0.0.1:8008/_continuwuity/server_version

实测回显：

... register an account on example.com using the registration token 6RNlL3hVseIdFVx1 . Pick your own username and password!
{"name":"continuwuity","version":"26.7.1 (83cf15bcc)"}

注册管理员（同 4.6，替换令牌即可）：

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

实测回显：

{"access_token":"otAZ9k4xPbt8wBLwWXo7JZ02","user_id":"@admin:example.com","device_id":"jh2pJq8Ahx"}

六、两种方案对比与选择建议

维度	A：静态二进制	B：APT 仓库 deb
实测版本	v26.9.1（最新稳定）	26.7.1（stable 组件滞后）
依赖	无（静态链接）	自动处理
安装位置	`/usr/local/bin/conduwuit`	`/usr/bin/conduwuit`
systemd 单元	自写（本文已给可用模板）	包自带（需按 5.5 打 override 补丁）
升级方式	重下二进制替换	`apt upgrade`
卸载	手动删文件	`apt purge` 自动清库

建议：公网联邦实例、在意安全补丁时效 → 选方案 A；内网小团队、希望包管理器托管升级 → 选方案 B，但注意 5.5 的兼容性处置不可省。

七、配置说明（共用）

无论哪种方案，运行时配置都集中在 /etc/conduwuit/conduwuit.toml（TOML 格式，全部键位于 [global] 段及少数子段）。与安装强相关的常用项：

参数	默认值	说明
`server_name`	无（必填）	Matrix 域名标识，首启后不可改
`database_path`	无	RocksDB 数据目录
`address`	`["127.0.0.1", "::1"]`	监听地址；前置反向代理场景保持回环即可
`port`	`8008`	监听端口
`allow_registration`	`false`	自由注册开关；首启用一次性令牌注册
`allow_federation`	`true`	联邦开关，纯内网可设 `false`
`log`	`info`	日志级别

对外提供服务的标准形态是「conduwuit 监听回环 8008 + 反向代理终结 TLS」，官方推荐 Caddy，最简配置示例：

example.com, example.com:8448 {
    reverse_proxy 127.0.0.1:8008
}

即客户端 443 与联邦 8448 两路流量统一回源到 127.0.0.1:8008。完整参数与环境变量（CONTINUWUITY_*）覆盖规则见《Continuwuity 26.9 配置参数详解》。

八、常见问题（FAQ）

Q1：启动报 Error: ... missing field server_name，但配置里明明写了？ deb 方案特有。原因是包内单元用 LoadCredential 注入配置，而 Ubuntu 22.04 的 systemd 249 实测凭据目录为空、文件未被注入。按 5.5 写 override 让 ExecStart 直读 /etc/conduwuit/conduwuit.toml 即可。

Q2：启动报 Permission denied (os error 13)，指向 conduwuit.toml？ 两种可能，按序排查：① 配置文件权限 640 而运行用户读不到 → chmod 644；② systemd 单元的 SystemCallFilter 没放行 io_uring（conduwuit 的文件 IO 依赖 io_uring，被拦截后统一报 EPERM）→ 在过滤表中追加 io_uring_setup io_uring_enter io_uring_register。

Q3：journalctl 提示 Unknown key name 'ReloadSignal' / Failed to parse service type: notify-reload？ systemd 249 不认识 253+ 的新指令，属无害告警；要消除就在 override 中把 Type= 改回 notify（见 5.5）。

Q4：默认端口到底是 8008 还是旧文档里的 6167？ 实测 v26.x 默认监听 8008（回环）；6167 是 conduwuit 时代旧默认值，部分旧文档未更新，以本机 ss -ltnp | grep conduwuit 实测为准。

Q5：改 server_name 后客户端登录异常？ server_name 写入数据库后不可更改，改动等同于换一台服务器。必须改时只能停服、清空 database_path、重新初始化。

Q6：注册令牌在哪看？丢失怎么办？ 首次启动打印在 journalctl -u conduwuit；每次启动若尚无本地用户会重新打印一个新令牌。已有管理员后，新用户注册由管理员在 #admin 房间用 !admin token 系列命令签发。

九、卸载与清理

方案 A（静态二进制）：

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

方案 B（deb 包）：apt purge 会连带删除配置与数据库目录，实测回显：

systemctl stop conduwuit
systemctl disable conduwuit
apt-get purge -y continuwuity
rm -f /etc/apt/sources.list.d/continuwuation.list /etc/apt/keyrings/forgejo-continuwuation.asc
apt-get update

实测回显（节选）：

Removed /etc/systemd/system/multi-user.target.wants/conduwuit.service.
Purging configuration files for continuwuity (26.7.1) ...
Deleting continuwuity database directory

十、参考链接

官方部署总览：https://continuwuity.org/deploying.html
Generic（二进制+systemd）部署：https://continuwuity.org/deploying/generic.html
Debian/Ubuntu 包部署：https://continuwuity.org/deploying/debian.html
Releases 页（二进制下载）：https://forgejo.ellis.link/continuwuation/continuwuity/releases
站内姊妹篇：《Continuwuity 介绍与选型指南》