轻量级matrix服务端tuwunel搭建

Posted on Jan 1, 2026

前言

先祝大家26年新年快乐最近需要重新搭建matrix服务端，刚好发现了tuwunel这个更轻量的实现虽然官方文档有搭建说明，但比较简略，实际操作中踩了一些小坑，刚好现在没事干，干脆写点东西记录一下相比于synapse，tuwunel在空载或少量聊天的情况下，内存占用约80mb左右
更加省资源，适合个人/小型聊天室/朋友之间使用

1.基础环境准备

本文基于debian和docker compose部署反代个人习惯用caddy，用nginx原理是一样的，只需要反代 8008 端口，其余配置可自行调整

开始前，先创建一个docker网络，方便caddy和matrix服务端通信

docker network create caddy

创建两个目录，分别用于管理caddy和matrix的配置文件：

mkdir -p /root/caddy /root/matrix

2.配置matrix服务端（tuwunel）

进入matrix目录并创建 docker-compose.yml：

cd /root/matrix
nano docker-compose.yml

示例配置如下（可替换域名直接使用）：

services:
  matrix:
    image: ghcr.io/matrix-construct/tuwunel:latest
    container_name: matrix_server   # 反代时使用的容器名，可自行修改
    restart: always
    volumes:
      - ./db:/var/lib/tuwunel/      # 数据库与聊天记录
    environment:
      - TUWUNEL_SERVER_NAME=你的域名
      - TUWUNEL_ALLOW_REGISTRATION=false  # 是否允许注册，true 为开启
      - TUWUNEL_ADDRESS=0.0.0.0
      - TUWUNEL_PORT=8008            # 容器内服务端口
    networks:
      - caddy

networks:
  caddy:
    external: true

启动matrix容器：

docker compose up -d

3.配置caddy反代

方式一：使用docker内的caddy（原方案）

如果服务器上还没有运行其他web服务，可以直接使用docker中的caddy进行反代

进入caddy目录并创建docker-compose.yml：

cd /root/caddy
nano docker-compose.yml

示例配置如下：

services:
  caddy:
    image: caddy:latest
    container_name: caddy_server
    restart: always
    ports:
      - "80:80"
      - "443:443"
      - "8448:8448"   #matrix联邦常用端口
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - caddy

networks:
  caddy:
    external: true

volumes:
  caddy_data:
  caddy_config:

接着编辑Caddyfile：

nano Caddyfile

caddyfile示例配置：

#【可选】禁止直接通过ip+端口访问，防止被扫描
:80, :443, :8448 {
    abort
}

你的域名 {
    reverse_proxy matrix_server:8008

    #【可选】客户端输入根域名自动识别matrix地址
    handle_path /.well-known/matrix/client {
        header Access-Control-Allow-Origin "*"
        header Content-Type "application/json"
        respond `{"m.homeserver": {"base_url": "https://你的域名"}}`
    }

    #【可选】告诉其他服务器可通过443端口进行联邦通信
    handle_path /.well-known/matrix/server {
        header Access-Control-Allow-Origin "*"
        header Content-Type "application/json"
        respond `{"m.server": "你的域名:443"}`
    }
}

#【可选】小部分服务器仍使用8448端口，以防万一
你的域名:8448 {
    reverse_proxy matrix_server:8008
}

如果服务器还运行了其他站点，使用 abort 前请确认不会影响其他站点

启动caddy：

docker compose up -d

方式二：宿主机已经安装caddy（推荐）

后来我自己的服务器逐渐开始运行更多服务后，已经改为：

宿主机 caddy → docker matrix/tuwunel

而不是：

docker caddy → docker matrix

对于低配置VPS来说，这样会更轻量、更稳定，同时也能统一管理HTTPS与反向代理配置

如果宿主机已经安装并运行了caddy，那么不建议再额外启动docker版caddy，否则可能会出现：

failed to bind host port 0.0.0.0:80: address already in use

因为80/443端口已经被宿主机caddy占用

此时只需要：

不启动docker版caddy
删除docker compose中的80/443映射
直接让宿主机caddy反代matrix即可

例如matrix compose可保持：

services:
  matrix:
    image: ghcr.io/matrix-construct/tuwunel:latest
    container_name: matrix_server
    restart: always
    volumes:
      - ./db:/var/lib/tuwunel/
    environment:
      - TUWUNEL_SERVER_NAME=你的域名
      - TUWUNEL_ALLOW_REGISTRATION=false
      - TUWUNEL_ADDRESS=0.0.0.0
      - TUWUNEL_PORT=8008
    ports:
      - "8008:8008"

然后直接修改宿主机：

nano /etc/caddy/Caddyfile

添加：

你的域名 {
    reverse_proxy 127.0.0.1:8008

    handle_path /.well-known/matrix/client {
        header Access-Control-Allow-Origin "*"
        header Content-Type "application/json"
        respond `{"m.homeserver": {"base_url": "https://你的域名"}}`
    }

    handle_path /.well-known/matrix/server {
        header Access-Control-Allow-Origin "*"
        header Content-Type "application/json"
        respond `{"m.server": "你的域名:443"}`
    }
}

保存后执行：

systemctl reload caddy

4.手动创建账号并设置管理员

如果你开启了注册（TUWUNEL_ALLOW_REGISTRATION=true），可以跳过这一步当关闭注册时，需要手动创建第一个账号

停止matrix服务

cd /root/matrix
docker compose stop

进入tuwunel控制台

docker run --rm -it \
  -v $(pwd)/db:/var/lib/tuwunel/ \
  -e TUWUNEL_SERVER_NAME=你的域名 \
  ghcr.io/matrix-construct/tuwunel:latest \
  --console

看到 uwu> 提示符后，依次执行：

创建用户：

admin users create-user 用户名

设置密码：

admin users reset-password @用户名:你的域名 密码

赋予管理员权限：

admin users make-user-admin @用户名:你的域名

退出控制台：

ctrl+\ （enter上面那个）
或 ctrl+d

重启matrix服务

docker compose up -d

5.联邦测试

官方联邦测试工具：

https://federationtester.matrix.org/

输入你的域名，如果全部显示为绿色，说明服务器可以被正常发现，并且可以和其他matrixm服务器互通

什么是「联邦」？

简单说一句话：

联邦=不同matrix服务器之间可以互相聊天

比如：

你在自己搭的matrix服务器上
朋友在别的matrix服务器上

只要开启了联邦，你们就能互相加好友、进同一个房间聊天就像不同邮箱之间可以互相发邮件一样

6.关于cf的说明

如果开了cf小黄云：

SSL/TLS模式务必设置为Full（完全）
否则可能会出现无限重定向的问题

适用场景说明

✅ 个人使用/朋友聊天/小型社区
❌ 不适合大型公共matrix服务器
❌ 不适合大量桥接或高并发场景