开源框架 Matrix-Dendrite 搭建聊天服务器的详细过程

时间：2025-12-20 00:30:02|栏目：其它服务器|点击：次

开源框架 Matrix-Dendrite 搭建聊天服务器

关于Matrix

Matrix 是一个开源、可交互、去中心化的实时通信服务框架。使用 Matrix 可以搭建安全的通信服务器，配合支持 Matrix 的客户端可以实现个人、团队间的实时聊天交互。

Matrix 相较于普通的通信服务（如微信、QQ等软件使用的服务），最特别的地方在于其去中心化的架构。每个运行着 Matrix 的服务器都是一个节点（homeserver），用户可以选择在任意节点进行注册、连接，和处于同一节点的其他用户自由交流，用户的隐私数据以加密的形式存储于当前的节点上。同时，节点与节点间也可以通过联锁（Federation）机制进行通信，使在不同节点上的用户之间可以互相交流。得益于去中心化的服务架构，用户完全可以自行搭建节点服务器，使自己的聊天数据安全和隐私得到保护。

开源框架 Matrix-Dendrite 搭建聊天服务器的详细过程

支持 Matrix 协议的客户端有很多，比较成熟的有 Element.io（Riot.IM），语音、视频通话、附件等功能都有，并且支持 Windows，Linux，Android 等多个平台。

开始搭建

Matrix 的服务端有两种：Synapse 和 Dendrite。

Synapse 是用 Python 编写的第一代 Matrix 服务端，是十分稳定的正式版，使用者非常多，适合用于生产环境中。Dendrite 是 Matrix 的开发团队使用 Go 语言编写的第二代 Matrix 服务端，它旨在为 Synapse 提供一个高效、可靠、可扩展的替代方案。目前 Dendrite 仍然在 Beta 开发中，像推送和提醒等一些功能还没有实现。

如果是生产环境使用，还是搭建 Synapse，更稳定并且相关的教程也十分丰富。

本文使用 Dendrite 来搭建，在 Unraid 系统通过 Docker 容器来实现，主要是想尝鲜哒！在其他系统下也可以参照本文进行部署。

需要准备的'东西'

一个域名和该域名的有效 TLS 证书
一个反向代理服务，比如 Nginx
可选：高性能数据库引擎，推荐 PostgreSQL。对性能无要求可以使用内置的 SQLite。

PostgreSQL

Matrix 并不强制要求使用哪种数据库，少量用户的情况下完全可以使用其内置的 SQLite 数据库。如果系统内已经有其他数据库引擎运行，当然也可以直接使用。本文只是按照官方推荐使用 PostgreSQL 作为 Matrix 数据库的管理引擎。

01.创建 PostgreSQL 配置文件目录

在安装 PostgreSQL Docker 前，先创建配置文件目录 /mnt/user/appdata/PostgreSQL/。

访问 https://github.com/matrix-org/dendrite/tree/main/build/docker/postgres 下载 create_db.sh 文件，使用文本编辑器打开它，修改代码中用户名字段为自己的数据库用户名。

# 这段代码的作用是初始化数据库，所以语句中的 Username 必须要替换成自己的数据库管理员用户名。
for db in userapi_accounts userapi_devices mediaapi syncapi roomserver keyserver federationapi appservice mscs; do
    createdb -U [Username] -O [Username] dendrite_$db # 注意修改[Username]
done

最后将 create_db.sh 文件上传到配置文件目录里：/mnt/user/appdata/PostgreSQL/create_db.sh

02.创建 databases 文件夹存储数据库

创建目录用来存放 PostgreSQL 的数据库：

/mnt/user/appdata/PostgreSQL/databases

03.配置 Docker 命令创建容器

本文使用 Unraid 系统进行搭建，进入 DOCKER -> ADD CONTAINER 即可配置容器参数。也可以使用 Unraid 插件中心进行安装。其他系统使用 docker create 命令可能还更简单，所以本文也将创建容器的命令行字符串附于其后。

Unraid 创建容器需要添加/修改的参数如下：

[Type] Variable            [Name] 管理员用户名
[Key]  POSTGRES_USER       [Value] FrozenSky

[Type] Variable            [Name] 管理员密码
[Key]  POSTGRES_PASSWORD   [Value] xxxxxxx
[Type] Path                [Name] 数据库存储路径
[Container Path] /var/lib/postgresql/data
[Host Path]      /mnt/user/appdata/PostgreSQL/databases
[Access Mode]    Read/Write
[Type] Path                [Name] 数据库初始化脚本
[Container Path] /docker-entrypoint-initdb.d/20-create_db.sh
[Host Path]      /mnt/user/appdata/PostgreSQL/create_db.sh
[Type] Port                [Name] 端口映射
[Container Port] 5432
[Host Port]      5432

