使用 Ansible 自动安装 Matrix 即时通信网络 Synapse + Element

Matrix 是一种协议,有不同的实现。工作方式类似电子邮件,拥有「去中心化」和「端到端加密」的特点。本文重在其部署流程,介绍和具体使用方法请到:自建 即时通信 – 全面监管下,一个自由无限制交流的赛博小屋 – 技焉洲 (vfly2.com)

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

走通预计时间:60 分钟

I might have made some mistakes, please let me know if I’ve gotten anything wrong!


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

实际上,需要什么样的服务器规格,很大程度上取决于你的实例,会连接多少大房间(上千人),而不是用户数量。
如果加入了具有丰富历史记录并包含数百台其他实例的房间,机器的 CPU 和内存都会非常繁重。

比如,可能可以使用 1 CPU + 1GB 内存服务器来托管数百个本地用户,但是一旦其中一个用户加入像 #matrix:matrix.org 这样的联合房间,服务器就必须有更高的配置,至少 2GB 内存等。

安装文档: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/README.md

本文流程下,实际安装项目:

  1. 服务端:Synapse
  2. 客户端:Element 的 Web 端

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

前置准备

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

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

为域名配置好 DNS 解析

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

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

基础:

  1. vfly2.com A记录 解析到 服务器 ip (这个不做也行,只是需要后面手动设置反向代理)
  2. matrix.vfly2.com A记录 解析到 服务器 ip
  3. element.vfly2.com CNAME记录 解析到 matrix.vfly2.com (A记录也可以,但是 CNAME 方便以后迁移服务器)

实际上,

  • matrix.vfly2.com 是 matrix 的服务端,也就是 synapse 的域名;
  • element.vfly2.com 是 Web 客户端 element 的域名。

可以看出,一个域名对应一个组件。如果要安装其他服务,比如 Grafana ,用以查看服务器资源使用情况,那么添加 stats.vfly2.com CNAME记录 解析到 matrix.vfly2.com 。

被控端

  1. 推荐用 Debian 最新系统,且最好是重装的全新系统
  2. 能用 root 登录,或有 sudo 权限(本文必须是能用 root 登录)
  3. 安装了 Python3 和 pip, apt install python3 python3-pip -y
  4. 确保防火墙放开下面的端口或确保端口没被其他程序占用
    1. 80/tcp: HTTP webserver
    2. 443/tcp: HTTPS webserver
    3. 3478: TURN over TCP/UDP (used by Coturn)
    4. 5349: TURN over TCP/UDP (used by Coturn)
    5. 8448/tcp: Matrix Federation API HTTPS webserver.
    6. the range 49152-49172/udp: TURN over UDP
# 方便读者使用
ufw allow 80/tcp comment http
ufw allow 443/tcp comment https
ufw allow 3478 comment Coturn
ufw allow 5349 comment Coturn
ufw allow 8448/tcp comment "Federation API"
ufw allow 49152:49172/udp comment "TURN over UDP"
ufw status

控制端

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

控制端要求:

  1. 安装有 git ,一般都有
  2. 安装有 just (它是 make 类型的工具,更好用)
  3. 安装 ansible ,和 PassLib

安装 just:

sudo -i   # 切换到 root
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/local/bin
just --help   # 检验是否安装成功

安装 ansible:

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

有些系统不支持 pip 这么安装,可以创建虚拟环境,再执行安装

python3 -m venv .env
source .env/bin/activate
python3 -m pip install ansible

安装 PassLib:

python3 -m pip install --user passlib
# 如果前面用的虚拟环境,则去掉 --user 执行
# python3 -m pip install passlib

控制端下载 playbook

创建一个目录(这里用 ~/Projects)放 Playbook:

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

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

自定义配置文件

所有操作都是在这个目录下进行的

cd ~/Projects/matrix-docker-ansible-deploy

  1. 创建目录(用于放置自定义配置)
mkdir inventory/host_vars/matrix.vfly2.com
  1. 复制样例文件和主机文件
cp examples/vars.yml inventory/host_vars/matrix.vfly2.com/vars.yml
cp examples/hosts inventory/hosts   # 存有被控端的连接信息
  1. 编辑主机文件
vim inventory/hosts

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

[matrix_servers]
matrix.vfly2.com ansible_host=<ip> ansible_ssh_user=root ansible_ssh_pass=<用户密码> ansible_ssh_port=<ssh端口>
  1. 自定义配置文件(参考下面的样例)
vim inventory/host_vars/matrix.vfly2.com/vars.yml

配置文件样例

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

需要修改:

  1. matrix_domain ,必须填裸域名,本文例子下,就是 vfly2.com 而不能是 matrix.vfly2.com
  2. matrix_homeserver_generic_secret_key
  3. devture_traefik_config_certificatesResolvers_acme_email
  4. devture_postgres_connection_password

