authentik 详细部署教程

1. 部署方式选择

authentik 是一款开源身份提供商（IdP），支持 SAML、OAuth2/OIDC、LDAP、RADIUS 等协议，可作为 Okta、Auth0、Entra ID 的自托管替代方案。

部署方式	适用场景	难度	推荐度
Docker Compose	小规模、测试环境、个人自托管	⭐⭐	⭐⭐⭐⭐
Kubernetes (Helm)	生产环境、大规模集群	⭐⭐⭐⭐	⭐⭐⭐⭐⭐
AWS CloudFormation	AWS 云环境	⭐⭐⭐	⭐⭐⭐
DigitalOcean Marketplace	DigitalOcean 一键部署	⭐	⭐⭐⭐

官方定位：Docker Compose 适用于测试和小型生产环境，Kubernetes Helm Chart 才是大型生产部署的推荐方式 。

2. Docker Compose 部署（推荐入门）

2.1 环境要求

官方最低要求：2 核 CPU、2 GB 内存 。建议生产环境配置 4 核 CPU、4 GB+ 内存，因为 PostgreSQL 和 worker 容器运行一天后会显著占用内存。

需要：

Docker 和 Docker Compose (Compose v2)
一个指向服务器的 DNS A 记录（如 auth.example.com）

2.2 创建项目目录并生成密钥

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik

# 生成 PostgreSQL 密码和 secret key
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env

⚠️ 关键提醒：

AUTHENTIK_SECRET_KEY 用于签名会话和令牌。更改它会导致所有用户退出登录，并使所有已签发的 API 令牌失效 。请务必备份此密钥。

PostgreSQL 密码长度上限为 99 个字符 。

将 .env 权限设为 600，并保存到安全位置。

2.3 下载官方 Compose 文件

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

2.4 配置环境变量（可选但推荐）

设置初始管理员密码（避免在公共 Web 表单输入密码）：

1 2	echo "AUTHENTIK_BOOTSTRAP_PASSWORD=你的强密码" >> .env echo "AUTHENTIK_BOOTSTRAP_EMAIL=admin@example.com" >> .env

修改对外端口（默认 9000/9443）：

1 2	echo "COMPOSE_PORT_HTTP=80" >> .env echo "COMPOSE_PORT_HTTPS=443" >> .env

启用错误报告（可选）：

1	echo "AUTHENTIK_ERROR_REPORTING__ENABLED=true" >> .env

📌 重要语法规则：authentik 使用双下划线 __ 映射嵌套配置键，如 AUTHENTIK_EMAIL__HOST 映射到 email.host。单下划线会被忽略且不报错——这是“设置似乎没生效”的最常见原因。

2.5 启动服务

1 2	docker compose pull docker compose up -d

首次启动会执行数据库迁移，等待约 1 分钟后再访问 Web 界面。

验证容器状态：

1	docker compose ps

应看到 3 个容器：postgresql（healthy）、server（running）、worker（running）。

版本说明：当前官方 Compose 部署使用 PostgreSQL + server + worker 三个容器，不再包含 Redis（旧版教程中的 Redis 配置已过时）。

2.6 访问并完成初始设置

1	http://你的服务器IP:9000/if/flow/initial-setup/

⚠️ 必须包含末尾斜杠 /，否则会返回 Not Found 错误。

在此页面为默认的 akadmin 用户设置密码。注意：此流程是为 akadmin 设置密码，而非创建新用户 。

3. 配置 HTTPS 反向代理（生产必需）

直接暴露 authentik 的 HTTP 端口是不安全的。必须配置 TLS 终止，推荐使用 Caddy（自动申请证书）或 Nginx。

3.1 防火墙配置（Ubuntu）

# 启用 UFW 并允许 SSH
sudo ufw enable && sudo ufw allow 22

# 开放 HTTP/HTTPS
sudo ufw allow 80
sudo ufw allow 443

3.2 Caddy 配置示例

安装 Caddy：

1	sudo apt update && sudo apt install -y caddy

编辑 Caddyfile：

1
2
3

auth.example.com {
    reverse_proxy 127.0.0.1:9000
}

Caddy 会自动申请并续期 TLS 证书。

3.3 修改 Compose 端口绑定

为配合反向代理，将 authentik 端口仅绑定到本地回环：

1
2
3

# 在 .env 中
COMPOSE_PORT_HTTP=127.0.0.1:9000
COMPOSE_PORT_HTTPS=127.0.0.1:9443

⚠️ DNS 前置条件：TLS 证书申请要求域名已正确解析到服务器 IP。DNS 未配置或端口被阻止会导致证书申请失败。

