SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor

Zitadel Docker VPS 自行代管設定與升級

Zitadel 本身約需 512 MB RAM,本文示範在單一 VPS 設定 PostgreSQL、masterkey、TLS、SMTP 與備份,並說明升級對資料庫的影響。

在 VPS 上自行代管 Zitadel 的必要條件

若要在 VPS 上自行代管 Zitadel,您需要 Docker 主機、指向該主機的公開 DNS 名稱、PostgreSQL,以及足以同時執行這些元件的 CPU 和 RAM。Zitadel 的正式環境指南指出,應用程式本身約需 512 MB RAM,且 CPU 使用量低於 1 個核心。會持續增加需求的是資料庫與密碼雜湊。Zitadel 是身分提供者。它透過 OIDC (OpenID Connect) 和 SAML (security assertion markup language) 發行 token,讓其他服務不必各自維護使用者清單。安裝內容是 curl 和 docker compose up。決定系統能否穩定運作的項目包括 masterkey、資料庫使用者、SMTP (simple mail transfer protocol)、備份,以及第一次升級。

以下內容假設使用 Ubuntu 24.04、含 Compose plugin 2.24.4 或更新版本的 Docker Engine 24 或更新版本,並且已有類似 auth.example.com 的名稱解析至該伺服器。TLS overlay 使用 !override,因此需要上述 Compose 版本。

Zitadel 需要多少 VPS 資源?

Zitadel 文件中的 Compose 快速入門指南建議配置 2 GB RAM。該數值僅適用於快速入門,Zitadel 的正式環境部署指南則提供了不同的數據。

圖表Zitadel's own published sizing guidance, October 2026
此圖表背後的資料
[
  {
    "config": "Zitadel itself, under 1 core",
    "cpu_cores": 0.5,
    "ram_gb": 0.5
  },
  {
    "config": "HA node, reduced setup",
    "cpu_cores": 4,
    "ram_gb": 8
  },
  {
    "config": "HA node, logs and metrics on",
    "cpu_cores": 4,
    "ram_gb": 16
  }
]

上述為官方建議值,而非實際運行環境的測量結果,請將其視為資源需求的參考基準。Zitadel 本身的處理程序佔用資源較小:指南指出其約需 0.5 GB RAM,且運行於單核心 CPU 以下即可。CPU 核心數主要用於密碼雜湊運算,由於該運算刻意設計為緩慢執行,大量登入請求會導致 CPU 瞬間飆升,因此指南建議保留 4 個 CPU 核心以應對此類負載。PostgreSQL 是另一項主要開銷:同一份指南建議每秒處理 100 次請求需配置約 1 個核心,且每個核心需配備 4 GB RAM。

表格中較大的數值並非單機配置。若要建立最小化的高可用性架構,指南建議使用由三個節點組成的叢集,每個節點配置 4 個核心與 16 GB RAM;若捨棄日誌收集與監控指標功能,則可將規格降至每個節點約 4 個核心與 8 GB RAM。指南並未針對單節點部署提供具體規格建議。

因此,2 GB 的 VPS 可以啟動此堆疊,但一旦面臨實際流量,其資源配置將遠低於指南為資料庫所預留的額度。登入服務是所有其他服務的依賴基礎,一旦服務中斷,所有依賴它的應用程式都將無法存取。若您評估後認為指南建議的資料庫與雜湊運算預算超出您的認證服務預算,這是一個合理的決策,且在遷移前做出此判斷遠比遷移後再調整更為經濟。Keycloak、Authentik 與 Zitadel 的比較 涵蓋了各項方案在記憶體與維運工作上的成本,而 自架 Authentik 伺服器 通常是小型伺服器環境下的常見替代方案。

取得 stack 並固定版本

mkdir zitadel-compose && cd zitadel-compose
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.yml
curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/.env.example
cp .env.example .env
chmod 600 .env

