SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-28

Matrix Synapse VPS 自架與長期維護指南

了解在 VPS 長期維持 Matrix Synapse homeserver 所需的配置,包含 1 vCPU、2 GB RAM 的限制、Postgres、media store 清理、註冊防護與雙重備份。

維持 Matrix Synapse homeserver 運作所需的工作

Matrix Synapse 容易安裝,也容易被忽略。安裝只需要加入一個 apt repository、建立一個設定檔、設定一個 reverse proxy 區塊,以及建立一筆 DNS 記錄。讓 homeserver 穩定運作一年則是另一回事:需要使用正式的資料庫、定期清理 media store、限制陌生人註冊,並建立同時涵蓋伺服器兩個部分的備份。

本指南以 Ubuntu 24.04 LTS 為目標,並從 matrix.org apt repository 安裝 Synapse。這是 Synapse 專案為 Debian 和 Ubuntu 維護的套件來源。套件版本每隔幾週就會變更,因此本文不列出版本號。以下所有路徑與選項均來自目前的 Synapse 文件。

Sizing:1 vCPU 和 2 GB RAM 實際能支援什麼

截至 August 2026,已發布的 sizing 頁面通常建議 Synapse homeserver 使用 1 vCPU 和 2 GB RAM。這個建議只適用於一種情況:私人伺服器、少數使用者、小型聊天室,且沒有繁忙的公開聊天室。Synapse 文件也明確說明另一種情況:如果要加入大型公開聊天室,例如 #matrix:matrix.org,「至少需要 1GB 的可用 RAM」。這裡的可用 RAM 是在 Python、Postgres 和 kernel 之外額外需要的記憶體。

加入聊天室的運作方式可能改變 sizing,單一聊天室就足以造成影響。當本機使用者加入聊天室時,homeserver 會成為該聊天室的完整參與者。它會從聊天室中的其他伺服器接收每個事件、驗證每個事件的簽章,並在本機儲存聊天室狀態。大型公開聊天室有數千名成員,分布在數百台伺服器上,因此即使使用者之後不再開啟該聊天室,伺服器仍會持續處理這些工作。之後離開聊天室,也不會刪除已儲存的歷史記錄。

Synapse 的大部分 RAM 用於快取。caches section 包含一個 global_factor,可同時調整所有快取,而 SYNAPSE_CACHE_FACTOR environment variable 會設定相同的值。提高該值會使用更多 RAM,以避免執行資料庫查詢。降低該值則會增加 CPU 和 Postgres 的負載,以節省 RAM。Postgres 也需要自己的記憶體,因此在 2 GB 的伺服器上,兩者會爭用相同的記憶體容量。

對小型方案而言,有兩項實用規則。加入 swap:swap 不會讓 Synapse 變快,但可避免 kernel 在大型加入作業期間終止該程序。接著從第一週開始監控磁碟,因為會無限制增長的兩項內容是 media store 和 room state tables,而且兩者都儲存在磁碟上。

為什麼選擇 Postgres,以及 SQLite 為何不再適用

Debian 套件會從 SQLite 開始使用。這對第一次啟動而言沒有問題,但不適合供其他人使用的伺服器。SQLite 同一時間只允許一個寫入者。聯邦流量與用戶端請求可能同時寫入,因此速度較慢的請求會阻塞其他低成本請求。使用者回報的症狀通常是應用程式偶爾停頓幾秒。

第二個原因是架構限制。Synapse 的 worker processes 是使用多個 CPU 核心的支援方式,而 workers 需要 Postgres。繼續使用 SQLite 不僅會犧牲效能,也會失去後續擴充的升級路徑。

之後再遷移仍受支援,但會造成停機,因此應在有使用者之前完成。Synapse 隨附 synapse_port_db,可將 SQLite 資料庫複製到已準備好的 Postgres 資料庫:

synapse_port_db --sqlite-database homeserver.db --postgres-config homeserver-postgres.yaml

如果您想在 Synapse 旁的容器中執行資料庫,請參閱在 Docker 或主機上執行資料庫,瞭解其中的取捨。

