这次我们来看 goauthentik 团队开源的 authentik。它是一套自托管的身份认证平台也就是常说的 IdPIdentity Provider。通俗讲它把多套系统的用户认证、账号管理、单点登录、MFA 双重验证、权限策略和审计日志集中到一个平台里让内部系统不再各自维护一套用户表。它能解决什么实际问题比如公司有 GitLab、Grafana、Jenkins、内部 Wiki 好几套系统员工希望登录一次就能全部访问而不是每个系统单独建账号再比如对外做的客户门户需要统一管理注册、登录、找回密码、强制二次验证这些需求都可以交给 authentik 统一收口。很多人在评估 authentik 时会拿它和 Keycloak 对比。从功能面上看authentik 覆盖了主流协议OAuth2 / OIDC、SAML、LDAP 都支持自带管理 Web UI不依赖外部 SaaS并且提供了 Proxy 代理认证、Flow 流程编排、策略引擎、审计日志。部署方式以 Docker Compose 为主已经用 Docker 的团队上手成本不高。这篇文章会按从零部署的完整流程展开先看核心能力再列环境准备然后走一遍 Docker Compose 启动接着测试用户创建、OIDC 接入、代理认证、API 调用最后给出资源占用观察、常见排查方法和工程化建议。适合正在评估自建统一登录平台、想把内部系统改成 SSO 接入或者需要理解 authentik 工作原理的开发、运维同学。1. 核心能力速览能力项说明项目类型开源身份认证平台 / IdP / SSO开源地址goauthentik/authentik主要功能统一认证、单点登录、用户与组管理、MFA、应用接入、Flow 流程、策略、审计日志支持的协议OAuth2 / OIDC、SAML、LDAP部署方式Docker Compose、Kubernetes Helm、源码方式核心组件Server、Worker、PostgreSQL、Redis、Outposts管理界面Web UI默认 HTTP 9000 / HTTPS 9443 端口API 能力/api/v3/ REST 接口支持 Token 认证批量能力可通过 API 或管理后台批量创建用户、导出导入配置适合场景内部系统统一登录、客户门户认证、API 权限认证、身份数据统一管理许可证社区版 AGPL-3.0另外提供商业企业版1.1 和传统自建账号体系的差异传统做法是每个业务系统自己维护用户表自己写登录、注册、找回密码逻辑。问题很直接员工离职要逐个系统禁用账号密码策略难以统一审计日志分散多系统之间也无法实现一次登录处处访问。authentik 这类身份认证平台把“认证”这个环节独立出来。业务系统不再存密码只需要按 OIDC、SAML 或 LDAP 协议对接 authentik用户数据、密码策略、MFA、审计日志都由平台统一承担。接多少个应用认证入口都是同一个。1.2 核心组件组成从部署结构看authentik 不是单体进程而是由多个组件组成。Server 承担 Web 管理界面和 APIWorker 处理后台任务比如邮件发送、事件处理、流程执行PostgreSQL 存用户、组、流程、策略等结构化数据Redis 提供缓存和 session 支持Outposts 是部署到业务网络里的代理组件常见用法是给 Nginx 做 ForwardAuth也可以用 LDAP Outpost 对接老系统。理解这个结构很重要因为启动、排错、升级时很多问题都出在组件之间的网络连通和数据一致性上。2. 适用场景与使用边界2.1 适合什么人用手上有多个内部系统想统一登录入口的团队。需要对外提供注册、登录、找回密码、MFA 能力的站点或应用。想按照标准协议接入 OIDC、SAML 的开发者。需要做身份权限统一管理和审计的运维人员。2.2 不适合什么场景只有一个静态网站或博客单独搭一套 SSO 平台过重。只有单一业务系统、没有多应用统一认证需求直接用简单账号体系更省成本。团队对自托管维护成本敏感希望用云厂商托管的身份服务那后者更合适。authentik 提供 LDA P/OIDC 接入但本身并不解决业务系统的权限细分问题授权还是要依赖接入方配合。2.3 安全与合规边界身份认证系统涉及用户密码、邮箱、手机号等敏感数据部署时必须注意数据加密、备份和访问控制。生产环境必须配置 HTTPS不能明文传输密码。接入生物识别或其他额外认证因素时要取得用户明确授权并遵守所在地区的数据保护要求。同时要明确authentik 解决的是认证入口不是弱口令治理工具。不要用它去复制、共享其他系统的账号密码也不要用它绕过其他系统的安全策略。离职用户的账号要定期清理长期未用的 API Token 要及时吊销。3. 本地部署环境准备3.1 运行环境清单推荐用 Docker Compose 方式部署最少需要一套能跑 Docker 的机器。参考清单如下操作系统Linux 发行版Debian、Ubuntu、CentOS 均可或 macOSWindows 建议用 WSL2。Docker建议 20.10 以上先执行docker --version确认。Docker Compose建议 v2执行docker compose version确认。内存至少 4GB 可用内存。磁盘预留 10GB 以上空间包含镜像和数据库数据。端口9000 和 9443 空闲可用。域名生产环境准备一个域名并配置 DNS方便申请 HTTPS 证书。这些数值是通用部署建议实际以本机配置和官方文档为准。3.2 端口规划authentik 默认暴露两个管理端口端口用途9000Web 管理界面 HTTP9443Web 管理界面 HTTPSPostgreSQL 的 5432 和 Redis 的 6379 一般在 Compose 网络内部使用不需要强制绑定到宿主机。如果宿主机端口已经被占用需要修改 compose 文件里的端口映射避免启动冲突。3.3 安装 Docker 与 Compose如果机器还没有 Docker先安装基础环境。Ubuntu/Debian 系列可以用官方安装脚本也可以在包管理器里安装。脚本方式要注意来源可信生产环境建议走官方文档的仓库安装流程。安装完成后执行验证docker --version docker compose version4. 安装部署与启动方式4.1 创建部署目录建议在专门的目录下部署方便后续升级和备份。mkdir -p /opt/authentik cd /opt/authentik4.2 compose 文件结构authentik 官方提供的 compose 模板包含四个核心服务PostgreSQL、Redis、Server、Worker。镜像地址通常使用ghcr.io/goauthentik/server。下面是一个结构参考不是直接生产配置具体镜像 tag、环境变量名、数据卷路径要以官方文档为准services: postgresql: image: docker.io/library/postgres:16 environment: POSTGRES_DB: ${PG_DB} POSTGRES_USER: ${PG_USER} POSTGRES_PASSWORD: ${PG_PASS} volumes: - pg_data:/var/lib/postgresql/data restart: unless-stopped redis: image: docker.io/library/redis:7 command: --save 60 1 volumes: - redis_data:/data restart: unless-stopped server: image: ghcr.io/goauthentik/server command: server environment: AUTHENTIK_REDIS__HOST: redis AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__NAME: ${PG_DB} AUTHENTIK_POSTGRESQL__USER: ${PG_USER} AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS} AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_TOKEN: ${AUTHENTIK_TOKEN} AUTHENTIK_URL: ${AUTHENTIK_URL} ports: - ${COMPOSE_PORT_HTTP:-9000}:9000 - ${COMPOSE_PORT_HTTPS:-9443}:9443 volumes: - ./media:/media - ./custom-templates:/templates restart: unless-stopped worker: image: ghcr.io/goauthentik/server command: worker environment: AUTHENTIK_REDIS__HOST: redis AUTHENTIK_POSTGRESQL__HOST: postgresql AUTHENTIK_POSTGRESQL__NAME: ${PG_DB} AUTHENTIK_POSTGRESQL__USER: ${PG_USER} AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS} AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY} AUTHENTIK_TOKEN: ${AUTHENTIK_TOKEN} volumes: - ./media:/media - ./custom-templates:/templates - ./certs:/certs restart: unless-stopped volumes: pg_data: redis_data:4.3 配置 .env 环境变量.env 文件里至少需要数据库账号密码、authentik 密钥和对外地址。密钥需要两个不同的长随机字符串可以用下面命令生成openssl rand -hex 32.env 参考结构PG_PASS请改成强密码 PG_USERauthentik PG_DBauthentik AUTHENTIK_SECRET_KEY第一个随机字符串 AUTHENTIK_TOKEN第二个随机字符串 AUTHENTIK_URLhttp://localhost:9000说明以上变量名是架构层面的通用结构具体以当前版本官方 compose 模板为准。密钥不要提交到 git 仓库生产环境建议用环境变量文件单独管理。4.4 拉取镜像并启动docker compose pull docker compose up -d启动后查看服务状态docker compose ps docker compose logs -f server worker如果 server 和 worker 没有报错浏览器访问http://服务器IP:9000就会进入初始化页面。如果打不开先检查防火墙是否放行 9000 端口再确认容器没有 CrashLoopBackOff。4.5 创建第一个超级管理员第一次打开 Web 界面会引导创建超级管理员账号。填写邮箱、用户名、密码即可。这个账号用于登录管理后台后续所有用户、应用、策略都在后台配置。需要注意如果启动后数据库连接失败最常见原因是 .env 里的 PG_PASS 和 compose 里读取的不一致。修改 .env 后要重新执行docker compose up -d让配置生效。5. 功能测试与效果验证5.1 登录和用户管理验证登录管理后台后进入 Directory - Users创建两个测试用户一个普通用户一个用于权限测试。创建用户时需要设置邮箱和密码。验证标准用户列表能正常显示配置了 SMTP 时用户能收到激活邮件没配 SMTP 时新用户创建后处于不活跃状态需要管理员手动激活。这里能直观看到 authentik 对用户生命周期的基础管理能力。5.2 创建组并分配权限进入 Groups 创建测试组例如ops把刚才的用户加入组。然后基于这个组创建一个授权策略比如“只有 ops 组成员可以访问某应用”。验证步骤先让普通用户登录访问目标应用预期被拒绝再把该用户加入 ops 组重新登录访问预期成功。这一步能验证策略引擎是否按设计工作是接入真实业务前的必要测试。5.3 接入一个 OIDC 应用这是 authentik 最常用的接入场景。操作路径Applications - Providers新建一个 OIDC Provider填写 Client ID、Redirect URI 等参数然后创建 Application 并绑定该 Provider。以一个支持 OIDC 的第三方应用为例通用接入流程如下在 authentik 中创建 OIDC Provider拿到client_id和client_secret。将client_id、client_secret、认证地址和回调地址填到第三方应用的 OAuth2 配置中。第三方应用发起登录浏览器跳转到 authentik 登录页。用户输入账号密码登录成功后跳回原应用。验证标准登录跳转链路完整第三方应用能正常读取到用户信息刷新页面不重复登录。如果出现回调错误优先检查 Redirect URI 是否完全一致包括协议、域名和路径。5.4 代理认证验证如果不希望改第三方应用的认证代码可以用 Proxy Outpost 做反向代理认证。以 Nginx 为例在站点配置里加auth_request指向 authentik 的 outpost未登录请求会被重定向到 authentik 登录页登录后携带 Cookie 回到原站点。Nginx 伪配置如下server { listen 80; server_name app.example.com; # 将 /outpost.goauthentik.io/ 转发给 authentik 的 outpost location /outpost.goauthentik.io/ { proxy_pass http://127.0.0.1:9000/outpost.goauthentik.io/; proxy_set_header Host $host; } location / { auth_request /outpost.goauthentik.io/auth/nginx; auth_request_set $auth_cookie $upstream_http_set_cookie; add_header Set-Cookie $auth_cookie; proxy_pass http://127.0.0.1:8080; } }说明这是代理认证接入的通用思路Outpost 的端口和路径需要按实际部署调整。验证点访问应用时未登录会跳到 authentik登录后能正常访问应用。如果出现 401 循环优先检查 outpost 路径和端口映射。5.5 MFA 多因素认证验证在用户设置或全局策略中开启 MFA。推荐先用 TOTP 一次性验证码方式用户绑定手机上的验证器 App。后台还可以配置强制 MFA 策略要求所有用户在登录时完成二次验证。验证步骤普通用户登录输入密码后系统会弹出验证码输入步骤用户用验证器 App 输入动态码验证通过后进入系统。要重点验证绑定流程是否顺畅、动态码过期后是否要求重新生成、强制策略是否对所有用户生效。6. 接口 API 与批量任务管理6.1 API 认证方式authentik 的 REST 管理接口位于/api/v3/。浏览器登录后会携带会话但自动化场景建议使用 API Token。在管理后台的 API Tokens 中生成长期 Token然后放进请求头curl -H Authorization: Bearer 你的_token \ http://127.0.0.1:9000/api/v3/core/users/请求成功会返回用户列表 JSON。如果返回 401说明 Token 过期或账号权限不足。6.2 创建用户示例用 API 创建用户是批量任务的常见入口。下面示例中字段名以当前版本返回结构为准正式调用前建议先 GET 一次现有用户数据观察字段格式再构造请求curl -X POST \ http://127.0.0.1:9000/api/v3/core/users/ \ -H Authorization: Bearer 你的_token \ -H Content-Type: application/json \ -d { username: batch_user_001, name: 批量用户001, email: batch_user_001example.com, is_active: true }6.3 批量导入用户脚本批量导入用户的常见做法准备 CSV 文件用 Python 脚本逐行读取并调用 API。脚本里要处理状态码、记录错误行、支持断点重跑。参考代码如下import csv import requests API_BASE http://127.0.0.1:9000/api/v3 TOKEN 替换为你的API Token headers { Authorization: fBearer {TOKEN}, Content-Type: application/json } with open(users.csv, r, encodingutf-8) as f: reader csv.DictReader(f) for row in reader: payload { username: row[username], name: row[name], email: row.get(email, ), is_active: True } resp requests.post( f{API_BASE}/core/users/, jsonpayload, headersheaders, timeout30 ) if resp.status_code in (200, 201): print(fOK: {row[username]}) else: print(fFAIL: {row[username]} - {resp.status_code} {resp.text})实际使用时用户名唯一性、邮箱格式、密码策略都需要提前校验。建议先在测试环境跑一遍确认数据结构和权限策略正常后再进生产。7. 资源占用与性能观察7.1 用 docker stats 观察资源部署完成后可以用docker stats实时查看各容器占用docker stats --format table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}空闲状态下server 和 worker 的 CPU 占用应该很低内存占用与容器内进程数和版本有关。这个数据因机器配置差异较大以本机实际观察为准。7.2 影响性能的关键点PostgreSQL用户量、审计日志量增大后数据库查询成为主要瓶颈。Redissession 和缓存使用量过大时内存占用会明显升高。Worker邮件发送、事件同步都会走 Worker任务堆积时队列会拉长。高并发登录大量用户短时间集中登录时登录页响应变慢需要关注 server 容器和对 PostgreSQL 的压力。7.3 降低资源占用的办法控制审计日志保留时间定期清理过期数据。不需要邮件通知时不配置 SMTP减少 Worker 任务。Outposts 尽量部署在业务系统同一网络内避免跨网络代理造成链路延迟。生产环境备份错峰执行避免备份和业务高峰叠加。8. 常见问题与排查方法问题现象可能原因排查方式解决方案9000 端口打开无响应server 容器未启动或启动失败docker compose ps 查看状态docker compose logs server 看日志修复数据库连接或镜像版本问题后重启登录后页面空白Web UI 静态资源加载失败浏览器控制台看资源请求状态检查 9000/9443 端口及反向代理配置忘记管理员密码长期未登录或密码丢失进入 server 容器执行管理命令参照官方恢复密码文档重置PostgreSQL 连接失败密码不匹配或数据卷权限异常查看 server 日志中的数据库连接报错检查 .env 中 PG_PASS 与 compose 环境变量一致首次启动迁移卡住数据库版本和代码版本不匹配查看 migrations 日志按升级文档逐版本迁移避免跨大版本升级代理认证 401 循环Nginx 配置或 Outpost 地址错误检查请求是否到达 outpost核对 /outpost.goauthentik.io/ 路径和端口映射API 调用返回 401Token 过期或权限不足用 curl 单独测试 Token重新生成 API Token检查账号权限批量创建用户部分失败字段不合法或用户已存在查看脚本返回的 4xx 状态码加去重逻辑更新错误记录后重跑HTTPS 证书无效未配置证书或域名不对浏览器查看证书信息使用 Lets Encrypt 或替换受信任证书升级前务必备份数据库。版本跨越较大时先看 release note 再做迁移操作避免数据结构和代码版本不兼容。9. 最佳实践与使用建议9.1 部署层面生产环境至少用数据卷持久化 PostgreSQL 和 Redis 数据不要把数据库文件放在容器可写层。备份时用 pg_dump 导出并定期异地保存。.env 文件和 compose 文件分开管理密钥不要提交到代码仓库。如果接入反向代理把 9000 端口限制为内网访问对外只暴露 HTTPS 端口。首次部署成功后保留一份最小可运行配置方便后续版本升级时对照。9.2 权限设计层面管理员账号只用于管理不用于日常业务登录。普通用户和应用账号要区分开能开 API Token 就不要共用管理员密码。配置影响面较大的策略时先在测试环境验证再逐步上线。定期检查用户活跃状态及时禁用离职人员账号。9.3 合规与安全边界涉及用户真实姓名、邮箱、手机号等个人信息时要有明确的保存和授权说明。高权限操作建议强制开启 MFA。对外服务必须走 HTTPS防止密码在传输中被截获。不要用 authentik 来复制、共享其他系统的账号密码。身份认证平台解决的是认证入口问题业务系统的访问授权、数据分级、敏感操作审计仍然需要接入方自行做好设计。10. 总结与下一步authentik 最值得尝试的地方是把散落各系统的账号认证集中起来用 Flow 和策略去控制登录、注册、MFA 和授权并且提供了 API 和 Outposts 来适配不同接入方式。对于有多个内部系统、想统一登录入口的团队这类平台带来的维护收益通常大于部署成本。最先应该验证的是用 Docker Compose 启动一套最小环境创建用户接一个支持 OIDC 的小应用跑通单点登录确认登录跳转链路完整然后按需启用 MFA 和代理认证。最容易踩的坑有三个一是 .env 中的密钥和数据库密码不一致导致启动失败二是升级版本时没有先看迁移说明数据库跨版本迁移卡住三是反向代理配置不对导致/outpost.goauthentik.io/路径无法命中。第一次部署时先把这三个问题记在排查清单里能省不少时间。后续可以继续扩展尝试 Kubernetes Helm 部署把内部系统逐个迁移到 SSO配置 LDAP Outpost 对接老系统设置审计日志定期导出研究 API 接口做用户自动化和统一身份生命周期管理。如果团队对自托管维护成本敏感也可以在社区版跑通后再评估是否引入商业企业版获得企业级支持。