使用 Ansible 自动安装 Matrix 即时通信网络，自由无限制的交流

自建一个赛博小屋供朋友间自由无限制的交流，而不必担心任何监视审查。

Matrix 是一种协议，有不同的实现。工作方式类似电子邮件，拥有「去中心化」和「端到端加密」的特点。

服务端的实现（只要遵循 Matrix 协议，无论什么实现，都能互相通信）：

老牌的 Synapse：Synapse: Matrix homeserver written in Python/Twisted. (github.com)

新锐的 Conduit： Conduit - Your own chat server

客户端的实现

推荐 Element，全平台支持

国区 iOS 则没有太好的客户端，可以暂时在浏览器用 Hydrogen。

除此之外，通过网桥组件，在 Matrix 网络就能与其他平台交流，比如 Telegram、E-mail。

最后，除了基本的发送文字，还可以语音通话和视频聊天，可以安装 Jitsi 视频会议平台， Etherpad 开源协作文本编辑器等。

本文重在其部署流程，介绍和具体使用方法请到：自建 即时通信 - 全面监管下，一个自由无限制交流的赛博小屋 - 技焉洲 (vfly2.com)

控制端适用系统：主流 Linux 发行版，本文使用 Debian 系统，非 Debian 系的在 Ansible 这块稍作调整同样可以。
被控端适用系统：主流 Linux 发行版

走通预计时间：60 分钟

这个 matrix-docker-ansible-deploy 项目，使用 Ansible 在被控端用 Docker 容器设置 Matrix 服务器，因此不必手动执行这些任务，操作简单，不费心；不过内存占用稍高于手动用 Docker 部署，另外 443 端口会被占用，想要复用对技术水平有一定要求。

被控端的内存不建议低于 2g，通过查看文档缩减服务 1g 勉强。在前面配置好后，第一次安装，一般要 20 分钟。

实际上，需要什么样的服务器规格，很大程度上取决于你的实例，会连接多少大房间（上千人），而不是用户数量。

本文流程下，实际安装项目：

服务端：Synapse

客户端：Element 的 Web 端

保持简单，一旦你能够走通这个流程，再增加其他组件不过是看看文档，添加几行配置的事情

前置准备

为了简单起见，使用 root 控制被控端，且用密码连接 SSH，因此，确保被控端的 SSH 能用 root 登录。

下面，如果出现「服务器」，指的是「被控端」，Ansible 安装在「控制端」上，这个控制端既可以在本地电脑上，也可以是在一台服务器上。

为域名配置好 DNS 解析

以域名 vfly2.com 为例，实操时，请自行修改实际域名。

如果是 Cloudflare DNS，确保用的是 DNS only

基础：

vfly2.com A 记录 解析到 服务器 ip （这个不做也行，只是需要后面手动设置反向代理）

matrix.vfly2.com A 记录 解析到 服务器 ip

element.vfly2.com CNAME 记录 解析到 matrix.vfly2.com （A 记录也可以，但是 CNAME 方便以后迁移服务器）

被控端

推荐用 Debian 最新系统，且最好是重装的全新系统

能用 root 登录，或有 sudo 权限（本文必须是能用 root 登录）

安装了 Python3 和 pip， apt install python3 python3-pip -y 。

确保防火墙放开下面的端口或确保端口没被其他程序占用

80/tcp: HTTP webserver

443/tcp: HTTPS webserver

3478: TURN over TCP/UDP (used by Coturn)

5349: TURN over TCP/UDP (used by Coturn)

8448/tcp: Matrix Federation API HTTPS webserver.

the range 49152-49172/udp: TURN over UDP

控制端

可以在另一台 Linux 服务器上，安装 Ansible 作为控制端，用普通用户操作即可，本文就是这种模式。

控制端要求：

安装有 git ，一般都有

安装有 just （它是 make 类型的工具，更好用）

安装 ansible ，和 PassLib 库

安装 just：

Copy
sudo -i # 切换到 root

Copy
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/local/bin

Copy
just --help # 检验是否安装成功

安装 ansible：

Copy
python3 -m pip install --user ansible
ansible --version
# 此时 ansible 安装在 ~/.local/bin/ansible

安装 PassLib：

Copy
python3 -m pip install --user passlib

控制端下载 playbook

创建一个目录（这里用 ~/Projects）放 Playbook：

Copy
mkdir ~/Projects && cd ~/Projects && \
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git

会创建名为 matrix-docker-ansible-deploy 的目录，后面所有操作都是在这个目录下进行的

自定义配置文件

创建目录（用于放置自定义配置）

Copy
mkdir inventory/host_vars/matrix.vfly2.com

复制样例文件和主机文件

Copy
cp examples/vars.yml inventory/host_vars/matrix.vfly2.com/vars.yml
cp examples/hosts inventory/hosts # 存有被控端的连接信息

编辑主机文件

Copy
vim inventory/hosts

将被控端信息放入其中，使 ansible 可以登陆控制，用密码登录的样例如下

Copy
[matrix_servers]
matrix.vfly2.com ansible_host=<ip> ansible_ssh_user=root ansible_ssh_pass=<用户密码> ansible_ssh_port=<ssh端口>

自定义配置文件（参考下面的样例）

Copy
vim inventory/host_vars/matrix.vfly2.com/vars.yml

配置文件样例

推荐先使用下面的配置文件走一遍，如果走通了，再慢慢添加其他组件等。

需要修改：

matrix_domain

matrix_homeserver_generic_secret_key

devture_traefik_config_certificatesResolvers_acme_email