在 Ubuntu 24.04 上安裝 Synapse

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

在 Ubuntu 24.04 上,lsb_release -cs會輸出noble,而 matrix.org repository 提供noble套件。請勿使用 Ubuntu 自有 archive 中的matrix-synapse套件。Synapse project 不建議使用該套件,因為這些 build 落後於其 releases,且包含已知的 security bugs。

installer 會要求輸入 server name,並將答案寫入/etc/matrix-synapse/conf.d/server_name.yaml。請仔細輸入。server_name是每個 user ID(@alice:example.com)中冒號後面的部分,也會嵌入 server 建立的每個 room。之後變更此值不會搬移任何內容,而是建立不同的 homeserver。請使用不含主機名稱的網域example.com,即使 Synapse 本身會在matrix.example.com上執行。delegation 會連結兩者,下一節將說明這項設定。

套件會以matrix-synapse使用者執行 Synapse,將資料放在/var/lib/matrix-synapse下,並讀取/etc/matrix-synapse/homeserver.yaml,接著讀取/etc/matrix-synapse/conf.d/中的每個檔案。請將自訂設定放在conf.d中的小型檔案裡。套件升級不會修改這些檔案。

sudo systemctl restart matrix-synapse
systemctl status matrix-synapse
sudo journalctl -u matrix-synapse -n 100 --no-pager

正常啟動時,監聽器會先啟動,之後不再輸出訊息。systemd unit 會在服務結束數秒後重新啟動,因此 Synapse 拒絕的設定會讓 unit 持續啟動後立即結束。journal 的最後幾行會指出它拒絕的 key。

將 Synapse 指向 Postgres

sudo apt install -y postgresql
sudo -u postgres createuser --pwprompt synapse_user
sudo -u postgres createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user synapse

locale 並非僅供顯示。除非在資料庫設定中設定 allow_unsafe_locale,否則 Synapse 無法使用以不同 COLLATE 和 CTYPE 值建立的資料庫啟動。之後的文件化修復方式,是將資料庫傾印後重新載入至正確建立的資料庫。請在第一次建立時就設定正確。

database:
  name: psycopg2
  txn_limit: 10000
  args:
    user: synapse_user
    password: secretpassword
    dbname: synapse
    host: localhost
    port: 5432
    cp_min: 5
    cp_max: 10

所有設定檔中只能保留一個 database: 金鑰。請取代 homeserver.yaml 內的 SQLite 區塊,不要在 conf.d 下方再加入第二份設定。如此便不會有設定檔實際採用哪一份的疑問。重新啟動後,確認 Synapse 確實使用 Postgres:

sudo -u postgres psql synapse -c "SELECT count(*) FROM users;"

若輸出數字,表示 Synapse 已在此資料庫中建立結構。若出現找不到 relation 的錯誤,表示它仍在寫入 SQLite 檔案,因此你編輯的設定檔不是實際讀取的檔案。

反向代理、TLS 與 federation 所需的 .well-known 檔案

Synapse 以純 HTTP 監聽 8008 埠,並繫結至 localhost。TLS 與公開連接埠應由前端的反向代理處理。

listeners:
- port: 8008
  tls: false
  type: http
  x_forwarded: true
  bind_addresses:
  - '::1'
  - '127.0.0.1'
  resources:
  - names:
    - client
    - federation
    compress: false

x_forwarded: true 會告知 Synapse 信任代理所設定的 X-Forwarded-For 標頭。若未設定,所有用戶端看起來都來自 127.0.0.1。如此一來,速率限制會將所有請求視為來自同一個極度繁忙的本機使用者,並一併限制所有人。

location ~ ^(/_matrix|/_synapse/client) {
    proxy_pass http://localhost:8008;
    proxy_set_header X-Forwarded-For $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Host $host:$server_port;
    client_max_body_size 50M;
    proxy_http_version 1.1;
}