該檔案定義了實際會執行的 4 個服務。Traefik 是反向代理:它依路徑轉送請求,並透過後文的 overlay 終止 TLS (transport layer security)。zitadel-api 是監聽 8080 埠的 Go 二進位檔。zitadel-login 是在 /ui/v2/login 提供的登入介面。postgres 儲存所有資料。Redis cache 和 OpenTelemetry collector 也位於同一檔案中,但受 Compose profiles 控制;除非明確啟用,否則不會啟動。

現在不要執行 docker compose up。第一次啟動會建立 instance,而下方的數項設定之後無法變更,或需要額外處理才能變更。

您複製的 .env 會固定自身的 image tags:

ZITADEL_VERSION=v4.16.0
TRAEFIK_IMAGE=traefik:v3.7.7
POSTGRES_IMAGE=postgres:17.10-alpine

目前的 v4 release 是 v4.20.3,於 13 November 2026 發布,比 shipped file 中固定的版本多 4 個 minor versions。v4.20.0 之前的 release,也就是 v4.19.5(15 October 2026),是 Zitadel technical advisory A-10018 首次涵蓋的版本:受影響的 v1 和 v2 API list endpoints 現在會套用預設與最大限制,因此未指定限制的 list client 不會再取得所有結果,而必須分頁;要求超過最大值的請求則會被拒絕。之後的每個 release,包括 v4.20.0,都包含這項變更。將 ZITADEL_VERSION 設為您要執行的版本,並維持在 v4 系列,不要追蹤最新版本。若您手動選擇版本,請跳過 v4.18.0:其 release notes 表示該版本的 setup step 會失敗,應改用 v4.19.0。上方的 curl 會從 main branch 取得 docker-compose.yml,而該 branch 未固定任何版本,因此請將這兩個檔案的副本都提交至 git repository。否則下個月在新主機上執行相同指令時,取得的會是不同檔案,而您將無法知道變更了哪些內容。

將 .env 中的 LOGIN_SESSION_COOKIE_SECRET 替換為使用 openssl rand -base64 32 產生的隨機值。Login UI 會使用它簽署 session cookies,而 v4.19.5 release notes 明確警告不要保留範例值。

為 Postgres 建立專屬使用者與強密碼

預設的 .env 會以超級使用者身分將 Zitadel 連接到 PostgreSQL,密碼為 postgres:

POSTGRES_ADMIN_USER=postgres
POSTGRES_ADMIN_PASSWORD=postgres
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://postgres:postgres@postgres:5432/zitadel?sslmode=disable

此處的加固步驟存在一個陷阱。Zitadel 文件建議將 POSTGRES_ZITADEL_PASSWORD 附加到 .env,但基礎的 docker-compose.yml 並不會讀取該變數,因此設定它不會產生任何作用。若僅更改 POSTGRES_ADMIN_PASSWORD 會導致連線中斷,因為密碼同時以明文寫入 DSN (data source name) 字串中。DSN 字串決定了 Zitadel 的連線方式。

.env.example 中的註解說明得很清楚:當配置了 DSN 時,Zitadel 會直接使用該使用者,而不會為您建立非特權使用者,因此該角色必須在首次啟動前就已存在。請為該角色產生密碼,在啟動 Postgres 前將 POSTGRES_ADMIN_PASSWORD 設定為 .env 中的隨機密碼,接著單獨啟動 Postgres 並建立該角色。Postgres 映像檔僅在初始化空資料目錄時才會套用該管理員密碼;事後更改 .env 並不會更新現有資料庫的密碼。

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

docker compose --env-file .env -f docker-compose.yml up -d postgres

docker compose --env-file .env -f docker-compose.yml exec -T postgres \
  psql -U postgres -d postgres <<'SQL'
CREATE ROLE zitadel LOGIN PASSWORD 'the-password-you-generated';
ALTER DATABASE zitadel OWNER TO zitadel;
SQL

