使用 Docker 安装和配置 Authentik 的完整指南

为每个应用程序管理单独的帐户必然会带来安全和管理问题。Authentik 允许您集中管理这些身份，并使用单一登录系统来管理内部服务、Web 应用程序以及托管在您自身基础设施上的平台。

这是一个开源解决方案，用于…… 身份和访问管理 它可以作为 OAuth 2.0、OpenID Connect、SAML、LDAP、SCIM 或身份验证代理提供程序。借助 Docker Compose，您无需手动安装所有依赖项即可部署它。

官方的 Docker Compose 安装是为以下目的而设计的： 家庭实验室、测试和小规模生产环境对于高可用性、多用户或更苛刻的业务需求，建议将 PostgreSQL 分离出来并实施分布式架构。

什么是Authentik？何时应该安装它？

Authentik 扮演着 中央身份提供商 您的基础架构。服务不再需要在每个应用程序中独立管理用户和密码，而是将身份验证委托给 Authentik。

当有人尝试访问受保护的应用程序时，Authentik 会验证其身份，应用已配置的策略，并决定是否允许其继续访问。它还允许您添加 多因素身份验证、群组、角色和上下文限制.

它可以直接与支持 OAuth 2.0、OIDC、SAML 或 LDAP 的应用程序集成。对于不支持这些协议的服务，它提供代理提供程序和 Outposts，能够使用反向代理保护应用程序。

当您管理多个自助服务应用程序、希望从单一位置强制执行多因素身份验证 (MFA) 或需要通过用户组控制访问权限时，Authentik 尤其有用。例如，安装后，您将能够： 与 Jellyfin 建立真正的联系 使用 LDAP 或 OpenID Connect。

Authentic 的当前架构

自 2025.10 版本起，Authentik 不再需要 Redis 了。任务、缓存、集成 Outpost 会话和 WebSocket 连接都使用 PostgreSQL。

官方的 Docker Compose 归档文件部署了三个主要服务：

• PostgreSQL： 它可以保留用户、策略、会话、提供者、流程以及其他配置信息。
• 服务器： 它提供网页界面、API、身份验证流程和集成的Outpost代理。
• 工人： 它可以运行后台任务、通知、电子邮件和管理作业。

移除 Redis 可以简化部署，但 PostgreSQL 会承担更多职责。在小型部署中，无需手动修改其连接，但在高流量环境中，建议进行修改。 监控数据库 及其资源。

使用 Docker 安装 Authentik 的要求

开始之前，请准备一台满足以下最低要求的 Linux 服务器：

• 双核CPU。
• 2GB 内存。
• Docker 引擎和 Docker Compose v2.
• 用于存储 PostgreSQL 和 Authentik 文件的持久空间。
• 访问端口 9000 和 9443，或访问选定的自定义端口。
• 如果要将其发布到互联网上，则需要域名和反向代理。

检查 Docker 和 Compose 是否可用：

docker --version
docker compose version

现代语法是 docker compose加一个空格。要是旧命令还能用就好了。 docker-compose建议您在继续操作之前更新 Compose 插件。

如何使用 Docker Compose 安装 Authentik

创建安装文件夹

创建一个专用文件夹并进入该文件夹。该文件夹的名称也会影响 Docker 为项目及其卷分配的名称。

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

如果您的用户无法写入 /opt使用主目录下的文件夹，或者仅使用适当的权限运行必要的操作。

下载官方 Compose 文件

下载Authentik维护的文件：

wget https://docs.goauthentik.io/compose.yml

您还可以使用：

curl -O https://docs.goauthentik.io/compose.yml

最好从……开始 完整官方存档 并在验证安装成功后进行修改。从头开始创建一个精简版的 Compose 文件可能会遗漏卷、健康检查或必要的变量。

下载的文件引用了一个 特定版本的Authentic不要用该版本替换它 latest该标签已冻结在 2025.2 版本，不再接收更新。

生成 PostgreSQL 和 Authentik 密钥

Authentik 需要 PostgreSQL 密码和自定义密钥。您可以使用 OpenSSL 生成这些信息并直接保存到文件中。 .env:

echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env

请保护此文件，因为它包含 整个安装过程的关键凭证:

chmod 600 .env

