Ubuntu 22.04 安装 Tuwunel v1.9.3 指南

目标：在 Ubuntu 22.04 LTS 上通过 Cargo 源码编译安装 Tuwunel v1.9.3，并配置 systemd 托管服务。两种安装方式：方式 A（推荐）下载预编译静态二进制，方式 B 从源码 cargo build 编译。编译过程已在 Ubuntu 22.04 容器中实测。

一、环境信息

项	值
Tuwunel 版本	v1.9.3
编译依赖	Rust ≥ 1.82（实测 1.99.1）、CMake、OpenSSL、libclang-dev、liburing-dev
运行内存	< 200MB（jemalloc + RocksDB）
编译内存	~2–4GB（release profile）
编译时间	首次 ~20–30 分钟（8 核 CPU）
数据库	RocksDB（嵌入式，135 column families）
配置格式	TOML
监听端口	8008（Matrix Client-Server + Federation 共用）

二、前置条件

操作系统：Ubuntu 22.04 LTS（x86_64 或 aarch64）
最小硬件：2 核 CPU、2GB RAM（编译需 4GB+）、2GB 磁盘
网络：能访问 GitHub（github.com/matrix-construct/tuwunel）和 GHCR（ghcr.io），如受限需配置代理 http_proxy
防火墙：开放 8008/tcp（Client-Server API）和 8448/tcp（Federation，可选）

三、版本选型说明

安装方式	优点	缺点	适用场景
方式 A：预编译静态二进制（推荐）	零编译时间、2 分钟搞定、musl 静态链接无依赖	版本滞后源码 1–2 天	生产部署、不想装 Rust 的用户
方式 B：Cargo 源码编译	最新代码、可自定义 feature（ldap/url_preview 等）	编译久（~30min）、编译依赖多	需要最新补丁、定制编译选项
Docker 镜像	见 B2 部署指南	非本文重点	容器化部署

💡 本文同时给出 A（二进制）和 B（源码）两种方式的完整步骤。首次部署推荐方式 A。

四、方式 A：预编译静态二进制安装（推荐）

4.1 下载预编译二进制

# 查询最新 release tag（2026-10-27 实测 v1.9.3）
curl -s https://api.github.com/repos/matrix-construct/tuwunel/releases/latest \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['tag_name'])"
# v1.9.3

# 下载 x86_64 静态二进制
VERSION="v1.9.3"
ARCH="x86_64"  # 或 aarch64
curl -fsSL -x http://192.168.1.62:7897 \
  "https://github.com/matrix-construct/tuwunel/releases/download/${VERSION}/tuwunel-${VERSION#v}-${ARCH}-unknown-linux-musl.tar.xz" \
  -o /tmp/tuwunel.tar.xz

⚠️ 网络说明：GitHub 直连在部分网络环境下可能被阻断（实测 connection reset by peer），需配置代理 curl -x http://192.168.1.62:7897 或设置 export http_proxy。

4.2 安装

# 创建系统用户（Tuwunel 非 root 运行）
sudo useradd --system --no-create-home --shell /usr/sbin/nologin --user-group tuwunel

# 解压并安装二进制
sudo tar -xJf /tmp/tuwunel.tar.xz -C /usr/local/bin/
sudo chmod +x /usr/local/bin/tuwunel
tuwunel --version  # 验证
# Tuwunel 1.9.3

# 创建数据目录
sudo mkdir -p /var/lib/tuwunel
sudo chown tuwunel:tuwunel /var/lib/tuwunel

# 创建配置目录
sudo mkdir -p /etc/tuwunel
sudo chown tuwunel:tuwunel /etc/tuwunel

# 下载示例配置
curl -fsSL "https://raw.githubusercontent.com/matrix-construct/tuwunel/v1.9.3/tuwunel-example.toml" \
  -o /etc/tuwunel/tuwunel.toml

4.3 配置

sudo vim /etc/tuwunel/tuwunel.toml

必须修改的项：

[global]
# 服务器名（⚠️ 改后数据库需清空）
server_name = "chat.example.com"

# 数据目录
database_path = "/var/lib/tuwunel"

# 监听地址（0.0.0.0 所有网卡）
address = ["0.0.0.0"]

# 监听端口
port = 8008

# 注册：token 模式（推荐）
allow_registration = true
registration_token = "你的32位随机字符串"

# 或：开放注册（需额外两个标志）
# allow_registration = true
# yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = true

# 管理员注册密钥（可选，启用 _synapse/admin/v1/register）
registration_shared_secret = "另一个长随机字符串"

# 日志
log_levels = "info"

# Admin Room（默认 true，首个注册用户自动 admin）
create_admin_room = true
admin_console_automatic = true

💡 完整配置 4314 行，按《Tuwunel v1.9.3 配置参数详解》逐项查阅。生产部署至少配置 server_name、registration_token、database_backup_path。

4.4 systemd 托管

创建 /etc/systemd/system/tuwunel.service：

[Unit]
Description=Tuwunel Matrix Homeserver
After=network.target

