用香港服务器搭建Matrix聊天服务,如何配置域名与HTTPS入口?

发布人:A5数据发布时间:2026-10-14 13:28阅读量:151

目标状态是:香港服务器对外只开放必要的 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. 推荐的访问结构

本例采用以下结构:

一、部署前的目标和边界|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 作为 Matrix server_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 可能包含数据库密码和私钥,备份介质必须限制访问。至少每月在隔离环境测试一次恢复,不要只检查备份文件是否存在。

七、证书续期、日志和备份|3. 建立可恢复的备份配图

八、上线前验证

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:

“413:比较 client max body size 与 max upload size”“根路径 404:预期行为,改查 / matrix 或 / syn

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 数据目录中手工删除文件。正确处理顺序是:

  1. 确认媒体、数据库还是日志占用;
  2. 先完成可恢复备份;
  3. 通过业务策略限制上传大小和媒体保留;
  4. 扩容磁盘或迁移媒体存储;
  5. 对日志使用 logrotate 或 journald 策略;
  6. 重启前确认数据库和媒体目录权限没有被改变。

十、回滚方法和影响范围

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

相关推荐