每次启动服务时，请勿重新生成这些变量。密钥必须保持稳定，并与恢复实例所需的备份文件一起存储。

配置自定义端口

Authentik 默认暴露端口 9000 对于 HTTP 和 9443 用于 HTTPS。如果已有一个配置文件正在使用，请将其添加到文件中。 .env 其他可用端口：

COMPOSE_PORT_HTTP=9001
COMPOSE_PORT_HTTPS=9444

这些变量会改变 主机上发布的端口如果默认值是自由的，则无需修改它们。

配置电子邮件

启动 Authentik 不需要电子邮件，但建议使用电子邮件发送警报、验证和恢复消息。基本的 SMTP 配置可能具有以下结构：

AUTHENTIK_EMAIL__HOST=smtp.ejemplo.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=usuario
AUTHENTIK_EMAIL__PASSWORD=contraseña
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__USE_SSL=false
[email protected]

请使用与您的服务提供商对应的 TLS 或 SSL 选项。通常情况下，不应同时启用这两种选项。

启动容器

下载镜像文件并进行安装：

docker compose pull
docker compose up -d

无需在其他服务运行之前手动启动 PostgreSQL。官方文件包含了 Compose 管理 PostgreSQL 所需的依赖项和检查。 初始化顺序.

使用以下命令检查状态：

docker compose ps

服务 server, worker y postgresql 它们应该显示正在运行。首次启动时，PostgreSQL 可能需要几分钟时间来准备并执行迁移。

不要挂载文件 /etc/timezone ni /etc/localtime 从容器内的主机获取数据。Authentik 以 UTC 时间执行其内部操作，更改此设置可能会导致问题。 OAuth 和 SAML 错误.

如何完成初始设置

在浏览器中打开服务器地址：

http://IP_DEL_SERVIDOR:9000

Authentik 将打开初始设置流程以设置密码。 akadmin， 他的 默认管理帐户.

如果重定向不起作用，请直接打开以下路径，注意路径末尾的斜杠：

http://IP_DEL_SERVIDOR:9000/if/flow/initial-setup/

选择一个独一无二的密码，并在登录后启用多因素身份验证 (MFA)。此外，最好创建一个备用的紧急管理员帐户，并将其凭据存储在安全的地方。

您可以通过面板开始创建：

• 用户和组 组织身份认同。
• 应用程序 将显示在用户门户网站上。
• 供应商 OAuth、OIDC、SAML、LDAP 或代理。
• 流程和阶段 定义身份验证的方式。
• 政策与联系 控制谁可以访问哪些资源。

如何使用反向代理发布 Authentik

对于可通过互联网访问的安装，您必须将 Authentic 放置在……之后。 使用 HTTPS 的反向代理您可以使用 Caddy、Traefik、Nginx 或 Nginx Proxy Manager。

代理服务器通常应将公共域指向 Authentik 的 HTTP 端口。 9000并至少保留以下标头：

• Host
• X-Forwarded-Proto
• X-Forwarded-For
• Connection: Upgrade
• Upgrade: WebSocket

真实用途 通过 WebSocket 连接与前哨站通信如果代理不允许连接更新，界面可能正常打开，但某些代理功能会失效。

当代理服务器位于 Authentik 识别的私有网络之外时，请使用以下命令添加其范围： AUTHENTIK_LISTEN__TRUSTED_PROXY_CIDRS将值限制为代理实际使用的地址。

如果您已在使用代理，请勿将端口 9000 直接暴露给互联网。请通过防火墙限制其访问权限，或仅将其连接到必要的接口。

Docker 套接字风险和 Outpost 管理

官方 Compose 默认会将 Docker socket 挂载到 worker 内部：

/var/run/docker.sock:/var/run/docker.sock

此访问权限允许身份验证 自动部署和管理前哨站但是，任何能够控制套接字的容器都对主机拥有非常高的权限。

为了降低风险，您可以：

• 放置 Docker 套接字代理 工作节点和 Docker 之间。
• 移除组件并手动部署前哨站。
• 限制对Authentik的管理访问权限。
• 保持 Docker、Authentik 和操作系统处于最新状态。

该服务器还集成了一个 Outpost 代理，足以满足许多简单的部署需求，无需创建另一个容器。

如何检查 Authentic 功能是否正常工作

