Authentik 自架 SSO：Docker Compose 與 Traefik 設定

每個自架應用程式使用同一組登入資訊

Authentik 是自架的 SSO（single sign-on）伺服器：使用者登入一次後，後方的所有應用程式都會接受該工作階段，不再要求各自的密碼。安裝方式是使用官方 Docker Compose 檔案，並產生 2 組 secret。真正需要思考的是後續設定：將反向代理指向 Authentik，並透過 forward auth 保護一個現有的應用程式。

Authentik 在該 Compose 檔案中以 3 個服務執行：PostgreSQL 資料庫、server 程序，以及 worker 程序。伺服器容器也會執行內嵌的 outpost。這個元件會針對每個受保護的應用程式回答「此請求是否已登入？」。截至 2026 年 10 月，目前版本為 2026.8.3。此版本於 2026 年 9 月 17 日發布，是 2026.8 系列的最新修補版本。該系列於 2026 年 8 月 18 日推出 2026.8.0，官方 Compose 檔案目前已將 2026.8.3 設為預設 image tag。專案要求主機至少具備 2 個 CPU 核心與 2 GB RAM。請將此視為最低需求。主機執行一天後，PostgreSQL 與 worker 都會持續占用記憶體。

開始前的準備

您需要安裝 Docker Engine 與 Compose v2 外掛程式。執行 docker compose version 可確認是否已安裝。如果該指令輸出錯誤而不是版本資訊，請先安裝外掛程式，再繼續後續步驟；基本操作請參閱 在 VPS 上使用 Docker Compose 執行應用程式。您也需要將 DNS A 記錄指向該伺服器。以下範例使用 auth.example.com，因為 Authentik 會根據瀏覽器使用的主機名稱建立重新導向 URL。

請以 docker 群組中的一般使用者執行此堆疊，不要使用 root。加入該群組等同於在主機上具備 root 權限，因此只應授予一個部署帳號，其他帳號不要加入；作法可參考 VPS 上的最小權限使用者帳號。

使用官方 Compose 檔案安裝

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps 應列出 3 個容器，其中 postgresql 應回報 healthy，server 應回報 worker，而 running 應回報 PG_PASS。首次啟動時會執行資料庫遷移，因此請等待 1 分鐘，讓 Web 介面完成回應。

這 2 個產生的值都很重要，但原因不同。AUTHENTIK_SECRET_KEY 是 PostgreSQL 密碼，長度上限為 99 個字元。.env 用來簽署工作階段與 token，因此日後變更它會讓所有使用者登出，並使已發出的所有 API token 失效。將 ${PG_PASS:?database password required} 的模式設為 600，並在安全的位置保留一份副本，因為還原資料庫時若沒有相符的 secret key，任何人都無法登入該資料庫。

Compose 檔案會以 docker compose up -d 形式讀取這 2 個值。若檔案不存在，Compose 就會拒絕啟動。從錯誤的目錄執行 required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required 時，會顯示 .env 並停止。這是路徑問題，不是設定問題。

重要的環境變數

其他設定都放在同一個 .env 檔案中。Authentik 會將雙底線對應至巢狀設定鍵，因此 AUTHENTIK_EMAIL__HOST 會設定 email.host。單底線會被忽略，且不會顯示警告。這是設定看似未生效最常見的原因。

• AUTHENTIK_BOOTSTRAP_PASSWORD 會在首次啟動時設定內建 akadmin 使用者的密碼，因此不必在公開 Web 表單中輸入密碼。AUTHENTIK_BOOTSTRAP_EMAIL 和 AUTHENTIK_BOOTSTRAP_TOKEN 會以相同方式設定該使用者的地址與 API token。
• COMPOSE_PORT_HTTP 和 COMPOSE_PORT_HTTPS 會將對外發布的連接埠從預設的 9000 和 9443 改至其他連接埠。
• AUTHENTIK_EMAIL__HOST、AUTHENTIK_EMAIL__PORT、AUTHENTIK_EMAIL__USERNAME、AUTHENTIK_EMAIL__PASSWORD、AUTHENTIK_EMAIL__USE_TLS 和 AUTHENTIK_EMAIL__FROM 會設定對外寄信功能。未設定這些值時，Authentik 會嘗試連線至 localhost 的 25 埠，因此密碼重設郵件會因連線錯誤而無法寄出，並在 worker 日誌中留下錯誤。
• AUTHENTIK_LOG_LEVEL=debug 會在登入流程異常時啟用所需的詳細資訊。問題排除後，請恢復為 info。
• AUTHENTIK_ERROR_REPORTING__ENABLED 預設為 false。只有在接受將當機報告傳送給上游專案時，才將其設為 true。

