matrix-org/synapse
GitHub: matrix-org/synapse
基于 Python/Twisted 的 Matrix 协议家庭服务器，支持联邦通信和端到端加密。
Stars: 12013 | Forks: 2116
# Synapse |support| |development| |documentation| |license| |pypi| |python|
# Synapse 目前在 `element-hq/synapse `_ 积极维护中
Synapse 是一个开源的 `Matrix `_；
此外，您还可以选择 `其他 Matrix 家庭服务器 `_ 有更多阐述，`正式规范
`_。我们建议使用
`Docker 镜像 `_ 或 `来自 Matrix.org 的 Debian 软件包
`_。
.. _federation:
Synapse 拥有各种 `配置选项
`_
可在安装后用于自定义其行为。
关于 `在此处配置 Synapse 以进行联盟
`_ 有更多详细信息。
.. _reverse-proxy:
## 在 Synapse 中使用反向代理
建议在 Synapse 前端放置一个反向代理，例如
`nginx `_、
`Apache `_、
`Caddy `_、
`HAProxy `_。这样做的一个优势是，
这意味着您可以将默认的 HTTPS 端口 (443) 暴露给
Matrix 客户端，而无需以 root 权限运行 Synapse。
有关配置其中一个的信息，请参阅 `反向代理文档
`_。
## 升级现有的 Synapse
升级 Synapse 的说明位于 `升级说明`_ 中。
请查看这些说明，因为对于某些版本的 Synapse，升级可能需要额外的步骤。
.. _the upgrade notes: https://matrix-org.github.io/synapse/develop/upgrade.html
## 平台依赖
Synapse 使用许多平台依赖项，例如 Python 和 PostgreSQL，
并旨在遵循受支持的上游版本。请参阅
`弃用政策 `_
了解更多详情。
## 安全说明
Matrix 在某些 API 中提供原始的、用户提供的数据——特别是 `内容存储库端点`_。
.. _content repository endpoints: https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid
虽然我们做出了合理的努力来缓解 XSS 攻击（例如，通过使用 `CSP`_），但 Matrix 家庭服务器不应托管在
托管其他 Web 应用程序的域上。这尤其适用于与 Matrix Web 客户端和其他敏感应用程序（如
Webmail）共享域的情况。请参阅
https://developer.github.com/changes/2014-04-25-user-content-security 了解更多信息。
.. _CSP: https://github.com/matrix-org/synapse/pull/1021
理想情况下，家庭服务器不仅应位于不同的子域，而且应位于完全不同的 `注册域`_（也称为顶级站点或
eTLD+1）。这是因为 `某些攻击`_ 仍然可能发生，只要两个
应用程序共享同一个注册域。
.. _registered domain: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3
.. _some attacks: https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie
举一个例子来说明，如果您的 Element Web 或其他敏感 Web
应用程序托管在 ``A.example1.com``，理想情况下您应该将 Synapse 托管在
``example2.com``。通过托管在
``B.example1.com`` 可以提供一定程度的保护，因此这在某些场景中也是可以接受的。
然而，您*不应*将您的 Synapse 托管在 ``A.example1.com``。
请注意，以上所有内容仅涉及 Synapse 的
``public_baseurl`` 设置中使用的域。特别是，它与该服务器上托管的 MXIDs 中提到的域
无关。
遵循此建议可确保即使在 Synapse 中发现 XSS，
对其他应用程序的影响也将微乎其微。
# 测试新安装
试用新 Synapse 安装的最简单方法是通过 Web 客户端连接到它。
除非您在本地机器上运行 Synapse 的测试实例，否则
通常，在成功从客户端连接之前，您需要启用 TLS 支持：请参阅
`TLS 证书 `_。
开始的一种简单方法是通过 Element 登录或注册，分别为
https://app.element.io/#/login 或 https://app.element.io/#/register。
您需要将登录的服务器从 ``matrix.org`` 更改
并指定家庭服务器 URL 为 ``https://:8448``
（或者，如果您使用反向代理，则仅为 ``https://``）。
如果您更喜欢使用其他客户端，请参考我们的
`客户端概览 `_
在 ``homeserver.yaml`` 中设置 ``enable_registration: true``。
2. 然后 **或者**：
a. 设置一个 `CAPTCHA `_，或者
b. 在 ``homeserver.yaml`` 中设置 ``enable_registration_without_verification: true``。
我们**强烈**建议使用 CAPTCHA，特别是如果您的家庭服务器暴露在
公共互联网上。如果没有它，任何人都可以在您的家庭服务器上自由注册账户。
这可能被攻击者利用，创建针对 Matrix 联盟其余部分的垃圾机器人。
您的新用户名将部分由 ``server_name`` 组成，部分由
您创建账户时指定的本地部分组成。您的名将采用
以下形式::
```
@localpart:my.domain.name
```
（读作“at localpart on my dot domain dot name”）。
与登录时一样，您需要指定一个“自定义服务器”。在“用户名”框中指定您
想要的 ``localpart``。
# 故障排除与支持
`管理 FAQ `_
包括处理一些常见问题的技巧。有关更多详细信息，请参阅
`Synapse 的更多文档 `_），但与此同时，
管理 Matrix 生态系统中受信任身份的角色被外包给
一群已知的受信任生态系统合作伙伴，他们运行“Matrix 身份
服务器”，例如 `Sydent `_，其角色
纯粹是验证和跟踪 3PID 登录并发布最终用户公
钥。
您可以托管自己的 Sydent 副本，但这将阻止您通过
电子邮件地址访问 Matrix 生态系统中的其他用户，并阻止他们找到
您。因此，我们建议您暂时使用
``https://matrix.org`` 或 ``https://vector.im`` 处的集中式身份服务器之一。
重申一下：仅当您选择将
电子邮件地址与您的账户关联，或通过
电子邮件地址向另一个用户发送邀请时，才会使用身份服务器。
# 开发
我们欢迎社区对 Synapse 做出贡献！
开始的最佳地点是我们的
`贡献者指南 `_。
这是我们更大的 `文档 `_ 的一部分，其中包括
Synapse 开发者以及 Synapse 管理员的信息。
开发者可能特别感兴趣的是：
* `Synapse 的数据库模式 `_，
* `关于 Synapse 实现细节的说明 `_，以及
* `我们如何使用 git `_。
除了这些之外，请在 Matrix 上加入我们的开发者社区：
`#synapse-dev:matrix.org `_，这里有真人！
.. |support| image:: https://img.shields.io/matrix/synapse:matrix.org?label=support&logo=matrix
:alt: (get support on #synapse:matrix.org)
:target: https://matrix.to/#/#synapse:matrix.org
.. |development| image:: https://img.shields.io/matrix/synapse-dev:matrix.org?label=development&logo=matrix
:alt: (discuss development on #synapse-dev:matrix.org)
:target: https://matrix.to/#/#synapse-dev:matrix.org
.. |documentation| image:: https://img.shields.io/badge/documentation-%E2%9C%93-success
:alt: (Rendered documentation on GitHub Pages)
:target: https://matrix-org.github.io/synapse/latest/
.. |license| image:: https://img.shields.io/github/license/matrix-org/synapse
:alt: (check license in LICENSE file)
:target: LICENSE
.. |pypi| image:: https://img.shields.io/pypi/v/matrix-synapse
:alt: (latest version released on PyPi)
:target: https://pypi.org/project/matrix-synapse
.. |python| image:: https://img.shields.io/pypi/pyversions/matrix-synapse
:alt: (supported python versions)
:target: https://pypi.org/project/matrix-synapse
标签：Ansible, Debian, Docker, Element, homeserver, Matrix, Matrix.org, Nginx, Python, Synapse, Twisted, VoIP, 协作工具, 即时通讯, 去中心化, 反向代理, 安全防御评估, 开源, 无后门, 服务器软件, 测试用例, 消息传递, 私有部署, 端到端加密, 聊天服务器, 联邦协议, 请求拦截, 逆向工具, 通信协议