Synapse 文件針對這個區塊有一項警告,許多人因此浪費數天排查問題。不要在 proxy_pass 的埠號後加入路徑,即使只是單一個 / 也不行。nginx 接著會將 URI 正規化,導致傳送端簽署的位元組內容改變。federation 請求會因此無法通過簽章驗證,但一般用戶端請求仍可正常運作。

client_max_body_size 必須至少與 Synapse 的 max_upload_size 一樣大。若 nginx 設定的值較小,超過該限制的上傳會先由 nginx 以 413 Request Entity Too Large 拒絕,Synapse 根本不會收到請求,因此 Synapse 日誌中不會留下可用來說明問題的訊息。

憑證本身請參閱 在 Ubuntu 24.04 上使用 Certbot 與 Let's Encrypt。若尚未決定使用哪個代理,反向代理比較會說明由哪個代理負責 TLS。

委派機制可讓 server_name 維持 example.com,同時讓 Synapse 執行於 matrix.example.com。請從裸網域提供以下兩個檔案:

location /.well-known/matrix/server {
    default_type application/json;
    return 200 '{"m.server": "matrix.example.com:443"}';
}

location /.well-known/matrix/client {
    default_type application/json;
    add_header Access-Control-Allow-Origin '*';
    return 200 '{"m.homeserver": {"base_url": "https://matrix.example.com"}}';
}

伺服器檔案會告知其他 homeserver federation 流量應傳送至何處。如此 federation 就能使用 443,而非預設的 8448 埠。用戶端檔案會告知 Matrix 用戶端哪個 URL 提供 @alice:example.com。用戶端檔案中的 Access-Control-Allow-Origin 標頭很重要,因為以瀏覽器為基礎的用戶端會跨來源擷取該檔案。若沒有此標頭,瀏覽器會封鎖回應,用戶端也會回報找不到你的 homeserver。

兩個檔案都必須由 example.com 本身透過有效的 TLS 提供。先檢查檔案,再檢查外部網路看到的內容:

curl -s https://example.com/.well-known/matrix/server
curl -s https://matrix.example.com/_matrix/federation/v1/version

第一個指令會回傳你撰寫的 JSON。第二個指令會回傳包含伺服器實作及其版本的 JSON 物件,證明代理能透過 federation 路徑連線至 Synapse。接著,使用 https://federationtester.matrix.org 的 Matrix federation tester 測試該網域。這項工具會遵循實際遠端伺服器所使用的相同路徑。

是否啟用 Federation:有意識地做出決定

Federation 是 Matrix 的核心功能,也是主要成本來源。啟用 Federation 的 homeserver 會接受來自陌生伺服器的連線、接收其事件、快取其媒體,並儲存使用者加入之每個房間的狀態。這是威脅模型的決策,不應視為預設設定。

當使用者需要與其他 homeserver 上的人員互通,或可攜式身分是選用 Matrix 的原因時,請啟用 Federation。若伺服器只供單一團隊使用,且其上的所有帳號都由你管理,則不要啟用 Federation。封閉式伺服器需要儲存的資料較少、接收的資料較少,也不易成為濫用目標。

若要限制而不是停用,Synapse 支援允許清單:

federation_domain_whitelist:
- lon.example.com
- nyc.example.com

文件也建議一併在防火牆封鎖 Federation listener,讓不需要的流量在網路層停止,而不是進入 Python 後才處理。若要完全關閉 Federation,將相同選項設為空清單:

federation_domain_whitelist: []

Synapse 設定手冊將空清單列為停用 Federation 的建議方式,Element 說明中心也提供相同設定。Federation 預設為啟用,因為未設定此選項時會允許所有伺服器。從 listener 的 resources 清單移除 federation、不發布 /.well-known/matrix/server,並保持連接埠 8448 關閉,只能阻止輸入的 Federation 流量抵達 Synapse。這些設定無法阻止伺服器發出輸出的 Federation 請求,因此應將它們與防火牆視為空清單之外的額外防護層,不能取代空清單。

