企业官网建设流程全解析

在业务系统越来越多、内部工具越来越分散的背景下，统一身份认证（Single Sign-On，SSO）几乎是每个技术团队都绕不开的基建需求。之前我在搭建内部平台时，尝试过自己写登录认证模块，也评估过不少开源方案，最后选择了 authentik。它既能当身份提供方（IdP），也能对接现有的 LDAP / OAuth2 / SAML 体系，部署方式足够轻量，社区也比较活跃。这篇文章会把 authentik 从概念到部署再到接入应用的完整流程整理出来，希望能帮你快速上手。

1. authentik 是什么，它能解决什么问题

先聊一个实际场景。假设公司内部有 GitLab、Jenkins、Grafana、Wiki 等多个系统，每个系统都有自己的账号体系。员工入职时要分别在各个平台创建账号，离职时要逐个注销，密码策略也各不相同。维护成本高不说，还容易留下僵尸账号，带来安全风险。

authentik 要解决的就是这类问题。它是一个开源的身份认证与身份管理平台，定位是Identity Provider（IdP），同时支持SSO（单点登录）、MFA（多因素认证）、LDAP 目录服务、用户生命周期管理等功能。简单来说，它把“账号认证”这件事从各个业务系统里抽离出来，做成一个统一的基础服务，其他系统只需要通过标准协议对接即可。

从技术实现角度来看，authentik 的核心组件由 Go 编写，同时在流程编排部分使用了 Python（具体版本会随官方发布变化），数据库默认采用 PostgreSQL，缓存使用 Redis。它对外提供 Web 管理界面，也提供完整的 REST API，适合以“基础设施”的方式嵌入到团队的技术栈中。

它的几个核心价值可以概括为：

需要区分的是，authentik 并不是一个“API 网关”，它不负责转发业务请求，也不做接口鉴权。它更专注于“你是谁”这个问题，至于“你能访问什么”，由业务系统根据认证返回的用户属性自行决定。理解这个边界对后续架构设计很重要。

2. 环境准备与版本说明

authentik 官方推荐使用 Docker Compose 方式部署，这也是目前最简单、最稳定的方式。它会同时启动多个服务，包括：

• server：主服务，负责处理认证请求和 API
• worker：后台任务服务，处理邮件发送、事件通知等异步任务
• postgresql：主数据库
• redis：缓存与临时数据存储

如果你的服务器还没安装 Docker 和 Docker Compose，可以先用下面命令确认环境：

docker --version docker compose version

如果没有安装，可以参考 Docker 官方文档安装，本文不再赘述。需要提醒的是，不同操作系统的 Docker 安装方式不同，安装完成后需要确保当前用户有权限执行 Docker 命令。

关于版本，authentik 的版本更新节奏比较快，不同版本之间的配置项可能会有细微差异。本文示例以官方文档推荐的 Docker Compose 部署方式为主，重点演示配置思路。你在实际操作时，建议使用官方最新的稳定版本号，不要盲目使用 latest 标签。

为了便于管理，建议在服务器上创建独立目录，例如/opt/authentik，所有相关文件都放在这个目录下。后续升级、备份、迁移都会方便很多。

sudo mkdir -p /opt/authentik cd /opt/authentik

3. 核心概念与认证原理

在动手部署之前，有必要先理解 authentik 的几个核心概念。如果跳过这部分直接配置，后面很容易被各种名词绕晕。

3.1 Provider 与 Application

在 authentik 中，Provider（提供方）和Application（应用）是两个最容易混淆的概念。

Provider 定义了“以什么协议对外提供服务”。例如，你可以创建以下类型的 Provider：

• OAuth2 / OIDC Provider：适合现代 Web 应用、移动端应用
• SAML Provider：适合企业级应用、老牌系统
• LDAP Provider：可以让 authentik 作为一个 LDAP 目录服务，供支持 LDAP 认证的系统对接
• Proxy Provider：适合需要反向代理认证的 Web 服务