這些是以明文儲存在檔案中的 secret，因此應像管理其他憑證儲存區一樣管理該目錄。使用 自架的 Vaultwarden 執行個體等密碼管理工具，會比將復原副本記在筆記型電腦上更適合。

首次登入與管理員帳戶

在瀏覽器中開啟 http://SERVER_IP:9000。Authentik 會顯示初始設定流程，並要求你為預設的 akadmin 使用者設定密碼。如果你已經設定 AUTHENTIK_BOOTSTRAP_PASSWORD，這個步驟就已完成，接著會直接進入登入頁面。

在 Directory，接著選取 Users，為自己建立一般管理員使用者，將該使用者加入 authentik Admins 群組，然後使用這個帳戶登入。將 akadmin 保留為緊急應變帳戶，並將長密碼離線保存。日常工作若使用共用的內建帳戶，會破壞稽核日誌，因為每個事件都只會顯示 akadmin，無法判斷實際操作者。這個原則也適用於 Authentik 下游的系統：例如 讓每個人擁有自己的 agent 的自架 OneCLI harness，只有在傳入的身分屬於單一使用者，而不是全團隊共用的登入帳戶時，才能留下可讀的操作軌跡。通話錄音也是同樣道理：若在 Authentik 後方執行自架的私有 AI 客服答錄系統，每次調閱錄音或逐字稿都能對應到具名帳戶，日後處理當事人依個資法提出的查詢或刪除請求時，才說得清楚有哪些人聽過那通電話。

將 Authentik 放在反向代理後方

將連接埠 9000 發布到網際網路可以運作，但您需要 TLS（傳輸層安全性）和正式的主機名稱。如果您已經依照使用 Traefik 作為多個 Compose 應用程式的反向代理完成設定，請使用 override 檔案，將 Authentik 加入相同的外部 proxy 網路。在 compose.yml 旁建立 docker-compose.override.yml：

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

使用 docker compose up -d 套用設定。Compose 會自動合併 override，因此 server 服務會保留官方檔案中的所有設定，並加入這些標籤。使用 curl -I https://auth.example.com/if/user/ 檢查，應該會回應 HTTP/2 200。Traefik 回傳 404 page not found，表示容器不在 proxy 網路上；Traefik 無法將流量路由到無法連線的容器。

主機名稱運作後，請在 override 中將已發布的連接埠繫結至 127.0.0.1，讓所有連線只能經由代理進入。

使用 forward auth 保護單一應用程式

Authentik 的 proxy provider 有 3 種模式，選錯模式可能浪費 1 小時。Proxy 表示由 outpost 本身將流量轉送到上游應用程式。Forward auth (single application) 表示仍由你自己的反向代理轉送流量，只向 Authentik 詢問請求是否已完成登入。Forward auth (domain level) 則使用單一 provider 保護同一父網域下的所有應用程式，但必須自行處理每個應用程式的授權規則。若前方使用 Traefik，應選擇 forward auth (single application)。若要找一個具體的應用程式練習，可以先使用 自架的 AFFiNE 工作區，因為這類內部工具通常只應允許你自己的裝置存取，不應公開給其他來源。團隊工具更能凸顯這種做法的優點：將 自架的 Chatwoot 客服中心 放在同一個 provider 後方，所有處理收件匣的人員每天只需登入一次，不必再共用另一組密碼。

在 Web 介面中，開啟 Applications，再開啟 Providers，建立 Proxy Provider，選擇 forward auth single application 模式，並將外部主機設為 https://app.example.com。建立一個指向該 provider 的 Application。接著開啟 Outposts，編輯 authentik Embedded Outpost，並將新的應用程式加入其 selected applications。outpost 只會處理已指派給它的應用程式，因此略過最後這個步驟時，即使 provider 設定正確，也不會回應。

在 Authentik 容器上定義一次 middleware，之後從每個受保護的應用程式引用它：

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-entitlements,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders 是 Traefik 從 Authentik 的回應中複製到上游請求的標頭清單。省略此設定後，應用程式仍受到保護，但不會得知使用者身分，因此任何讀取 X-authentik-username 以自動登入的功能都會維持登出狀態。對於本身也保留登入機制的應用程式，這個差異最為明顯，例如 自架的 openGym 運動追蹤器及其 passkey 登入功能；對同一個頁面而言，這些標頭可將登入提示從 2 次減少為 1 次。

受保護的應用程式本身需要 2 個 router，而不是 1 個：

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

第二個 router 是最常被遺漏的部分。登入完成後，Authentik 會將瀏覽器導回 /outpost.goauthentik.io/ 下、位於應用程式主機名稱的路徑，而不是導回 auth.example.com。如果沒有 router 將此前綴路徑轉送到 Authentik 服務，請求就會抵達你的應用程式，由應用程式回應 404，登入流程也無法完成。較高的 priority 會讓特定路徑規則優先於同一網域上的一般 Host() 規則。