如果執行 Matrix 的原因是提供私有團隊聊天,而 Federation 從未列入需求,請先將執行成本與其他 自架 Slack 替代方案比較,再決定是否採用 Synapse。使用 Docker Compose 執行 Rocket.Chat即可在較小的機器上提供團隊聊天,因為它不必儲存其他組織的房間狀態。

媒體儲存庫會在背景中悄悄填滿磁碟

使用者自行上傳的檔案會永久留在你的磁碟上。其他 homeserver 的使用者發布檔案後,只要你的某個用戶端顯示這些檔案,Synapse 就會將它們擷取並快取到你的磁碟上。Synapse 也會為圖片產生縮圖,因此一張照片會變成多個檔案。預設不會自動讓任何檔案過期。

先找出儲存位置並測量其大小:

grep media_store_path /etc/matrix-synapse/homeserver.yaml
sudo du -sh /var/lib/matrix-synapse/media_store

測量你自己的設定所輸出的路徑。Debian 套件會將 Synapse 的資料存放在 /var/lib/matrix-synapse 下,因此儲存庫通常就在該位置。接著在 conf.d 中設定保留政策:

media_retention:
  local_media_lifetime: 90d
  remote_media_lifetime: 14d

請仔細閱讀這兩行,因為它們不是同一類型的設定。兩者計算的都是檔案上次存取後經過的時間,不是檔案上傳後經過的時間。remote_media_lifetime 會讓快取過期;刪除的內容之後仍可從擁有該檔案的伺服器重新擷取。local_media_lifetime 則會在檔案長時間未被存取後,永久刪除你自己的使用者所上傳的媒體。若團隊在聊天室中共用文件,並預期明年仍能找到這些文件,就會遺失這些內容。許多伺服器只設定遠端媒體的值。

若要執行一次性清理,管理 API 接受以毫秒表示的 Unix 時間戳記:

BEFORE_TS=$(date -d '30 days ago' +%s%3N)
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  "https://matrix.example.com/_synapse/admin/v1/purge_media_cache?before_ts=$BEFORE_TS"

POST /_synapse/admin/v1/purge_media_cache 會捨棄在該時間戳記之前最後存取的遠端媒體快取。POST /_synapse/admin/v1/media/delete?before_ts=<ms> 會依相同規則刪除本機媒體。先執行遠端清理,再次測量大小,因為在支援聯邦的伺服器上,遠端快取通常占較大部分。

兩項設定都會影響同一個磁碟。max_upload_size 限制單一上傳檔案的大小,且必須與 nginx 中的 client_max_body_size 保持一致。url_preview_enabled: true 會讓你的伺服器擷取遠端頁面,讓用戶端顯示連結預覽;這會消耗頻寬,並儲存由你以外的使用者發布之內容的縮圖。

在有人找到你的 homeserver 前關閉註冊

掃描器只需幾天就能找到開放的 homeserver。帳號一旦可自由建立,你的伺服器就會成為與它進行聯邦連線的每個聊天室中的垃圾訊息來源,對方的管理員也會封鎖你的整個網域。這項聲譽損害會持續到清理作業之後,因為封鎖清單是人工維護的。

Synapse 預設會關閉註冊。enable_registration 預設為 false,而 registration_requires_token 預設為 false。如果啟用註冊卻未設定驗證步驟,Synapse 也會拒絕啟動;除非你另外設定 enable_registration_without_verification: true。這項拒絕是刻意設計的,因此不要啟用 enable_registration_without_verification 來消除啟動錯誤。

手動建立所需的帳號:

sudo register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008

程式會提示你輸入使用者名稱、密碼,以及該帳號是否為伺服器管理員。它會從你透過 -c 傳入的設定檔讀取 registration_shared_secret;如果顯示找不到 shared secret,請將 -c 指向存放該 secret 的檔案。

手動建立帳號無法再因應規模時,可改用註冊 token。Token 是新使用者註冊時必須提供的字串,每個 token 都能設定可使用的次數上限:

enable_registration: true
registration_requires_token: true
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"uses_allowed": 1}' \
  https://matrix.example.com/_synapse/admin/v1/registration_tokens/new

