家庭网络环境软路由搭建Matrix

家庭网络环境软路由搭建Matrix

Matrix 3 2025-07-10

简介

Matrix是一个去中心化的安全消息协议，使用HTTP和JSON API，能够完全端到端加密发送和接收消息，支持WebRTC VoIP/video护驾，以及提供更多重要的集成能力。

Matrix内建集成了IRC服务器和其他通讯协议，并且有各种客户端实现。例如，最主要的客户端是 Element ，提供了跨平台(Windows/macOS/Linux/Android/iOS)客户端软件。此外，Matrix还提供了桥接 Freenode 和 Mozilla IRC等服务，也就是可以用Element作为统一客户端来连接上述服务。

Matrix 和 Element 都是开源实现，你可以自己架设企业内部服务器以及分发企业客户端。当然， Element也提供注册服务，可以直接使用连接到互联网庞大的IRC讨论中。

本篇将介绍如何在国内家庭网络环境下通过Matrix搭建一个完整的属于自己的去中心化的IM即时通讯服务，并接入到Matrix联邦网络中。那么我们开始吧！

准备工作

为了完成这项搭建工作，你需要准备：

  • 一台国内可以访问的境外VPS，如果你没有可以想办法先去购买一台，并不是很贵一年100左右。

  • 一个你自己拥有的海外域名，如果有条件可以托管到Cloudflare上去

  • 一台软路由（主路由或者旁路由都可以）并且可以科学上网，或者一台小型家庭NAS并且可以科学上网

  • 部署的设备安装有Docker和Docker-Compose

  • 家庭网络需要有公网IP，如果没有可以选择内网穿透+反向代理在此不做教程，默认你已经拥有了公网IP

如果你成功的拥有你上文所诉的所有，那么恭喜你可以开始我们的部署工作了！

部署Synapse

Matrix的核心就是Synapse，成功部署Synapse就等于成功了一半，那么我们赶紧开始吧！

准备Synapse配置文件

具体的Synapse配置文件内容请参考官方的文档，本篇会给一个配置示例。

  • 新建一个文件，重命名为homeserver.yaml

  • 打开并编辑该文件，配置示例如下所示：

# Configuration file for Synapse.
#
# This is a YAML file: see [1] for a quick introduction. Note in particular
# that *indentation is important*: all the elements of a list or dictionary
# should have the same indentation.
#
# [1] https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html
#
# For more information on how to configure Synapse, including a complete accounting of
# each option, go to docs/usage/configuration/config_documentation.md or
# https://element-hq.github.io/synapse/latest/usage/configuration/config_documentation.html
server_name: "你的域名也可以是子域名"
pid_file: /data/homeserver.pid
listeners:
  - port: 8008 #监听端口
    tls: false #是否https因为是docker创建的所以选false
    type: http
    x_forwarded: true
    resources:
      - names: [client, federation] #要加入联邦网络那么federation必须选上，如果你不希望加入联邦网络那么可以不选
        compress: false
database:
  #我这里使用的是sqlite文件数据库，如果你想使用pg或者其他数据库可以参考官网配置
  name: sqlite3
  args:
    database: DATADIR/homeserver.db
log_config: "/data/SERVERNAME.log.config" #这里的SERVERNAME替换为你的域名
media_store_path: /data/media_store
registration_shared_secret: "你的密钥"
report_stats: true
macaroon_secret_key: "macaroon密钥"
form_secret: "form_secret密钥"
signing_key_path: "/data/SERVERNAME.signing.key" #这里的SERVERNAME替换为你的域名
trusted_key_servers:
  - server_name: "matrix.org"
  - server_name: "neo.angry.im"
  - server_name: "bgme.me"