[Service]
Type=simple
User=tuwunel
Group=tuwunel
WorkingDirectory=/var/lib/tuwunel
ExecStart=/usr/local/bin/tuwunel -c /etc/tuwunel/tuwunel.toml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5

# 硬限制（生产环境建议）
NoNewPrivileges=true
ProtectSystem=full
ProtectHome=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
PrivateTmp=true
PrivateDevices=true
MemoryDenyWriteExecute=true
SystemCallFilter=@system-service

# jemalloc 内存分配器建议（降低 Fragmentation）
Environment="MALLOC_CONF=background_thread:true,prof:false"

# OOM 保护
MemoryMax=2G
MemoryHigh=1.5G

[Install]
WantedBy=multi-user.target

# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable tuwunel
sudo systemctl start tuwunel

# 验证
sudo systemctl status tuwunel
# ● tuwunel.service - Tuwunel Matrix Homeserver
#   Active: active (running) since ...

# 查看日志
sudo journalctl -u tuwunel -f
# tuwunel::server: 1.9.3 server_name=chat.example.com database_path="/var/lib/tuwunel"
# tuwunel_database::engine::open: Opened database. columns=135 sequence=0
# tuwunel_router::serve: Listening on ["tcp:0.0.0.0:8008"]

五、方式 B：Cargo 源码编译安装

5.1 安装编译依赖

sudo apt-get update
sudo apt-get install -y \
  build-essential cmake pkg-config \
  libssl-dev libclang-dev protobuf-compiler \
  liburing-dev liblz4-dev libsnappy-dev librocksdb-dev \
  ca-certificates git curl

💡 这些依赖覆盖了 Tuwunel 的全部 Rust crate 的 native build 需求：OpenSSL（TLS）、Clang（bindgen）、liburing（Linux io_uring 异步加速）、lz4/snappy/rocksdb（RocksDB LSM-Tree 压缩与存储）。

5.2 安装 Rust 工具链

curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --profile minimal
# rustup 1.27.1 installed
# rustc 1.99.1
# cargo 1.99.1

source "$HOME/.cargo/env"
rustc --version
# rustc 1.99.1 (58cf8f9c3 2026-10-13)

5.3 Clone 源码并编译

export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897

# Clone 指定版本 tag
git clone --depth 1 --branch v1.9.3 https://github.com/matrix-construct/tuwunel.git
cd tuwunel

# release profile 编译
cargo build --release 2>&1 | tail -5
# Compiling tuwunel v1.9.3 (/opt/tuwunel)
# Finished `release` profile [optimized] target(s) in 25m 32s

# 可选：带定制 feature 编译（如关闭 ldap、开启 url_preview 等）
# cargo build --release --no-default-features --features "ldap,url_preview,media_thumbnail"

5.4 安装编译产物

# 创建用户（同方式 A）
sudo useradd --system --no-create-home --shell /usr/sbin/nologin --user-group tuwunel
sudo mkdir -p /var/lib/tuwunel /etc/tuwunel
sudo chown tuwunel:tuwunel /var/lib/tuwunel /etc/tuwunel

# 安装二进制
sudo cp target/release/tuwunel /usr/local/bin/
sudo cp tuwunel-example.toml /etc/tuwunel/tuwunel.toml
sudo chmod +x /usr/local/bin/tuwunel

# 验证
tuwunel --version
# Tuwunel 1.9.3

⚠️ 源码编译产物静态链接 RocksDB（非系统 librocksdb.so），所以二进制体积较大（release 约 30–40MB），但运行时无额外 native 依赖。

六、方案对比与选择建议

维度	方式 A（预编译二进制）	方式 B（Cargo 源码编译）
安装时间	~5 分钟	~30 分钟
编译依赖	无	build-essential + Rust + liburing + librocksdb 等
源码最新度	release tag	可指定 main 分支
定制编译选项	❌	✅（feature flags）
二进制体积	~35MB（musl 静态）	~40MB（glibc release）
系统依赖	无（musl）	glibc
推荐场景	生产部署、首次装	需要最新补丁、定制 feature

选择建议：

99% 场景 → 方式 A：预编译二进制零依赖、musl 静态链接、运维友好
只有当你需要：最新 bugfix（release 之间）、禁用某些 feature（缩小二进制）、启用实验性 feature 时才用方式 B

七、配置说明

安装后必须完成以下配置才能正常启动：

7.1 必填项

server_name = "你的域名"    # 绑定到用户 ID 的后缀
database_path = "/var/lib/tuwunel"   # 数据存放
registration_token = "随机令牌"       # 注册验证

7.2 安全加固

# 关闭开放注册（token 模式已开）
yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse = false

# Federation 黑名单（可选）
forbidden_remote_server_names = ["evil.*", "spam\\.example\\.com"]

# 媒体自动清理
expire_media_days = 90

# Admin 权限收敛
grant_admin_to_first_user = true  # 生产部署建议手动设 admin，关掉自动授权

7.3 性能调优

# 缓存倍数（内存充裕设 1.5–2.0）
cache_capacity_modifier = 1.0

# RocksDB 读缓存
db_cache_capacity_mb = 256

# RocksDB 写缓冲
db_write_buffer_capacity_mb = 64