請在私密瀏覽器視窗中測試。瀏覽器應被導向 auth.example.com；完成登入後，應返回應用程式。Authentik 端的 docker compose logs -f server 會為每次嘗試輸出一筆授權事件，藉此確認請求是否確實抵達 Authentik。

實際上會遇到的故障

應用程式與登入頁面之間不斷重新導向。 提供者上的外部主機名稱與瀏覽器使用的主機名稱不一致，通常是提供者中的 http:// 與網址列中的 https:// 不同。工作階段 Cookie 隨後會針對不同來源設定，因此每次返回時都會被視為新的匿名請求。修正外部主機名稱，並清除這兩個網域的 Cookie，再重新測試。

/outpost.goauthentik.io/start 回傳 404。 outpost 路由器不存在，或其優先順序低於該主機的 catch-all 路由器。

應用程式載入，但完全沒有要求登入。 middlewares 標籤指定了不存在的 middleware。Traefik 不會針對此情況發出警告，因此 authentik@docker 中的拼字錯誤只會導致沒有 middleware 執行。開啟 Traefik dashboard，確認路由器列出了該 middleware。

成功登入後，Authentik 回傳 403。 使用者已完成驗證，但未獲得授權：應用程式套用了該使用者不符合的 policy binding 或群組要求。管理介面中的 Events log 會指出拒絕請求的 policy。

Keycloak 更適合的情況

Keycloak 是較早期的專案，由 Red Hat 支持。對於傳統企業身分識別工作，它通常是更強的選擇，例如大量使用 SAML federation、同時代理來自多個外部身分識別提供者的登入，以及將 realm 匯出與匯入作為有文件記載的遷移途徑。對部分組織而言，背後具備商業支援在正式評估中相當重要。代價是 Keycloak 沒有內建 proxy。因此，若要保護不支援 OIDC (OpenID Connect) 的應用程式，就必須另外執行類似 oauth2-proxy 的元件。Authentik 內建的 proxy provider 已整合這項功能。這也是多數同時使用多種應用程式的自架服務使用者最後選擇 Authentik 的原因。

備份與升級

還原需要 3 項內容：PostgreSQL 資料庫、./data 目錄，以及 .env。

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

將該傾印檔與 .env 一起儲存。只有傾印檔並不足夠，因為保護工作階段與權杖資料的密鑰位於 .env。

升級只需變更標籤。在 .env 中將 AUTHENTIK_TAG 設為所需的版本，然後執行 docker compose pull，再執行 docker compose up -d。如果從未設定 AUTHENTIK_TAG，版本會取自 compose.yml 內寫入的預設值。因此，下載該檔案的較新版就是升級方式，官方升級文件也說明了這條路徑。請先閱讀版本說明。Authentik 採用日期式版本，截至 October 2026，其文件指出升級必須依照主要版本的順序進行：先升級到目前所用系列的最新修補版本，再依序逐一升級到後續系列，不得跳過任何系列。Authentik 不支援降級，因此請在 pull 之前建立資料庫傾印，而不是之後才建立。

FAQ

Authentik 可免費自架嗎？

開放原始碼版本可免費使用，涵蓋上述所有功能：proxy provider、forward auth、OIDC (OpenID Connect)、SAML 及 flows engine。付費的 enterprise tier 會提供支援與部分企業功能，但本文內容不需要授權。

使用 Authentik 時是否需要 Traefik？

不需要。Forward auth 可透過 auth_request 搭配 nginx 使用，也可透過 forward_auth 搭配 Caddy 使用。每種情況的模式都相同：反向代理會針對每個請求詢問 Authentik，而受保護主機名稱上的路徑前綴 /outpost.goauthentik.io/ 必須路由至 Authentik，而不是應用程式。

為什麼受保護的應用程式會不停在登入頁面與錯誤頁面之間跳轉？

proxy provider 設定的外部主機名稱，與瀏覽器使用的 URL 不一致，最常見的是 http 與 https 不一致。工作階段 cookie 是針對其中一個來源簽發，卻從另一個來源讀取，因此 Authentik 每次都會將請求視為匿名請求。修正外部主機名稱，然後清除這兩個主機名稱的 cookie，再重新測試。

Authentik 需要多少 RAM？

截至 October 2026，文件記載的最低需求是 2 個 CPU 核心與 2 GB RAM，涵蓋 PostgreSQL、server 與 worker。使用 2 GB 記憶體的主機在記憶體壓力下，worker 會最先被核心終止；症狀是背景工作與外寄電子郵件停止，但登入頁面仍可正常運作。如果同一台伺服器也執行受保護的應用程式，請配置 4 GB RAM。