首先，检查整体状况：

docker compose ps

如果服务重启或未能恢复到正常状态，请检查其日志：

docker compose logs -f server
docker compose logs -f worker
docker compose logs -f postgresql

您还可以查看Authentik加载的实际配置：

docker compose run --rm worker ak dump_config

请勿发布全部输出信息，因为它可能会泄露基础设施信息。请特别注意 PostgreSQL 连接、端口、电子邮件和受信任网络等信息。

如何备份 Authentic

PostgreSQL数据库是最重要的组件。它包含用户、组、策略、流程、应用程序、提供程序和其他持久化配置。

您可以使用以下命令创建逻辑转储：

docker compose exec -T postgresql pg_dump -U authentik -d authentik -cC > authentik-postgres-backup.sql

确认文件已创建并将其保存。 其他存储设备或系统仅保存在同一磁盘上的副本无法防止服务器丢失。

除了 PostgreSQL 之外，还要检查所使用的持久化目录：

• /data: 图标、背景、上传的文件和 CSV 报告。
• /certs: 存储在文件系统中的外部证书。
• /custom-templates: 自定义界面修改。
• /blueprints: 实例使用的自定义蓝图。

它还会记录已安装的版本；它会保留该文件。 .env 备份受到保护并定期进行测试，以确保备份可以恢复。

如何使用 Docker Compose 更新 Authentik

更新前，请阅读发行说明并创建 PostgreSQL 备份Authentik 不支持在应用迁移后安全地恢复到以前的版本。

更新必须遵循主版本号的顺序。例如，旧版本不应直接从 2025.2 版本跳到 2026.8 版本。必须先安装文档中列出的每个中间版本的最新版本。

在相应的序列中进行更新：

wget -O compose.yml https://docs.goauthentik.io/compose.yml
docker compose pull
docker compose up -d

然后检查日志并确认迁移已完成。服务器和所有前哨站都必须使用 同一版本的Authentic.

使用 Docker 安装 Authentik 时常见的错误

初始设置页面未显示

请确认所有三项服务都在运行，并查看日志。您也可以重启系统。

docker compose restart

然后直接打开 /if/flow/initial-setup/作为最后的手段，密码是 akadmin 可以从服务器端设置：

docker compose exec server ak changepassword akadmin

PostgreSQL 不接受密码

检查一下 PG_PASS 存在于 .env 并且该文件位于与以下位置相同的文件夹中： compose.yml请勿在未更新连接设置和 PostgreSQL 存储的凭据的情况下更改密码。

9000端口已被占用

定义另一个已发布的端口 .env:

COMPOSE_PORT_HTTP=9001

然后使用以下命令重新创建容器 docker compose up -d 并使用新端口进行访问。

代理返回 502 错误

验证代理服务器是否可以访问 Authentik 服务器。如果两者都运行在 Docker 容器中，则它们必须共享同一网络或使用可访问的地址。此外，还要验证 Authentik 是否已完成迁移。

出现 CSRF 错误或不正确的重定向

它们通常是由于标头引起的。 Host o X-Forwarded-Proto请查看与您的代理对应的官方模板，避免在会话期间随意更改域名。

前哨站似乎彼此断开连接

检查 WebSocket 连接、域名解析和 Docker 套接字访问。如果您出于安全原因移除了其挂载，则需要…… 手动部署前哨站.

由于时差导致 OAuth 或 SAML 失败

移除所有安装件 /etc/timezone o /etc/localtime 在容器内部，使用 NTP 保持主机时钟同步，并让 Authentik 在内部以 UTC 时间运行。

工作进程不断重启。

检查工作进程日志和 PostgreSQL 日志。密码错误、数据库不可用、权限不足或变量拼写错误都可能导致任务无法处理。

使用 Docker Compose 安装 Authentik 可以创建 集中式身份和访问系统 无需手动配置每个依赖项。正确的流程包括使用官方 Compose 工具、生成持久密钥、保护 PostgreSQL 数据库、完成初始流程，并通过兼容 WebSocket 的代理发布服务。

安装只是第一步。为了确保安全，您必须启用多因素身份验证 (MFA)、限制管理员访问权限、保护 Docker 套接字、执行可验证的备份，并始终按照版本顺序更新 Authentik。