上述 psql 呼叫會在容器內透過本機 socket 執行,官方 Postgres 映像檔預設信任此連線,因此不會提示輸入密碼。擁有權才是關鍵。Zitadel 的初始化階段會建立自己的 schema (eventstore、projections、system) 與資料表。資料庫擁有權賦予該角色引導這些 schema 所需的 CREATE 權限。PostgreSQL 15 對 public schema 的 CREATE 權限變更屬於獨立事項,並不代表 Zitadel 的 schema 引導會失敗。

現在將 DSN 指向新角色,並保留您在啟動 Postgres 前設定的管理員密碼:

POSTGRES_ADMIN_PASSWORD=a-32-character-random-string
ZITADEL_DATABASE_POSTGRES_DSN=postgresql://zitadel:the-password-you-generated@postgres:5432/zitadel?sslmode=disable

sslmode=disable 會讓資料庫連線在私有的 Compose 網路上保持未加密狀態;其連接埠不會對外公開。Zitadel 的資料庫指南建議在正式環境的資料庫連線中使用 TLS。首次完整啟動後,請確認該角色確實擁有其資料:

docker compose exec -T postgres psql -U zitadel -d zitadel -c '\dn'

這應該會列出 eventstore schema、projections schema 與 system schema。如果缺少這些 schema,代表初始化階段未執行到該步驟,API 容器日誌會說明原因。

主金鑰及其遺失的代價

Zitadel 會在儲存機密資訊前進行加密,包括身分提供者憑證、SMTP 密碼、一次性密碼 (OTP) 種子以及機器金鑰。主金鑰用於解鎖所有這些資料。它必須正好是 32 位元組,且官方文件已明確指出後果:若未妥善保存,一旦遺失將無法存取任何加密資料。

請產生一組金鑰並替換 .env 中的預留位置:

tr -dc A-Za-z0-9 </dev/urandom | head -c 32; echo

請直接編輯 ZITADEL_MASTERKEY=MasterkeyNeedsToHave32Characters 這一行,而非在檔案末端新增第二行。Docker Compose 會採用重複鍵值的最後一個定義,因此新增雖然有效,但若檔案中同時存在兩行主金鑰設定,將會誤導後續維護人員。

現在請考慮該金鑰的存放位置。Compose 檔案啟動 API 容器的方式如下:

command: start-from-init --masterkey "${ZITADEL_MASTERKEY}"

因此,主金鑰會出現在容器的命令列參數中,任何能存取 Docker socket 的使用者皆可透過 docker inspect 查看。在單一管理員的 VPS 環境中,這屬於可接受的權限範圍,且 .env 的檔案權限設定可在磁碟層級提供保護。若此方式不符合您的安全需求,請將金鑰掛載為檔案,並改用 --masterkeyFile /run/secrets/zitadel-masterkey,這能避免將金鑰值暴露在處理程序參數中。

在首次啟動服務前,請務必將主金鑰複製到您的密碼管理員中。資料庫傾印檔 (dump) 不會包含此金鑰,因此若在不同主金鑰下還原資料庫,將導致執行個體無法讀取其加密機密。請將金鑰存放在與資料庫備份檔不同的位置,以確保即使備份遭竊,攻擊者也無法同時取得加密資料與解鎖金鑰。

在首次啟動前設定外部網域

ZITADEL_DOMAIN 位於 .env 中,會傳入容器內的 ZITADEL_EXTERNALDOMAIN,這是使用者輸入的名稱。Zitadel 會據此推導 OIDC 發行者、登入介面基礎 URI、SAML 端點以及首位管理員的登入名稱,因此這並非僅是裝飾性的設定。

ZITADEL_DOMAIN=auth.example.com
ZITADEL_EXTERNALPORT=443
ZITADEL_EXTERNALSECURE=true

Zitadel 會根據 Host 標頭判斷您正在存取哪個實例。若該標頭與其已知的網域不符,所有請求都會得到相同的回應:

ID=QUERY-1kIjX Message=Instance not found