devture_postgres_connection_password

Copy
---
# 裸域名，用于用户 ID 的
# 如果填错了，只能先卸载，再重新安装
matrix_domain: vfly2.com

# 要安装的 matrix 服务端，这里用的是 synapse 实现
# 更多选项可以查看 roles/custom/matrix-base/defaults/main.yml
# docs/configuring-playbook-IMPLEMENTATION_NAME.md 下查看具体说明
matrix_homeserver_implementation: synapse

# 对 synapse 的一些设置
# 默认设置 roles/custom/matrix-synapse/defaults/main.yml
# 允许注册
matrix_synapse_enable_registration: true
# 注册需要邀请码
matrix_synapse_registration_requires_token: true

# 一个基础密钥，用于生成多个其他密码
# 可以是任意字符串，推荐用 openssl rand -base64 48 生成 64 位字符串
matrix_homeserver_generic_secret_key: 'Wddx05J0Tty9R1M7fzw2nEdR1U9wtGh61+wm3T4SUQi2IbtF2roi6VfqSrMzfKJc'

# 默认用的是 Traefik 实现反代，他可以自动申请 SSL 证书，并自动化反代组件
# 其他替代，查看 `docs/configuring-playbook-own-webserver.md`.
matrix_playbook_reverse_proxy_type: playbook-managed-traefik

# 申请 Let's Encrypt 颁发证书用的邮箱
# 更多说明： docs/configuring-playbook-ssl-certificates.md
devture_traefik_config_certificatesResolvers_acme_email: 'blog@vfly2.com'

# Postgres 的超级用户是 matrix ，这里设置其密码
# 这个 playbook 对于每个组件都会创建一个用户和数据库，通过 matrix 用户执行
devture_postgres_connection_password: '9HwDqeQ/ZzRlRyaH7KsjW0Q7mEwO7t52YrIsiRUzFieDmvfJ6U4aiMMcrU/5Hdsq'

# 安装 synapse_admin 组件，就是一个后台，可以查看用户，添加注册用的邀请码
# 它不需要单独设置域名，网址是 https://matrix.vfly2.com/synapse-admin/
matrix_synapse_admin_enabled: true

正式安装

Copy
# 所有操作都是在这个目录下进行的
cd ~/Projects/matrix-docker-ansible-deploy

为了能通过密码登陆，需要安装 sshpass：

Copy
sudo apt install sshpass

还要先手动登陆一次

Copy
ssh -p 22 root@matrix.vfly2.com

在安装之前，包括以后更新 playbook 或配置文件之后，都需要更新 Ansible roles，它指挥怎么操作被控端

Copy
just roles # 没错，运行一下这个命令就可以了

如果是要迁移旧实例，到这步就可以走迁移那部分的流程了。

在全新机子上安装

完全安装并启动所有 Matrix 服务

Copy
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start

这行命令执行完成后，其实就可以打开 Web 端了，注册用户之后就可以使用了。

互相发现

配置以实现联邦之间相互发现，如果将裸域名 vfly2.com 直接解析到服务端，那么可忽略此节，因为 playbook 自行配置好了。

(important) Federation Server discovery

辅助其他实例 发现自己，没有正确配置，就无法接入联邦，无法与联邦其他成员建立连接。但单机使用是不受影响的。

也就是网页 https://<matrix_domain>/.well-known/matrix/server 的内容，是否正常。

这个 playbook 将实例安装在另一个域（比如本文是 matrix.vfly2.com ）上，而不是在基本域（vfly2.com ）上，但 Matrix 协议本身要求去基本域发现。

本文使用这个 playbook 安装的在这里： https://matrix.vfly2.com/.well-known/matrix/server ，里面的内容是：

Copy
{
"m.server": "matrix.vfly2.com:8448"
}

只需要确保，访问 https://vfly2.com/.well-known/matrix/server 的内容和上面的一样就行，可以利用反代等，甚至手动复制内容到新文件里，让 Web 服务器公开即可。

(not that important) Client Server discovery

辅助自己的客户端发现它连接的服务端，这样能更方便查询用户

也就是网页 https://<matrix_domain>/.well-known/matrix/client 的内容，是否正常。

跟上面的一样

检查服务是否工作正常

Copy
ansible-playbook -i inventory/hosts setup.yml --tags=self-check

也可以用 Federation Tester 检测。

创建用户

通过管理后台添加是最简单的，如果你按照上面的配置样例安装，到 https://<domain>/synapse-admin/ 即可进入后台，里面可以直接创建用户。

后台也可以生成邀请码，其他人用邀请码就能注册了。

更多方法查看官方说明： https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/registering-users.md

既然都自建了 Matrix，那怎么能不会 Matrix 维护 呢？对本文使用 Ansible 安装的 Matrix 进行备份和迁移： Matrix 维护 ：备份和迁移 - 技焉洲 (vfly2.com)

原文链接： https://technique.vfly2.com/2024/01/automated-installation-of-matrix-using-ansible/

版权声明：本博客所有文章除特別声明外，均为 AhFei 原创，采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 技焉洲 (technique.vfly2.com) 。

保持更新 ٩(・̤̀ᵕ・̤́๑)ᵒᵏᵎᵎᵎᵎ 清晰恒益的实用技能，欢迎使用 RSS 订阅，或在支持 ActivityPub 的平台关注 @vfly2tech@technique.vfly2.com 接收新文章的推送，如果能留言互动就更好了。

可在 Telegram 群组 https://t.me/vfly2 交流依文章步骤遇到的问题。