- “黑客帝国”里的一切都发生在一个房间里。房间是分布式的，不存在于任何单个服务器上。可以使用方便的别名查找房间，例如
#matrix:matrix.org或#test:localhost:8448 - 矩阵用户ID如下所示
@matthew:matrix.org(尽管在将来，您通常会使用第三方标识符(3PID)来指代自己和他人：电子邮件地址、电话号码等，而不是操纵矩阵用户ID)
整体架构为：
client <----> homeserver <=====================> homeserver <----> client
https://somewhere.org/_matrix https://elsewhere.net/_matrix
#matrix:matrix.org是Matrix的官方支持室，任何客户端都可以从https://matrix.org/docs/projects/try-matrix-now.html或通过irc：//irc.Libera.chat/Matrix上的IRC桥
Synapse目前正处于快速开发阶段，但从0.5版开始，我们相信它已经足够稳定，可以作为面向互联网的服务真正使用！
About Matrix
Matrix指定一组实用的RESTful HTTP JSON API作为开放标准，它们处理：
- 创建和管理完全分布式的聊天室，没有单点控制或故障
- 跨联合服务器和服务的全球开放网络最终一致的密码安全的房间状态同步
- 在房间内使用(可选)端到端加密发送和接收可扩展消息
- 邀请、加入、离开、踢、禁止会议室成员
- 管理用户帐户(注册、登录、注销)
- 使用电子邮件地址、电话号码、Facebook帐户等第三方ID(3PID)验证、识别和发现Matrix上的用户
- 发出1：1 VoIP和视频呼叫
这些API旨在广泛的服务器、服务和客户端上实施，让开发人员在完全开放的Matrix生态系统之上构建消息传送和VoIP功能，而不是使用封闭或专有的解决方案。我们希望Matrix能成为新一代完全开放、可互操作的互联网消息传递和VoIP应用程序的基石
Synapse是由matrix.org的核心开发团队用Python/Twisted编写的Matrix的参考“本地服务器”实现。它的目的是展示Matrix的概念，让人们在代码库的上下文中查看规范，并让您运行自己的家庭服务器，通常帮助引导生态系统
在Matrix中，每个用户都运行一个或多个Matrix客户端，这些客户端连接到Matrix主服务器。家庭服务器存储他们所有的个人聊天历史记录和用户帐户信息-就像邮件客户端连接到IMAP/SMTP服务器一样。就像电子邮件一样，您可以运行自己的Matrix Home服务器并控制自己的通信和历史记录，也可以使用由其他人托管的服务器(例如matrix.org)-Matrix中没有单一控制点或强制服务提供商，这与WhatsApp、Facebook、Hangout等不同
我们邀请您加入#Matrix：matrix.org(通过https://matrix.org/docs/projects/try-matrix-now.html)，运行送货上门服务，看看Matrix spec，并尝试使用APIs和Client SDKs
感谢您使用Matrix！
Support
要获得安装或管理Synapse的支持，请加入#synapse:matrix.org(如果需要，可以从matrix.org帐户)并在那里提问。我们不将GitHub问题用于支持请求，仅用于错误报告和功能请求
Synapse Installation
- 有关如何安装synapse的详细信息，请参见Installation Instructions
- 有关如何为联合配置Synapse的特定详细信息，请参见docs/federate.md
Connecting to Synapse from a client
试用新的Synapse安装的最简单方法是从Web客户端连接到它
除非您在本地计算机上运行Synapse的测试实例，否则通常需要启用TLS支持，然后才能从客户端成功连接：请参见TLS certificates
一种简单的入门方法是通过Element登录或注册，地址为https://app.element.io/#/login或https://app.element.io/#/register分别为。您需要更改从其登录的服务器matrix.org并改为将Homeserver URL指定为https://<server_name>:8448(或仅https://<server_name>如果您正在使用反向代理)。如果您更喜欢使用其他客户端，请参阅我们的client breakdown
如果一切顺利，您至少应该能够登录、创建文件室并开始发送消息
Registering a new user from a client
默认情况下，禁用通过Matrix客户端注册新用户。要启用它，请指定enable_registration: true在……里面homeserver.yaml(然后建议还设置验证码-请参阅docs/CAPTCHA_SETUP.md)
一次enable_registration设置为true，则可以通过Matrix客户端注册用户
您的新用户名将部分由server_name，部分来自您在创建帐户时指定的本地部分。您的名字将采用以下形式：
@localpart:my.domain.name
(读作“at localpart on my dot domain dot name”)
与登录时一样，您需要指定“自定义服务器”。指定您需要的localpart在“用户名”框中
Security note
Matrix在某些API中提供用户提供的原始数据–具体地说，content
repository endpoints
虽然我们做出合理的努力来缓解XSS攻击(例如，通过使用CSP)，则Matrix主服务器不应托管在托管其他Web应用程序的域上。这尤其适用于与Matrix Web客户端和其他敏感应用程序(如WebMail)共享域。看见https://developer.github.com/changes/2014-04-25-user-content-security了解更多信息
理想情况下，主服务器不应该简单地位于不同的子域上，而应该位于完全不同的子域上registered domain(也称为顶级站点或eTLD+1)。这是因为some attacks只要这两个应用程序共享相同的注册域，仍然是可能的
为了举例说明这一点，如果您的Element Web或其他敏感的Web应用程序托管在A.example1.com，理想情况下，您应该将Synapse托管在example2.com通过在上托管可提供一定程度的保护B.example1.com相反，因此这在某些情况下也是可以接受的。但是，您应该不托管您的SynapseA.example1.com
请注意，以上所有内容仅指Synapse中使用的域public_baseurl设置。特别是，它对该服务器上托管的MXID中提到的域没有影响
遵循此建议可确保即使在Synapse中找到XSS，对其他应用程序的影响也将微乎其微
Upgrading an existing Synapse
升级synapse的说明在the upgrade notes请检查这些说明，因为某些版本的Synapse升级可能需要额外的步骤
Using a reverse proxy with Synapse
建议将反向代理(如nginx，Apache，Caddy，HAProxy或relayd在Synapse面前。这样做的一个好处是，这意味着您可以向Matrix客户端公开默认的https端口(443)，而无需使用root权限运行Synapse
有关配置的信息，请参见docs/reverse_proxy.md
Identity Servers
身份服务器负责将电子邮件地址和其他第三方ID(3PID)映射到矩阵用户ID，并在创建映射之前验证3PID的所有权
它们不是存储帐户或凭据的位置-它们位于家庭服务器上。身份服务器仅用于将第三方ID映射到矩阵ID
此过程对安全非常敏感，因为如果注册Matrix帐户或获取3PID数据太容易，则存在明显的垃圾邮件风险。长远来说，我们希望建立一个分散的系统来管理它(matrix-doc #712)，但同时，在Matrix生态系统中管理可信身份的角色被外包给一群已知的可信生态系统合作伙伴，这些合作伙伴运行“Matrix Identity Server”，例如Sydent，其角色纯粹是验证和跟踪3PID登录并发布最终用户公钥
您可以托管您自己的Sydent副本，但这将阻止您通过Matrix生态系统中的其他用户的电子邮件地址联系到他们，并阻止他们找到您。因此，我们建议您使用位于https://matrix.org或https://vector.im就目前而言
再次重申：仅当您选择将电子邮件地址与您的帐户相关联，或通过其他用户的电子邮件地址向其发送邀请时，才会使用身份服务器
Password reset
用户可以通过其客户端重置其密码。或者，服务器管理员可以使用admin API或者直接编辑数据库，如下所示
首先计算新密码的哈希：
$ ~/synapse/env/bin/hash_password Password: Confirm password: $2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
然后更新users数据库中的表：
UPDATE users SET password_hash='$2a$12$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
WHERE name='@test:test.com';
Synapse Development
在Matrix上加入我们的开发人员社区：#synapse-dev:matrix.org
在为synapse设置开发环境之前，请确保已安装系统依赖项(如python头文件)请参阅Installing from source
要签出用于开发的synapse，请将git存储库克隆到您选择的工作目录中：
git clone https://github.com/matrix-org/synapse.git cd synapse
Synapse有许多外部依赖项，最容易使用pip和viralenv进行安装：
python3 -m venv ./env source ./env/bin/activate pip install -e ".[all,test]"
这将运行下载所有需要的依赖项并将其安装到虚拟环境中的过程。如果任何依赖项安装失败，请尝试单独安装出现故障的模块：
pip install -e "module-name"
我们建议使用演示来启动在端口8080-8082上运行的3个联合实例
/demo/start.sh
(要停止，可以使用./demo/stop.sh)
如果您只想启动应用程序的单个实例并直接运行，请执行以下操作：
# Create the homeserver.yaml config once python -m synapse.app.homeserver \ --server-name my.domain.name \ --config-path homeserver.yaml \ --generate-config \ --report-stats=[yes|no] # Start the app python -m synapse.app.homeserver --config-path homeserver.yaml
Running the unit tests
在启动和运行之后，您可能希望运行Synapse的单元测试来检查一切是否安装正确：
trial tests
这应该以“通过”的结果结束(请注意，确切的数字会有所不同)：
Ran 1337 tests in 716.064s PASSED (skips=15, successes=1322)
有关运行单元测试的更多提示，如运行特定测试或查看日志记录输出，请参见CONTRIBUTING doc
Running the Integration Tests
Synapse伴随着SyTest作为Matrix本地服务器集成测试套件，它使用HTTP请求来访问API，就像Matrix客户端一样。它可以直接从源树运行Synapse，因此不需要安装服务器
建议使用SyTest进行测试，以验证与客户端-服务器API相关的更改是否正常运行。请参阅SyTest installation
instructions有关详细信息，请参阅
Platform dependencies
Synapse使用许多平台依赖项，如Python和PostgreSQL，目标是遵循受支持的上游版本。请参阅docs/deprecation_policy.md有关更多详细信息，请参阅文档
Troubleshooting
需要帮忙吗？在Matrix上加入我们的社区支持室：#synapse:matrix.org
Running out of File Handles
如果synapse用完了文件句柄，它通常会严重失败-100%CPU的实时锁定，和/或无法接受新的TCP连接(阻塞连接的客户端)。Matrix目前可以合法地使用大量文件句柄，这要归功于#Matrix：matrix.org这样包含数百个参与服务器的繁忙房间。当服务器第一次在房间中通话时，它将尝试同时连接到所有参与的服务器，这可能会耗尽DNS查询和HTTPS套接字之间的可用文件描述符，特别是在DNS响应较慢的情况下。(我们需要改进过去比全网状更好的路由算法，但截至2019年3月，这还没有发生)
如果您进入此故障模式，我们建议将打开文件句柄的最大数量增加到至少4096个(假设默认值为1024或256)。这通常通过编辑来完成/etc/security/limits.conf
另外，如果入站HTTP请求在处理过程中受阻，Synapse可能会泄漏文件句柄-例如，锁定后被阻塞或与远程服务器通信等。最佳诊断方法是匹配“已接收的请求”和“已处理的请求”日志行，并查找执行时间超过几秒钟的任何“已处理的请求”行。如果您看到此故障模式，请在#synapse：matrix.org上通知我们，以便我们可以帮助对其进行调试
Help!! Synapse is slow and eats all my RAM/CPU!
首先，确保您正在运行最新版本的Synapse，将Python 3与PostgreSQL数据库配合使用
Synapse的架构目前非常需要RAM-我们故意在RAM中缓存大量最近的房间数据和元数据，以加快常见请求的速度。我们将在将来改进这一点，但目前减少RAM使用(冒着放慢速度的风险)的最简单方法是将几乎没有文档记录的SYNAPSE_CACHE_FACTOR环境变量。默认值为0.5，可以减少内存受限环境中的RAM使用量，也可以在性能开始下降时增加此值
但是，由于缓存系数低而导致的性能下降(这在磁盘速度较慢的计算机上很常见)通常会导致由于积压的请求而导致内存使用量激增。在这种情况下，降低缓存因子会使情况变得更糟。取而代之的是，试着大幅增加它。2.0是个不错的起始值
使用libjemalloc还可以显著提高总体内存使用率，特别是在将RAM返还给操作系统方面。要使用它，只需在启动Synapse时将库放入LD_PRELOAD环境变量中即可。在Debian上，这可以通过安装libjemalloc1打包并将此行添加到/etc/default/matrix-synapse：
LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.1
这可能会对Python 2.7产生重大影响-目前还不清楚它对Python 3.x有多大改进
如果您遇到Synapse进程本身的高CPU使用率，您可能会受到状态跟踪错误的影响，该错误会导致大量过多的传出联合请求(请参见discussion)。如果指标表明您的服务器发出的传出联合请求也远远多于您的用户活动所能解释的数量，这可能是一个原因。通过在Synapse配置文件中设置以下内容，可以解决该错误行为：
presence:
enabled: falsePeople can’t accept room invitations from me
这里典型的失败模式是，您向某人发送加入房间或直接聊天的邀请，但当他们接受邀请时，他们会收到一个错误(通常类似于“无效签名”)。他们可能会在日志中看到类似以下内容：
2019-09-11 19:32:04,271 - synapse.federation.transport.server - 288 - WARNING - GET-11752 - authenticate_request failed: 401: Invalid signature for server <server> with key ed25519:a_EqML: Unable to verify signature for <server>
这通常是由反向代理中的错误配置引起的。看见docs/reverse_proxy.md并仔细检查您的设置是否正确
