Authentik Docker Compose 部署指南

‍‍‌> 目标：从零在 Ubuntu 22.04 上用官方 Compose 文件把 Authentik 2026.8.4 部署起来并完成初始化验证，含真实排障记录（ghcr 拉取失败、数据库密码不匹配的定位与修复）。已在 Ubuntu 22.04 实测通过。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
Docker Engine：29.8.1（docker compose v2 插件）
Authentik：2026.8.4（ghcr.io/goauthentik/server:2026.8.4，与 postgres:16-alpine）
服务端口：HTTP 13904（容器内 9000）、HTTPS 13906（容器内 9443）
数据目录：/opt/data/authentik/
实测部署完成态（docker compose ps 实测回显）：

NAME                            STATUS
authentik-2026.8.4-postgresql   Up 18 minutes (healthy)
authentik-2026.8.4-server       Up 13 minutes (healthy)
authentik-2026.8.4-worker       Up 13 minutes (healthy)

二、镜像选型说明

镜像	用途	选型理由
ghcr.io/goauthentik/server:2026.8.4	server 与 worker 共用	官方主镜像（一份镜像两种 command：server/worker）
postgres:16-alpine	数据库	官方 compose 指定；本机已有 16-alpine 缓存可直接复用

版本选择：2026.8.4 为官方最新稳定版（2026-10-14 发布，GitHub Releases 实测 tag version/2026.8.4）。生产建议固定具体版本号，不追 latest。

⚠️ 注意：2026.x 官方 compose 已不包含 Redis 服务（早期版本为四服务）。缺 Redis 不是配置遗漏，缓存由进程内缓存与 PostgreSQL 承担，请勿按旧教程自行补挂 Redis。

三、前置条件

Docker Engine 20.10+ 与 Compose v2 插件（本机实测 29.8.1）；
主机 2 CPU / 2 GB RAM 起步（官方要求）；
端口 13904/13906 未被占用（ss -tlnp | grep -E '13904|13906' 实测无输出）；
建议准备访问 ghcr.io 的网络通道（若不通见「常见问题 6.1」的 skopeo 方案）。

四、部署步骤

4.1 创建目录与下载官方 Compose 文件

mkdir -p /opt/data/authentik && cd /opt/data/authentik
curl -s -o docker-compose.yml https://goauthentik.io/docker-compose.yml

实测下载得到 67 行的 compose 文件，核心结构（实测原文节选）：

services:
  postgresql:
    image: docker.io/library/postgres:16-alpine
    volumes:
    - database:/var/lib/postgresql/data
  server:
    command: server
    image: ${AUTHENTIK_IMAGE:-ghcr.io/goauthentik/server}:${AUTHENTIK_TAG:-2026.8.4}
    ports:
    - ${COMPOSE_PORT_HTTP:-9000}:9000
    - ${COMPOSE_PORT_HTTPS:-9443}:9443
    shm_size: 512mb
    volumes:
    - ./data:/data
    - ./custom-templates:/templates
  worker:
    command: worker
    user: root
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - ./data:/data
    - ./certs:/certs
    - ./custom-templates:/templates
volumes:
  database:
    driver: local

逐项说明：server/worker 共用同一镜像、仅 command 不同；端口经 COMPOSE_PORT_HTTP/HTTPS 变量映射；worker 挂载 docker.sock 用于 Outpost 自动部署（不需要该能力时可删）；数据库为 named volume database。

为便于识别，本机在 compose 中为三个服务各加一行 container_name（可选，不影响功能）：authentik-2026.8.4-postgresql / authentik-2026.8.4-server / authentik-2026.8.4-worker。

4.2 编写 .env

cd /opt/data/authentik
printf 'AUTHENTIK_BOOTSTRAP_PASSWORD=<你的初始管理密码>\nAUTHENTIK_BOOTSTRAP_TOKEN=<你的初始API令牌>\nPG_USER=authentik\nPG_DB=authentik\nCOMPOSE_PORT_HTTP=13904\nCOMPOSE_PORT_HTTPS=13906\n' > .env

两个敏感值（数据库密码与加密密钥）在启动命令中生成并注入（见 4.3），不落明文；若在可信内网想持久化到 .env，务必 chmod 600 .env。bootstrap 两个变量说明：BOOTSTRAP_PASSWORD 决定 akadmin 初始密码；BOOTSTRAP_TOKEN 创建同名管理员 API Token（首次启动生效，仅初始化前有效）。