Application 则是“某个具体业务系统的注册信息”。一个 Application 可以关联一个 Provider，也可以关联多个 Provider（例如同一应用同时支持 OIDC 和 SAML 两种接入方式）。

理解这两者的关系，可以类比为“接口定义”和“接口实现”。Provider 是协议模板，Application 是实际接入方。

3.2 Flow 与 Stage

Flow（流程）和 Stage（阶段）是 authentik 最灵活的编排机制。

Stage 是认证过程中一个独立步骤，比如：

• 用户名密码校验
• MFA 验证
• 用户信息填写
• 同意授权页面
• 验证码验证

Flow 则是由多个 Stage 按顺序组成的完整流程。例如“登录流程”可能包含“用户名密码验证”和“MFA 验证”两个阶段；“注册流程”可能包含“填写基本信息”“验证邮箱”“设置密码”等阶段。

authentik 预置了多种默认 Flow，比如：

• default-authentication-flow：默认登录流程
• default-enrollment-flow：默认注册流程
• default-password-change-flow：密码修改流程
• default-recovery-flow：密码找回流程

你可以直接使用这些默认流程，也可以复制后修改，添加或删减 Stage。这种设计让 authentik 能适配各种个性化的认证需求。

3.3 OAuth2 / OIDC 接入流程

OIDC（OpenID Connect）是在 OAuth2 基础上扩展的身份认证协议，目前是 authentik 集成应用时最常用的方式。它的核心流程如下：

1. 用户访问第三方应用，应用发现用户未登录
2. 应用将用户重定向到 authentik 的授权端点
3. authentik 校验用户身份（登录、MFA）
4. authentik 将用户重定向回应用，并携带授权码
5. 应用后端用授权码向 authentik 换取 ID Token 和 Access Token
6. 应用验证 Token，获取用户信息，完成登录

从整体来看，authentik 充当的是“集中认证中心”的角色。第三方应用不再关心用户密码如何校验、Session 如何管理，只需要相信 authentik 返回的 Token 即可。

4. 完整实战：Docker Compose 部署 authentik

这一节我们从零开始，完成 authentik 的部署。

4.1 准备 docker-compose.yml

进入/opt/authentik目录，创建docker-compose.yml文件：

version: "3.8" services: postgresql: image: docker.io/library/postgres:16-alpine restart: unless-stopped volumes: - database:/var/lib/postgresql/data environment: - POSTGRES_DB=${PG_DB} - POSTGRES_USER=${PG_USER} - POSTGRES_PASSWORD=${PG_PASS} redis: image: docker.io/library/redis:7-alpine restart: unless-stopped command: --save 60 1 --loglevel warning volumes: - redis:/data server: image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG} restart: unless-stopped command: server environment: - AUTHENTIK_REDIS__HOST=redis - AUTHENTIK_POSTGRESQL__HOST=postgresql - AUTHENTIK_POSTGRESQL__USER=${PG_USER} - AUTHENTIK_POSTGRESQL__NAME=${PG_DB} - AUTHENTIK_POSTGRESQL__PASSWORD=${PG_PASS} - AUTHENTIK_SECRET_KEY=${AUTHENTIK_SECRET_KEY} - AUTHENTIK_ERROR_REPORTING__ENABLED=${AUTHENTIK_ERROR_REPORTING__ENABLED} - AUTHENTIK_COOKIE_DOMAIN=${AUTHENTIK_COOKIE_DOMAIN} volumes: - ./media:/media - ./custom-templates:/templates ports: - "${COMPOSE_PORT_HTTP:-9000}:9000" - "${COMPOSE_PORT_HTTPS:-9443}:9443" depends_on: - postgresql - redis worker: image: ghcr.io/goauthentik/server:${AUTHENTIK_TAG} restart: unless-stopped command: worker environment: - AUTHENTIK_REDIS__HOST=redis - AUTHENTIK_POSTGRESQL__HOST=postgresql - AUTHENTIK_POSTGRESQL__USER=${PG_USER} - AUTHENTIK_POSTGRESQL__NAME=${PG_DB} - AUTHENTIK_POSTGRESQL__PASSWORD=${PG_PASS} - AUTHENTIK_SECRET_KEY=${AUTHENTIK_SECRET_KEY} - AUTHENTIK_ERROR_REPORTING__ENABLED=${AUTHENTIK_ERROR_REPORTING__ENABLED} - AUTHENTIK_COOKIE_DOMAIN=${AUTHENTIK_COOKIE_DOMAIN} volumes: - ./media:/media - ./custom-templates:/templates depends_on: - server volumes: database: redis:

这个文件里需要注意几个点：

• ghcr.io/goauthentik/server是官方镜像地址，AUTHENTIK_TAG变量决定镜像版本
• postgresql和redis的数据通过 Docker Volume 持久化，避免容器删除后数据丢失
• server同时映射 9000（HTTP）和 9443（HTTPS）端口
• worker与server使用相同的镜像和环境变量，只是启动命令不同
• depends_on确保服务按顺序启动

4.2 配置 .env 环境变量

创建.env文件，用于存放环境变量：

# authentik 镜像版本 AUTHENTIK_TAG=2024.12.2 # PostgreSQL 配置 PG_DB=authentik PG_USER=authentik PG_PASS=请替换为随机强密码 # authentik 核心密钥（务必替换为随机字符串） AUTHENTIK_SECRET_KEY=请替换为至少32位的随机字符串 # 错误上报开关，建议关闭 AUTHENTIK_ERROR_REPORTING__ENABLED=false # Cookie 域名，生产环境建议配置为你的域名 AUTHENTIK_COOKIE_DOMAIN=example.com # 端口映射 COMPOSE_PORT_HTTP=9000 COMPOSE_PORT_HTTPS=9443

这里有一个需要特别提醒的地方：AUTHENTIK_SECRET_KEY是 authentik 用于加密 Session、Token 等敏感数据的密钥，一旦部署完成并产生数据，后续不要随意修改，否则会导致已登录用户 Session 失效。生成密钥可以使用以下命令：

openssl rand -hex 32

另外，PG_PASS是 PostgreSQL 的密码，也建议使用随机强密码。不要把生产环境的数据库密码设置成弱密码。

AUTHENTIK_COOKIE_DOMAIN的含义是限定 authentik Session Cookie 生效的域名。如果你有多个子域系统接入 authentik，可以配置为共同的父域名，例如example.com，这样server1.example.com和server2.example.com共享认证状态。如果是纯 IP 访问或单域名测试，可以留空。

4.3 启动服务

确认文件就绪后，在/opt/authentik目录下执行：

docker compose up -d

首次启动会拉取多个镜像，耗时取决于网络状况。等待一段时间后，查看容器状态：

docker compose ps

正常情况下，所有服务的状态都应该是Up。如果某个服务反复重启，可以查看日志定位问题：

docker compose logs -f server

服务启动后，authentik 需要执行一次数据库初始化，并在数据库中创建初始用户。打开浏览器访问：

http://你的服务器IP:9000

或者 HTTPS 方式：

https://你的服务器IP:9443

由于默认使用的是自签名证书，浏览器会提示证书不受信任，本地测试可以点击“继续访问”。生产环境建议在 authentik 前面加一层 Nginx / Caddy，配置正式证书后对外提供服务。

4.4 初始化管理员账号

首次访问时，authentik 会进入初始化引导界面，要求创建管理员账号。填写邮箱和用户名，设置强密码即可完成初始化。

这里特别强调：初始管理员密码务必妥善保存。如果忘记密码，后续需要通过命令行方式重置，操作会比较麻烦。初始化完成后，使用管理员账号登录，就进入了 authentik 的管理后台。

4.5 验证部署结果

登录管理后台后，可以看到左侧菜单包含 Dashboard、Applications、Flows、Directory、System 等模块。在 Dashboard 页面可以查看系统版本和资源状态，这就说明 authentik 的核心服务已经正常运行了。