# jemalloc（在 systemd Environment 设置 MALLOC_CONF）

八、验证

# 1. 服务状态
sudo systemctl is-active tuwunel
# active

# 2. 监听端口
ss -ltnp | grep tuwunel
# LISTEN 0 511 0.0.0.0:8008 ... users:(("tuwunel",pid=12345))

# 3. Matrix Client-Server 版本端点
curl -s http://localhost:8008/_matrix/client/versions | python3 -c "import sys,json; d=json.load(sys.stdin); print('CS API versions:', len(d['versions']), '; Latest:', d['versions'][-1])"
# CS API versions: 27; Latest: v1.19

# 4. 注册测试用户
SESSION=$(curl -s -X POST http://localhost:8008/_matrix/client/v3/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['session'])")
curl -s -X POST http://localhost:8008/_matrix/client/v3/register \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"admin\",\"password\":\"q1w2e3r4\",\"auth\":{\"type\":\"m.login.dummy\",\"session\":\"$SESSION\"}}" \
  | python3 -m json.tool
# {"user_id": "@admin:chat.example.com", "access_token": "..."}

# 5. 进程资源
ps -o pid,rss,vsz,comm,args -p $(pgrep tuwunel)
# PID  RSS    VSZ   COMMAND  ARGS
# 12345 187564 3500232 tuwunel  tuwunel -c /etc/tuwunel/tuwunel.toml

九、升级与降级

# 方式 A 升级：下载新版本覆盖二进制
VERSION="v1.9.4"  # 改版本
curl -fsSL "https://github.com/matrix-construct/tuwunel/releases/download/${VERSION}/tuwunel-${VERSION#v}-x86_64-unknown-linux-musl.tar.xz" \
  -o /tmp/tuwunel.tar.xz
sudo tar -xJf /tmp/tuwunel.tar.xz -C /usr/local/bin/
sudo systemctl restart tuwunel

# 方式 B 升级：pull 新 tag 重新编译
cd tuwunel
git fetch --tags
git checkout v1.9.4
source "$HOME/.cargo/env"
cargo build --release
sudo cp target/release/tuwunel /usr/local/bin/
sudo systemctl restart tuwunel

# 升级后验证
sudo journalctl -u tuwunel --since "2 min ago" | grep -i "version\|server_name"
# 1.9.4 server_name=chat.example.com

十、常见问题

Q1: liburing 找不到怎么办？

A: 确保 apt install liburing-dev（Ubuntu 22.04 默认源有）。如果还报错：

dpkg -l | grep liburing
apt install --reinstall liburing-dev

Q2: 编译时 RocksDB 编译太慢？

A: RocksDB 首次编译 C++ 源码 ~10 分钟。已安装系统 librocksdb-dev 后 Tuwunel 会尝试动态链接（需在 Cargo.toml feature 中启用），但默认仍静态编译。耐心等待即可。

Q3: systemd 启动后日志显示 "WARN Config parameter X is unknown"？

A: Tuwunel 启动时解析配置文件，如果有拼写错误或版本过时的 key，会 WARN 并忽略。v1.9.3 新增了一些配置项，建议用同版本的 tuwunel-example.toml 作为基础。

Q4: 注册用户时提示 "Registration has been disabled"？

A: 生产默认禁用注册。修改 /etc/tuwunel/tuwunel.toml：

allow_registration = true
registration_token = "你的令牌"

然后：

sudo systemctl restart tuwunel

Q5: Federation 不通怎么办？

A: 检查 DNS（至少满足其一）：

chat.example.com:8448 直接可达
_matrix._tcp.chat.example.com SRV 记录指向 chat.example.com:8448
https://chat.example.com/.well-known/matrix/server 返回 {"m.server":"chat.example.com:8448"}

十一、卸载与清理

# 停止服务
sudo systemctl stop tuwunel
sudo systemctl disable tuwunel

# 删除服务文件
sudo rm /etc/systemd/system/tuwunel.service
sudo systemctl daemon-reload

# 删除二进制
sudo rm /usr/local/bin/tuwunel

# 删除配置
sudo rm -rf /etc/tuwunel

# 删除数据（⚠️ 所有用户/房间/消息全部丢失）
sudo rm -rf /var/lib/tuwunel

# 删除用户
sudo userdel -r tuwunel

# 方式 B 额外：清理编译产物（释放 ~5GB）
cd ~/.cargo
rm -rf registry cache  # 可选，清理 cargo 下载缓存

十二、参考链接

资源	URL
Tuwunel 源码仓库	https://github.com/matrix-construct/tuwunel
Releases（二进制下载）	https://github.com/matrix-construct/tuwunel/releases
官方 Generic 部署文档	https://matrix-construct.github.io/tuwunel/deploying/generic.html
tuwunel-example.toml（v1.9.3）	https://raw.githubusercontent.com/matrix-construct/tuwunel/v1.9.3/tuwunel-example.toml
Cargo 构建系统	https://doc.rust-lang.org/cargo/
systemd 官方文档	https://www.freedesktop.org/software/systemd/man/latest/systemd.unit.html