4.3 生成密钥并启动

官方对两个必填变量的生成建议（:? 断言会强制检查）：

# 一次性注入并启动（PG_PASS 与 SECRET_KEY 随机生成，不出现在历史/文件中）
cd /opt/data/authentik
export AUTHENTIK_SECRET_KEY=$(openssl rand -hex 32) PG_PASS=$(openssl rand -hex 16)
docker compose up -d

实测启动回显（节选）：

 Container authentik-2026.8.4-postgresql Healthy
 Container authentik-2026.8.4-server Started
 Container authentik-2026.8.4-worker Started

⚠️ 注意：compose 文件中 ${PG_PASS:?database password required} 与 ${AUTHENTIK_SECRET_KEY:?secret key required} 是强制断言，缺变量时命令直接失败，实测报错： error while interpolating services.postgresql.environment.POSTGRES_PASSWORD: required variable PG_PASS is missing a value: database password required down/up 等所有 compose 子命令都会做插值检查，同样需要这两个变量在环境中（restart/stop 不需要）。

4.4 等待初始化并验证

首次启动 worker 需执行数据库迁移与 Blueprint 导入（约 1~3 分钟）。轮询就绪接口：

for i in $(seq 1 30); do code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:13904/-/health/ready/); [ "$code" = "200" ] && break; sleep 10; done
curl -s http://localhost:13904/-/health/ready/

实测返回 HTTP 200。用初始 Token 验证版本（实测）：

curl -s -H "Authorization: Bearer <你的初始API令牌>" http://localhost:13904/api/v3/admin/version/

实测返回：

{"version_current":"2026.8.4","version_latest":"2026.8.4","version_latest_valid":true,"build_hash":"","outdated":false,"outpost_outdated":false}

浏览器打开 http://<服务器IP>:13904，用 akadmin 与 BOOTSTRAP_PASSWORD 登录即可进入管理台。

五、数据持久化说明

数据	位置	形态
数据库	named volume `authentik_database`	docker volume（`docker volume ls` 可见）
媒体/自定义	./data → 容器 /data	bind mount
TLS 证书	./certs → 容器 /certs	bind mount（worker）
自定义模板	./custom-templates → /templates	bind mount

备份以数据库为准：docker exec authentik-2026.8.4-postgresql pg_dump -U authentik authentik > authentik-$(date +%F).sql（命令形态，执行前确认容器名）。升级版本时数据在 volume 与 ./data 中保留。

六、环境变量表（逐项实测依据）

变量	示例/来源	作用	实测验证方式
AUTHENTIK_SECRET_KEY	openssl rand -hex 32	数据加密密钥，server/worker 必须一致	缺失时 compose 插值报错（实测回显见 4.3）
PG_PASS	openssl rand -hex 16	数据库密码	同上；且仅在数据卷首初始化时生效（见 6.2）
PG_USER / PG_DB	authentik	库用户与库名	启动日志 `PostgreSQL connection successful`
AUTHENTIK_BOOTSTRAP_PASSWORD	自定	akadmin 初始密码	实测用其走登录 Flow 成功并以 akadmin 身份取得会话
AUTHENTIK_BOOTSTRAP_TOKEN	自定	akadmin 初始 API Token	实测以 Bearer 方式调通 /api/v3/admin/version/
COMPOSE_PORT_HTTP / COMPOSE_PORT_HTTPS	13904 / 13906	宿主侧端口映射	实测 13904→9000、13906→9443（docker compose ps 回显）
AUTHENTIK_TAG	2026.8.4	镜像 tag	compose 默认值即 2026.8.4

七、配置文件挂载

需要自定义 Brand 模板/邮件模板时放入 ./custom-templates；需要给 worker 预置证书时放 ./certs。自定义环境变量也可直接写进 .env（AUTHENTIK_ 前缀），server/worker 由 env_file 自动加载。完整参数逐条说明见《Authentik 2026.8 配置参数详解》。

八、等价 docker run（理解 compose 的最小形态）