有人把这种 vfly2.com 叫作二级域名、也有叫作一级域名的,还有本文的裸域名,反正不知道有哪个权威定义了这些域名到底该用什么称呼。
至少 .com 这种叫顶级域名是公认的

---
# 裸域名,用于用户 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

正式安装

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

为了能通过密码登陆,需要安装 sshpass:

sudo apt install sshpass

还要先手动登陆一次

ssh -p 22 root@matrix.vfly2.com

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

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

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

在全新机子上安装

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

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

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


可能的错误

其他问题可以问 ChatGPT 试试

如果出现错误:

E:Conflicting values set for option Signed-By regarding source https://download.docker.com/linux/debian/ bookworm: /etc/apt/keyrings/docker.gpg != /etc/apt/trusted.gpg.d/docker.asc

其实是因为在被控端预先安装了 Docker,比如 AhFei 通过 Docker 官方的脚本安装,会添加一个软件源在 /etc/apt/sources.list.d/docker.list ,这个 playbook 会再添加一个软件源,导致冲突,这个文件会变成这样:

$ cat /etc/apt/sources.list.d/docker.list

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable
deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/docker.asc] https://download.docker.com/linux/debian bookworm stable   # 第二个是 playbook 添加的

删除第一个,由官方脚本添加的软件源,即可解决冲突,先备份一下:

cp /etc/apt/sources.list.d/docker.list /etc/apt/sources.list.d/docker.list.bak

再删除

vim /etc/apt/sources.list.d/docker.list

在被控端,运行命令 apt update ,如果没出错,就可以了

或者,不通过 playbook 安装:vars.yml 文件中添加它:

matrix_playbook_docker_installation_enabled: false

互相发现

配置以实现联邦之间相互发现,如果将裸域名 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 ,里面的内容是:

{
    "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 的内容,是否正常。

跟上面的一样

检查服务是否工作正常

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

也可以用 Federation Tester 检测。

创建用户

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

手动添加

通过 just 调用 ansible 添加用户(按照本文的话,推荐使用 just,形式简单)

just register-user <your-username> <your-password> <admin access: yes or no>

# 例子: just register-user john secret-password yes

直接通过 ansible 添加用户

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=<your-username> password=<your-password> admin=<yes|no>' --tags=register-user

通过被控机的命令行添加用户(速度快,通过 ansible 会有很多额外工作)

/matrix/synapse/bin/register-user <your-username> <your-password> <admin access: 0 or 1>

然后就可以通过客户端 比如 element 登陆了

管理后台

通过管理后台添加是最简单的,不过需要先手动添加一个管理员用户才能登录后台。

如果你按照上面的配置样例安装,到 https://<domain>/synapse-admin/ 即可进入后台,里面可以直接创建用户。

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

将来更新

  1. 更新 playbook
cd ~/Projects/matrix-docker-ansible-deploy && git pull
  1. 查看 the changelog 看是否有向后不兼容的改变
  2. 通过运行 just roles 下载 playbook 使用的上游 Ansible 角色。
  3. 运行下面命令执行更新
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start

如果增删了组件(或者项目方改变了默认安装项),用 setup-all 而不是 install-all.

ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start

既然都自建了 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 交流依文章步骤遇到的问题。

暂无评论

发送评论 编辑评论


				
|´・ω・)ノ
ヾ(≧∇≦*)ゝ
(☆ω☆)
(╯‵□′)╯︵┴─┴
 ̄﹃ ̄
(/ω\)
∠( ᐛ 」∠)_
(๑•̀ㅁ•́ฅ)
→_→
୧(๑•̀⌄•́๑)૭
٩(ˊᗜˋ*)و
(ノ°ο°)ノ
(´இ皿இ`)
⌇●﹏●⌇
(ฅ´ω`ฅ)
(╯°A°)╯︵○○○
φ( ̄∇ ̄o)
ヾ(´・ ・`。)ノ"
( ง ᵒ̌皿ᵒ̌)ง⁼³₌₃
(ó﹏ò。)
Σ(っ °Д °;)っ
( ,,´・ω・)ノ"(´っω・`。)
╮(╯▽╰)╭
o(*////▽////*)q
>﹏<
( ๑´•ω•) "(ㆆᴗㆆ)
😂
😀
😅
😊
🙂
🙃
😌
😍
😘
😜
😝
😏
😒
🙄
😳
😡
😔
😫
😱
😭
💩
👻
🙌
🖕
👍
👫
👬
👭
🌚
🌝
🙈
💊
😶
🙏
🍦
🍉
😣
Source: github.com/k4yt3x/flowerhd
颜文字
Emoji
小恐龙
花!
上一篇
下一篇