在命令內容中省略 token,Synapse 就會產生一個 token 並回傳。GET /_synapse/admin/v1/registration_tokens 會列出所有 token,包括已過期或已用完的 token。加入 ?valid=true 後,只會顯示仍可使用的 token。這兩個呼叫都需要伺服器管理員帳號的 access token;你可以使用上方建立的管理員使用者登入來取得。

已在其他位置管理帳號的組織,可以完全略過本機密碼,因為 Synapse 能將登入委派給 OIDC(OpenID Connect)provider,例如 以 Authentik 自架 SSO provider。之後,加入者與離職者都能在同一處管理。

能實際重建伺服器的備份

Synapse 備份包含 3 個部分,缺少任何一個部分,還原出的伺服器都無法正常使用。

  • Postgres 資料庫,其中儲存所有事件、帳戶與房間。
  • media store 目錄,其中儲存所有上傳的檔案。
  • /etc/matrix-synapse,其中儲存設定與伺服器的 signing key。

最容易被遺漏的是 signing key。這是 homeserver 用來簽署事件的私密金鑰,遠端伺服器會使用相符的公開金鑰驗證事件。執行 grep signing_key_path /etc/matrix-synapse/homeserver.yaml 查看金鑰的位置。遺失金鑰後,還原出的伺服器將無法證明自己就是房間原本認得的那台伺服器。

sudo -u postgres pg_dump --format=custom --file=/var/backups/synapse-$(date +%F).dump synapse
sudo tar czf /var/backups/synapse-etc-$(date +%F).tgz -C /etc matrix-synapse

先傾印資料庫,再複製 media store。媒體檔案只會寫入一次,並以 ID 建立參照,因此在傾印後執行的媒體複製只可能包含額外檔案,不會遺漏檔案。若順序相反,還原後的資料庫可能會指向備份中未擷取的檔案。

將這 3 個部分全部備份到 VPS 之外的位置。使用具有異地快照的 restic 很適合這種架構,因為 media store 是較大的部分,且各次執行之間幾乎不會變動,所以 deduplication 能讓每個 snapshot 保持較小。

接著演練還原流程,因為從未還原過的備份只是假設。建立第 2 台 VPS,安裝相同套件,還原設定,使用相同的 encoding 與 locale 建立資料庫,將傾印檔 pg_restore 到資料庫,還原 media store,然後登入。記錄所需時間。這個數字才是實際的復原時間。

狀態表持續增長時:壓縮

Synapse 會將房間狀態儲存為狀態群組。在聯邦伺服器上,state_groups_state 通常會成為資料庫中最大的物件。變更任何設定前,先進行測量:

sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_database_size('synapse'));"
sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_total_relation_size('state_groups_state'));"

如果該資料表佔資料庫容量的大部分,專案提供了專用的壓縮工具 rust-synapse-compress-state。這個工具會將狀態群組階層重新寫入較少的資料列,但不會改變任何房間狀態的意義。它以 Rust 建置:

sudo apt install -y build-essential libssl-dev pkg-config git
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/matrix-org/rust-synapse-compress-state.git
cd rust-synapse-compress-state/synapse_auto_compressor
cargo build --release
./target/release/synapse_auto_compressor -p postgresql://synapse_user:secretpassword@localhost/synapse -c 500 -n 100

-c 是每次處理的狀態群組數量,-n 則是本次執行處理的區塊數量。自動壓縮工具會記錄處理進度,因此下一次執行時會從上次的位置繼續。這也是它適合排程執行的原因。專案 README 說明 state_groups 與 state_groups_state 僅供附加,且變更會在交易中執行,因此 Synapse 執行期間套用其 SQL 是安全的。不過,這項說明位於 README 的簡介,而不是自動壓縮工具自己的段落中。因此,無論如何,第一次執行前都應先備份資料庫。

這裡有一項 Postgres 細節容易讓人意外。刪除資料列後,釋出的空間會交還 Postgres 重複使用,而不是交還給檔案系統。因此,大量壓縮後,df 可能完全不會變小。VACUUM FULL 才會將空間交還給檔案系統,而且會對資料表取得獨佔鎖定,並需要約等同於該資料表大小的可用磁碟空間。因此,應將它排程為維護作業,不要在沒有規劃的情況下執行。