另外，官方还推荐开启容器健康状态检查功能，在添加容器界面点击高级视图(ADVANCED VIEW)，在 Post Arguments 中添加下面的语句：

--health-cmd='["CMD-SHELL", "pg_isready -U dendrite"]' --health-interval=5s --health-timeout=5s --health-retries=5

配置完成后，点击 APPLY 即可创建容器。

国内网络访问 DockerHub 可能出现无法连接的问题，可以通过阿里云加速来解决。网络上教程很多，但多是需要更改 Unraid 系统文件，其实完全没必要。Docker 命令是支持自定义拉取服务器的。只需要在配置界面中仓库(Repository)这一栏添加加速服务器即可：

比如：dazeaikzq.mirror.aliyuncs.com/library/postgres:14

关于 HEALTHCHECK

官方 docker-compose 文件中，有个 HEALTHCHECK 字段，如果使用 docker-cli 启动容器的话可以参照下面的字段进行替换。这个字段是配置容器健康状态检查的，貌似不加也可以。

 --health-cmd            Command to run to check health
  --health-interval       Time between running the check
  --health-retries        Consecutive failures needed to report unhealthy
  --health-timeout        Maximum time to allow one check to run
  --health-start-period   Start period for the container to initialize before starting health-retries countdown
  --no-healthcheck        Disable any container-specified HEALTHCHECK

附：命令行方式创建Docker

docker create
    --name='PostgreSQL' 
    --net='bridge' 
    -e TZ="Asia/Shanghai" 
    -e HOST_OS="Unraid" 
    -e 'POSTGRES_PASSWORD'='xxxxxxx' 
    -e 'POSTGRES_USER'='FrozenSky' 
    -e 'POSTGRES_DB'='' 
    -p '5432:5432/tcp' 
    -v '/mnt/user/appdata/PostgreSQL/databases':'/var/lib/postgresql/data':'rw' 
    -v '/mnt/user/appdata/PostgreSQL/create_db.sh':'/docker-entrypoint-initdb.d/20-create_db.sh':'rw' 
    --restart=always 'postgres:14'
    --health-cmd='["CMD-SHELL", "pg_isready -U dendrite"]' 
    --health-interval=5s
    --health-timeout=5s
    --health-retries=5

04.连接数据库以确认初始化正常

可以使用 PGAdmin、dbeaver、phpMyAdmin 等管理软件连接远程数据库，查看是否已经创建了好多个 dendrite 开头的数据。

PostgreSQL 的默认连接地址是： [IP]:5432

Matrix-Dendrite

Matrix-Dendrite 服务端分为2个版本，monolith 和 polylith，本文选择了 monolith，因为它的各个组件都是整合在一起的，配置简单。

Dendrite 的 Github 仓库：https://github.com/matrix-org/dendrite

01.创建 Dendrite 文件夹存储配置文件

创建目录：/mnt/user/appdata/Dendrite/config

该目录下必须包含如下文件：

dendrite.yaml 配置文件
matrix_key.pem 服务端密钥（通过下文的命令生成）
server.crt 证书文件（打算作为Matrix服务器的域名的证书）
server.key 证书私钥

(1) 生成 matrix_key.pem 服务器密钥文件

把你的网站域名证书和私钥上传到配置目录里：

/mnt/user/appdata/Dendrite/config/server.key
/mnt/user/appdata/Dendrite/config/server.crt

打开 Unraid 终端，进入配置文件目录，执行下面的 Docker 命令：

# 注意：命令参数中 -tls-cert 和 -tls-key 的文件名要和上面保持一致。
docker run --rm --entrypoint="" \

  -v $(pwd):/mnt \

  matrixdotorg/dendrite-monolith:latest \

  /usr/bin/generate-keys \

  -private-key /mnt/matrix_key.pem \

  -tls-cert /mnt/server.crt \

  -tls-key /mnt/server.key

该命令将在当前目录中生成服务端密钥 matrix_key.pem

# 命令输出
Created TLS cert file:    /mnt/server.crt
Created TLS key file:     /mnt/server.key
Created private key file: /mnt/matrix_key.pem

(2) 修改 Dendrite 配置文件

从 Github 仓库下载配置文件 dendrite.yaml 示例进行修改。下载地址：配置文件示例

以下配置文件将假设我的域名是 frozensky.org 并且打算在 1443 端口进行反向代理，将 Matrix 的 API 请求进行转发；我的数据库用户名是 FrozenSky 密码是 xxxxxxx ，数据库访问地址是：192.168.7.9:5432