當您看到此錯誤時,請檢查兩件事。要麼 ZITADEL_DOMAIN 並非您瀏覽時使用的名稱,要麼位於前端的代理伺服器將 Host 重寫為上游位址。直接瀏覽伺服器的 IP 位址而非網域名稱也會導致此錯誤。

您可以在日後變更這些數值。Zitadel 必須重新執行設定階段才能套用變更,且您已註冊的每個應用程式仍會保留其舊有的重新導向 URI。現在就決定最終名稱,遠比日後遷移要節省成本。

使用 Let's Encrypt 覆蓋設定終止 TLS

若要使用公開網域,請加入 Zitadel 的 Let's Encrypt 覆蓋設定。此設定會將 Traefik 切換為 ACME (automatic certificate management environment) HTTP 驗證模式,並將公開連接埠替換為 80 與 443,因此伺服器上不得有其他服務佔用這些埠。

curl -fsSLO https://raw.githubusercontent.com/zitadel/zitadel/main/deploy/compose/docker-compose.mode-letsencrypt.yml
echo 'LETSENCRYPT_EMAIL=ops@example.com' >> .env

此覆蓋設定同時會在 API 容器上設定 ZITADEL_EXTERNALPORT: 443 與 ZITADEL_EXTERNALSECURE: true,確保公開 URL 與 Zitadel 自身產生的 URL 一致。啟動前必須先完成 A 紀錄解析,否則 HTTP 驗證將會失敗。

若您已在 nginx 或負載平衡器上終止 TLS,請改用 docker-compose.mode-external-tls.yml 並將 TRAEFIK_TRUSTED_IPS 設定為代理伺服器發送請求的 IP 範圍。Traefik 僅會採納來自該清單中位址的 X-Forwarded-* 標頭。此覆蓋設定會明確將 Zitadel 的外部 URL 與登入 URL 設為 HTTPS。

上游代理伺服器必須執行兩項 Zitadel 強制要求的任務。首先,必須與後端使用 HTTP/2 通訊,因為 API 採用 gRPC。其次,必須完整傳遞 Host 以及 X-Forwarded-Proto: https。在此 Compose 堆疊中,nginx 設定格式如下:

server {
    listen 443 ssl;
    http2 on;
    ssl_certificate     /etc/certs/selfsigned.crt;
    ssl_certificate_key /etc/certs/selfsigned.key;
    location /ui/v2/login {
        proxy_pass http://YOUR_LOGIN_UPSTREAM:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
    }
    location / {
        grpc_pass grpc://YOUR_API_UPSTREAM:8080;
        grpc_set_header Host $host;
        grpc_set_header X-Forwarded-Proto https;
    }
}

請將上游預留位置替換為 nginx 可存取的位址。若您並非透過 443 埠提供 Zitadel 服務,請使用 grpc_set_header Host $host:$server_port; 以確保連接埠資訊隨標頭傳遞。其餘部分為一般的虛擬主機設定,逐行解讀 nginx 反向代理設定 一文涵蓋了非 Zitadel 專屬的設定細節。

首次管理員與強制變更密碼

第一次啟動會建立 1 個 instance、1 個 organisation 和 1 個 human admin。登入名稱是 zitadel-admin@ 加上 zitadel.,再加上您的外部網域。因此使用 ZITADEL_DOMAIN=auth.example.com 時,登入名稱為:

zitadel-admin@zitadel.auth.example.com

如果未自行設定,密碼就是 Password1!。Zitadel 的上游預設值會要求使用者在首次登入時變更密碼,而隨附的 compose 檔案會覆寫這項預設值:

ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: false

這一行直接寫在 docker-compose.yml 中,不會從 .env 讀取。因此,請在自行建立的小型 overlay 中填入自訂值。將檔案命名為 docker-compose.local.yml:

services:
  zitadel-api:
    environment:
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS: you@example.com
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORD: "a-long-temporary-password"
      ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED: "true"

只有在不使用 -f 旗標執行 Compose 時,Compose 才會自行載入 docker-compose.override.yml;而 Zitadel 指南中的每個指令都會傳入 -f,因此會停用這項行為。與其重複增加中的旗標清單,不如在 .env 中固定檔案清單:

COMPOSE_FILE=docker-compose.yml:docker-compose.mode-letsencrypt.yml:docker-compose.local.yml

現在啟動服務:

docker compose pull
docker compose up -d --wait

--wait 會持續執行該指令,直到 healthcheck 通過為止。API 容器始終無法達到該狀態時,Compose 會以 dependency failed to start: container zitadel-zitadel-api-1 is unhealthy 停止,而 docker compose logs zitadel-api 會提供原因。容器會依 project 命名;隨附的 compose 檔案會在頂層設定 name: zitadel,因此不會使用目錄名稱。第一次啟動時,原因通常是 masterkey 長度或資料庫 DSN。

在 https://auth.example.com/ui/console 登入,變更密碼,然後在建立其他項目之前,為該帳戶啟用第二因素驗證。每個 ZITADEL_FIRSTINSTANCE_* 值只會在建立第一個 instance 時生效。instance 建立後,再編輯這些值完全不會產生作用。

為何 SMTP 運作正常前,密碼重設功能無效

若身分提供者無法發送郵件,該故障將會隱蔽數週之久。Zitadel 會針對使用者邀請、地址驗證、密碼重設連結、一次性驗證碼及網域宣告通知發送電子郵件。若未設定 SMTP 提供者,Console 仍會回報動作已完成,而訊息會進入通知處理程序,但卻無處可送。在 v4.20.0 版本中,通知預設使用舊版模式(LegacyEnabled: true),這會忽略平行處理器的 MaxAttempts: 3 與 MaxTtl: 5m 設定。這些數值並未描述預設的通知重試行為。等待連結的使用者將不會收到任何通知。

請在 Console 的執行個體設定中,於 https://auth.example.com/ui/console/settings 處進行設定。SMTP 提供者表單會要求輸入寄件者電子郵件地址、寄件者名稱、主機與埠號、使用者名稱、SMTP 密碼以及 TLS 開關。儲存前請先使用表單中的測試按鈕,因為它會發送一封真實郵件:郵件不是送達就是失敗。請啟用該提供者,以便 Zitadel 使用它來發送郵件。

有一組對應的環境變數,即 ZITADEL_DEFAULTINSTANCE_SMTPCONFIGURATION_SMTP_HOST 及其相關變數。它們僅在建立執行個體時生效。對於已在運作的堆疊,這些變數無效,因此 Console 是現有執行個體的正確設定位置。

關於從 VPS 進行傳送,有兩點注意事項,因為這通常是失敗的原因。在選擇轉送服務前,請先檢查提供者的對外 SMTP 政策:DigitalOcean 預設會封鎖 Droplet 的 25、465 與 587 埠,因此 587 埠並非萬用的解決方案。請使用提供者允許的埠號,並透過驗證機制進行轉送。此外,請為寄件網域發布 SPF (sender policy framework) 與 DKIM (domainkeys identified mail) 記錄,否則重設連結會被歸類為垃圾郵件,這對使用者而言,看起來就像郵件從未寄出一樣。

在 v4.20.0 版本中,對外 SMTP TLS 連線會拒絕透過受損的 eMudhra 中繼 CA 所簽發的憑證鏈。受影響的轉送服務需要更換憑證。

在邀請任何人之前,請先進行驗證。建立一個拋棄式使用者,要求進行密碼重設,並觀察郵件是否送達。若未送達,docker compose logs -f zitadel-api 會顯示 SMTP 失敗的相關資訊。SMTP 密碼會以加密形式儲存在資料庫中,這是 masterkey 為您保護的項目之一。

分別備份 Postgres 和 masterkey

Zitadel 知道的所有資料都在 PostgreSQL 中。負責解密這些資料的是 masterkey。請將兩者備份到不同的位置。

先建立 dump:

sudo install -d -m 700 /srv/zitadel-backups
docker compose exec -T postgres \
  pg_dump -U postgres -Fc zitadel > "/srv/zitadel-backups/zitadel-$(date +%F).dump"

-Fc 是 custom format,會在輸出時壓縮,並可由 pg_restore 選擇性讀取。exec -T 會停用 TTY 配置;這很重要,因為此命令會由 cron 執行,且不會連接終端機。

接著使用 restic 將該目錄推送到異地;restic 會加密並進行去重:

export RESTIC_REPOSITORY="sftp:backup@backup.example.com:/srv/restic/zitadel"
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init
restic backup /srv/zitadel-backups
restic forget --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune

restic init 只會執行一次,且僅在第一天執行。將 dump 和最後兩個命令放入 /usr/local/bin/zitadel-backup.sh,並設定為每晚執行:

0 3 * * * /usr/local/bin/zitadel-backup.sh

將 .env 及你使用的每個 compose 檔案備份到 git。masterkey 不適用於上述做法。它應放在 password manager 中,並另外存放於不是這個 restic repository 的第二個位置,因為同時保存資料庫及其解密金鑰的 archive,已不再是加密系統的備份。

未曾還原過的備份只是猜測。請在同一台伺服器上還原到 scratch database,然後檢查內容:

docker compose exec -T postgres createdb -U postgres zitadel_restore_test
docker compose exec -T postgres pg_restore -U postgres -d zitadel_restore_test \
  < /srv/zitadel-backups/zitadel-2026-08-21.dump
docker compose exec -T postgres psql -U postgres -d zitadel_restore_test -c '\dt eventstore.*'
docker compose exec -T postgres dropdb -U postgres zitadel_restore_test

eventstore schema 中列出資料表,表示 dump 確實有效。如果錯誤訊息表示 schema 不存在,則代表 dump 無效;而你能在不造成任何損失的日子發現這件事。備份和升級 Compose stack 的一般模式幾乎可直接套用於此,將 masterkey 排除在同一個 archive 外則是唯一與 Zitadel 特有的部分。

升級 Zitadel 且不遺失 instance

升級方式是在 .env 中提升版本,接著執行 2 個指令:

docker compose pull
docker compose up -d --wait

在對供人員登入的系統執行前,先了解第 2 個指令的作用。容器的 command 是 start-from-init,它會在開始提供服務前執行 init 和 setup phases,而 setup phase 就是資料庫 migration。因此,提升版本時,容器啟動會在無人值守的情況下對正式資料庫執行 schema migrations,同時 --wait 會等待 healthcheck。這正是上方的 restore test 不可省略的原因。

在升級前立即建立最新 dump。昨晚的 dump 是不同的資料。

對 v4.20.3 而言,進行中的 external identity provider sign-ins 必須重新開始,而尚未兌換的 Login V1 authorization codes 會被拒絕 1 次。自訂 login UIs 需要 session.link permission 才能完成 OIDC 或 SAML requests;請在升級前將該角色授予其 service user IAM_LOGIN_CLIENT。shipped Login V2 service user 已經具備該角色。Session API 的密碼檢查現在會套用使用者組織的 login policy,因此停用 username/password login 的組織必須將使用者導向其 identity provider。

不要跳過 major version。從 v3 移至 v4 前,先升級至 v3.4.1 或更新版本。v4 強制要求 OIDC web keys,並移除 legacy signing path。因此,如果您的 v3 instance 從未啟用 web keys,升級後便無法再驗證使用舊版 legacy keys 簽署的 tokens。Zitadel technical advisory A-10017 表示,現有的 JWT access tokens 和 ID tokens 可能會立即失效,使用者可能必須再次登入。其修正方式是先經由 v3.4.1 或更新版本逐步升級,並在升級前等待使用 legacy keys 簽署的 tokens 和 sessions 過期;或者接受預先安排的重新登入時段。若您已經執行 v3.4.1 或更新版本,且自啟用 web keys 後已等待足夠時間,該 advisory 表示不需採取任何行動。