docker run -d --name authentik-pg -e POSTGRES_PASSWORD=<PG_PASS> -e POSTGRES_USER=authentik -e POSTGRES_DB=authentik -v authentik_database:/var/lib/postgresql/data postgres:16-alpine
docker run -d --name authentik-server -p 13904:9000 -p 13906:9443 --env-file /opt/data/authentik/.env -e AUTHENTIK_POSTGRESQL__HOST=<pg地址> -e AUTHENTIK_SECRET_KEY=<SECRET_KEY> -e AUTHENTIK_POSTGRESQL__PASSWORD=<PG_PASS> ghcr.io/goauthentik/server:2026.8.4 server
docker run -d --name authentik-worker --env-file /opt/data/authentik/.env -e AUTHENTIK_POSTGRESQL__HOST=<pg地址> -e AUTHENTIK_SECRET_KEY=<SECRET_KEY> -e AUTHENTIK_POSTGRESQL__PASSWORD=<PG_PASS> ghcr.io/goauthentik/server:2026.8.4 worker

仅作原理理解，实际部署以 compose 为准（网络、健康检查、依赖顺序 compose 已代管）。

九、常用运维命令

cd /opt/data/authentik
export AUTHENTIK_SECRET_KEY=$(openssl rand -hex 32) PG_PASS=$(openssl rand -hex 16)   # 仅占位满足插值断言
docker compose ps                        # 实测可看三服务 healthy 与端口映射
docker compose logs -f server            # 跟踪 server 日志
docker compose restart server            # 重启单服务（不需要敏感变量）
docker compose stop && docker compose start
docker compose up -d --force-recreate server   # 应用新环境变量

十、常见问题（含实测排障记录）

Q1：ghcr.io 镜像拉不动（EOF/超时）怎么办？ 实测现象：docker pull ghcr.io/goauthentik/server:2026.8.4 反复报 failed to do request: Head "https://ghcr.io/v2/.../manifests/2026.8.4": EOF；Docker Hub 同名仓库经镜像加速器返回 502。定位：宿主机 curl -s -o /dev/null -w '%{http_code}' https://ghcr.io/v2/ 实测 401（说明直连可达，daemon 通道异常）。解决：用 skopeo 绕过 daemon 直连下载再导入（实测成功）：

skopeo copy docker://ghcr.io/goauthentik/server:2026.8.4 oci-archive:/tmp/ak.tar:2026.8.4
docker load -i /tmp/ak.tar
docker tag <上一步输出的镜像ID> ghcr.io/goauthentik/server:2026.8.4

实测 docker load 输出 Loaded image: 2026.8.4:latest，用 docker images 查到镜像 ID 后按 ID 打 tag 即可。

Q2：日志刷 FATAL: password authentication failed for user "authentik"？ 实测成因：postgres 数据卷只在首次初始化时采纳 POSTGRES_PASSWORD；之后再改该变量，卷内密码仍是旧值，而 server/worker 已用新值连接 → 认证失败（server 日志每秒重试，实测现象）。修复（不清库，实测成功）：

# 1) 取当前 server 容器持有的密码（与 .env 保持一致）
PGPW=$(docker exec authentik-2026.8.4-server printenv AUTHENTIK_POSTGRESQL__PASSWORD)
# 2) 在 postgres 容器内把库用户密码改成一致
docker exec authentik-2026.8.4-postgresql psql -U authentik -d authentik \
  -c "ALTER USER authentik WITH PASSWORD '$PGPW';"
# 3) 重启两个应用进程
docker restart authentik-2026.8.4-server authentik-2026.8.4-worker

实测：ALTER ROLE 后重启，随即 docker ps 显示 healthy，/-/health/ready/ 返回 200。预防：.env 与 compose 固化后不要单独改 PG_PASS；确要改库密码，同步执行上述三步。

Q3：首次启动 /-/health/ready/ 一直不通？ 属正常：首次初始化含迁移与 Blueprint 导入，实测约 1~3 分钟；用 4.4 的轮询脚本等待即可。若 10 分钟仍不通，docker compose logs worker | grep -iE 'error|migrate' 定位。

Q4：worker 需要 docker.sock 吗？ 仅当要用「Outpost 自动部署到本机」能力。不需要可删除该挂载，实测不影响核心功能。

Q5：升级版本？ 改 .env 的 AUTHENTIK_TAG（或 compose 里默认值）为新版本号，docker compose up -d 重建；数据库迁移由 worker 首启自动执行。回滚改回旧 tag 前先备份数据库。

十一、参考链接

官方 Compose 安装文档：https://docs.goauthentik.io/docs/install-config/install/docker-compose
官方 compose 文件（官网直链）：https://goauthentik.io/docker-compose.yml
2026.8 Release：https://docs.goauthentik.io/docs/releases/2026.8
相关篇：《Authentik 2026.8 配置参数详解》《Authentik 2026.8 API 使用详解》