Authentik 2026.8 配置参数详解

Authentik 2026.8.4 配置来源三层模型与核心参数逐条详解：必填密钥、引导参数、数据库族、缓存日志，均标注默认值与生效证据，附生产模板

AuthentikAuthentik2026/10/18

Authentik 2026.8 配置参数详解

‍‍​​‌​> 目标：把 Authentik 2026.8.4 的配置来源（内置默认文件 → .env → 环境变量）与高频参数逐条讲清，每个参数标注默认值与生效证据（本机实例实测回显），并给出生产模板。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Authentik 版本：2026.8.4（版本自报接口实测 version_current: 2026.8.4）
  • 部署形态：server + worker + PostgreSQL 16 三服务，配置经 .env 与环境变量注入
  • 配置实例目录：/opt/data/authentik/（.env 与 data/、certs/、custom-templates/ 同级）
  • 实测时间：2026-10-18

二、前置条件

  1. 已按《Authentik Docker Compose 部署指南》完成部署并 /-/health/ready/ 返回 200；
  2. 拥有管理员 API Token（初始 Token 由引导变量创建，见《Authentik 2026.8 API 使用详解》）；
  3. 理解参数生效原则：环境变量仅在进程启动时读取，改动后需重启对应进程。

三、参数查看与修改方式

3.1 三层来源与优先级

层位置优先级
内置默认程序内置 default.yml最低
.env 文件/opt/data/authentik/.env（compose 的 env_file 自动注入）中
显式环境变量compose environment 段 / 服务启动环境最高

3.2 查看当前生效值

只读接口（管理员 Token，实测）：

curl -s -H "Authorization: Bearer <API Token>" http://localhost:13904/api/v3/root/config/

实测返回节选：

{
    "error_reporting": {"enabled": false, "send_pii": false, "traces_sample_rate": 0.1},
    "capabilities": ["can_save_media","can_save_reports","can_asn","can_geo_ip","can_impersonate","is_enterprise","can_agent_self_service"],
    "cache_timeout": 300,
    "cache_timeout_flows": 300,
    "cache_timeout_policies": 300
}

缓存类参数实测恰为默认值 300 秒。内置默认文件的程序侧默认值实拍（worker 内置 default.yml，键值实测）：

postgresql.host: localhost
postgresql.name: authentik
listen.http: ["[::]:9000"]
listen.https: ["[::]:9443"]
web.workers: 2
web.threads: 4
cache.timeout: 300
log_level: info

服务进程当前注入的环境变量键名（server 进程 printenv 过滤 AUTHENTIK_ 前缀，实测）：

AUTHENTIK_POSTGRESQL__HOST
AUTHENTIK_POSTGRESQL__NAME
AUTHENTIK_POSTGRESQL__USER
AUTHENTIK_BOOTSTRAP_PASSWORD
AUTHENTIK_BOOTSTRAP_TOKEN
AUTHENTIK_SECRET_KEY

3.3 修改与生效

  1. 改 .env（或 compose 的 environment 段）；
  2. 重建对应进程使新变量进入启动环境（restart 不重读编排文件，需 force-recreate 形态的重建操作，命令见《Authentik Docker Compose 部署指南》第九节）；
  3. 复验：健康检查 200 + /root/config/ 或日志确认新值。

四、参数总览

参数默认值说明生效证据
AUTHENTIK_SECRET_KEY无（必填）数据加密主密钥缺失时启动编排直接失败（实测报错见 5.1）
PG_PASS无（必填）数据库密码同上
PG_USER / PG_DBauthentik库用户/库名启动日志 PostgreSQL connection successful（实测）
AUTHENTIK_BOOTSTRAP_PASSWORD无akadmin 初始密码用其登录成功（实测走完默认登录 Flow）
AUTHENTIK_BOOTSTRAP_TOKEN无akadmin 初始 API TokenBearer 调 /api/v3/admin/version/ 返回 200（实测）
COMPOSE_PORT_HTTP(S)9000 / 9443宿主映射端口13904/13906 映射生效（实测 ps 回显）
AUTHENTIK_WEB__PATH/Web 根路径前缀子路径反代场景使用
AUTHENTIK_POSTGRESQL__HOSTlocalhost数据库地址编排中实测注入 postgresql 服务名
AUTHENTIK_LOG_LEVELinfo日志级别默认日志级别 info（实测）
cache_timeout*300三类缓存超时秒数/root/config/ 实测 300

五、核心参数分类详解

5.1 必填安全参数：AUTHENTIK_SECRET_KEY 与 PG_PASS

二者在编排文件中以 :? 断言强制（实测缺失时的报错原文）：