主要修改的地方如下：

# 域名（运营商封443的话，就要填写你的自定义反向代理端口）
server_name: frozensky.org:1443
# 服务器私钥路径（上文生成的私钥）
private_key: /etc/dendrite/matrix_key.pem
# Well-known服务的域名（同域名）
well_known_server_name: "frozensky.org:1443"
# 每个组件的数据库连接字符串 connection_string 
# 配置文件中所有组件的数据库连接URL都要改（使用内置SQLite则不需要改）
connection_string: postgresql://FrozenSky:xxxxxxxx@192.168.7.9:5432/............

# 注释掉 JetStream 默认的服务器地址
# Configuration for NATS JetStream
  jetstream:
    addresses:
    # - jetstream:4222  #注释该行
    storage_path: /etc/JetStream_NATS #设置一个容器内目录用来存储数据

02.创建数据存储目录

创建一些目录用来存储 Dendrite 的数据：

JetStream：/mnt/user/appdata/Dendrite/JetStream

Media: /mnt/user/appdata/Dendrite/media

03.创建 Dendrite 容器

使用官方镜像：matrixdotorg/dendrite-monolith

以下是容器配置：

[Type] Port 1              [Name] 端口映射
[Container Port] 8008
[Host Port]      8008

[Type] Port 2              [Name] 端口映射
[Container Port] 8448
[Host Port]      8448
[Type] Path                [Name] 配置文件路径
[Container Path] /etc/dendrite
[Host Path]      /mnt/user/appdata/Dendrite/config
[Access Mode]    Read/Write
[Type] Path                [Name] 媒体文件路径
[Container Path] /var/dendrite/media
[Host Path]      /mnt/user/appdata/Dendrite/media
[Type] Path                [Name] JetStream路径
[Container Path] /etc/JetStream_NATS
[Host Path]      /mnt/user/appdata/Dendrite/JetStream

在添加容器界面点击高级视图(ADVANCED VIEW)，在 Post Arguments 中添加下面的语句：

--tls-cert=server.crt --tls-key=server.key

点击 APPLY 创建容器。

Nginx反向代理

安装完成 Dendrite 后，其实 Matrix 服务框架的后端就已经运行起来了，但想要让客户端软件与我们的服务端通信还需要通过 Nginx 配置，将客户端的请求转发到对应的服务器端口上来。

修改 Nginx 配置文件 /etc/nginx/sites-available （Nginx版本不同配置文件路径可能不同）

以本文环境为例，因运营商封杀443端口，我在路由上将 1443 端口转发到内部的 443 端口。配置文件要修改的部分本文都作了注释，就不再为 Nginx 的配置做过多说明了，遇到问题可以自行搜索，教程还是很详细的。

server {
	listen 80;
	listen 443 ssl;
	server_name frozensky.org; #域名
	charset utf-8;

	#ssl on;
	ssl_certificate     /etc/ssl/frozensky.org/fullchain.crt; #证书
	ssl_certificate_key /etc/ssl/frozensky.org/frozensky.org.key; #密钥
	ssl_session_timeout 5m;
	ssl_protocols       SSLv2 SSLv3 TLSv1 TLSv1.2;
	ssl_ciphers         HIGH:!aNULL:!MD5;
	ssl_prefer_server_ciphers   on;
    # 代理请求的一些设置
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout         600;
	
    # Dendrite配置文件中的server_name，注意端口是外部端口！！！
    location /.well-known/matrix/server {
        return 200 '{ "m.server": "frozensky.org:1443" }'; 
    }
	# Dendrite配置文件中的server_name，注意端口是外部端口！！！
    location /.well-known/matrix/client {
        return 200 '{ "m.homeserver": { "base_url": "https://frozensky.org:1443" } }';
    # Dendrite后端的地址，IP是搭建Dendrite的服务器IP，端口是8008
    location /_matrix {
        proxy_pass http://192.168.7.10:8008;
}

配置完成后保存退出。

重载配置文件和证书，重启Nginx服务

sudo service nginx force-reload
sudo service nginx restart

测试连接

至此，Matrix 服务就全部配置完成了，可以访问 Federation Tester 输入自己的 Matrix 网址 https://frozensky.org:1443 进行测试，全部通过的话就表示服务运行正常且 Federation 联锁也已启用，可以和其他服务器的小伙伴进行通信了。本文推荐安装 Element.io 客户端来使用，虽然 Matrix-Dendrite 还处于开发测试阶段，但经过这几天的使用发现主要功能并没有什么问题。

开源框架 Matrix-Dendrite 搭建聊天服务器的详细过程