这篇记录 Matrix Synapse 的 Docker Compose 部署配置。Synapse 是 Matrix 的服务端实现，可以用来搭建私有化、去中心化的即时通信服务，再配合 Element 这类客户端使用。
这里把 Synapse 的数据目录和静态页面目录挂载到宿主机，同时把容器内的 8008 端口映射到宿主机 8008，方便内网客户端访问或后续接入反代。
网络方面使用统一的 matrix bridge 网络，后续如果 Nginx Proxy Manager、ntfy、LiveKit 等服务也接入同一个网络，就可以直接通过容器名互相访问。
注意：Synapse 服务器不建议走 fakeip DNS 代理上网。尤其后续和 ntfy、推送通知、联邦通信等功能配合时，优先让 Synapse 使用正常的本地网络解析和出站连接。
一、安装基础环境
如果宿主机还没有 Docker，可以先更新系统并安装常用工具：
apt update -y && apt upgrade -y
apt install -y curl wget sudo socat安装 Docker：
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh如果你的系统还没有 docker compose，也需要先安装 Docker Compose 插件或二进制文件。新系统一般建议直接使用 Docker 官方仓库里的 Compose 插件。
二、准备数据目录
先在宿主机创建 Synapse 使用的数据目录和静态页面目录：
mkdir -p /root/data/docker_data/synapse/data
mkdir -p /root/data/docker_data/synapse/postgres
mkdir -p /root/data/docker_data/synapse/html目录用途如下：
/root/data/docker_data/synapse/data：挂载到容器内/data/，保存 Synapse 配置和运行数据。/root/data/docker_data/synapse/postgres：如果使用 PostgreSQL，用来保存数据库数据。/root/data/docker_data/synapse/html：挂载到容器内 Synapse 静态资源目录，方便自定义静态页面。
三、创建 matrix 网络
为了让 Synapse、反代、通知服务和其他 Matrix 相关容器可以互相通信，先创建统一的 Docker 网络：
docker network create matrix如果后面使用的是本文主配置里的 driver: bridge 写法，也可以让 Compose 创建这个网络。更稳妥的做法是先手动创建 matrix，然后在 Compose 中使用外部网络写法，本文后面会单独说明。
四、生成 homeserver.yaml
先拉取 Synapse 镜像：
docker pull matrixdotorg/synapse:latest首次部署前，先生成 Synapse 配置文件。把 matrix.example.com 改成你自己的 Matrix 服务域名：
docker run -it --rm \
-v /root/data/docker_data/synapse/data:/data \
-e SYNAPSE_SERVER_NAME=matrix.example.com \
-e SYNAPSE_REPORT_STATS=yes \
matrixdotorg/synapse:latest generate生成完成后，配置文件会出现在：
/root/data/docker_data/synapse/data/homeserver.yaml如果只是测试体验，可以先使用默认 SQLite。正式长期使用时，更建议切换到 PostgreSQL。
五、可选：准备 PostgreSQL
如果要用 PostgreSQL，可以先启动一个 PostgreSQL 16 容器，并接入 matrix 网络：
docker run --name postgres16 \
--network matrix \
--restart=always \
-v /root/data/docker_data/synapse/postgres:/var/lib/postgresql/data \
-e POSTGRES_PASSWORD=自定义PostgreSQL密码 \
-p 5432:5432 \
-d postgres:16-alpine创建 Synapse 使用的数据库用户：
docker exec -it postgres16 createuser -U postgres --pwprompt synapse_user进入 PostgreSQL：
docker exec -it postgres16 psql -U postgres创建数据库：
CREATE DATABASE synapse
ENCODING 'UTF8'
LC_COLLATE='C'
LC_CTYPE='C'
template=template0
OWNER synapse_user;执行完成后输入：
\q然后编辑 Synapse 配置：
nvim /root/data/docker_data/synapse/data/homeserver.yaml找到默认的 SQLite 配置并注释掉：
# database:
# name: sqlite3
# args:
# database: /data/homeserver.db改成 PostgreSQL 配置：
database:
name: psycopg2
args:
user: synapse_user
password: <数据库密码>
database: synapse
host: postgres16
cp_min: 5
cp_max: 10如果 Synapse 和 PostgreSQL 都在同一个 matrix 网络内，host 可以直接写 PostgreSQL 容器名 postgres16。如果你使用的是宿主机或其他内网数据库，就改成对应内网 IP。
六、创建 docker-compose.yaml
新建并编辑 docker-compose.yaml：
nvim docker-compose.yaml写入下面的配置：
services:
synapse:
image: matrixdotorg/synapse:latest
container_name: matrix-synapse
volumes:
- /root/data/docker_data/synapse/data/:/data/
- /root/data/docker_data/synapse/html/:/usr/local/lib/python3.13/site-packages/synapse/static/
ports:
# 客户端内网端口：宿主机 8008 -> 容器 8008
- '8008:8008'
networks:
- matrix
restart: always
environment:
- "TZ=Asia/Shanghai"
networks:
matrix:
name: matrix
driver: bridge这份配置里有三个重点：
matrixdotorg/synapse:latest是官方 Synapse 镜像。8008:8008会把 Synapse 客户端端口暴露到宿主机内网。matrix网络使用固定名称，方便其他容器加入同一个网络。/usr/local/lib/python3.13/site-packages/synapse/static/是新版镜像里的静态页面路径；旧版镜像里有时会看到python3.11路径，实际以容器内 Python 版本为准。
如果某些域名必须指定 IPv4 解析，也可以按需加 extra_hosts，例如：
extra_hosts:
- "sms.example.com:192.0.2.10"七、启动 Synapse
启动服务：
docker compose up -d查看容器状态：
docker ps | grep matrix-synapse查看运行日志：
docker logs -f matrix-synapse如果容器正常运行，就可以通过宿主机的 8008 端口访问 Synapse。
八、创建 Matrix 用户
Synapse 默认不开放公开注册。可以进入 Compose 目录后，用下面的命令创建用户：
cd /root/data/docker_data/synapse
docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008根据提示输入用户名、密码，并选择是否设置为管理员。
如果你明确要允许公开注册，可以在 homeserver.yaml 中设置：
enable_registration: true然后重启 Synapse：
docker compose restart synapse公开注册会带来垃圾注册和滥用风险，建议只在明确需要时开启。
九、关于 matrix 网络
上面的写法会让当前 Compose 项目管理一个名为 matrix 的 bridge 网络。适合把 Synapse 作为这套 Matrix 服务的核心容器，由它所在的 Compose 配置创建网络。
如果你的宿主机上已经提前手动创建过 matrix 网络，或者这个网络已经由其他 Compose 项目管理，那么建议把网络部分改成外部网络写法：
networks:
matrix:
external: true
name: matrix这样 Compose 就不会尝试重新创建 matrix，而是直接使用已有网络。
如果不写 name: matrix，Docker Compose 可能会给网络名称加上项目名前缀，例如生成类似 synapse_matrix 的网络。为了让其他 Compose 项目也能稳定接入，建议显式写 name: matrix 或使用 external: true。
十、反代时的上游地址
如果 Nginx Proxy Manager 也接入同一个 matrix 网络，可以在 NPM 后台把 Synapse 的上游写成：
http://matrix-synapse:8008如果是内网直接访问，则使用：
http://服务器IP:8008实际部署时，还需要结合你的 homeserver 域名、TLS 证书和客户端访问方式继续配置 Synapse 的 homeserver.yaml。
十一、安装 Synapse Admin
如果需要一个 Web 管理界面，可以部署 synapse-admin：
docker run -d \
-p 8100:80 \
--restart unless-stopped \
--name synapse-admin \
awesometechnologies/synapse-admin启动后通过宿主机 8100 端口访问管理界面。
十二、备份与恢复
备份时重点保存整个 Synapse 数据目录：
/root/data/docker_data/synapse如果使用 PostgreSQL，也要一起备份：
/root/data/docker_data/synapse/postgres恢复时，把备份目录放回同样路径，确认 matrix 网络存在，再启动 Compose：
docker network create matrix
cd /root/data/docker_data/synapse
docker compose up -d如果需要进入容器检查文件，可以先用 docker ps 找到容器 ID，然后执行：
docker exec -it matrix-synapse /bin/bash如果镜像里没有 bash，改用：
docker exec -it matrix-synapse /bin/sh