error while interpolating services.postgresql.environment.POSTGRES_PASSWORD: required variable PG_PASS is missing a value: database password required
error while interpolating services.server.environment.AUTHENTIK_SECRET_KEY: required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required

生成建议（实测使用的命令形态）：openssl rand -hex 32（SECRET_KEY）、openssl rand -hex 16（PG_PASS）。SECRET_KEY 变更会使既有加密数据不可解，禁止随意轮换；PG_PASS 有一个重要行为——数据库仅在数据目录首次初始化时采纳该密码，之后再改变量不会自动同步库内密码，必须用 SQL 同步（实测排障全过程见《Authentik Docker Compose 部署指南》Q2）。

5.2 引导参数：AUTHENTIK_BOOTSTRAP_*

仅在首次初始化时生效。BOOTSTRAP_PASSWORD 实测验证：以 akadmin + 该密码走默认登录 Flow，三步后 final_redirect: true 并以 akadmin（is_superuser: true）取得会话；BOOTSTRAP_TOKEN 实测验证：作为 Bearer Token 调用版本接口成功。初始化完成后如需新 Token，走管理台或 API 创建。

5.3 端口与路径参数

COMPOSE_PORT_HTTP/COMPOSE_PORT_HTTPS 控制宿主侧映射（实测 13904→9000、13906→9443）。AUTHENTIK_WEB__PATH 用于把整站挂在子路径（如反代到 /authentik/ 下），修改后需重启 server 生效；官方默认 /。

5.4 数据库参数族（AUTHENTIK_POSTGRESQL__*）

双下划线映射嵌套配置（POSTGRESQL__HOST → postgresql.host）。实测本机注入 HOST=postgresql、NAME=authentik、USER=authentik、PASSWORD=PG_PASS 值；连接成功的日志证据（实测）：PostgreSQL connection successful。其余可选项含 AUTHENTIK_POSTGRESQL__PORT（默认 5432）、__SSL_MODE、__MAX_CONNS 等，按需追加。

5.5 缓存与日志参数

cache_timeout（通用）、cache_timeout_flows、cache_timeout_policies 实测均为 300 秒；修改后需重启。日志级别 AUTHENTIK_LOG_LEVEL 默认 info；排障时可临时调 debug，问题定位后回 info（日志为 JSON 行格式，含 timestamp/level/logger/event 字段，实测样例）：

{"event": "PostgreSQL connection successful", "level": "info", "logger": "authentik.lib.config", "timestamp": 1792267900.7896}

5.6 Web 并发参数（内置默认）

web.workers 默认 2、web.threads 默认 4（内置默认文件实测值）；authentik 另受官方 2C/2G 最低规格约束，扩容先加 CPU 再考虑加 workers。

六、生产配置模板

适用场景：4C/8G、NVMe、2000 用户以内、数十应用接入的中小规模自托管。

# /opt/data/authentik/.env （600 权限；敏感值示例用生成命令替换占位）
AUTHENTIK_SECRET_KEY=<openssl rand -hex 32 生成>
AUTHENTIK_BOOTSTRAP_PASSWORD=<首次初始化用，初始化后可删除本行>
AUTHENTIK_BOOTSTRAP_TOKEN=<首次初始化用，初始化后可删除本行>
PG_USER=authentik
PG_DB=authentik
PG_PASS=<openssl rand -hex 16 生成>
COMPOSE_PORT_HTTP=13904
COMPOSE_PORT_HTTPS=13906
AUTHENTIK_LOG_LEVEL=info
AUTHENTIK_ERROR_REPORTING__ENABLED=false
AUTHENTIK_WEB__PATH=/

逐项说明：上报开关关闭（error_reporting 实测默认即 false）；端口按内网规划映射；bootstrap 两行在初始化稳定后从 .env 移除以收敛敏感面。

七、常见问题

Q1：改了 .env 不生效？ 进程只在启动时读环境变量；restart 不重读编排文件。需重建进程（compose up -d --force-recreate <服务> 形态），并注意插值断言要求会话中提供两个必填变量（见 5.1 实测报错）。

Q2：PG_PASS 改了之后连接失败？ 数据库密码不随变量自动更新。实测现象与 SQL 同步修复见《Authentik Docker Compose 部署指南》Q2。

Q3：如何确认某参数已被进程读到？ 三步：服务进程内查看环境变量键名（printenv 过滤）→ /root/config/ 或对应接口比对值 → 观察行为（如缓存超时、日志级别）。

Q4：多进程实例 SECRET_KEY 不一致会怎样？ 加密数据跨进程不可解，属严重故障。务必所有应用进程使用同一 SECRET_KEY（本部署中经同一变量同时注入，天然一致）。

八、参考链接