確認伺服器運作正常的檢查項目

systemctl status matrix-synapse
curl -s https://example.com/.well-known/matrix/server
curl -s https://matrix.example.com/_matrix/federation/v1/version
sudo -u postgres psql synapse -c "SELECT pg_size_pretty(pg_database_size('synapse'));"
sudo du -sh /var/lib/matrix-synapse/media_store

運作正常表示服務單元處於 active 狀態且未反覆重新啟動、delegation 檔案回傳您的 m.server 值、federation 版本端點回傳 JSON,並且可將兩個大小數值與上個月的數值比較。大小檢查最容易被跳過,而磁碟問題會在毫無警告的情況下使 Synapse 伺服器停止運作:磁碟區填滿後,Postgres 無法寫入,Synapse 也就無法處理所有需要存取資料庫的請求。

FAQ

Matrix Synapse 伺服器需要多少 RAM?

對於只有少數使用者、小型房間且沒有大型公開房間的私人 homeserver,2 GB 通常足夠。這也是截至 August 2026,多數已發布的容量規劃頁面所建議的配置。若使用者會加入 #matrix:matrix.org 等大型公開房間,Synapse 文件要求除了其他需求外,至少保留 1 GB 可用 RAM,因為伺服器會儲存該房間的狀態,並持續處理其網路流量。在 2 GB 方案上加入 swap,避免單次大型加入操作導致 kernel 終止程序。

我必須使用 PostgreSQL,而不能使用 SQLite 嗎?

使用者超過少數幾名後,是的。SQLite 同一時間只能有一個寫入者,因此 federation 流量與用戶端請求在高負載下會互相阻塞,請求也可能一次停滯數秒。Synapse 的 worker process 是使用多個 CPU core 的支援方式,而這需要 Postgres。之後仍可使用 synapse_port_db 進行遷移,但會造成停機,因此應在有使用者前,先使用 --encoding=UTF8 --locale=C --template=template0 建立資料庫。

為什麼我的 Synapse 磁碟使用量持續增加?

問題主要在一個目錄和一個資料表。media store 會保留伺服器所在房間中上傳的每個檔案,包括遠端使用者媒體的快取副本與產生的縮圖;除非設定 media_retention,否則這些資料不會過期。對使用 federation 的伺服器而言,state_groups_state 資料表會隨房間狀態增加,而 rust-synapse-compress-state 可予以縮減。在決定要處理哪一項前,先使用 du -sh 測量 media_store_path,並使用 SELECT pg_size_pretty(pg_total_relation_size('state_groups_state')); 測量另一項。

如何阻止陌生人在我的 homeserver 上註冊?

保留 enable_registration 的預設值 false,並使用 register_new_matrix_user 建立帳戶。當這種方式無法擴展時,同時設定 enable_registration: true 和 registration_requires_token: true,再發放透過 POST /_synapse/admin/v1/registration_tokens/new 建立的 token。不要只為了消除 Synapse 拒絕啟動的訊息而設定 enable_registration_without_verification: true,因為開放的 homeserver 會成為垃圾訊息來源,其他管理員也可能因此封鎖你的整個網域。

我的 homeserver 應該使用 federation 嗎?

Federation 是暴露範圍的決策,不應視為預設設定。如果使用者需要聯絡其他 homeserver 上的人員,就啟用 federation。如果伺服器只服務一個團隊,則使用 federation_domain_whitelist: [] 關閉 federation,因為不使用 federation 的伺服器儲存量較少、接收的流量較少,也較不容易遭受濫用。在兩者之間,federation_domain_whitelist 可將 federation 限制為指定的合作夥伴網域;Synapse 文件也建議一併對 federation listener 設定防火牆規則,不要只依賴應用程式層的檢查。

這篇文章對您有幫助嗎?

#matrix#synapse#self-hosting#postgresql#federation