goauthentik / authentik 這個項目我會直接把它當成一套自建系統的統一登錄入口來用。它是一個開源的、基于 Go 實現的身份認證和單點登錄平臺也就是常說的 IdP核心解決的是“一套賬號登錄多個內部應用”的問題。如果你手頭有 NAS、代碼倉庫、監控面板、運維平臺這類系統不想每個地方單獨維護一套用戶名密碼authentik 值得先跑一遍。它最值得關注的點不是某個花哨的界面功能而是把登錄、授權、MFA、LDAP 目錄服務都集中到了同一個地方并且能通過標準協議和外部應用對接。下面按我從零部署到接入應用的路徑把關鍵步驟和容易踩的坑拆開說。1. 先搞懂 goauthentik / authentik 在認證體系里的位置1.1 goauthentik 和 authentik 是什么關系項目標題里的 goauthentik 并不是某個分支版本而是 authentik 在 GitHub 上的組織和倉庫名。簡單說goauthentik/authentik 就是這個項目的源碼倉庫平時大家討論的 authentik 產品本身也來自這里。后端選擇 Go帶來的直接好處是部署體量和內存占用比不少 Java 系身份認證產品輕。實際跑起來之后一個 docker-compose 項目里會同時出現多個服務包括 server、worker、PostgreSQL、Redis。server 負責對外提供 API 和頁面worker 負責執行后臺任務比如策略判斷、流處理、憑證校驗。兩者共用同一個鏡像只是啟動命令不同。剛開始接觸時不要以為“goauthentik”是一個只靠單一二進制就包打天下的工具它仍然需要依賴數據庫和緩存這一點要先有預期。1.2 它適合放在什么位置authentik 在自托管體系里的定位可以概括成一句話面向應用提供認證能力面向用戶提供統一登錄入口。它常見的落地方式有三種作為 OIDC/OAuth2 服務端讓 Grafana、GitLab、Nextcloud 這類支持標準協議的應用跳轉登錄。作為 LDAP 認證源給只支持 LDAP 的老系統或網絡設備提供用戶校驗。作為反向代理認證網關在 Nginx 或 Traefik 后面統一攔截未登錄請求。它和同類方案經常放在一起對比我看到的典型選擇可以整理成一個表格方案部署方式協議廣度配置復雜度Authelia單容器或二進制重定向認證為主較簡單低Keycloak容器或獨立服務OIDC、SAML高功能重authentikdocker-composeOIDC、SAML、LDAP、代理認證中等Casdoor容器或二進制OIDC 為主中等如果只是兩三個應用并且只做簡單登錄用 Authelia 會更輕概念也更少。一旦開始考慮多協議、用戶分組、MFA、審批流程、審計日志這些“組織級需求”authentik 的組件化設計才更有優勢。我個人的體會是authentik 的復雜度屬于“需要理解流程和策略但不需要像 Keycloak 那樣配置大量領域模型”的程度。2. 部署之前環境、資源、網絡策略要確定的內容2.1 我推薦的最低資源邊界直接給結論我個人的最低推薦是 2 核 CPU、4G 內存、40G 以上磁盤。更低配置能不能跑能跑通但數據庫連接、worker 后臺任務和頁面響應速度都會變差。如果只是 docker-compose 啟一個學習環境1G 內存也未必起不來但我不建議拿這種配置去做真實的日常認證服務。資源占用和接入應用的數量有關。10 個以內應用的統一登錄上面的配置一般夠用。如果是幾十個應用、每天大量登錄跳轉就要關注 PostgreSQL 的連接數、Redis 的緩存命中率和 worker 的任務堆積情況。我一般會先用小規模跑幾天再根據內存和 CPU 曲線決定是否需要擴容。2.2 域名、反代端口和 HTTPS 策略authentik 啟動后默認會同時監聽 HTTP 9000 和 HTTPS 9443 兩個端口。容器內部的配置是這樣實際部署時我通常不會直接對外暴露這兩個端口而是在前面放一層 Nginx 或 Caddy把 443 端口的請求轉發到 9000。這里要提前統一一個判斷標準所有回調地址、Provider 地址、應用跳轉地址盡量使用同一個對外域名不要一會兒用 IP一會兒用內網域名。OIDC 對回調地址、Host 頭、Scheme 非常敏感域名和端口不一致是最常見的登錄失敗原因。HTTPS 建議直接交給反向代理處理內部 9000 端口保持 HTTP 即可。如果反代配置不正確最常見的問題是回調地址被寫成了http://127.0.0.1:9000導致登錄成功后回不到應用。2.3 持久化目錄和備份邊界PostgreSQL 和 Redis 都涉及數據持久化。PostgreSQL 存用戶、權限、Flow、Stage、Provider 這類核心數據Redis 主要存會話和緩存。Redis 丟了可以恢復PostgreSQL 丟了就等于整個認證體系重建。我部署時會把持久化目錄單獨拎出來比如/data/authentik/postgresql、/data/authentik/redis而不是讓 Docker 默認 volume 埋在系統盤里。這樣后面備份、遷移、升級時目錄結構一眼就能看明白。3. 最小落地部署docker-compose 跑起來3.1 準備 .env 環境變量authentik 官方推薦用 docker-compose 部署。環境變量中最重要的是密鑰和數據庫配置。authentik 會把環境變量里AUTHENTIK_開頭、用雙下劃線分隔的部分映射成配置項例如AUTHENTIK_SECRET_KEY對應全局密鑰AUTHENTIK_POSTGRESQL__HOST對應 PostgreSQL 地址。生成密鑰可以用這樣一條命令openssl rand -base64 48把輸出結果填到.env文件里。示例結構大致如下AUTHENTIK_SECRET_KEY這里填上面命令生成的一長串隨機值 AUTHENTIK_POSTGRESQL__PASSWORD獨立創建一個數據庫密碼 AUTHENTIK_REDIS__HOSTredis注意.env文件的換行和引號會影響讀取不要粘貼之后隨手加空格。密鑰一旦生成后續升級和恢復都要使用同一個值不能隨便更換。3.2 一個可參考的 docker-compose 服務結構下面這個 YAML 是演示用結構具體鏡像版本和參數以官方倉庫最新的 compose 文件為準services: postgresql: image: docker.io/library/postgres:16-alpine environment: POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} volumes: - /data/authentik/postgresql:/var/lib/postgresql/data restart: unless-stopped redis: image: docker.io/library/redis:7-alpine volumes: - /data/authentik/redis:/data restart: unless-stopped server: image: ghcr.io/goauthentik/server:latest command: server environment: AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} AUTHENTIK_REDIS__HOST: redis ports: - 9000:9000 - 9443:9443 depends_on: - postgresql - redis restart: unless-stopped worker: image: ghcr.io/goauthentik/server:latest command: worker environment: AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} AUTHENTIK_REDIS__HOST: redis depends_on: - postgresql - redis restart: unless-stopped實際使用時要特別注意server 和 worker 必須使用同一個鏡像版本避免出現 API 和后臺任務邏輯不一致的情況。3.3 啟動順序和驗證先把目錄和.env文件準備好然后執行docker compose up -d docker compose ps如果服務沒有全部進入 running 狀態不要急著配置頁面先看日志docker compose logs -f server docker compose logs -f worker首次啟動通常會有數據庫初始化和遷移過程日志里出現大量遷移輸出是正常的需要耐心等。啟動完成后瀏覽器訪問http://服務器IP:9000。如果一切正常應該能看到 authentik 的引導頁面用于創建初始管理員賬號如果你在環境變量里預置了 bootstrap 管理員相關的配置也會自動完成初始化。注意第一次打開時不要一上來就反復刷新。如果服務還在遷移數據庫頁面可能會短暫不可用等日志穩定后再試。4. 第一次真正接入應用OIDC/OAuth2 流程拆解4.1 在 authentik 里新建 Provider 和應用authentik 管理后臺分為 Admin 和 User 兩個入口。Admin 界面用于配置User 界面是普通用戶登錄后的門戶。接入一個支持 OIDC 的應用要先創建 Provider。Provider 是技術服務端它定義了使用什么協議、回調地址、客戶端類型。創建完成后authentik 會生成對應的 Client ID 和 Client Secret這兩個值要復制給第三方應用使用。然后創建 Application。Application 是面向用戶的可視化入口可以配置名稱、圖標、顯示位置并且必須綁定一個 Provider。綁定之后用戶登錄門戶里才會出現這個應用圖標點擊圖標才能跳轉到第三方應用。這里經常有一個理解偏差Provider 是協議層面的“服務端”Application 是展示層面的“應用入口”兩者不是一回事。如果只創建 Provider 不創建 Application外部應用可能仍然能調通但用戶門戶里不會出現入口排查時會一頭霧水。4.2 第三方應用側要填哪些地址支持 OIDC 的應用一般需要配置這幾項授權地址/application/o/authorize/Token 地址/application/o/token/用戶信息地址/application/o/userinfo/回調地址必須和 Provider 里的 Redirect URI 完全一致完整 URL 由你自己的對外域名拼接而成例如https://auth.example.com/application/o/authorize/。不是所有客戶端的字段名稱都叫“授權地址”有的叫 Authorization Endpoint有的叫 Login URL但含義一致。常見的不兼容情況是末尾斜杠不一致。比如 Provider 里填了https://app.example.com/callback第三方應用里卻寫成https://app.example.com/callback/OIDC 會嚴格判斷這兩個地址不相同導致認證失敗。4.3 驗證登錄流程的方法先用一個不影響生產的小應用驗證建議流程如下未登錄狀態下打開第三方應用。應用跳轉回 authentik 登錄頁。用戶輸入用戶名密碼。瀏覽器跳回應用應用拿到 token。應用請求用戶信息并建立本地會話。整個過程中最重要的是觀察瀏覽器 Network 面板里的 302 跳轉順序。正常情況下請求會從第三方應用跳到 authentik 的 authorize 地址再跳回應用的回調地址。如果回調地址匹配不上瀏覽器會直接顯示“Invalid redirect URI”或類似的錯誤提示。提示第一次接入時先不要強制 MFA也不要隱藏注冊入口先用默認登錄流程跑通再逐層加策略。5. 深入 authentik 的核心概念Flow、Stage、Policy、Outpost5.1 Flow 和 Stage 是認證流程的骨架authentik 和其他簡單認證工具最大的不同是它把登錄邏輯拆成了 Flow 和 Stage。Flow 可以理解成一條認證流水線比如“登錄流程”“注冊流程”“密碼找回流程”。Stage 是流水線上的一個具體環節比如“用戶名密碼校驗”“TOTP 校驗”“WebAuthn 校驗”“寫入 Session”。默認的登錄 Flow 看起來可能只是一個登錄框其實背后是由多個 Stage 組成的。自定義場景時可以插入一個新的 Stage比如在密碼校驗之后加一個“必須完成 MFA”的階段。理解了這個模型很多看似復雜的需求就會變成“在哪個 Flow 的哪個位置插入什么 Stage”的問題。5.2 Policy 和 Binding 決定誰能通過Policy 是 authentik 里的判斷規則。它可以綁定到 Flow、Stage、Application、Provider 上決定當前用戶或當前請求是否滿足繼續執行的條件。常見的 Policy 有用戶是否屬于某個組屬性是否滿足表達式是否已經完成 MFA請求 IP 或瀏覽器信息判斷Binding 指的是“把 Policy 綁定到某個對象”的動作。比如你要實現“只允許運維組訪問 Grafana”可以在 Application 綁定一個用戶組策略效果比在 Provider 里寫死更靈活。Provider 只管協議Application 管訪問控制后面換協議時不需要重寫權限。5.3 Outpost 是連接外部代理認證的組件Outpost 是 authentik 用來管理某些外部服務連接的組件使用代理 Provider 時需要部署。它的作用大致是作為反向代理認證的后端接收請求檢查 authentik 的會話狀態沒有登錄就跳轉登錄頁登錄后放行并把用戶信息傳給后端應用。學習階段可以先不碰 Outpost。先通過 OIDC 接入一兩個應用理解 Flow 和 Policy 之后再去看代理認證會更順。否則上來就部署 Outpost概念疊加在一起出了問題很難定位是 Outpost 連不上 authentik還是反代配置轉發錯地址。6. 擴展能力MFA、LDAP、反向代理認證6.1 MFA 的強制和測試方式authentik 支持 TOTP 驗證碼、WebAuthn 通行密鑰、DUO 等。我的建議是先以 TOTP 或 WebAuthn 為主因為它們不需要額外的第三方服務。配置 MFA 的路徑通常可以這樣理解在登錄 Flow 里加入 MFA Stage并通過 Policy 判斷“用戶是否已經綁定 MFA 設備”。如果用戶沒綁定先跳轉注冊 MFA 的階段如果已綁定直接驗證即可。關鍵點是不要一上來就把 MFA 設為全局強制。先在一個測試用戶身上驗證完整流程確認用戶綁定、登錄、解綁都正常再逐步放開策略。否則批量用戶登錄時才發現設備綁定失敗會造成大面積登錄卡頓。6.2 LDAP Provider 適合哪些場景LDAP 適合那些不支持 OIDC/SAML 的應用比如一些舊系統只允許配置 LDAP 地址和 bind 賬號。authentik 提供 LDAP Provider 后會生成一個對外的 LDAP 地址和端口外部應用可以通過它讀取用戶目錄和校驗密碼。使用 LDAP Provider 時需要把 base DN、bind DN、密碼這些信息填到外部應用里。這里要提前糾正一個預期authentik 的 LDAP 主要用于用戶認證和基礎目錄查詢不是完整的企業 AD復雜目錄同步、Exchange 集成這類功能不要過度期待。它能把 authentik 的用戶帶到支持 LDAP 的應用里但目錄數據結構相對簡潔。6.3 反向代理認證接入思路反向代理認證適合的場景是應用不支持 OIDC/SAML但可以通過統一網關轉發。部署方式大致是創建一個 Proxy Provider填寫你要保護的外部域名再部署 outpost由 outpost 監聽一個本地端口反向代理把需要保護的路徑轉發到 outpost由 outpost 判斷會話。認證成功之后后端應用會從請求頭里讀到 authentik 寫入的用戶信息例如用戶名、郵箱、組。使用這個模式時要注意反代必須把原始 Host 頭和用戶請求 IP 透傳給 outpost否則 Cookie 校驗和會話識別可能失敗。7. 排查鏈路啟動失敗、登錄回跳、回調報錯的定位順序7.1 容器起不來先看數據庫和 Redis遇到容器起不來不要先懷疑 authentik 本身先按這個順序查docker compose ps看哪些服務是 restarting。docker compose logs postgresql看數據庫是否正常啟動。docker compose logs redis看緩存是否正常。docker compose logs server看 authentik 的報錯信息。最常見的問題是 PostgreSQL 密碼不一致。比如.env里的AUTHENTIK_POSTGRESQL__PASSWORD和 compose 文件中POSTGRES_PASSWORD取值不一致導致 server 連接數據庫失敗。另一個常見問題是AUTHENTIK_SECRET_KEY為空或在遷移后更換了所有簽名和加密信息都會失效。這里我遇到過最多的情況是容器一直 restarting日志里提示數據庫連接被拒絕。改完密碼統一之后啟動就正常了和 authentik 本身的鏡像沒有任何關系。7.2 登錄后回不到應用回調地址和 Host 頭優先登錄后回不到第三方應用90% 是回調地址不一致。檢查三個位置authentik Provider 里的 Redirect URI。第三方應用里配置的 Redirect URI。瀏覽器網絡請求里實際跳轉的 redirect_uri 參數。三個必須完全一致包括協議、域名、端口、路徑、末尾斜杠。另外一種情況是反向代理沒有保留 Host 頭。Nginx 中至少要設置proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr;如果 Host 頭不對OIDC 的 issuer 和回調拼接就會出錯表現是頁面能打開但跳轉后報錯或循環重定向。7.3 頁面能進但沒有用戶或權限不對登錄頁面能正常打開但用戶登錄后看不到應用或者訪問應用被拒絕優先檢查授權邏輯。用戶是通過注冊流程創建的還是通過 LDAP 同步的。用戶是否綁定了正確的組。Application 上綁定了哪些 Policy是否限制了用戶組。注冊流程是否默認禁用或要求審批。這類問題通常不會出現在 server 日志里而會出現在 worker 日志中。可以執行docker compose logs -f workerworker 負責執行策略和流程階段權限判斷失敗時往往能在里面看到對應錯誤。7.4 會話失效和 Cookie 設置使用 HTTPS 反代時Cookie 的 Secure 屬性會影響瀏覽器是否發送 Cookie。如果反代配置了 HTTPS但 authentik 認為自己運行在 HTTP 環境可能不會設置 Secure Cookie瀏覽器端行為會變得奇怪。處理辦法是確保反代正確傳遞X-Forwarded-Proto并且在瀏覽器開發者工具里查看Set-Cookie和后續請求的Cookie頭確認域名、路徑、Secure 屬性都符合預期。8. 生產化之前務必確認的幾個邊界8.1 版本固定和升級順序學習環境可以直接使用 latest 鏡像但生產環境不建議長期跟隨 latest。每次升級都可能導致數據遷移不固定的版本會讓環境難以重現。我建議的升級順序是備份 PostgreSQL。記錄當前版本號。查看官方升級說明確認有沒有特殊的遷移步驟。修改鏡像版本標簽。執行docker compose up -d。觀察 server 和 worker 日志。用測試賬號完成一次完整登錄。升級完成后不要馬上把舊版本鏡像刪掉保留一份備用確認運行幾天沒問題再清理。8.2 備份策略要覆蓋數據庫和密鑰備份 authentik最核心的是備份 PostgreSQL 數據庫。可以用pg_dump導出也可以直接快照數據庫目錄。Redis 數據是緩存和會話丟失后用戶會重新登錄一般不作為關鍵備份對象。比數據庫更隱蔽的是.env里的密鑰。AUTHENTIK_SECRET_KEY如果丟失或更換所有基于簽名的 token、會話、授權碼都會失效。恢復舊數據庫時必須使用舊的密鑰否則業務無法銜接。備份時可以把.env單獨保存到安全位置不要寫進博客或倉庫明文。8.3 什么時候不建議上 authentik如果你的場景只有兩三個內部系統并且所有系統都只是簡單登錄直接上 authentik 會有一種“殺雞用牛刀”的感覺。Flow、Stage、Application、Policy 這些概念需要學習成本維護也需要額外精力。這種情況下使用更輕量的單容器認證轉發工具能把問題更快解決。反過來如果團隊已經有很多應用協議需求混雜還需要分組授權、MFA、統一審計這時 authentik 的組件化設計才會真正體現出價值。它的復雜度不是無意義的只是要把配置成本和長期收益一起評估。我自己的體會是先跑通默認 Flow再考慮 MFA 和 LDAP先接一個 OIDC 應用再想批量接入。踩過幾次之后我發現很多問題不是 authentik 能力不夠而是前置環境、域名、回調地址和密鑰沒有處理干凈。只要把這些基礎項盯住這套系統能穩定承擔整個內部應用體系的登錄入口。 goauthentik/authentik部署指南：用OIDC與LDAP搭建統一登錄中心
goauthentik / authentik 這個項目我會直接把它當成一套自建系統的統一登錄入口來用。它是一個開源的、基于 Go 實現的身份認證和單點登錄平臺也就是常說的 IdP核心解決的是“一套賬號登錄多個內部應用”的問題。如果你手頭有 NAS、代碼倉庫、監控面板、運維平臺這類系統不想每個地方單獨維護一套用戶名密碼authentik 值得先跑一遍。它最值得關注的點不是某個花哨的界面功能而是把登錄、授權、MFA、LDAP 目錄服務都集中到了同一個地方并且能通過標準協議和外部應用對接。下面按我從零部署到接入應用的路徑把關鍵步驟和容易踩的坑拆開說。1. 先搞懂 goauthentik / authentik 在認證體系里的位置1.1 goauthentik 和 authentik 是什么關系項目標題里的 goauthentik 并不是某個分支版本而是 authentik 在 GitHub 上的組織和倉庫名。簡單說goauthentik/authentik 就是這個項目的源碼倉庫平時大家討論的 authentik 產品本身也來自這里。后端選擇 Go帶來的直接好處是部署體量和內存占用比不少 Java 系身份認證產品輕。實際跑起來之后一個 docker-compose 項目里會同時出現多個服務包括 server、worker、PostgreSQL、Redis。server 負責對外提供 API 和頁面worker 負責執行后臺任務比如策略判斷、流處理、憑證校驗。兩者共用同一個鏡像只是啟動命令不同。剛開始接觸時不要以為“goauthentik”是一個只靠單一二進制就包打天下的工具它仍然需要依賴數據庫和緩存這一點要先有預期。1.2 它適合放在什么位置authentik 在自托管體系里的定位可以概括成一句話面向應用提供認證能力面向用戶提供統一登錄入口。它常見的落地方式有三種作為 OIDC/OAuth2 服務端讓 Grafana、GitLab、Nextcloud 這類支持標準協議的應用跳轉登錄。作為 LDAP 認證源給只支持 LDAP 的老系統或網絡設備提供用戶校驗。作為反向代理認證網關在 Nginx 或 Traefik 后面統一攔截未登錄請求。它和同類方案經常放在一起對比我看到的典型選擇可以整理成一個表格方案部署方式協議廣度配置復雜度Authelia單容器或二進制重定向認證為主較簡單低Keycloak容器或獨立服務OIDC、SAML高功能重authentikdocker-composeOIDC、SAML、LDAP、代理認證中等Casdoor容器或二進制OIDC 為主中等如果只是兩三個應用并且只做簡單登錄用 Authelia 會更輕概念也更少。一旦開始考慮多協議、用戶分組、MFA、審批流程、審計日志這些“組織級需求”authentik 的組件化設計才更有優勢。我個人的體會是authentik 的復雜度屬于“需要理解流程和策略但不需要像 Keycloak 那樣配置大量領域模型”的程度。2. 部署之前環境、資源、網絡策略要確定的內容2.1 我推薦的最低資源邊界直接給結論我個人的最低推薦是 2 核 CPU、4G 內存、40G 以上磁盤。更低配置能不能跑能跑通但數據庫連接、worker 后臺任務和頁面響應速度都會變差。如果只是 docker-compose 啟一個學習環境1G 內存也未必起不來但我不建議拿這種配置去做真實的日常認證服務。資源占用和接入應用的數量有關。10 個以內應用的統一登錄上面的配置一般夠用。如果是幾十個應用、每天大量登錄跳轉就要關注 PostgreSQL 的連接數、Redis 的緩存命中率和 worker 的任務堆積情況。我一般會先用小規模跑幾天再根據內存和 CPU 曲線決定是否需要擴容。2.2 域名、反代端口和 HTTPS 策略authentik 啟動后默認會同時監聽 HTTP 9000 和 HTTPS 9443 兩個端口。容器內部的配置是這樣實際部署時我通常不會直接對外暴露這兩個端口而是在前面放一層 Nginx 或 Caddy把 443 端口的請求轉發到 9000。這里要提前統一一個判斷標準所有回調地址、Provider 地址、應用跳轉地址盡量使用同一個對外域名不要一會兒用 IP一會兒用內網域名。OIDC 對回調地址、Host 頭、Scheme 非常敏感域名和端口不一致是最常見的登錄失敗原因。HTTPS 建議直接交給反向代理處理內部 9000 端口保持 HTTP 即可。如果反代配置不正確最常見的問題是回調地址被寫成了http://127.0.0.1:9000導致登錄成功后回不到應用。2.3 持久化目錄和備份邊界PostgreSQL 和 Redis 都涉及數據持久化。PostgreSQL 存用戶、權限、Flow、Stage、Provider 這類核心數據Redis 主要存會話和緩存。Redis 丟了可以恢復PostgreSQL 丟了就等于整個認證體系重建。我部署時會把持久化目錄單獨拎出來比如/data/authentik/postgresql、/data/authentik/redis而不是讓 Docker 默認 volume 埋在系統盤里。這樣后面備份、遷移、升級時目錄結構一眼就能看明白。3. 最小落地部署docker-compose 跑起來3.1 準備 .env 環境變量authentik 官方推薦用 docker-compose 部署。環境變量中最重要的是密鑰和數據庫配置。authentik 會把環境變量里AUTHENTIK_開頭、用雙下劃線分隔的部分映射成配置項例如AUTHENTIK_SECRET_KEY對應全局密鑰AUTHENTIK_POSTGRESQL__HOST對應 PostgreSQL 地址。生成密鑰可以用這樣一條命令openssl rand -base64 48把輸出結果填到.env文件里。示例結構大致如下AUTHENTIK_SECRET_KEY這里填上面命令生成的一長串隨機值 AUTHENTIK_POSTGRESQL__PASSWORD獨立創建一個數據庫密碼 AUTHENTIK_REDIS__HOSTredis注意.env文件的換行和引號會影響讀取不要粘貼之后隨手加空格。密鑰一旦生成后續升級和恢復都要使用同一個值不能隨便更換。3.2 一個可參考的 docker-compose 服務結構下面這個 YAML 是演示用結構具體鏡像版本和參數以官方倉庫最新的 compose 文件為準services: postgresql: image: docker.io/library/postgres:16-alpine environment: POSTGRES_PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} volumes: - /data/authentik/postgresql:/var/lib/postgresql/data restart: unless-stopped redis: image: docker.io/library/redis:7-alpine volumes: - /data/authentik/redis:/data restart: unless-stopped server: image: ghcr.io/goauthentik/server:latest command: server environment: AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} AUTHENTIK_REDIS__HOST: redis ports: - 9000:9000 - 9443:9443 depends_on: - postgresql - redis restart: unless-stopped worker: image: ghcr.io/goauthentik/server:latest command: worker environment: AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__PASSWORD: ${AUTHENTIK_POSTGRESQL__PASSWORD} AUTHENTIK_REDIS__HOST: redis depends_on: - postgresql - redis restart: unless-stopped實際使用時要特別注意server 和 worker 必須使用同一個鏡像版本避免出現 API 和后臺任務邏輯不一致的情況。3.3 啟動順序和驗證先把目錄和.env文件準備好然后執行docker compose up -d docker compose ps如果服務沒有全部進入 running 狀態不要急著配置頁面先看日志docker compose logs -f server docker compose logs -f worker首次啟動通常會有數據庫初始化和遷移過程日志里出現大量遷移輸出是正常的需要耐心等。啟動完成后瀏覽器訪問http://服務器IP:9000。如果一切正常應該能看到 authentik 的引導頁面用于創建初始管理員賬號如果你在環境變量里預置了 bootstrap 管理員相關的配置也會自動完成初始化。注意第一次打開時不要一上來就反復刷新。如果服務還在遷移數據庫頁面可能會短暫不可用等日志穩定后再試。4. 第一次真正接入應用OIDC/OAuth2 流程拆解4.1 在 authentik 里新建 Provider 和應用authentik 管理后臺分為 Admin 和 User 兩個入口。Admin 界面用于配置User 界面是普通用戶登錄后的門戶。接入一個支持 OIDC 的應用要先創建 Provider。Provider 是技術服務端它定義了使用什么協議、回調地址、客戶端類型。創建完成后authentik 會生成對應的 Client ID 和 Client Secret這兩個值要復制給第三方應用使用。然后創建 Application。Application 是面向用戶的可視化入口可以配置名稱、圖標、顯示位置并且必須綁定一個 Provider。綁定之后用戶登錄門戶里才會出現這個應用圖標點擊圖標才能跳轉到第三方應用。這里經常有一個理解偏差Provider 是協議層面的“服務端”Application 是展示層面的“應用入口”兩者不是一回事。如果只創建 Provider 不創建 Application外部應用可能仍然能調通但用戶門戶里不會出現入口排查時會一頭霧水。4.2 第三方應用側要填哪些地址支持 OIDC 的應用一般需要配置這幾項授權地址/application/o/authorize/Token 地址/application/o/token/用戶信息地址/application/o/userinfo/回調地址必須和 Provider 里的 Redirect URI 完全一致完整 URL 由你自己的對外域名拼接而成例如https://auth.example.com/application/o/authorize/。不是所有客戶端的字段名稱都叫“授權地址”有的叫 Authorization Endpoint有的叫 Login URL但含義一致。常見的不兼容情況是末尾斜杠不一致。比如 Provider 里填了https://app.example.com/callback第三方應用里卻寫成https://app.example.com/callback/OIDC 會嚴格判斷這兩個地址不相同導致認證失敗。4.3 驗證登錄流程的方法先用一個不影響生產的小應用驗證建議流程如下未登錄狀態下打開第三方應用。應用跳轉回 authentik 登錄頁。用戶輸入用戶名密碼。瀏覽器跳回應用應用拿到 token。應用請求用戶信息并建立本地會話。整個過程中最重要的是觀察瀏覽器 Network 面板里的 302 跳轉順序。正常情況下請求會從第三方應用跳到 authentik 的 authorize 地址再跳回應用的回調地址。如果回調地址匹配不上瀏覽器會直接顯示“Invalid redirect URI”或類似的錯誤提示。提示第一次接入時先不要強制 MFA也不要隱藏注冊入口先用默認登錄流程跑通再逐層加策略。5. 深入 authentik 的核心概念Flow、Stage、Policy、Outpost5.1 Flow 和 Stage 是認證流程的骨架authentik 和其他簡單認證工具最大的不同是它把登錄邏輯拆成了 Flow 和 Stage。Flow 可以理解成一條認證流水線比如“登錄流程”“注冊流程”“密碼找回流程”。Stage 是流水線上的一個具體環節比如“用戶名密碼校驗”“TOTP 校驗”“WebAuthn 校驗”“寫入 Session”。默認的登錄 Flow 看起來可能只是一個登錄框其實背后是由多個 Stage 組成的。自定義場景時可以插入一個新的 Stage比如在密碼校驗之后加一個“必須完成 MFA”的階段。理解了這個模型很多看似復雜的需求就會變成“在哪個 Flow 的哪個位置插入什么 Stage”的問題。5.2 Policy 和 Binding 決定誰能通過Policy 是 authentik 里的判斷規則。它可以綁定到 Flow、Stage、Application、Provider 上決定當前用戶或當前請求是否滿足繼續執行的條件。常見的 Policy 有用戶是否屬于某個組屬性是否滿足表達式是否已經完成 MFA請求 IP 或瀏覽器信息判斷Binding 指的是“把 Policy 綁定到某個對象”的動作。比如你要實現“只允許運維組訪問 Grafana”可以在 Application 綁定一個用戶組策略效果比在 Provider 里寫死更靈活。Provider 只管協議Application 管訪問控制后面換協議時不需要重寫權限。5.3 Outpost 是連接外部代理認證的組件Outpost 是 authentik 用來管理某些外部服務連接的組件使用代理 Provider 時需要部署。它的作用大致是作為反向代理認證的后端接收請求檢查 authentik 的會話狀態沒有登錄就跳轉登錄頁登錄后放行并把用戶信息傳給后端應用。學習階段可以先不碰 Outpost。先通過 OIDC 接入一兩個應用理解 Flow 和 Policy 之后再去看代理認證會更順。否則上來就部署 Outpost概念疊加在一起出了問題很難定位是 Outpost 連不上 authentik還是反代配置轉發錯地址。6. 擴展能力MFA、LDAP、反向代理認證6.1 MFA 的強制和測試方式authentik 支持 TOTP 驗證碼、WebAuthn 通行密鑰、DUO 等。我的建議是先以 TOTP 或 WebAuthn 為主因為它們不需要額外的第三方服務。配置 MFA 的路徑通常可以這樣理解在登錄 Flow 里加入 MFA Stage并通過 Policy 判斷“用戶是否已經綁定 MFA 設備”。如果用戶沒綁定先跳轉注冊 MFA 的階段如果已綁定直接驗證即可。關鍵點是不要一上來就把 MFA 設為全局強制。先在一個測試用戶身上驗證完整流程確認用戶綁定、登錄、解綁都正常再逐步放開策略。否則批量用戶登錄時才發現設備綁定失敗會造成大面積登錄卡頓。6.2 LDAP Provider 適合哪些場景LDAP 適合那些不支持 OIDC/SAML 的應用比如一些舊系統只允許配置 LDAP 地址和 bind 賬號。authentik 提供 LDAP Provider 后會生成一個對外的 LDAP 地址和端口外部應用可以通過它讀取用戶目錄和校驗密碼。使用 LDAP Provider 時需要把 base DN、bind DN、密碼這些信息填到外部應用里。這里要提前糾正一個預期authentik 的 LDAP 主要用于用戶認證和基礎目錄查詢不是完整的企業 AD復雜目錄同步、Exchange 集成這類功能不要過度期待。它能把 authentik 的用戶帶到支持 LDAP 的應用里但目錄數據結構相對簡潔。6.3 反向代理認證接入思路反向代理認證適合的場景是應用不支持 OIDC/SAML但可以通過統一網關轉發。部署方式大致是創建一個 Proxy Provider填寫你要保護的外部域名再部署 outpost由 outpost 監聽一個本地端口反向代理把需要保護的路徑轉發到 outpost由 outpost 判斷會話。認證成功之后后端應用會從請求頭里讀到 authentik 寫入的用戶信息例如用戶名、郵箱、組。使用這個模式時要注意反代必須把原始 Host 頭和用戶請求 IP 透傳給 outpost否則 Cookie 校驗和會話識別可能失敗。7. 排查鏈路啟動失敗、登錄回跳、回調報錯的定位順序7.1 容器起不來先看數據庫和 Redis遇到容器起不來不要先懷疑 authentik 本身先按這個順序查docker compose ps看哪些服務是 restarting。docker compose logs postgresql看數據庫是否正常啟動。docker compose logs redis看緩存是否正常。docker compose logs server看 authentik 的報錯信息。最常見的問題是 PostgreSQL 密碼不一致。比如.env里的AUTHENTIK_POSTGRESQL__PASSWORD和 compose 文件中POSTGRES_PASSWORD取值不一致導致 server 連接數據庫失敗。另一個常見問題是AUTHENTIK_SECRET_KEY為空或在遷移后更換了所有簽名和加密信息都會失效。這里我遇到過最多的情況是容器一直 restarting日志里提示數據庫連接被拒絕。改完密碼統一之后啟動就正常了和 authentik 本身的鏡像沒有任何關系。7.2 登錄后回不到應用回調地址和 Host 頭優先登錄后回不到第三方應用90% 是回調地址不一致。檢查三個位置authentik Provider 里的 Redirect URI。第三方應用里配置的 Redirect URI。瀏覽器網絡請求里實際跳轉的 redirect_uri 參數。三個必須完全一致包括協議、域名、端口、路徑、末尾斜杠。另外一種情況是反向代理沒有保留 Host 頭。Nginx 中至少要設置proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-For $remote_addr;如果 Host 頭不對OIDC 的 issuer 和回調拼接就會出錯表現是頁面能打開但跳轉后報錯或循環重定向。7.3 頁面能進但沒有用戶或權限不對登錄頁面能正常打開但用戶登錄后看不到應用或者訪問應用被拒絕優先檢查授權邏輯。用戶是通過注冊流程創建的還是通過 LDAP 同步的。用戶是否綁定了正確的組。Application 上綁定了哪些 Policy是否限制了用戶組。注冊流程是否默認禁用或要求審批。這類問題通常不會出現在 server 日志里而會出現在 worker 日志中。可以執行docker compose logs -f workerworker 負責執行策略和流程階段權限判斷失敗時往往能在里面看到對應錯誤。7.4 會話失效和 Cookie 設置使用 HTTPS 反代時Cookie 的 Secure 屬性會影響瀏覽器是否發送 Cookie。如果反代配置了 HTTPS但 authentik 認為自己運行在 HTTP 環境可能不會設置 Secure Cookie瀏覽器端行為會變得奇怪。處理辦法是確保反代正確傳遞X-Forwarded-Proto并且在瀏覽器開發者工具里查看Set-Cookie和后續請求的Cookie頭確認域名、路徑、Secure 屬性都符合預期。8. 生產化之前務必確認的幾個邊界8.1 版本固定和升級順序學習環境可以直接使用 latest 鏡像但生產環境不建議長期跟隨 latest。每次升級都可能導致數據遷移不固定的版本會讓環境難以重現。我建議的升級順序是備份 PostgreSQL。記錄當前版本號。查看官方升級說明確認有沒有特殊的遷移步驟。修改鏡像版本標簽。執行docker compose up -d。觀察 server 和 worker 日志。用測試賬號完成一次完整登錄。升級完成后不要馬上把舊版本鏡像刪掉保留一份備用確認運行幾天沒問題再清理。8.2 備份策略要覆蓋數據庫和密鑰備份 authentik最核心的是備份 PostgreSQL 數據庫。可以用pg_dump導出也可以直接快照數據庫目錄。Redis 數據是緩存和會話丟失后用戶會重新登錄一般不作為關鍵備份對象。比數據庫更隱蔽的是.env里的密鑰。AUTHENTIK_SECRET_KEY如果丟失或更換所有基于簽名的 token、會話、授權碼都會失效。恢復舊數據庫時必須使用舊的密鑰否則業務無法銜接。備份時可以把.env單獨保存到安全位置不要寫進博客或倉庫明文。8.3 什么時候不建議上 authentik如果你的場景只有兩三個內部系統并且所有系統都只是簡單登錄直接上 authentik 會有一種“殺雞用牛刀”的感覺。Flow、Stage、Application、Policy 這些概念需要學習成本維護也需要額外精力。這種情況下使用更輕量的單容器認證轉發工具能把問題更快解決。反過來如果團隊已經有很多應用協議需求混雜還需要分組授權、MFA、統一審計這時 authentik 的組件化設計才會真正體現出價值。它的復雜度不是無意義的只是要把配置成本和長期收益一起評估。我自己的體會是先跑通默認 Flow再考慮 MFA 和 LDAP先接一個 OIDC 應用再想批量接入。踩過幾次之后我發現很多問題不是 authentik 能力不夠而是前置環境、域名、回調地址和密鑰沒有處理干凈。只要把這些基礎項盯住這套系統能穩定承擔整個內部應用體系的登錄入口。