用香港服务器搭建Matrix聊天服务,如何配置域名与HTTPS入口?
目标状态是:香港服务器对外只开放必要的 Web 入口,Matrix Synapse 仅监听本机回环地址,由 Nginx 负责域名接入、HTTPS 终止和反向代理;PostgreSQL 保存业务数据,systemd 负责进程守护,日志和备份具备明确的查看、恢复路径。完成后,客户端可以通过 https://chat.example.com 连接,Matrix 联邦请求也通过 443 端口进入,不需要把 Synapse 的 8008 端口直接暴露到公网。
下面以 Ubuntu 22.04/24.04 或 Debian 12、单台香港服务器、Nginx、PostgreSQL 和 Synapse 为例。示例域名使用 chat.example.com,请替换为实际域名。若服务器上已经运行网站或数据库,不要直接覆盖现有配置,应先确认端口、站点文件和备份范围。
一、部署前的目标和边界
1. 推荐的访问结构
本例采用以下结构:

Matrix 客户端
│
│ HTTPS 443
▼
chat.example.com
│
│ Nginx 反向代理
▼
127.0.0.1:8008
│
▼
Synapse ───── PostgreSQL 127.0.0.1:5432
各组件的职责如下:
| 组件 | 作用 | 公网是否直接开放 |
|---|---|---|
| Nginx | 接收 HTTPS、转发 Matrix 请求、限制上传大小 | 是,80/443 |
| Synapse | 处理客户端 API 和联邦 API | 否,仅监听 127.0.0.1:8008 |
| PostgreSQL | 保存 Matrix 账号、房间、消息索引等数据 | 否,仅监听本机 |
| 媒体目录 | 保存图片、文件和缩略图 | 通过 Synapse 间接访问 |
| systemd | 启停、开机启动和异常重启 | 不涉及公网端口 |
Matrix 的域名有两种常见设计:
- 简单方案:直接使用
chat.example.com作为 Matrixserver_name,用户 ID 类似@alice:chat.example.com。配置少,适合独立聊天域名。 - 品牌域名方案:使用
example.com作为server_name,客户端入口使用chat.example.com,用户 ID 类似@alice:example.com。需要在example.com/.well-known/matrix/下提供发现配置,并确保两个域名都能正确解析和签发证书。
本文先完整部署简单方案,后文补充品牌域名方案的差异。
A5数据提供中国香港物理服务器租用,覆盖入门建站、Xeon Gold与AMD EPYC等配置,并提供SSD或NVMe存储、不同内存规格及CN2与国际带宽方案,可为Matrix Synapse、PostgreSQL数据库、媒体文件和长连接访问提供相应的硬件与网络资源基础。对于需要跨地区联邦通信或扩展业务节点的场景,A5数据还提供美国、日本、韩国、新加坡等地区的服务器资源。
2. 香港服务器的资源起点
Matrix 的资源消耗与房间数量、历史消息、媒体文件、联邦连接和同步请求有关,不能只按账号数量估算。以下是便于规划的起始范围,不代表固定容量上限:
| 使用场景 | 可作为起点的配置 | 主要限制 |
|---|---|---|
| 内部沟通、低并发、小规模房间 | 2 vCPU、4 GB 内存、50 GB SSD | 上传文件建议限制在 50 MB,关注媒体目录增长 |
| 多房间、较多移动端长连接 | 4 vCPU、8 GB 内存、100 GB 以上 SSD | 需要持续观察 PostgreSQL、内存和磁盘 |
| 较大规模或联邦连接较多 | 独立规划数据库、媒体存储和 Synapse 扩展 | 不建议继续依赖单机资源简单堆叠 |
生产环境至少应保留约 20% 的内存和磁盘余量。/var/lib/matrix-synapse/media 通常是磁盘增长的主要来源,磁盘使用率达到 70% 时就应检查增长趋势,达到 85% 前应完成扩容、清理策略或迁移安排。
二、准备域名、服务器和备份
1. 配置 DNS
在域名控制台添加:
chat.example.com A 香港服务器公网 IPv4
chat.example.com AAAA 香港服务器公网 IPv6(只有 IPv6 已配置时添加)
如果服务器没有可用 IPv6,不要保留指向错误地址的 AAAA 记录,否则部分客户端或证书验证节点可能优先访问 IPv6,表现为间歇性连接失败。
在本地或服务器上检查解析:
dig +short chat.example.com A
dig +short chat.example.com AAAA
解析结果应与实际公网地址一致。若使用 CDN、云防护或其他代理服务,需要确认其是否支持长连接、较大的请求体和 Matrix 联邦请求;本文默认域名直接解析到香港服务器。
2. 确认系统和端口
确认系统版本、磁盘和已有监听端口:
cat /etc/os-release
uname -m
df -h
free -h
sudo ss -lntp
需要特别确认 80、443、8008 和 5432 是否已被其他服务占用。若 80/443 已有网站,Matrix 可以作为新的 Nginx server 块加入,不要停止或删除原有站点。
建议在第二个 SSH 会话中保持登录,再调整防火墙。以下规则只开放常见必要端口;如果服务器已有防火墙策略,应先查看现有规则,不要直接重置:
sudo ufw status numbered
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
如果确认当前 SSH 连接不依赖其他端口,并且准备采用 UFW 作为主防火墙,再根据现有策略启用 UFW。启用或修改默认拒绝规则可能导致 SSH 断连,操作前应确认云厂商控制台具备应急登录或串行控制台能力。8008 和 5432 不应加入公网放行规则。
3. 建立变更前备份
首次部署前先建立配置备份目录:
sudo install -d -m 700 /var/backups/matrix-prechange
sudo tar -czf /var/backups/matrix-prechange/etc-before-$(date +%F-%H%M%S).tar.gz \
/etc/nginx /etc/matrix-synapse 2>/dev/null || true
如果服务器上原本已经存在 Matrix 数据,还要执行 PostgreSQL 逻辑备份:
sudo install -d -m 700 /var/backups/matrix
sudo -u postgres pg_dump -Fc synapse \
> /var/backups/matrix/synapse-before-$(date +%F-%H%M%S).dump
本机备份只能用于误配置回退,不能替代异机或对象存储备份。配置文件中可能包含数据库密码、注册密钥和签名密钥,备份目录必须限制权限,并按照同等安全级别保存。
三、安装 Nginx、PostgreSQL 和 Synapse
1. 安装基础软件
以下命令适用于使用 APT 的系统。先安装 Nginx、PostgreSQL、Certbot 和仓库管理工具:
sudo apt update
sudo apt install -y \
ca-certificates curl gnupg lsb-release \
postgresql nginx certbot
添加 Matrix 软件源时,应确认该源支持当前发行版。不要把 Debian 和 Ubuntu 的软件源混用,也不要为了绕过依赖强行安装不匹配的 Synapse 包:
sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL \
https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg \
-o /etc/apt/keyrings/matrix-org-archive-keyring.gpg
echo "deb [signed-by=/etc/apt/keyrings/matrix-org-archive-keyring.gpg] \
https://packages.matrix.org/debian/ \
$(. /etc/os-release && echo "$VERSION_CODENAME") main" \
| sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install -y matrix-synapse-py3
安装过程中如果出现配置向导:
Server Name填写chat.example.com;- 公网入口使用 HTTPS;
- 使用统计是否开启,按照组织隐私策略选择;
- 不要把
127.0.0.1:8008改成公网地址。
如果安装向导没有出现,或者服务器已有配置,先查看当前配置:
sudo systemctl list-unit-files | grep -i synapse
sudo grep -E '^(server_name|public_baseurl|database:|listeners:)' \
/etc/matrix-synapse/homeserver.yaml
常见服务名是 matrix-synapse,配置文件通常位于 /etc/matrix-synapse/homeserver.yaml,但仍应以系统实际结果为准。
2. 创建 PostgreSQL 数据库
Synapse 生产环境应使用 PostgreSQL,不建议长期使用 SQLite 承载正式服务。创建独立数据库账号时采用交互式输入,避免把密码直接写入 shell 历史:
sudo -u postgres createuser --pwprompt synapse
sudo -u postgres createdb \
--encoding=UTF8 \
--locale=C \
--template=template0 \
--owner=synapse \
synapse
如果提示角色或数据库已存在,不要重复创建。先核对现有对象:
sudo -u postgres psql -c '\du synapse'
sudo -u postgres psql -lqt | awk '{print $1}' | grep '^synapse$'
后续配置中的数据库密码必须与这里设置的密码一致。建议使用只包含字母和数字的随机长密码,避免 YAML 引号、特殊字符和复制过程引发问题。
3. 配置 Synapse 的域名、数据库和监听地址
编辑配置前再次备份:
sudo cp -a /etc/matrix-synapse/homeserver.yaml \
/etc/matrix-synapse/homeserver.yaml.before-nginx
sudoedit /etc/matrix-synapse/homeserver.yaml
不要把下面内容整段追加到文件末尾。YAML 中重复的顶级键可能导致配置解析错误,应修改现有对应项目,确保每个顶级键只保留一份。核心配置可以参考:
server_name: "chat.example.com"
public_baseurl: "https://chat.example.com/"
database:
name: psycopg2
args:
user: synapse
password: "替换为PostgreSQL密码"
database: synapse
host: 127.0.0.1
port: 5432
listeners:
- port: 8008
tls: false
type: http
x_forwarded: true
bind_addresses:
- "127.0.0.1"
resources:
- names:
- client
- federation
compress: false
enable_registration: false
max_upload_size: 50M
registration_shared_secret: "替换为openssl生成的随机值"
生成注册密钥:
openssl rand -hex 32
registration_shared_secret 用于通过本机命令创建用户,不能公开给客户端。若配置文件已有 macaroon_secret_key、签名密钥等密钥,不要因为修改域名而重新生成,否则可能影响现有会话或身份验证。
如果只计划内部使用,保持 enable_registration: false。创建初始管理员时使用本机工具,而不是临时开放公网注册入口。
配置文件包含数据库密码和密钥,应限制权限:
sudo chown root:matrix-synapse /etc/matrix-synapse/homeserver.yaml
sudo chmod 640 /etc/matrix-synapse/homeserver.yaml
如果发行版中的服务用户不是 matrix-synapse,以服务文件中的 User= 为准:
systemctl cat matrix-synapse | grep -E '^(User|ExecStart)='
四、先建立 HTTP 入口并签发证书
1. 创建证书验证目录
sudo install -d -m 755 /var/www/certbot
创建 Nginx 临时 HTTP 配置:
server {
listen 80;
server_name chat.example.com;
location ^~ /.well-known/acme-challenge/ {
root /var/www/certbot;
try_files $uri =404;
}
location / {
return 301 https://$host$request_uri;
}
}
保存到 /etc/nginx/sites-available/matrix.conf。如果系统存在同名站点,先备份,不要直接覆盖:
sudo cp -a /etc/nginx/sites-available/matrix.conf \
/var/backups/matrix-prechange/matrix.conf.before-cert 2>/dev/null || true
sudo ln -sfn /etc/nginx/sites-available/matrix.conf \
/etc/nginx/sites-enabled/matrix.conf
sudo nginx -t
sudo systemctl reload nginx
如果配置中使用了 IPv6 listen [::]:80;,必须同时确认服务器 IPv6 路由和防火墙可用;否则先只使用 IPv4。
2. 使用 Webroot 方式申请证书
将命令中的邮箱替换为实际运维邮箱:
sudo certbot certonly \
--webroot \
-w /var/www/certbot \
-d chat.example.com \
--agree-tos \
-m ops@example.com \
--no-eff-email
证书申请失败时,先检查:
curl -i http://chat.example.com/.well-known/acme-challenge/test
sudo ss -lntp | grep ':80'
sudo journalctl -u nginx -n 80 --no-pager
curl 返回 404 并不一定是错误,只要请求确实到达本机 Nginx 即可;如果域名解析到其他地址、80 端口被云防火墙拦截,或 AAAA 记录指向错误服务器,验证会失败。
五、配置 HTTPS 反向代理
1. 配置 WebSocket 连接头
在 Debian/Ubuntu 的 Nginx 中,map 应放在 http 配置上下文。可以单独建立文件:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
保存为 /etc/nginx/conf.d/matrix-upgrade.conf。如果系统没有加载 conf.d/*.conf,应把这段放到 /etc/nginx/nginx.conf 的 http {} 内,而不是 server {} 内。
2. 替换为 HTTPS 站点配置
在确认 /etc/letsencrypt/live/chat.example.com/ 已经生成证书后,将站点文件调整为:
server {
listen 80;
server_name chat.example.com;
location ^~ /.well-known/acme-challenge/ {
root /var/www/certbot;
try_files $uri =404;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl http2;
server_name chat.example.com;
ssl_certificate /etc/letsencrypt/live/chat.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/chat.example.com/privkey.pem;
access_log /var/log/nginx/matrix_access.log;
error_log /var/log/nginx/matrix_error.log;
client_max_body_size 50M;
location = /.well-known/matrix/server {
default_type application/json;
add_header Access-Control-Allow-Origin "*" always;
return 200 '{"m.server":"chat.example.com:443"}';
}
location = /.well-known/matrix/client {
default_type application/json;
add_header Access-Control-Allow-Origin "*" always;
return 200 '{"m.homeserver":{"base_url":"https://chat.example.com"}}';
}
location ~ ^(/_matrix|/_synapse/client) {
proxy_pass http://127.0.0.1:8008;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
proxy_buffering off;
}
location / {
return 404;
}
}
这里有两个容易忽略的限制:
client_max_body_size与 Synapse 的max_upload_size应保持一致或前者略大,否则 Nginx 可能先返回 413;proxy_read_timeout是为了容纳客户端同步请求,不代表服务端可以无限制堆积连接。出现大量长连接时,仍需观察内存、文件描述符和数据库负载。
检查并加载配置:
sudo nginx -t
sudo systemctl reload nginx
如果 nginx -t 报证书文件不存在,不要删除证书配置来“绕过”检查,应先确认 Certbot 是否成功完成,或临时恢复 HTTP 配置。
3. 品牌域名方案的额外配置
如果希望用户 ID 使用 @alice:example.com,Synapse 中应设置:
server_name: "example.com"
public_baseurl: "https://chat.example.com/"
此时至少要满足:
https://example.com/.well-known/matrix/server
https://example.com/.well-known/matrix/client
响应内容可分别为:
{"m.server":"chat.example.com:443"}
{"m.homeserver":{"base_url":"https://chat.example.com"}}
example.com 和 chat.example.com 都需要正确解析,且 HTTPS 证书分别覆盖对应域名。example.com 的 Nginx 站点应保留原有网站,只新增精确的 .well-known 路径,不能把主站整站改成 Matrix 代理。配置错误时,常见表现是客户端能打开 chat.example.com,但无法发现 example.com 对应的 homeserver,或者联邦请求无法建立。
六、启动服务、进程守护和创建管理员
1. 配置 systemd 自动启动和异常重启
先启动 PostgreSQL 和 Nginx,再启动 Synapse:
sudo systemctl enable --now postgresql
sudo systemctl enable --now nginx
sudo systemctl enable matrix-synapse
sudo systemctl restart matrix-synapse
确认服务名称和状态:
sudo systemctl is-active postgresql nginx matrix-synapse
sudo systemctl status matrix-synapse --no-pager
如果服务单元没有异常重启策略,可以创建 systemd drop-in:
sudo systemctl edit matrix-synapse
写入:
[Service]
Restart=on-failure
RestartSec=5s
保存后执行:
sudo systemctl daemon-reload
sudo systemctl restart matrix-synapse
不要配置无间隔的无限重启。YAML、数据库密码或权限错误时,连续重启只会增加日志噪声,正确做法是先查看失败原因。
2. 创建首个管理员账号
确认服务已经监听本机 8008:
sudo ss -lntp | grep ':8008'
然后使用 Synapse 提供的本机注册工具:
sudo -u matrix-synapse register_new_matrix_user \
-c /etc/matrix-synapse/homeserver.yaml \
http://127.0.0.1:8008
按照提示输入用户名、密码,并将首个账号设为管理员。该命令需要配置 registration_shared_secret。如果提示找不到命令,可先定位安装路径:
command -v register_new_matrix_user
dpkg -L matrix-synapse-py3 | grep register_new_matrix_user
创建完成后,仍然保持 enable_registration: false,避免任何访问者通过公网注册。
七、证书续期、日志和备份
1. 检查证书自动续期
Certbot 通常会安装 systemd timer。检查其状态:
sudo systemctl list-timers --all | grep -i certbot
sudo certbot renew --dry-run
证书续期成功后,Nginx 需要重新加载才能读取新证书。可以增加 deploy hook:
sudo install -d -m 755 /etc/letsencrypt/renewal-hooks/deploy
sudo tee /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh >/dev/null <<'EOF'
#!/bin/sh
systemctl reload nginx
EOF
sudo chmod 755 /etc/letsencrypt/renewal-hooks/deploy/reload-nginx.sh
这个 hook 只执行平滑 reload,不会主动中断现有 Nginx 进程。
2. 查看服务和访问日志
Synapse 主要日志:
sudo journalctl -u matrix-synapse -n 100 --no-pager
sudo journalctl -u matrix-synapse -f
Nginx 访问和错误日志:
sudo tail -f /var/log/nginx/matrix_access.log
sudo tail -f /var/log/nginx/matrix_error.log
查看系统资源:
df -h
free -h
uptime
sudo du -sh /var/lib/matrix-synapse/media
sudo du -sh /var/lib/postgresql
如果使用 journald 保存大量服务日志,应为整个系统设置合理上限,而不是直接删除正在使用的日志文件。修改 /etc/systemd/journald.conf 会影响整台服务器的所有 systemd 日志,变更前应备份该文件,并根据磁盘容量设置,例如:
SystemMaxUse=1G
RuntimeMaxUse=256M
MaxRetentionSec=14day
修改后:
sudo systemctl restart systemd-journald
3. 建立可恢复的备份
备份至少包含三部分:
- PostgreSQL 逻辑备份;
/var/lib/matrix-synapse/media媒体目录;/etc/matrix-synapse、Nginx 站点和证书续期配置。
下面是一个示例脚本,假定 /backup 是已经挂载并具备足够容量的异机或独立存储。脚本不会自动删除旧备份,保留策略应结合存储容量另行制定:
#!/usr/bin/env bash
set -euo pipefail
if ! mountpoint -q /backup; then
echo "/backup is not mounted" >&2
exit 1
fi
backup_dir="/backup/matrix/$(date +%F-%H%M%S)"
install -d -m 700 "$backup_dir"
sudo -u postgres pg_dump -Fc synapse \
> "$backup_dir/synapse.dump"
rsync -a \
/var/lib/matrix-synapse/media/ \
"$backup_dir/media/"
tar -czf "$backup_dir/config.tar.gz" \
-C /etc matrix-synapse nginx/ sites-enabled/ 2>/dev/null || true
chmod -R go-rwx "$backup_dir"
echo "backup completed: $backup_dir"
脚本中的 config.tar.gz 可能包含数据库密码和私钥,备份介质必须限制访问。至少每月在隔离环境测试一次恢复,不要只检查备份文件是否存在。

八、上线前验证
1. 验证端口边界
sudo ss -lntp | grep -E ':(80|443|8008|5432)\b'
期望结果是:
- Nginx 监听
0.0.0.0:80和0.0.0.0:443; - Synapse 只监听
127.0.0.1:8008; - PostgreSQL 只监听本机地址;
- 公网扫描不到 8008 和 5432。
如果 8008 监听在 0.0.0.0,应立即回到 homeserver.yaml 检查 bind_addresses,并确认云防火墙没有放行该端口。
2. 验证 HTTPS 和 Matrix API
检查证书:
openssl s_client \
-connect chat.example.com:443 \
-servername chat.example.com </dev/null 2>/dev/null \
| openssl x509 -noout -subject -issuer -dates
检查客户端版本接口:
curl -fsS https://chat.example.com/_matrix/client/versions
检查服务端发现信息:
curl -i https://chat.example.com/.well-known/matrix/server
curl -i https://chat.example.com/.well-known/matrix/client
检查联邦 API 的入口:
curl -i https://chat.example.com/_matrix/federation/v1/version
接口返回 200 或 JSON 响应,说明请求已经经过 HTTPS 和 Nginx 到达 Synapse。访问 https://chat.example.com/ 返回 404 在本配置中是正常的,因为根路径没有提供网页,Matrix 客户端使用的是 /_matrix API。
3. 验证客户端和管理员操作
使用实际客户端完成以下检查:
- 能发现
chat.example.com; - 能使用首个管理员账号登录;
- 能创建房间并发送普通文本;
- 能上传不超过 50 MB 的图片或文件;
- 关闭并重新打开客户端后,历史消息仍可同步;
- 重启服务器后,PostgreSQL、Nginx 和 Synapse 都能自动启动。
模拟重启前先确认正在进行的维护窗口:
sudo systemctl restart matrix-synapse
sudo systemctl is-active matrix-synapse
不要在业务高峰期直接重启 PostgreSQL。数据库重启会短暂中断登录、同步和消息写入,影响范围比单独 reload Nginx 更大。
九、常见失败处理
1. 域名能解析,但证书申请失败
按由外到内的顺序检查:
dig +short chat.example.com A
sudo ss -lntp | grep ':80'
sudo ufw status
curl -i http://chat.example.com/.well-known/acme-challenge/test
不同结果的含义:
- 解析结果错误:修正 A 或 AAAA 记录,等待 DNS 生效;
- 80 端口没有监听:检查 Nginx 配置和服务状态;
- 本机访问正常、外部访问失败:检查云安全组、UFW 和上游网络策略;
- IPv4 正常、IPv6 失败:修正 IPv6 路由,或暂时删除错误 AAAA 记录。
2. HTTPS 返回 502 Bad Gateway
502 通常表示 Nginx 无法连接上游 Synapse:

sudo systemctl status matrix-synapse --no-pager
sudo ss -lntp | grep ':8008'
sudo journalctl -u matrix-synapse -n 100 --no-pager
- 没有 8008 监听:先修复 Synapse 启动失败;
- 8008 监听在错误地址:检查
bind_addresses和端口; - Synapse 正常但仍 502:检查
proxy_pass是否为http://127.0.0.1:8008,以及本机安全策略; - 返回 413:比较 Nginx 的
client_max_body_size和 Synapse 的max_upload_size; - 返回 404:先确认请求路径是否为
/_matrix或/_synapse/client,根路径 404 在本文配置中是预期行为。
3. Synapse 启动失败
优先查看日志,不要立即删除配置:
sudo systemctl status matrix-synapse --no-pager
sudo journalctl -u matrix-synapse -b --no-pager
常见原因包括:
- YAML 缩进错误;
- 同一个顶级键出现两次;
- PostgreSQL 用户名、密码或数据库名不匹配;
- 配置文件权限使服务用户无法读取;
- 迁移过程中仍保留旧的 SQLite 数据库配置。
如果只是刚刚修改配置导致失败,可恢复变更前副本,再验证服务:
sudo cp -a \
/etc/matrix-synapse/homeserver.yaml.before-nginx \
/etc/matrix-synapse/homeserver.yaml
sudo systemctl restart matrix-synapse
这只适用于确认副本是同一台服务器、同一业务阶段生成的情况。若期间已经产生新数据,不要用旧配置覆盖密钥或数据库相关配置,先保留当前文件并进行差异比较。
4. 客户端能登录,但联邦请求失败
检查:
curl -i https://chat.example.com/.well-known/matrix/server
openssl s_client \
-connect chat.example.com:443 \
-servername chat.example.com </dev/null
重点核对:
server_name与用户 ID 中的域名是否一致;m.server是否明确指向chat.example.com:443;- 证书是否覆盖目标域名;
- 443 端口是否可从公网访问;
- 品牌域名方案中,
example.com的.well-known是否仍被主站或其他 Nginx 规则覆盖。
本文使用 :443 的联邦目标,不需要额外开放 8448。但如果改为其他端口,发现信息、证书、防火墙和 Nginx 监听必须同步调整。
5. 磁盘或内存持续增长
先确认增长位置:
df -h
sudo du -xhd1 /var/lib/matrix-synapse
sudo du -xhd1 /var/lib/postgresql
free -h
不要直接执行 rm -rf /var/lib/matrix-synapse/media,这会破坏房间中的媒体引用。也不要在 PostgreSQL 数据目录中手工删除文件。正确处理顺序是:
- 确认媒体、数据库还是日志占用;
- 先完成可恢复备份;
- 通过业务策略限制上传大小和媒体保留;
- 扩容磁盘或迁移媒体存储;
- 对日志使用 logrotate 或 journald 策略;
- 重启前确认数据库和媒体目录权限没有被改变。
十、回滚方法和影响范围
1. 回滚 Nginx 或 HTTPS 配置
如果修改 Nginx 后 nginx -t 失败,先恢复站点文件:
sudo cp -a \
/var/backups/matrix-prechange/matrix.conf.before-cert \
/etc/nginx/sites-available/matrix.conf
sudo nginx -t
sudo systemctl reload nginx
这通常只影响域名入口,不会删除 Synapse 数据。若新证书已经签发,证书文件可以保留;回滚到旧站点配置时,必须确认旧配置引用的证书仍然存在。
2. 回滚 Synapse 配置
恢复配置前先停止 Synapse,避免进程继续读取正在替换的文件:
sudo systemctl stop matrix-synapse
sudo cp -a \
/var/backups/matrix-prechange/etc-before-日期时间.tar.gz \
/root/
不要直接对整个 /etc 解压覆盖。应先解压到临时目录,比较目标文件后再单独恢复:
sudo mkdir -p /root/matrix-rollback
sudo tar -xzf /root/etc-before-日期时间.tar.gz \
-C /root/matrix-rollback
sudo diff -u \
/etc/matrix-synapse/homeserver.yaml \
/root/matrix-rollback/etc/matrix-synapse/homeserver.yaml
确认需要恢复后:
sudo cp -a \
/root/matrix-rollback/etc/matrix-synapse/homeserver.yaml \
/etc/matrix-synapse/homeserver.yaml
sudo systemctl start matrix-synapse
3. 恢复 PostgreSQL 和媒体数据
数据库恢复是高风险操作,会覆盖当前数据库内容。只有在确认备份时间点、维护窗口和恢复目标后执行。恢复前停止 Synapse,并再次保存当前数据库:
sudo systemctl stop matrix-synapse
sudo -u postgres pg_dump -Fc synapse \
> /var/backups/matrix/synapse-before-restore-$(date +%F-%H%M%S).dump
恢复示例:
sudo -u postgres dropdb --if-exists synapse
sudo -u postgres createdb \
--encoding=UTF8 \
--locale=C \
--template=template0 \
--owner=synapse \
synapse
sudo -u postgres pg_restore \
--no-owner \
-d synapse \
/backup/matrix/备份时间/synapse.dump
sudo rsync -a \
/backup/matrix/备份时间/media/ \
/var/lib/matrix-synapse/media/
sudo chown -R matrix-synapse:matrix-synapse \
/var/lib/matrix-synapse/media
sudo systemctl start matrix-synapse
dropdb 会删除当前数据库,影响全部账号、房间和消息索引,不能在没有有效备份的情况下执行。恢复后必须重新验证管理员登录、历史消息、媒体文件和客户端同步。
上线验收清单
- [ ]
chat.example.com的 A/AAAA 记录指向正确服务器,错误 AAAA 已清理。 - [ ] 公网只开放符合策略的 22、80、443 端口。
- [ ] Synapse 仅监听
127.0.0.1:8008,PostgreSQL 未对公网监听。 - [ ]
nginx -t通过,HTTPS 证书包含实际访问域名。 - [ ] Certbot
--dry-run续期测试通过,并已配置 Nginx reload hook。 - [ ]
/_matrix/client/versions返回正常 JSON。 - [ ]
/.well-known/matrix/server和/.well-known/matrix/client内容与域名方案一致。 - [ ] 客户端可以登录、建房间、发送消息和上传符合限制的文件。
- [ ]
matrix-synapse、PostgreSQL 和 Nginx 已设置开机启动。 - [ ] 已验证 Synapse 日志、Nginx 错误日志和访问日志的查看方式。
- [ ] PostgreSQL、媒体目录和配置文件已有异机或独立存储备份。
- [ ] 至少完成一次备份文件可读性检查,恢复流程中的破坏性步骤已记录。
- [ ] 已明确磁盘、内存和媒体目录的告警阈值,并安排定期复核。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/3669.html