4. Kubernetes 部署（生产推荐）

4.1 前置要求

Kubernetes 集群
Helm

4.2 生成密码并创建 values.yaml

# 生成数据库和缓存密码
pwgen -s 50 1
# 或
openssl rand 60 | base64 -w 0

创建 values.yaml：

authentik:
    secret_key: "请生成一个安全的密钥"
    error_reporting:
        enabled: true
    postgresql:
        password: "请设置一个安全的数据库密码"

server:
    ingress:
        ingressClassName: nginx   # 或 traefik / kong
        enabled: true
        hosts:
            - authentik.domain.tld

4.3 安装 Helm Chart

1
2
3

helm repo add authentik https://charts.goauthentik.io
helm repo update
helm upgrade --install authentik authentik/authentik -f values.yaml

数据库迁移会在启动时自动执行。

4.4 访问并初始化

1	https://<你的域名>/if/flow/initial-setup/

同样必须包含末尾斜杠，在此为 akadmin 设置密码。

4.5 生产环境数据库要求（重要）

⚠️ Helm Chart 默认创建的 PostgreSQL 仅用于演示和测试。生产环境应使用以下 Operator 之一：

CloudNativePG

Zalando Postgres Operator

不要在生产环境使用内置的演示数据库。

5. 邮件配置（强烈推荐）

未配置邮件会导致 authentik 无法发送密码重置、验证邮件，也无法通知管理员系统告警 。

邮件变量同样使用双下划线语法：

AUTHENTIK_EMAIL__HOST=smtp.example.com
AUTHENTIK_EMAIL__PORT=587
AUTHENTIK_EMAIL__USERNAME=user@example.com
AUTHENTIK_EMAIL__PASSWORD=yourpassword
AUTHENTIK_EMAIL__USE_TLS=true
AUTHENTIK_EMAIL__FROM=authentik@example.com

⚠️ 常见配置错误：SMTP 设置需同时应用于 server 和 worker 容器，因为 authentik 从 worker 发送邮件。

6. 安全注意事项

6.1 Docker Socket 挂载风险

官方 Compose 文件默认将 Docker Socket 挂载到 worker 容器（/var/run/docker.sock:/var/run/docker.sock），以便自动管理 outpost 容器。

⚠️ 安全风险：挂载 Docker Socket 等同于赋予容器主机 root 权限。生产环境建议：

使用 Docker Socket Proxy 作为额外保护层

或移除此挂载，改为手动部署和管理 outposts

6.2 时区配置警告

⚠️ 不要在容器中更新或挂载 /etc/timezone 或 /etc/localtime。这会导致 OAuth 和 SAML 认证出现问题。authentik 所有内部操作使用 UTC，UI 会为每个用户自动本地化显示。

7. 升级与备份

7.1 升级

Compose 文件静态引用下载时的最新版本。升级时需重新下载最新的 compose.yml，然后执行：

1 2	docker compose pull docker compose up -d

详见 Release Notes 中的升级章节。

7.2 备份关键数据

数据	位置/形式	重要性
数据库	PostgreSQL	⭐⭐⭐⭐⭐
`AUTHENTIK_SECRET_KEY`	`.env` 文件	⭐⭐⭐⭐⭐
`.env` 文件	项目目录	⭐⭐⭐⭐⭐

恢复时必须同时拥有数据库备份和匹配的 AUTHENTIK_SECRET_KEY，否则无人能登录。

社区提供了生产就绪的 Compose 配置，包含备份脚本和更新脚本。

8. 常见问题排查

问题	原因	解决方案
`Not Found` 错误	初始设置 URL 缺少末尾斜杠	确保 URL 以 `/if/flow/initial-setup/` 结尾
环境变量不生效	使用了单下划线	authentik 仅识别双下划线 `__`，检查变量名
`required variable ... is missing`	从错误目录运行命令	确保在包含 `.env` 的目录执行 `docker compose`
容器启动但无法访问	数据库迁移未完成	等待 1-2 分钟再访问
邮件不发送	未配置 SMTP 或仅配置 server	确保 server 和 worker 都配置了邮件变量

9. 部署方式选择建议

你的情况	推荐方案
个人/小团队自托管，首次接触	Docker Compose + Caddy
生产环境，已有 K8s 集群	Helm Chart + CloudNativePG/Zalando Operator
需要快速验证功能	Docker Compose + 默认端口
AWS 环境	AWS CloudFormation 官方模板
DigitalOcean 用户	Marketplace 一键部署