{"id":13398383,"url":"https://github.com/matrix-org/synapse","last_synced_at":"2025-10-05T18:31:10.415Z","repository":{"id":19594365,"uuid":"22844864","full_name":"matrix-org/synapse","owner":"matrix-org","description":"Synapse: Matrix homeserver written in Python/Twisted.","archived":true,"fork":false,"pushed_at":"2023-12-14T07:12:07.000Z","size":431700,"stargazers_count":11748,"open_issues_count":1517,"forks_count":2131,"subscribers_count":246,"default_branch":"develop","last_synced_at":"2024-04-14T10:19:10.511Z","etag":null,"topics":["matrix-org","python"],"latest_commit_sha":null,"homepage":"https://matrix-org.github.io/synapse","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"matrixdotorg","liberapay":"matrixdotorg","custom":"https://paypal.me/matrixdotorg"}},"created_at":"2014-08-11T15:51:42.000Z","updated_at":"2024-04-26T16:55:49.994Z","dependencies_parsed_at":"2024-04-26T16:54:47.629Z","dependency_job_id":null,"html_url":"https://github.com/matrix-org/synapse","commit_stats":{"total_commits":18982,"total_committers":591,"mean_commits":32.11844331641286,"dds":0.7130966178484881,"last_synced_commit":"c14a7de6af0b8a3cbf2e17afca1cab339bc5912d"},"previous_names":[],"tags_count":672,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fsynapse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fsynapse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fsynapse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fsynapse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/synapse/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235432162,"owners_count":18989467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["matrix-org","python"],"created_at":"2024-07-30T19:00:24.397Z","updated_at":"2025-10-05T18:31:08.332Z","avatar_url":"https://github.com/matrix-org.png","language":"Python","readme":"=========================================================================\nSynapse |support| |development| |documentation| |license| |pypi| |python|\n=========================================================================\n\nSynapse is now actively maintained at `element-hq/synapse \u003chttps://github.com/element-hq/synapse\u003e`_\n=================================================================================================\n\nSynapse is an open-source `Matrix \u003chttps://matrix.org/\u003e`_ homeserver developed\nfrom 2019 through 2023 as part of the Matrix.org Foundation. The Matrix.org\nFoundation is not able to resource maintenance of Synapse and it\n`continues to be developed by Element \u003chttps://github.com/element-hq/synapse\u003e`_;\nadditionally you have the choice of `other Matrix homeservers \u003chttps://matrix.org/ecosystem/servers/\u003e`_.\n\nSee `The future of Synapse and Dendrite \u003chttps://matrix.org/blog/2023/11/06/future-of-synapse-dendrite/\u003e`_\nblog post for more information.\n\n=========================================================================\n\nBriefly, Matrix is an open standard for communications on the internet, supporting\nfederation, encryption and VoIP. Matrix.org has more to say about the `goals of the\nMatrix project \u003chttps://matrix.org/docs/guides/introduction\u003e`_, and the `formal specification\n\u003chttps://spec.matrix.org/\u003e`_ describes the technical details.\n\n.. contents::\n\nInstalling and configuration\n============================\n\nThe Synapse documentation describes `how to install Synapse \u003chttps://matrix-org.github.io/synapse/latest/setup/installation.html\u003e`_. We recommend using\n`Docker images \u003chttps://matrix-org.github.io/synapse/latest/setup/installation.html#docker-images-and-ansible-playbooks\u003e`_ or `Debian packages from Matrix.org\n\u003chttps://matrix-org.github.io/synapse/latest/setup/installation.html#matrixorg-packages\u003e`_.\n\n.. _federation:\n\nSynapse has a variety of `config options\n\u003chttps://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html\u003e`_\nwhich can be used to customise its behaviour after installation.\nThere are additional details on how to `configure Synapse for federation here\n\u003chttps://matrix-org.github.io/synapse/latest/federate.html\u003e`_.\n\n.. _reverse-proxy:\n\nUsing a reverse proxy with Synapse\n----------------------------------\n\nIt is recommended to put a reverse proxy such as\n`nginx \u003chttps://nginx.org/en/docs/http/ngx_http_proxy_module.html\u003e`_,\n`Apache \u003chttps://httpd.apache.org/docs/current/mod/mod_proxy_http.html\u003e`_,\n`Caddy \u003chttps://caddyserver.com/docs/quick-starts/reverse-proxy\u003e`_,\n`HAProxy \u003chttps://www.haproxy.org/\u003e`_ or\n`relayd \u003chttps://man.openbsd.org/relayd.8\u003e`_ in front of Synapse. One advantage of\ndoing so is that it means that you can expose the default https port (443) to\nMatrix clients without needing to run Synapse with root privileges.\nFor information on configuring one, see `the reverse proxy docs\n\u003chttps://matrix-org.github.io/synapse/latest/reverse_proxy.html\u003e`_.\n\nUpgrading an existing Synapse\n-----------------------------\n\nThe instructions for upgrading Synapse are in `the upgrade notes`_.\nPlease check these instructions as upgrading may require extra steps for some\nversions of Synapse.\n\n.. _the upgrade notes: https://matrix-org.github.io/synapse/develop/upgrade.html\n\n\nPlatform dependencies\n---------------------\n\nSynapse uses a number of platform dependencies such as Python and PostgreSQL,\nand aims to follow supported upstream versions. See the\n`deprecation policy \u003chttps://matrix-org.github.io/synapse/latest/deprecation_policy.html\u003e`_\nfor more details.\n\n\nSecurity note\n-------------\n\nMatrix serves raw, user-supplied data in some APIs -- specifically the `content\nrepository endpoints`_.\n\n.. _content repository endpoints: https://matrix.org/docs/spec/client_server/latest.html#get-matrix-media-r0-download-servername-mediaid\n\nWhilst we make a reasonable effort to mitigate against XSS attacks (for\ninstance, by using `CSP`_), a Matrix homeserver should not be hosted on a\ndomain hosting other web applications. This especially applies to sharing\nthe domain with Matrix web clients and other sensitive applications like\nwebmail. See\nhttps://developer.github.com/changes/2014-04-25-user-content-security for more\ninformation.\n\n.. _CSP: https://github.com/matrix-org/synapse/pull/1021\n\nIdeally, the homeserver should not simply be on a different subdomain, but on\na completely different `registered domain`_ (also known as top-level site or\neTLD+1). This is because `some attacks`_ are still possible as long as the two\napplications share the same registered domain.\n\n.. _registered domain: https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-2.3\n\n.. _some attacks: https://en.wikipedia.org/wiki/Session_fixation#Attacks_using_cross-subdomain_cookie\n\nTo illustrate this with an example, if your Element Web or other sensitive web\napplication is hosted on ``A.example1.com``, you should ideally host Synapse on\n``example2.com``. Some amount of protection is offered by hosting on\n``B.example1.com`` instead, so this is also acceptable in some scenarios.\nHowever, you should *not* host your Synapse on ``A.example1.com``.\n\nNote that all of the above refers exclusively to the domain used in Synapse's\n``public_baseurl`` setting. In particular, it has no bearing on the domain\nmentioned in MXIDs hosted on that server.\n\nFollowing this advice ensures that even if an XSS is found in Synapse, the\nimpact to other applications will be minimal.\n\n\nTesting a new installation\n==========================\n\nThe easiest way to try out your new Synapse installation is by connecting to it\nfrom a web client.\n\nUnless you are running a test instance of Synapse on your local machine, in\ngeneral, you will need to enable TLS support before you can successfully\nconnect from a client: see\n`TLS certificates \u003chttps://matrix-org.github.io/synapse/latest/setup/installation.html#tls-certificates\u003e`_.\n\nAn easy way to get started is to login or register via Element at\nhttps://app.element.io/#/login or https://app.element.io/#/register respectively.\nYou will need to change the server you are logging into from ``matrix.org``\nand instead specify a Homeserver URL of ``https://\u003cserver_name\u003e:8448``\n(or just ``https://\u003cserver_name\u003e`` if you are using a reverse proxy).\nIf you prefer to use another client, refer to our\n`client breakdown \u003chttps://matrix.org/ecosystem/clients/\u003e`_.\n\nIf all goes well you should at least be able to log in, create a room, and\nstart sending messages.\n\n.. _`client-user-reg`:\n\nRegistering a new user from a client\n------------------------------------\n\nBy default, registration of new users via Matrix clients is disabled. To enable\nit:\n\n1. In the\n   `registration config section \u003chttps://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#registration\u003e`_\n   set ``enable_registration: true`` in ``homeserver.yaml``.\n2. Then **either**:\n\n   a. set up a `CAPTCHA \u003chttps://matrix-org.github.io/synapse/latest/CAPTCHA_SETUP.html\u003e`_, or\n   b. set ``enable_registration_without_verification: true`` in ``homeserver.yaml``.\n\nWe **strongly** recommend using a CAPTCHA, particularly if your homeserver is exposed to\nthe public internet. Without it, anyone can freely register accounts on your homeserver.\nThis can be exploited by attackers to create spambots targetting the rest of the Matrix\nfederation.\n\nYour new user name will be formed partly from the ``server_name``, and partly\nfrom a localpart you specify when you create the account. Your name will take\nthe form of::\n\n    @localpart:my.domain.name\n\n(pronounced \"at localpart on my dot domain dot name\").\n\nAs when logging in, you will need to specify a \"Custom server\".  Specify your\ndesired ``localpart`` in the 'User name' box.\n\nTroubleshooting and support\n===========================\n\nThe `Admin FAQ \u003chttps://matrix-org.github.io/synapse/latest/usage/administration/admin_faq.html\u003e`_\nincludes tips on dealing with some common problems. For more details, see\n`Synapse's wider documentation \u003chttps://matrix-org.github.io/synapse/latest/\u003e`_.\n\nFor additional support installing or managing Synapse, please ask in the community\nsupport room |room|_ (from a matrix.org account if necessary). We do not use GitHub\nissues for support requests, only for bug reports and feature requests.\n\n.. |room| replace:: ``#synapse:matrix.org``\n.. _room: https://matrix.to/#/#synapse:matrix.org\n\n.. |docs| replace:: ``docs``\n.. _docs: docs\n\nIdentity Servers\n================\n\nIdentity servers have the job of mapping email addresses and other 3rd Party\nIDs (3PIDs) to Matrix user IDs, as well as verifying the ownership of 3PIDs\nbefore creating that mapping.\n\n**They are not where accounts or credentials are stored - these live on home\nservers. Identity Servers are just for mapping 3rd party IDs to matrix IDs.**\n\nThis process is very security-sensitive, as there is obvious risk of spam if it\nis too easy to sign up for Matrix accounts or harvest 3PID data. In the longer\nterm, we hope to create a decentralised system to manage it (`matrix-doc #712\n\u003chttps://github.com/matrix-org/matrix-doc/issues/712\u003e`_), but in the meantime,\nthe role of managing trusted identity in the Matrix ecosystem is farmed out to\na cluster of known trusted ecosystem partners, who run 'Matrix Identity\nServers' such as `Sydent \u003chttps://github.com/matrix-org/sydent\u003e`_, whose role\nis purely to authenticate and track 3PID logins and publish end-user public\nkeys.\n\nYou can host your own copy of Sydent, but this will prevent you reaching other\nusers in the Matrix ecosystem via their email address, and prevent them finding\nyou. We therefore recommend that you use one of the centralised identity servers\nat ``https://matrix.org`` or ``https://vector.im`` for now.\n\nTo reiterate: the Identity server will only be used if you choose to associate\nan email address with your account, or send an invite to another user via their\nemail address.\n\n\nDevelopment\n===========\n\nWe welcome contributions to Synapse from the community!\nThe best place to get started is our\n`guide for contributors \u003chttps://matrix-org.github.io/synapse/latest/development/contributing_guide.html\u003e`_.\nThis is part of our larger `documentation \u003chttps://matrix-org.github.io/synapse/latest\u003e`_, which includes\n\ninformation for Synapse developers as well as Synapse administrators.\nDevelopers might be particularly interested in:\n\n* `Synapse's database schema \u003chttps://matrix-org.github.io/synapse/latest/development/database_schema.html\u003e`_,\n* `notes on Synapse's implementation details \u003chttps://matrix-org.github.io/synapse/latest/development/internal_documentation/index.html\u003e`_, and\n* `how we use git \u003chttps://matrix-org.github.io/synapse/latest/development/git.html\u003e`_.\n\nAlongside all that, join our developer community on Matrix:\n`#synapse-dev:matrix.org \u003chttps://matrix.to/#/#synapse-dev:matrix.org\u003e`_, featuring real humans!\n\n\n.. |support| image:: https://img.shields.io/matrix/synapse:matrix.org?label=support\u0026logo=matrix\n  :alt: (get support on #synapse:matrix.org)\n  :target: https://matrix.to/#/#synapse:matrix.org\n\n.. |development| image:: https://img.shields.io/matrix/synapse-dev:matrix.org?label=development\u0026logo=matrix\n  :alt: (discuss development on #synapse-dev:matrix.org)\n  :target: https://matrix.to/#/#synapse-dev:matrix.org\n\n.. |documentation| image:: https://img.shields.io/badge/documentation-%E2%9C%93-success\n  :alt: (Rendered documentation on GitHub Pages)\n  :target: https://matrix-org.github.io/synapse/latest/\n\n.. |license| image:: https://img.shields.io/github/license/matrix-org/synapse\n  :alt: (check license in LICENSE file)\n  :target: LICENSE\n\n.. |pypi| image:: https://img.shields.io/pypi/v/matrix-synapse\n  :alt: (latest version released on PyPi)\n  :target: https://pypi.org/project/matrix-synapse\n\n.. |python| image:: https://img.shields.io/pypi/pyversions/matrix-synapse\n  :alt: (supported python versions)\n  :target: https://pypi.org/project/matrix-synapse\n","funding_links":["https://patreon.com/matrixdotorg","https://liberapay.com/matrixdotorg","https://paypal.me/matrixdotorg"],"categories":["Python","\u003ca id=\"tag-communication\" href=\"#tag-communication\"\u003eCommunication\u003c/a\u003e","Servers","Related projects","HarmonyOS","python","后端开发框架及项目","Apps","Communication"],"sub_categories":["2016","Other services","Windows Manager","管理面板","Communication"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fsynapse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fsynapse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fsynapse/lists"}