用 Docker Compose 安装 authentik 并完成首次登录-未完纪

authentik 官方将 Docker Compose 安装定位为测试环境和小规模生产环境的部署方式。本文按官方安装页依次整理主机准备、配置下载、密钥生成、端口与 Docker socket、邮件设置、启动和管理员首次登录，保留原文每个实质步骤，并在容易误用的地方注明静态审核发现。

来源核对日期为 2026-10-05。本文没有执行安装命令、启动容器或创建管理员账号；示例用于部署前阅读和受控环境验证。原文由 authentik 项目维护，未见可确认的个人作者署名。

原创安装关系示意图，不是实际部署截图。

1. 准备主机与 Compose

官方给出的最低要求是至少 2 个 CPU 核和 2 GB 内存，以及 Podman 或 Docker Compose。使用 Docker Compose 时要求 Compose v2；命令形式是 docker compose。最低资源值不是针对任意用户量、认证流量或高可用需求的容量保证。

原页另附官方安装视频作为辅助材料。以下文字已覆盖页面安装步骤；视频入口可从官方安装页的视频章节进入。本文未把视频里可能使用的历史版本当作当前配置依据。

2. 下载 Compose 文件

进入计划保存配置的专用目录，然后按系统选择一种下载方式。Linux 示例：

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

macOS 示例：

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

下载得到的是 compose.yml。原页启动段落仍提到 docker-compose.yml，这里统一使用实际下载文件名；不要误以为需要再创建第二份配置。下载后应先阅读服务、卷、端口和镜像版本，再在同一目录准备 .env。下文的 Shell 命令面向类 Unix 环境，不能原样当作 PowerShell 命令运行。

3. 生成 PostgreSQL 密码与 authentik 密钥

全新安装需要 PostgreSQL 密码和 authentik secret key。官方允许使用可靠的密码生成器，例如 pwgen，或下面的 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

openssl rand 生成随机字节，Base64 将其转成文本，tr -d '\n' 去掉换行。前者生成的密码长度约为 48 个字符，符合该安装页所写的“不支持超过 99 个字符的 PostgreSQL 密码”约束。原页将该说法链接到 PostgreSQL 邮件列表讨论；这里将其视为该部署流程的兼容性要求，不扩大成所有 PostgreSQL 版本和认证方法统一的固有限制。

编辑补充：这是首次安装操作。不要在已有实例上随意重跑：追加会制造重复变量，重新生成密码可能与已初始化数据库不一致，替换 secret key 也可能破坏已有加密数据或凭据的使用。执行前确认 OpenSSL 可用并检查命令成功，避免把空值写入配置。

.env 保存明文秘密，应限制目录和文件访问权限，避免提交到版本控制、贴入工单或录入日志。类 Unix 主机可在创建文件前采用仅允许当前用户读取的默认权限：

umask 077

这条是本文补充的权限准备步骤，不是原文安装命令。对已经存在的文件，还需单独核查实际权限。密钥和数据库应纳入受保护的备份策略。

如果选择启用错误上报，原文给出：

echo "AUTHENTIK_ERROR_REPORTING__ENABLED=true" >> .env

错误上报是可选配置；应按组织的数据处理要求决定是否启用，不要把它混同于安装必须步骤。各 Compose 服务的职责可查看官方核心概念与架构说明。

4. 配置对外端口

authentik 默认内部 HTTP 端口为 9000，HTTPS 端口为 9443。如果希望主机对外使用 80 和 443，可在 .env 设置：

COMPOSE_PORT_HTTP=80
COMPOSE_PORT_HTTPS=443

这两个变量调整的是暴露端口；修改服务内部端口应参考官方配置文档。修改后需要重新运行 docker compose up -d 让配置生效。端口映射到 443 本身不证明证书可信或外部访问链路已经安全；使用反向代理时还需按官方反向代理文档配置。

5. 理解 Docker socket 的用途和权限

官方 Compose 默认把 Docker socket 挂载到 authentik worker 容器：

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

这个挂载用于自动部署和管理 authentik Outpost。它会让容器获得与 Docker 守护进程交互的能力，因此权限影响远大于普通业务文件挂载。原文给出了两条路径：使用 Docker Socket Proxy 增加保护层，或移除此挂载，改为手工部署和管理 Outpost。

是否保留挂载应在启动前决定，并核对所需自动化功能。socket proxy 需要配置合适的 API 访问范围，不能仅因为加了一层代理就认为已经消除了宿主机控制风险。相应操作入口均列在原页 Docker socket 章节。

6. 配置邮件：可选，但建议在实际使用前完成

全局邮件设置用于向管理员发送告警、配置问题和新版本通知，也能供 Email stage 发送验证邮件与账号恢复邮件。原文没有在安装页展开 SMTP 参数，而是链接到邮件配置文档；应根据实际邮件服务设置和验证，不要把缺少邮件能力的实例当作已经具备可靠的账号恢复流程。

7. 拉取镜像并启动

准备好 Compose 文件、密码、secret key 和可选邮件配置后，在配置目录运行：

docker compose pull
docker compose up -d

第一条拉取 Compose 中指定的镜像，第二条创建或更新服务并在后台运行。启动会改变主机容器、网络和卷的状态；本文未执行这些操作。部署前应检查下载文件的具体内容、主机端口占用以及已有同名项目和数据卷。

不要挂载本地时区文件。authentik 的内部操作使用 UTC，用户界面会自动按用户本地时区显示时间。官方明确要求不要修改或挂载容器内的 /etc/timezone、/etc/localtime，否则可能引发 OAuth 和 SAML 认证问题。

下载的 compose.yml 静态指向下载时可用的版本。以后执行 docker compose pull 不等于自动切换到任意新版本；升级时官方要求获取指向新版本的 Compose 文件，并阅读发行说明中的升级章节。既有实例应另行核对升级路径、备份和恢复措施，不能把首次安装步骤直接当成完整升级方案。