使用 docker compose logs -f zitadel-api 監看 setup phase。大型 eventstore 的 migrations 可能需要數分鐘,而在 healthcheck 通過前,Traefik 不會將流量轉送至 API,因此網站會在這段期間中斷。請事先規劃,不要等到發生時才發現。

Rollback 不是把舊 tag 放回去這麼簡單。Migration 執行後,舊版 binary 無法理解它所遇到的 schema,因此 rollback 代表還原 dump。當 instance 開始承載真實使用者後,請改用 docker-compose.prodlike.yml;該 overlay 會將 init 和 setup 作為獨立於 start 的步驟執行,使 migration 成為您主動觸發並監看的程序,而不是 container restart 的副作用。

新身分識別提供者應指向的位置

在 Console 中建立專案,再於專案內建立應用程式。對於現代應用程式,請選擇 OIDC;Zitadel 會提供 client ID、client secret,以及位於 https://auth.example.com/.well-known/openid-configuration 的 discovery document。大多數支援單一登入的自架軟體,正是需要這些資訊。

許多軟體不支援單一登入,或僅在付費方案中提供。對於第一種情況,可在應用程式前方部署 oauth2-proxy,保護應用程式,將任何 HTTP 服務交由 Zitadel 進行存取控管。對於第二種情況,在規劃以尚未購買的功能為基礎進行遷移前,建議先閱讀 自架應用程式的 SSO 費用。

FAQ

自架 Zitadel 需要多少 RAM 與 CPU?

Zitadel 的生產環境指南指出,Zitadel 本身約需 0.5 GB 的 RAM,且可在不到一個 CPU 核心的環境下執行,但建議保留 4 個核心以處理密碼雜湊。PostgreSQL 的資源需求需另行計算,大約每秒 100 次請求需配置一個核心,且每個核心需 4 GB RAM。指南中較高的數值是指三節點高可用性叢集中每個節點的需求:各需 4 個核心與 16 GB RAM;若不包含日誌收集與指標監控,則約需 4 個核心與 8 GB RAM。Docker Compose 快速啟動設定要求至少 2 GB RAM,這僅足夠進行測試,且幾乎沒有餘裕留給其他服務所需的資料庫。

如果遺失 Zitadel masterkey 會發生什麼事?

所有以此金鑰加密的資料將無法解密。身分提供者憑證、SMTP 密碼與一次性密碼(OTP)種子將永久失效,且金鑰無法在事後變更。單憑資料庫備份無法還原可運作的實例,因為備份檔內僅存密文,且缺乏金鑰。請將 masterkey 存放在密碼管理員中,並與存放資料庫備份的位置分開。若兩者皆遺失,重建實例是唯一的解決途徑。

為什麼 Zitadel 的密碼重設郵件一直沒收到?

原因通常是未設定 SMTP 提供者,或是設定的提供者無法投遞郵件。Zitadel v4.20.0 預設使用舊版通知處理機制,因此平行處理器的三次嘗試與五分鐘間隔設定會被忽略。請在實例設定中配置 SMTP 提供者,並使用該表單中的測試按鈕發送實際郵件。請啟用該提供者,使用 VPS 提供商允許的連接埠進行驗證轉發,並為發信網域發布 SPF 與 DKIM 記錄,以避免郵件被過濾為垃圾郵件。

安裝後可以變更 Zitadel 的外部網域名稱嗎?

可以,但不能僅透過編輯 .env 來達成。請變更 ZITADEL_EXTERNALDOMAIN、ZITADEL_EXTERNALPORT 與 ZITADEL_EXTERNALSECURE,接著讓 Zitadel 重新執行安裝階段以套用變更。您先前註冊的應用程式仍會保留舊的重新導向 URI,必須手動更新;任何 Host 標頭與 Zitadel 已知網域不符的請求,將會收到 Instance not found 錯誤。在首次啟動前決定最終網域名稱可避免上述所有問題。

這篇文章對您有幫助嗎?