Authentik 自行託管 SSO：Docker Compose 設定

為您託管的每個應用程式使用單一登入

Authentik 是自行託管的 SSO（單一登入）伺服器：使用者只需登入一次，後方的每個應用程式都會接受該工作階段，不必各自要求密碼。安裝方式是使用官方 Docker Compose 檔案和 2 個產生的密鑰。真正需要仔細規劃的是後續設定：將反向 Proxy 指向它，並將 1 個現有應用程式置於 forward auth 保護之下。

Authentik 在該 Compose 檔案中以 3 個服務執行：PostgreSQL 資料庫、server 程序，以及 worker 程序。伺服器容器也會執行內嵌的 outpost；這是針對每個受保護應用程式回答「此要求是否已登入？」的元件。截至 2026 年 7 月，2026.5 版是目前的版本，專案要求主機至少具備 2 個 CPU 核心和 2 GB RAM。請將此視為最低需求。主機持續運作 1 天後，PostgreSQL 和 worker 都會占用記憶體。

開始前的必要條件

您需要安裝含 Compose v2 外掛程式的 Docker Engine。執行 docker compose version 即可確認。若輸出的是錯誤而非版本資訊，請先安裝此外掛程式再繼續；基本說明請參閱 在 VPS 上使用 Docker Compose 執行應用程式。您也需要一筆指向該伺服器的 DNS A 記錄。以下範例使用 auth.example.com，因為 Authentik 會根據瀏覽器使用的主機名稱建立重新導向 URL。

請以 docker 群組中的一般使用者執行此堆疊，不要使用 root。主機上的該群組具備等同 root 的權限，因此只應授予一個部署帳戶，其他人不得使用；相關原則請參閱 VPS 上的最小權限使用者帳戶。

Install with the official Compose file

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 should list three containers, with postgresql reporting healthy and server and worker reporting running. The first start runs the database migrations, so give it a minute before the web interface answers.

Both generated values matter, for different reasons. PG_PASS is the PostgreSQL password, and it has a hard limit of 99 characters. AUTHENTIK_SECRET_KEY signs sessions and tokens, so changing it later logs every user out and invalidates every API token you have issued. Keep .env at mode 600 and keep a copy somewhere safe, because a database restored without its matching secret key is a database nobody can log into.

The Compose file reads both values with the ${PG_PASS:?database password required} form, which means Compose refuses to start when the file is missing. Running docker compose up -d from the wrong directory prints required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required and stops. That message is a path problem, not a config problem.

重要的環境值

其他內容都放在相同的 .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 會嘗試在連接埠 25 上連線至 localhost，因此密碼重設郵件最終會在 worker log 中顯示連線錯誤。
• AUTHENTIK_LOG_LEVEL=debug 會在登入流程運作異常時啟用所需的詳細資訊。完成後請恢復為 info。
• AUTHENTIK_ERROR_REPORTING__ENABLED 預設為 false。只有在您願意將當機報告傳送至上游時，才將其設為 true。

這些是純文字檔中的機密資訊，因此請以處理其他認證儲存區的方式保護該目錄。密碼管理器，例如 自行託管的 Vaultwarden 執行個體，比筆記型電腦上的備忘錄更適合儲存復原副本。

第一次登入與管理員帳戶

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

在 Directory 下依序進入 Users，建立您自己的一般管理員使用者，將其加入 authentik Admins 群組，然後使用該帳戶登入。保留 akadmin 作為緊急應變帳戶，並將長密碼離線保存。日常工作若使用共用的內建帳戶，會使稽核記錄失去作用，因為每個事件都顯示為 akadmin，無法辨識實際操作者。

將 Authentik 置於反向 Proxy 後方

將連接埠 9000 發布至網際網路雖然可行，但您需要 TLS（傳輸層安全性）和正式的主機名稱。如果您已經使用 Traefik 作為多個 Compose 應用程式的反向 Proxy 中的設定，請使用覆寫檔案，將 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 會自動合併覆寫檔案，因此 server 服務會保留官方檔案中的所有設定，並取得這些標籤。使用 curl -I https://auth.example.com/if/user/ 檢查，該指令應回應 HTTP/2 200。Traefik 回報 404 page not found 表示容器不在 proxy 網路上，而 Traefik 無法將流量路由至無法連線的容器。

主機名稱正常運作後，請在覆寫檔案中將發布的連接埠繫結至 127.0.0.1，讓流量只能透過 Proxy 進入。

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

Authentik 的 Proxy Provider 有 3 種模式。選錯模式可能浪費 1 小時。Proxy 表示由 outpost 本身將流量轉送至上游應用程式。Forward auth (single application) 表示由您自己的反向 Proxy 傳送流量，並只向 Authentik 確認要求是否已登入。Forward auth (domain level) 則使用單一 Provider 保護同一父網域下的所有應用程式，但必須另外設定每個應用程式的授權規則。若前方使用 Traefik，應選擇 forward auth (single application)。

在 Web 介面中，開啟 Applications，再開啟 Providers，建立 Proxy Provider，選擇 forward auth single application 模式，並將外部主機設為 https://app.example.com。建立一個指向該 Provider 的 Application。接著開啟 Outposts，編輯 authentik Embedded Outpost，並將新的應用程式移至其選取的應用程式清單。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-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 以自動登入的功能都會保持未登入狀態。

受保護的應用程式本身需要 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。如果沒有將該路徑前綴傳送至 Authentik 服務的 router，要求就會送到您的應用程式。應用程式會回應 404，登入流程也就無法完成。較高的 priority 會讓特定路徑規則在相同網域上的一般 Host() 規則之前套用。

使用私密瀏覽器視窗進行測試。瀏覽器應會被導向 auth.example.com；完成登入後，應返回應用程式。Authentik 端的 docker compose logs -f server 會針對每次嘗試列出一個授權事件，您可藉此確認要求是否確實到達 Authentik。

實際會遇到的失敗情況

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

/outpost.goauthentik.io/start 回傳 404。 缺少 outpost router，或其優先順序低於該主機的 catch-all router。

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

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

Keycloak 更適合的情況

Keycloak 是較早期的專案，由 Red Hat 支援。對於傳統企業身分識別工作，它通常是更合適的選擇，例如大量使用 SAML 聯合、同時透過多個外部身分識別提供者代理登入，以及將 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 使用依日期編號的版本，部分版本包含的遷移作業要求您從前一個版本升級。請在 pull 之前建立資料庫傾印，而不是之後。

FAQ

Authentik 可免費自行代管嗎？

開放原始碼版本可免費使用，並涵蓋上述所有功能：proxy provider、forward auth、OIDC (OpenID Connect)、SAML 和 flows engine。付費企業版另提供支援及部分企業功能，但本指南中的任何功能都不需要授權。

使用 Authentik 必須搭配 Traefik 嗎？

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

為什麼受保護的應用程式會在登入和錯誤之間無限跳轉？

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

Authentik 需要多少 RAM？

截至 2026 年 7 月，文件列出的最低需求是 2 個 CPU 核心和 2 GB RAM，供 PostgreSQL、server 和 worker 一起使用。在 2 GB 的主機上，記憶體壓力過大時，worker 會是核心最先終止的程序；其症狀是背景工作和外寄電子郵件停止，但登入頁面仍可正常運作。如果同一台 server 也執行受保護的應用程式，請配置 4 GB RAM。