Synapse 安装部署完全指南：从服务器命名到生产环境配置的实战手册

Synapse 安装部署完全指南从服务器命名到生产环境配置的实战手册【免费下载链接】synapseSynapse: Matrix homeserver written in Python/Twisted.项目地址: https://gitcode.com/gh_mirrors/sy/synapse本文基于 Matrix 开源仓库中docs/setup/installation.md编写围绕 Python/Twisted 实现的 Matrix homeserver —— Synapse 展开覆盖安装前的服务器命名决策、各大平台预编译包安装、PyPI 源码安装、配置生成与启动以及 PostgreSQL、TLS、Well-Known、邮件、用户注册、TURN、URL 预览等上线必需环节。读者读完可以独立完成一套可运行、可联邦、可投入生产的 Synapse 部署并理解每个关键步骤背后的配置原理与源码行为。一、安装之前慎重选择你的服务器名server name选择服务器名是整个部署中最重要、且不可事后更改的决定必须在安装 Synapse 之前完成。服务器名决定了本服务器上所有用户 ID 的“域名”部分例如user:my.domain.name。它同时也决定了其他 Matrix 服务器如何通过联邦federation协议找到你的服务器。测试配置直接使用你服务器的 hostname 即可生产配置更推荐使用你的业务域名如example.com而非矩阵专用主机名。这与电子邮件地址的习惯一致——userexample.com比useremail.example.com更自然。但选择域名方式通常需要更高级的配置端口 8448、DNS 委派等详见 联邦配置指南。从源码看server_name是 Synapse 的核心身份标识在 synapse/app/homeserver.py 中HomeServer实例以config.server.server_name作为构造参数并拼装出Synapse/{VERSION}的版本字符串对外标识本服务器的身份。因此一旦对外发布并被其他服务器缓存更换server_name会导致既有用户 ID 与联邦身份全部失效。二、安装 Synapse预编译包路线推荐大多数用户对于大多数用户官方推荐直接使用各平台的预编译包省去编译依赖的麻烦。2.1 Docker 镜像与 Ansible Playbook官方 Synapse 镜像发布在 Docker Hub 的matrixdotorg/synapse与ghcr.io/matrix-org/synapse可配合仓库内提供的 docker-compose 文件使用见 contrib/docker/README.md 与 contrib/docker/docker-compose.yml。仓库自带的 compose 文件给出了一个可直接参考的骨架synapse服务使用docker.io/matrixdotorg/synapse:latest镜像通过环境变量SYNAPSE_CONFIG_PATH/data/homeserver.yaml指定配置路径并将./files挂载到/data同时内置一个postgres:12-alpine数据库服务并特别设置POSTGRES_INITDB_ARGS--encodingUTF-8 --lc-collateC --lc-ctypeC以确保数据库以正确编码初始化这与 PostgreSQL 使用指南 中的建库要求一致。生成初始配置的方式docker-compose run --rm -e SYNAPSE_SERVER_NAMEmy.matrix.host -e SYNAPSE_REPORT_STATSyes synapse generate该命令会同时生成必要的签名密钥。之后按需修改配置并启动docker-compose up -d此外社区还有 avhost 的单镜像 Dockerfile、以及 Slavi Pantaleev 的matrix-docker-ansible-deployPlaybook后者会一并部署 Postgres、Element、coturn、ma1sd、SSL 等周边服务。Docker 镜像的完整环境变量说明见 docker/README.md。2.2 Debian / UbuntuMatrix.org 官方仓库Matrix.org 提供 amd64 架构的官方 Debian/Ubuntu 软件包仓库地址为https://packages.matrix.org/debian/。安装最新正式版sudo apt install -y lsb-release wget apt-transport-https sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg echo deb [signed-by/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main | sudo tee /etc/apt/sources.list.d/matrix-org.list sudo apt update sudo apt install matrix-synapse-py3如果需要安装发布候选版本release candidate在sources.list行末尾追加prerelease启用预发布通道sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg echo deb [signed-by/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main prerelease | sudo tee /etc/apt/sources.list.d/matrix-org.list sudo apt update sudo apt install matrix-synapse-py3仓库签名密钥指纹为AAF9AE843A7584B5A3E4CD2BCF45A512DE2DA058可用gpg /usr/share/keyrings/matrix-org-archive-keyring.gpg核对。升级友好小技巧使用 Debian 包安装时建议将自定义配置放在/etc/matrix-synapse/conf.d/目录下覆盖主配置而不要直接编辑/etc/matrix-synapse/homeserver.yaml。这样在升级 Debian 包时不会被询问是否替换配置文件。Debian 下游仓库Debian 官方仓库维护了matrix-synapse包bookworm与sid可直接安装sudo apt install matrix-synapsebullseye-backports中也有可用版本使用 backports 的方法参见 Debian 官方 backports 文档。注意buster及更早版本已不再维护matrix-synapse包。Ubuntu 下游仓库不推荐默认 Ubuntu 源中的 Synapse 包版本过旧且存在已知安全漏洞官方不推荐使用。如需在 Ubuntu 上获取最新版本请从上面的 Matrix.org 官方仓库 安装。2.3 Fedora / OpenSUSE / SLESFedora 官方仓库内置matrix-synapsesudo dnf install matrix-synapseOpenSUSE 仓库同样提供matrix-synapsesudo zypper install matrix-synapseSLES 15 可在 openSUSE:Backports:SLE-15 仓库获取非官方构建包。2.4 ArchLinux / Alpine / Void / FreeBSD / OpenBSD / NixOSArchLinux官方 extra 仓库的matrix-synapse包会拉取大部分依赖。若pip版本过旧如 6.0.7-1 需升级到 6.0.8-1sudo pip install --upgrade pip若在 x64 系统上遇到py-bcrypt的Wrong ELF Class: ELFCLASS32错误可重装该包使其在正确的架构下编译virtualenv 环境下一般无需处理sudo pip uninstall py-bcrypt sudo pip install py-bcryptAlpine Linux社区仓库提供synapsesudo apk add synapseVoid Linuxvoid 仓库提供synapsexbps-install -Su xbps-install -S synapseFreeBSDPorts 或 Packages 均可安装cd /usr/ports/net-im/py-matrix-synapse make install clean pkg install py38-matrix-synapseOpenBSD自 OpenBSD 6.7 起提供预编译二进制包。注意 homeserver 目录默认/var/synapse所在的文件系统必须以wxallowed挂载参见mount(8)因此建议单独划分文件系统挂载到/var/synapsedoas pkg_add synapseNixOSnixpkgs 中已有services/matrix/synapse.nix模块化打包。三、PyPI 源码安装从 virtualenv 到首个 homeserver当目标平台没有预编译包或需要自定义构建时可以将 Synapse 作为 Python 模块从 PyPI 安装。走这条路之前务必先完成 平台专属前置依赖 的安装。3.1 系统要求POSIX 兼容系统已在 Linux 与 macOS 上测试通过Python 3.8 及以上最高支持到 Python 3.11与 pyproject.toml 中python ^3.8.0的约束一致若想加入#matrix:matrix.org这类大型公共房间至少需要1GB 可用内存。如果在无预编译 wheel 的冷门架构上构建还需要较新的 Rust 编译器推荐通过 rustup 安装。这是因为 Synapse 的部分组件如 push 规则评估、ACL 等由 Rust 实现构建时会通过build_rust.py编译synapse.synapse_rust扩展见 pyproject.toml 与 build_rust.py。3.2 创建虚拟环境并安装mkdir -p ~/synapse virtualenv -p python3 ~/synapse/env source ~/synapse/env/bin/activate pip install --upgrade pip pip install --upgrade setuptools pip install matrix-synapse上述命令会从 PyPI 下载matrix-synapse及其 Python 依赖库安装到~/synapse/env虚拟环境中目录可自选。日后升级同样简单source ~/synapse/env/bin/activate pip install -U matrix-synapse3.3 生成配置文件与签名密钥启动 Synapse 前必须先生成配置文件。在虚拟环境中执行cd ~/synapse python -m synapse.app.homeserver \ --server-name my.domain.name \ --config-path homeserver.yaml \ --generate-config \ --report-stats[yes|no]--server-name替换为你的服务器名--report-stats选择是否向开发团队上报使用统计信息主机名、Synapse 版本、运行时长、用户总数等。这个命令背后的逻辑可以在 synapse/app/homeserver.py 中看到setup()调用HomeServerConfig.load_or_generate_config()当配置只用于生成--generate-config时不会返回配置对象进程直接以退出码 0 结束。生成过程本身由 synapse/_scripts/generate_config.py 实现它支持--config-dir、--data-dir、--server-name、--report-stats、--generate-secrets等参数。生成配置的同时还会生成一组签名密钥用于让本 homeserver 向其他 homeserver 标识自己的身份千万不要丢失或删除这些密钥建议备份到安全位置若确需更换签名密钥其他服务器可能仍缓存着旧密钥更换后应修改server name.signing.key文件中的密钥名第二个词详见 Matrix 服务端规范中关于密钥管理Retrieving server keys的说明。3.4 启动 homeserver选择 Synapse 的工作目录如~/synapse然后cd ~/synapse source env/bin/activate synctl startsynctl是 Synapse 自带的管理脚本入口定义在 pyproject.toml 的synctl synapse._scripts.synctl:main其实现位于 synapse/_scripts/synctl.py。从源码看synctl start读取配置中的pid_file若进程已在运行会提示 already running 并直接返回否则以python -m synapse.app.homeserver -c config [--daemonize]拉起主进程见 synctl.py支持start/stop/restart三种动作还支持-w worker配置管理单个 worker、-a worker配置目录管理全部进程、--no-daemonize前台运行以便调试若配置文件不存在synctl会提示用python -m synapse.app.homeserver -c file --generate-config --server-namename --report-statsyes/no生成。3.5 平台专属前置依赖Platform-specific prerequisitesSynapse 本身是 Python 写的但部分依赖库是 C 实现如bcrypt、lxml、psycopg2、PyICU等因此需要可用的 C 编译器与 Python C 扩展头文件。Debian / Ubuntu / Raspbiansudo apt install build-essential python3-dev libffi-dev \ python3-pip python3-setuptools sqlite3 \ libssl-dev virtualenv libjpeg-dev libxslt1-dev libicu-devArchLinuxsudo pacman -S base-devel python python-pip \ python-setuptools python-virtualenv sqlite3 icuCentOS / Fedorasudo dnf install libtiff-devel libjpeg-devel libzip-devel freetype-devel \ libwebp-devel libxml2-devel libxslt-devel libpq-devel \ python3-virtualenv libffi-devel openssl-devel python3-devel \ libicu-devel sudo dnf groupinstall Development ToolsmacOSxcode-select --install可能需要通过 Homebrew 安装额外的依赖尤其是 ICU请遵循 PyICU 的官方安装指引。ARM 版 Mac 还需要brew install jpeg libpqmacOS Catalina10.15上可能需要显式安装 OpenSSL 并告知 pip以便psycopg2能正常构建brew install openssl1.1 export LDFLAGS-L/usr/local/opt/openssl/lib export CPPFLAGS-I/usr/local/opt/openssl/includeOpenSUSEsudo zypper in -t pattern devel_basis sudo zypper in python-pip python-setuptools sqlite3 python-virtualenv \ python-devel libffi-devel libopenssl-devel libjpeg62-devel \ libicu-develOpenBSDnet/synapse端口可用。除了前述wxallowed挂载要求外构建 Python 依赖时WRKOBJDIR也必须位于wxallowed文件系统上默认 OpenBSD 安装中/usr/local即满足可按需执行doas mkdir /usr/local/pobj_wxallowed doas chown _pbuild:_pbuild /usr/local/pobj_wxallowed echo WRKOBJDIR_lang/python/3.7/usr/local/pobj_wxallowed \nWRKOBJDIR_lang/python/2.7/usr/local/pobj_wxallowed /etc/mk.conf cd /usr/ports/net/synapse make installWindowsSynapse不官方支持在 Windows 上原生运行。如需在 Windows 上运行或开发请使用 WSLWindows Subsystem for Linux获得 Linux 环境从而复用 Debian、Fedora 或源码安装方式。四、安装后的配置与上线准备4.1 使用 PostgreSQL强烈建议Synapse 默认使用 SQLite 数据库——这是以性能换取便利的选择。几乎所有安装都应改用 PostgreSQL其优势包括更优秀的线程与缓存模型、更智能的查询优化器带来的显著性能提升允许数据库运行在独立硬件上。SQLite 仅适用于测试场景绝不能用于生产服务器——Synapse 在 SQLite 下性能很差尤其是在大型房间中。详细的安装与配置方法见 PostgreSQL 使用指南。4.2 TLS 证书与 HTTPS 暴露默认配置只在本机接口暴露一个 HTTP 端口http://localhost:8008。这适合本地测试但任何实际使用场景都需要通过 HTTPS 提供 API。推荐方式反向代理 端口 8448。在 8448 端口前架设反向代理具体配置见 反向代理文档。备选方式Synapse 直接暴露 HTTPS 端口。编辑homeserver.yaml在listeners下增加启用 TLS 的监听器listeners: - port: 8448 type: http tls: true resources: - names: [client, federation]同时添加tls_certificate_path与tls_private_key_path两个配置项证书的签发与续期需要自行管理。关于上述选项的完整说明见 配置手册。特别提醒如果使用自有证书请使用包含完整证书链含中间证书的.pem文件——例如使用 certbot 时应选fullchain.pem而非cert.pem。从源码实现看TLS 监听器最终由 synapse/app/homeserver.py 的start_listening()统一处理http类型的监听器会经由_listener_http()挂载client、federation、media、keys等命名资源而tls: true的配置会驱动 Twisted 的 TLS context 工厂完成握手。更详细的联邦部署指引见 联邦配置指南。4.3 客户端 Well-Known URI可选但推荐配置 Well-Known URI 后支持 well-known 查询的客户端允许用户直接输入完整用户名如user:server_name客户端会自动解析出 homeserver 与 identity server 地址用户无需记忆实际的服务器 URL。要求https://server_name/.well-known/matrix/client返回如下 JSON{ m.homeserver: { base_url: https://matrix.example.com } }可选地还可以附带 identity server 信息{ m.homeserver: { base_url: https://matrix.example.com }, m.identity_server: { base_url: https://identity.example.com } }浏览器客户端要求文件必须带有正确的跨域CORS头推荐值Access-Control-Allow-Origin: *允许所有浏览器客户端访问。nginx 配置示例location /.well-known/matrix/client { return 200 {m.homeserver: {base_url: https://matrix.example.com}}; default_type application/json; add_header Access-Control-Allow-Origin *; }同时确保homeserver.yaml中的public_baseurl设置正确——它应指向客户端连接本服务器所用的 URL与上面m.homeserver的base_url保持一致public_baseurl: https://matrix.example.com4.4 邮件SMTP配置Synapse 具备发信能力后可以实现三类功能密码重置邮件、邮箱添加验证、新消息邮件通知。配置email配置段至少填写smtp_host、smtp_port与notif_from三个字段若 SMTP 服务器需要认证还需设置smtp_user、smtp_pass必要时开启require_transport_security。注意如果邮件未配置密码重置、邮件注册与邮件通知功能都将被禁用。4.5 注册用户创建新用户有两种途径方式一从客户端注册。使用 Element 等客户端注册前提是在配置中启用enable_registration设置。方式二命令行注册推荐可创建管理员。步骤如下pip 安装的 Synapse 先激活虚拟环境预编译包安装则register_new_matrix_user已在 PATH 中cd ~/synapse source env/bin/activate synctl start # 如果尚未运行执行注册脚本register_new_matrix_user -c homeserver.yaml脚本会交互式询问新用户信息然后连接运行中的 Synapse 创建用户示例输出New user localpart: erikj Password: Confirm password: Make admin [no]: Success!从源码看该脚本synapse/_scripts/register_new_matrix_user.py的工作机制很值得了解它基于配置中的registration_shared_secret或registration_shared_secret_path指向的文件与 Synapse 共享密钥见 config_documentation.md 中registration_shared_secret说明。两个选项同时出现会报错退出见 register_new_matrix_user.py实现上先GET /_synapse/admin/v1/register获取 nonce再用 HMAC-SHA1 对nonce \x00 username \x00 password \x00 admin/notadmin [\x00 user_type]计算 MAC最后POST提交注册见 register_new_matrix_user.py支持-u/--user、-p/--password、-t/--user_type、-a/--admin、--no-admin、-k/--shared-secret等参数不传 server_url 时脚本会尝试从配置的listeners中自动寻找 client HTTP 监听器见 register_new_matrix_user.py找不到时回退到http://localhost:8008。安全提示registration_shared_secret的值无关紧要--generate-config会生成随机值但必须严格保密——任何掌握该密钥的人都可以在你的服务器上注册用户包括管理员账号即使enable_registration为false。4.6 配置 TURN 服务器VoIP 必需要让 VoIP 通话可靠地经由本 homeserver 路由必须配置 TURN 服务器。详细步骤见 TURN 服务器配置指南。4.7 URL 预览默认关闭开启需谨慎Synapse 内置 URL 预览功能默认关闭。开启需满足两个条件设置url_preview_enabled: True在url_preview_ip_range_blacklist中显式指定 Synapse 禁止抓取的 IP 范围。这是关键的安全措施用于防止任意 Matrix 用户借预览功能爬取你内网的“内部” URL。至少应把 loopback 与 RFC1918 私网地址加入黑名单。此外还需要安装可选依赖lxml它依赖系统库libxml2——Debian/Ubuntu 下为apt-get install libxml2-dev其他系统等价。这与 pyproject.toml 中lxml { version 4.2.0, optional true }以及url-preview [lxml]extra 的定义一致即pip install matrix-synapse[url-preview]可一并安装。五、安装排障Troubleshootingpip安装时内存泄漏严重例如 512MB 内存的 Linux 主机可能在安装 Twisted 时耗尽内存。此时需要逐个安装失败的依赖例如pip install twisted逐个装完后再继续整体安装即可。其他问题可前往#synapse:matrix.org房间Matrix 官方社区寻求帮助。六、进一步阅读联邦配置指南如何让其他服务器访问你的 homeserver、端口委派与常见故障排查PostgreSQL 使用指南在生产环境中正确配置数据库反向代理文档在 8448 端口前配置 Nginx/Caddy 等反向代理配置手册全部配置项、默认值与示例可用python -m synapse.config -c path to config校验配置TURN 服务器配置指南为 VoIP 通话配置 TURNDocker 使用说明 与 docker-compose 示例容器化部署参考synctl 管理脚本 与 注册脚本管理进程与用户的源码级实现。【免费下载链接】synapseSynapse: Matrix homeserver written in Python/Twisted.项目地址: https://gitcode.com/gh_mirrors/sy/synapse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考