5. 实战：接入一个第三方应用（OIDC 方式）

部署只是第一步。接下来我们以一个典型的内部 Web 应用为例，演示如何通过 OIDC 协议接入 authentik。

5.1 创建 Provider

在 authentik 管理后台中，依次进入Applications > Providers，点击Create。

表单关键字段说明：

• Name：Provider 名称，建议包含应用名和协议，例如GitLab OIDC Provider
• Authorization flow：选择授权流程，通常使用default-provider-authorization-explicit-consent，这里是授权时是否展示同意页面的控制
• Client Type：Confidential，表示需要客户端密钥
• Client ID / Client Secret：可以自己填写，也可以留空让系统生成。推荐让系统自动生成
• Redirect URIs / Origins：填写第三方应用的回调地址。例如 GitLab 的 OIDC 回调地址是https://gitlab.example.com/users/auth/openid_connect/callback

创建完成后，Provider 列表里会生成一条记录，包含 Client ID 和 Client Secret。这部分信息需要填到第三方应用中。

5.2 关联 Application

在Applications > Applications页面，点击Create，创建一个 Application：

• Name：例如GitLab
• Slug：建议使用英文短横线格式，例如gitlab
• Provider：选择上一步创建的 Provider

保存后，第三方应用与 authentik 之间的绑定关系就建立起来了。

5.3 在第三方应用中配置 OIDC

这里以常见的通用 OIDC 客户端为例。无论使用哪个框架，都需要配置以下信息：

# 认证端点 Authorization Endpoint: https://auth.example.com/application/o/authorize/ # Token 端点 Token Endpoint: https://auth.example.com/application/o/token/ # 用户信息端点 Userinfo Endpoint: https://auth.example.com/application/o/userinfo/ # 登出端点 End Session Endpoint: https://auth.example.com/application/o/{slug}/end-session/

以 Python 的Authlib库为例，客户端配置大致如下：

from authlib.integrations.requests_client import OAuth2Session client = OAuth2Session( client_id="你的ClientID", client_secret="你的ClientSecret", redirect_uri="https://your-app.example.com/callback", scope="openid profile email", ) # 生成跳转链接 authorization_url, state = client.create_authorization_url( "https://auth.example.com/application/o/authorize/" )

回调地址处理逻辑：

# 回调后获取 Token token = client.fetch_token( "https://auth.example.com/application/o/token/", authorization_response=request.url, grant_type="authorization_code", ) # 获取用户信息 userinfo = client.get("https://auth.example.com/application/o/userinfo/").json()

不管是 Java 的 Spring Security、Node.js 的 Passport.js，还是 Go 的 oidc 库，原理都是相通的：重定向到授权端点，拿授权码换 Token，再用 Token 获取用户信息。

5.4 验证登录流程

配置完成后，访问第三方应用，点击登录时会被重定向到 authentik 的登录页面。输入账号密码后，如果 Provider 配置了授权确认页面，还会看到一次授权确认，确认后自动跳转回第三方应用。

此时第三方应用已经拿到 authentik 返回的用户信息，包括sub（用户唯一标识）、email、name等字段。业务系统可以用来创建本地会话、绑定内部账号、做权限映射。

6. 常见问题与排查思路

在实际部署和接入过程中，我整理了几个高频问题，按现象、原因、解决思路列出。

这里单独说一下重置管理员密码的方法。如果管理员密码遗忘，可以进入server容器执行命令：

docker compose exec server ak create_recovery_key 管理员用户名 --token -o /dev/stdout

执行后命令会输出一个一次性链接，用浏览器访问该链接，即可进入重置密码页面。需要注意的是，这个链接有有效期限制，生成后应尽快使用。

7. 最佳实践与工程建议

authentik 作为身份认证基础设施，一旦投入生产环境，它的稳定性和安全性直接影响所有接入系统。下面这些建议都是我在实际使用中觉得比较重要的点。

7.1 版本管理与升级策略