suppress_key_server_warning: true
enable_registration: true #开启注册
enable_registration_without_verification: true #开启注册无需验证
registration_requires_token: true #开启注册需要注册码
#element call配置
#由于element弃用了原生tun的配置转向Livekit，如果你不需要语音视频通话下面的配置可不写
experimental_features:
  # MSC3266：房间摘要 API。用于跨服务器敲门功能
  msc3266_enabled: true
  # MSC4222：syncv2 state_after 所需。允许客户端
  # 正确追踪房间状态。
  msc4222_enabled: true
  # MSC4140：延迟事件需要正确的呼叫参与信令。如果禁用，很可能你会在矩阵房间里被卡住
  msc4140_enabled: true

# 按照 MSC4140，允许已发送事件的最大延迟时长。
max_event_delay_duration: 24h

rc_message:
  # 这需要至少匹配端到端加密密钥共享的频率，并留有一定余量
  # 注意密钥共享事件是突发性的
  per_second: 0.5
  burst_count: 30

rc_delayed_event_mgmt:
  # 这需要至少匹配心跳频率，并留有一定余量
  # 当前心跳为每 5 秒一次，换算为 0.2 次/秒
  per_second: 1
  burst_count: 20
# vim:ft=yaml

部署并配置Synapse

  • 通过ssh命令进入你的软路由或NAS，输入以下命令

docker run -d --name synapse \
-v 你想要存储synapse文件的位置:/data \
--restart=unless-stopped \
-p 8008:8008
matrixdotorg/synapse:latest

等待进度条完成，那么你的Synapse就部署完成了。

  • 此时你的Syanpse还未正常工作，你需要把之前创建好的homesever.yaml 文件放入你的synapse文件目录中并重启容器，致辞Syanpse创建完成。

  • 接下来，在ssh终端中输入以下命令用于创建管理员账户

    docker exec -it synapse register_new_matrix_user http://ip:8008 -c /data/homeserver.yaml -a -u 用户名 -p 密码

打开浏览器，输入你部署Synapse机器的ip地址，如http://192.168.1.1:8008，如果出现以下界面，那么恭喜你，你的Synapse服务已经部署完成部署livekit

在Synapse中我们已经配置好让Synapse支持Element Call，那么接下来我们开始部署真正让ElementCall可以正常使用的关键服务livekit

准备livekit工作目录

mkdir /livekit

准备Docker-Compose文件

在工作目录中新建一个文件名为docker-compose.yaml在文件中写下面的内容：

version: "1"
services:
  auth-service:
    image: ghcr.io/element-hq/lk-jwt-service:latest
    container_name: element-call-jwt
    hostname: synapse-jwt-auth-server
    ports:
      - "8080:8080"
    environment:
      - LIVEKIT_JWT_PORT=8080
      - LIVEKIT_URL=https://你的主路由（你家庭网络）域名注意这里的域名与synapse的域名不同，synapse的域名是用在VPS上的:8448/livekit/sfu
      - LIVEKIT_KEY=你的key
      - LIVEKIT_SECRET=你的secret
    restart: unless-stopped
  livekit:
    image: livekit/livekit-server:latest
    container_name: synapse-element-call-livekit
    network_mode: host
    command: --config /etc/livekit.yaml
    restart: unless-stopped
    volumes:
      - /livekit/livekit.yaml:/etc/livekit.yaml:ro
      - https证书路径:/cert/

准备livekit配置文件

在工作目录中新建一个文件名为livekit.yaml并在文件中写下面内容：

port: 7880
bind_addresses:
    - "0.0.0.0"
rtc:
    tcp_port: 7881
    port_range_start: 50000
    port_range_end: 60000
    use_external_ip: true
    enable_loopback_candidate: false
turn:
    enabled: true
    domain: 你的主路由（你家庭网络）域名注意这里的域名与synapse的域名不同，synapse的域名是用在VPS上的
    tls_port: 5349
    udp_port: 3478
    external_tls: true
    cert_file : /cert/证书文件.crt
    key_file : /cert/证书文件.key
keys:
    key: secret

部署livekit

使用ssh命令行至/livekit文件夹中输入命令docker-compose up -d等待进度条走完即可。

