ProjectAGiPrompt/36-统一单点登录/3-authentik部署.md

以下是为你量身打造的 Authentik 单机 docker-compose 部署方案，适合中国大陆服务器环境，镜像使用 ghcr.io 官方源（如访问有困难可配置代理或 mirror）。

---

目录结构

部署前先创建工作目录：

mkdir -p /opt/authentik/{media,certs,custom-templates,backups}
cd /opt/authentik

---

.env 环境变量文件

先生成密钥并写入 .env，这一步必须执行： docs.goauthentik

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

完整 .env 参考（根据实际修改）：

# PostgreSQL 密码（由上面命令自动生成，勿手填）
PG_PASS=<auto-generated>

# Authentik 核心密钥（由上面命令自动生成）
AUTHENTIK_SECRET_KEY=<auto-generated>

# 对外暴露端口（按需修改，如已有反代则设为内部端口即可）
COMPOSE_PORT_HTTP=9000
COMPOSE_PORT_HTTPS=9443

# 邮件配置（可选，用于验证码/告警，中国大陆推荐 SMTP 465）
# AUTHENTIK_EMAIL__HOST=smtp.example.com
# AUTHENTIK_EMAIL__PORT=465
# AUTHENTIK_EMAIL__USERNAME=noreply@example.com
# AUTHENTIK_EMAIL__PASSWORD=your_email_password
# AUTHENTIK_EMAIL__USE_SSL=true
# AUTHENTIK_EMAIL__FROM=authentik@example.com

# 禁用错误上报（中国大陆环境下建议关闭，避免外联超时）
AUTHENTIK_ERROR_REPORTING__ENABLED=false

# 时区（注意：authentik 容器内部必须使用 UTC，不要挂载 /etc/localtime）
# Web UI 会自动本地化显示时间

⚠️ 重要：官方明确说明，不要在 authentik 容器内修改或挂载 /etc/timezone / /etc/localtime，否则会导致 OAuth/SAML 认证异常。 docs.goauthentik

---

docker-compose.yml

---
services:

  # ── PostgreSQL 数据库 ──────────────────────────────────────────
  postgresql:
    image: docker.io/library/postgres:16-alpine
    container_name: authentik-db
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 5s
    environment:
      POSTGRES_PASSWORD: ${PG_PASS}
      POSTGRES_USER: authentik
      POSTGRES_DB: authentik
    volumes:
      - authentik_db:/var/lib/postgresql/data   # 持久化数据库
    networks:
      - authentik-internal

  # ── Redis 缓存 ─────────────────────────────────────────────────
  redis:
    image: docker.io/library/redis:7-alpine
    container_name: authentik-redis
    restart: unless-stopped
    command: --save 60 1 --loglevel warning
    healthcheck:
      test: ["CMD-SHELL", "redis-cli ping | grep PONG"]
      start_period: 20s
      interval: 30s
      retries: 5
      timeout: 3s
    volumes:
      - authentik_redis:/data                   # 持久化 Redis 数据
    networks:
      - authentik-internal

  # ── Authentik Server（Web UI + API）───────────────────────────
  server:
    image: ghcr.io/goauthentik/server:2025.6
    container_name: authentik-server
    restart: unless-stopped
    command: server
    depends_on:
      postgresql:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
      AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING__ENABLED:-false}
      # 邮件配置（与 .env 联动，未配置时留空即可）
      AUTHENTIK_EMAIL__HOST: ${AUTHENTIK_EMAIL__HOST:-localhost}
      AUTHENTIK_EMAIL__PORT: ${AUTHENTIK_EMAIL__PORT:-25}
      AUTHENTIK_EMAIL__USERNAME: ${AUTHENTIK_EMAIL__USERNAME:-}
      AUTHENTIK_EMAIL__PASSWORD: ${AUTHENTIK_EMAIL__PASSWORD:-}
      AUTHENTIK_EMAIL__USE_SSL: ${AUTHENTIK_EMAIL__USE_SSL:-false}
      AUTHENTIK_EMAIL__FROM: ${AUTHENTIK_EMAIL__FROM:-authentik@localhost}
    volumes:
      - ./media:/media                          # 上传文件/品牌Logo等
      - ./custom-templates:/templates           # 自定义模板（可选）
      - ./certs:/certs                          # 自定义 TLS 证书（可选）
    ports:
      - "${COMPOSE_PORT_HTTP:-9000}:9000"
      - "${COMPOSE_PORT_HTTPS:-9443}:9443"
    networks:
      - authentik-internal

  # ── Authentik Worker（后台任务/Outpost 管理）─────────────────
  worker:
    image: ghcr.io/goauthentik/server:2025.6
    container_name: authentik-worker
    restart: unless-stopped
    command: worker
    depends_on:
      postgresql:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      AUTHENTIK_REDIS__HOST: redis
      AUTHENTIK_POSTGRESQL__HOST: postgresql
      AUTHENTIK_POSTGRESQL__USER: authentik
      AUTHENTIK_POSTGRESQL__NAME: authentik
      AUTHENTIK_POSTGRESQL__PASSWORD: ${PG_PASS}
      AUTHENTIK_SECRET_KEY: ${AUTHENTIK_SECRET_KEY}
      AUTHENTIK_ERROR_REPORTING__ENABLED: ${AUTHENTIK_ERROR_REPORTING__ENABLED:-false}
    volumes:
      - ./media:/media
      - ./custom-templates:/templates
      - ./certs:/certs
      - ./backups:/backups                      # 备份输出目录
      - /var/run/docker.sock:/var/run/docker.sock  # Outpost 自动部署用
    user: root                                  # 访问 Docker socket 需要 root
    networks:
      - authentik-internal

# ── 持久化 Named Volumes ──────────────────────────────────────────
volumes:
  authentik_db:
    driver: local
  authentik_redis:
    driver: local

# ── 隔离网络 ──────────────────────────────────────────────────────
networks:
  authentik-internal:
    driver: bridge

---

启动与初始化

# 拉取镜像
docker compose pull

# 后台启动
docker compose up -d

# 查看日志（等待 server 健康）
docker compose logs -f server

浏览器访问 http://<服务器IP>:9000/if/flow/initial-setup/ 完成管理员密码设置。 docs.goauthentik

---

关键持久化路径说明

持久化内容	存储位置	说明
数据库数据	Named Volume authentik_db	所有用户、应用、策略配置
Redis 状态	Named Volume authentik_redis	Session、任务队列 github
媒体文件	./media 绑定挂载	品牌 Logo、用户头像等
证书	./certs 绑定挂载	自定义 TLS/SAML 证书
备份文件	./backups 绑定挂载	数据库备份输出

---

后续接入 Docmost / GitLab SSO 的协议选择

Authentik 支持多种协议，国内自托管场景推荐：

• GitLab → 使用 OAuth2/OIDC Provider（GitLab 原生支持，配置最简）
• Docmost → 使用 OIDC Provider（Docmost 支持标准 OIDC）
• 无 OIDC 支持的旧系统 → 使用 LDAP Outpost（Worker 容器自动管理）

如果 ghcr.io 在你的服务器上拉取速度慢，可在 /etc/docker/daemon.json 中配置国内镜像加速，或使用 docker pull 走代理后 docker save/load 离线导入。