不要把镜像标签写成latest。生产环境应固定到具体版本号，升级前先阅读官方 changelog，确认是否有破坏性变更。升级操作建议在业务低峰期执行，操作前备份数据库。

# 备份数据库示例 docker compose exec postgresql pg_dump -U authentik authentik > authentik_backup_$(date +%Y%m%d).sql

数据备份无小事，尤其是身份认证系统的数据，丢失后影响范围是非常大的。

7.2 反向代理与 TLS 配置

生产环境不建议直接把 authentik 的 9000 和 9443 端口暴露到公网。推荐前面加一层反向代理，例如 Nginx，由反向代理统一管理 HTTPS 证书。

关键配置示例如下：

server { listen 80; server_name auth.example.com; return 301 https://$host$request_uri; } server { listen 443 ssl; server_name auth.example.com; ssl_certificate /etc/nginx/certs/fullchain.pem; ssl_certificate_key /etc/nginx/certs/privkey.pem; client_max_body_size 25M; location / { proxy_pass http://127.0.0.1:9000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

配置反向代理后，AUTHENTIK_COOKIE_DOMAIN和外部访问地址要统一规划，保证回调地址、Cookie 域、代理域名之间不冲突。

7.3 用户目录与权限模型

authentik 自带的用户体系适合中小团队，但如果公司已经存在 AD / LDAP / 飞书 / 钉钉等身份源，建议优先通过 authentik 的Source功能对接现有目录，避免重复维护一套账号体系。

在权限模型方面，authentik 支持 Group 和 Role。建议按“业务角色”而非“个人”来分配权限，例如dev-team、ops-team、admin等。这样后续人员变动时，只需要调整用户所在组，不需要逐个应用修改授权。

7.4 租户与环境隔离

如果公司有多个环境（测试环境、预发环境、生产环境），建议根据实际情况决定是否拆分 authentik 实例。测试环境和生产环境使用同一套 authentik 实例可以简化账号管理，但要注意客户端 ID 和回调地址不要混淆。对于安全等级较高的生产环境，更推荐单独部署独立的 authentik 实例，实现完全隔离。

7.5 安全加固清单

从安全角度，以下几个配置项值得优先关注：

1. 强制 MFA：在登录流程中添加 MFA Stage，要求管理员账号必须开启 MFA。
2. 组织密码策略：在 authentik 中配置最小密码长度、复杂度要求，避免用户设置弱密码。
3. 登录限流：配置失败尝试次数限制，防止暴力破解。
4. 审计日志：定期查看 authentik 的管理事件日志，关注异常登录行为。
5. 最小化暴露：authentik 管理后台不应对公网开放，至少应限制 IP 访问范围。

7.6 监控与告警

作为基础设施，authentik 的运行状态需要纳入监控体系。至少监控以下指标：

• 容器存活状态
• PostgreSQL 磁盘使用率
• Redis 内存使用率
• authentik 登录失败率异常升高

如果公司已经有 Prometheus + Grafana，可以通过 exporter 采集相关指标。没有专业监控体系的小团队，至少配置容器重启策略，并定期检查日志。

8. 总结与下一步学习方向

本文从 authentik 的概念入手，完整演示了 Docker Compose 部署过程，以及通过 OIDC 协议接入第三方应用的流程，最后整理了常见排错和最佳实践。掌握了这些内容，你已经可以独立部署一个 authentik 实例，并把它作为团队内部系统的统一登录入口。

接下来可以按方向继续深入：

• Flow / Stage 进阶：自定义注册流程、邀请链接、组自动分配等场景
• 对接 LDAP 源：把现有 AD / LDAP 中的用户同步到 authentik，实现账号统一
• SAML 协议接入：学习如何对接支持 SAML 的旧系统
• API 二次开发：通过 authentik REST API 实现用户批量管理、自动化运维脚本

身份认证是所有系统的第一道门，也是安全体系里最核心的一环。花些时间把 authentik 的原理和配置吃透，后续搭建内部平台时会省下很多不必要的沟通和排错成本。希望这篇文章能帮你少走一些弯路。