此时，你已经完成livekit的部署。

反向代理配置

本篇将以Caddy为例书写Caddy File，在后面的文章中我会介绍如何在国内环境下部署Caddy服务并且自动申请自己的SSL证书以及如何做动态DNS。

#synapse和liviekit
你的主路由域名（注意这个域名和synapse的域名不同）:8448 {
	handle_path /livekit/jwt* {
		reverse_proxy http://localhost:8080
	}
	handle_path /livekit/sfu* {
		reverse_proxy http://localhost:7880
	}
	reverse_proxy http://localhost:8008
}

VPS配置

首先你需要创建一个工作目录，此时我选择使用的工作目录上/data/public/

VPS的配置很简单还是Caddy的配置，本篇还是以Caddy file配置为例，因为VPS的网络没有像国内一样的限制所以配置很简单，如下：

你的VPS域名或子域名与Synapse配置的域名相同 {
	handle_path /.well-known/matrix/client {
		header {
			Content-Type application/json
			Access-Control-Allow-Origin *
			Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS
		}
		root * /data/public/client.json
		file_server
	}
	handle_path /.well-known/matrix/server {
		header {
			Content-Type application/json
			Access-Control-Allow-Origin *
			Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS
		}
		root * /data/public/server.json
		file_server
	}
	
}
你的VPS域名或子域名与Synapse配置的域名相同:8448 {
	reverse_proxy https://你的主路由（你家庭网络）域名注意这里的域名与synapse的域名不同，synapse的域名是用在VPS上的:8448 {
		header_up Host {upstream_hostport}
	}
}

.well-known文件写法

众所周知，Matrix引入了.well-known，使得matrix服务可以使用.well-known文件告诉客户端真正的synapse服务在哪里以及livekit服务在哪里

首先是client.json

{
    "m.homeserver": {
        "base_url": "https://你的VPS域名或子域名与Synapse配置的域名相同:8448"
    },
    "org.matrix.msc4143.rtc_foci": [
        {
            "livekit_service_url": "https://你的主路由（你家庭网络）域名注意这里的域名与synapse的域名不同，synapse的域名是用在VPS上的:8448/livekit/jwt",
            "type": "livekit"
        },
        {
            "livekit_service_url": "https://livekit-jwt.call.matrix.org",
            "type": "livekit"
        },
        {
            "props_for_nextgen_foci": "val",
            "type": "nextgen_new_foci_type"
        }
    ]
}

然后是server.json

{"m.server": "你的VPS域名或子域名与Synapse配置的域名相同:8448"}

至此，所有的配置已经完成，你可以通过你 下载的Element手机APP或者Element.io网站进行登陆你的Matrix服务了。

结语

补充几点额外的。

Synapse-admin管理

这个工具可以更有效的管理你的Synapse服务，有兴趣的可以Google安装方式，它的安装方式非常简单，在这里就不做赘述了。

Cloudflare

当然，如果你没有VPS也可以使用CloudFlare的Tun服务和Workers服务达到相同的Element Call效果，但是本篇文章没有使用它的原因是，如果你需要使用Cloudflare，你就必须单独给Matrix在你的主路由上新建一个子域名，因为要使用CLoudflare的Workers服务是需要打开Cloudfare代理的，因为我自己主路由的域名只想分配一个并且我主路由下还有其他服务，开启Cloudflare的代理会影响我其他服务在国内的访问速度，故而没有选择使用，如果你想使用，请参考如这位大神的博客。

自建Element网页客户端

自建一个自己私有的Element Matrix网页客户端非常简单，也是Docker部署即可，示例的Docker部署命令如下：

docker run -d --name matrix-element \
-v /matrix/element/config.json:/app/config.json \
-p 3000:80 \
vectorim/element-web

其中网页客户端的配置文件示例可以去他官方仓库中查找。

最后祝大家都能成功拥有自己的Matrx服务！

matrix vps web3 element-call