garrison 0.9.0

Garrison - 面向 Rust 生态的一站式身份认证鉴权框架
Documentation
# Copyright (c) 2026 Kirky.X🌠
# SPDX-License-Identifier: Apache-2.0
#
# Garrison Auth Server 单机部署示例(本地构建镜像)。
#
# 用法:
#   export GARRISON_INTERNAL_API_KEY='<强随机密钥>'   # 必填,缺失或不足 32 字节即失败(fail-loud)
#                                                     # 生成建议:openssl rand -hex 32
#   docker compose -f docker-compose.example.yml up -d
#   docker compose -f docker-compose.example.yml ps   # STATUS 应为 healthy
#
# 镜像变体:默认 debian-slim;改用 distroless 时将 dockerfile 改为
# docker/Dockerfile.distroless(两变体的 healthcheck 均已用绝对路径
# /app/garrison healthcheck,distroless 无 /usr/local/bin 符号链接)。

name: garrison

services:
  auth-server:
    build:
      context: ..          # 仓库根(.dockerignore 与 Cargo.lock 在根)
      dockerfile: docker/Dockerfile
      args:
        # 仅落 OCI labels(org.opencontainers.image.version/revision),
        # garrison 无运行时版本端点,不做伪注入
        VERSION: dev
        GIT_SHA: unknown
    container_name: garrison-auth-server
    ports:
      - "8080:8080"
      # 管理面(check-* 等端点,需 X-API-Key)最小暴露:仅绑回环,防本机外
      # 网络直接触达;确认需要跨机访问时再显式放开
      - "127.0.0.1:8081:8081"
    environment:
      # 内网 API Key:auth_server fail-closed,未配置拒绝启动;
      # 长度强制 ≥32 字节(管理面唯一凭证,建议 `openssl rand -hex 32` 生成);
      # `:?required` 让 compose 在变量缺失/为空时直接报错,不静默起容器
      GARRISON_INTERNAL_API_KEY: ${GARRISON_INTERNAL_API_KEY:?required}
      # 端口覆盖(默认 8080/8081,改动后需同步 ports 映射):
      # GARRISON_EXTERNAL_PORT: 8080
      # GARRISON_INTERNAL_PORT: 8081
      # 绑定地址:镜像已内置 GARRISON_EXTERNAL_BIND/GARRISON_INTERNAL_BIND=0.0.0.0
      # (容器内必须绑 0.0.0.0 才能被 ports 映射);对外暴露面由上方 ports 控制
      # (内网端口已收敛为 127.0.0.1 宿主回环映射),勿改容器内绑定
      # GARRISON_EXTERNAL_BIND: 0.0.0.0
      # GARRISON_INTERNAL_BIND: 0.0.0.0
      # 并发会话策略:同账号最多 10 个在线会话,超出踢最早会话(0 = 不限制):
      # GARRISON_MAX_LOGIN_COUNT: 10
      # 可信代理:仅当本容器部署在可信反代(nginx/traefik 等)之后才配置,
      # 逗号分隔的内网/回环 IP;配置后 XFF 解析(限速键/客户端 IP)才启用:
      # GARRISON_TRUSTED_PROXIES: 10.0.0.1
      # 外网登录端点默认关闭(secure-by-default)。
      # ⚠️ 业务层必须先注入凭证校验再开启(框架 login 零凭证校验);
      #    开启后(镜像绑定 0.0.0.0,非回环)还须同时设置显式风险确认,
      #    否则容器 fail-closed 拒绝启动:
      # GARRISON_EXTERNAL_LOGIN_ENABLED: "true"
      # GARRISON_EXTERNAL_LOGIN_ACK: "i-understand-no-credential-check"
    restart: unless-stopped
    healthcheck:
      # 探测本容器外网端口的 sdforge liveness 探针(进程存活恒 200),
      # 目标端口自动跟随 GARRISON_EXTERNAL_PORT
      test: ["CMD", "/app/garrison", "healthcheck"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  # Redis(可选:rc.4 起限流后端 redis 真实驱动切换;会话/DAO 侧 Redis L2 仍未接线)
  # ⚠️ 接线范围如实说明,勿照抄本块假设:
  #   - GARRISON_RATE_LIMIT_BACKEND=redis 时,登录防火墙 hook 与 RateLimitStrategy
  #     切换到独立 Redis 限流运行时(oxcache RedisBackend + limiteron Lua 原子计数/滑窗),
  #     多实例限流计数共享;启动连接失败 fail-closed 拒绝启动,运行期 Redis 错误向上
  #     传播(登录 fail-closed),不静默回退内存。前置条件:backend=redis 须配
  #     GARRISON_REDIS_URL;需构建时传
  #     args: { FEATURES: "auth-server,cache-memory,server-health-check,tracing-log,rate-limit-redis" };
  #     开发用 redis://(非 TLS)需显式设 OXCACHE_ALLOW_INSECURE_REDIS=I_UNDERSTAND_THE_RISKS。
  #   - 会话/DAO 侧的 Redis L2 尚未接线(oxcache with_redis_config 仅存储配置,
  #     auth_server 未调用):多实例会话共享当前不可用,本示例不构成
  #     Redis 会话存储方案;跨实例会话请用 sticky session 或 stateless JWT。
  # 满足上述条件后取消下方注释,并给 auth-server 追加:
  #   environment:
  #     GARRISON_RATE_LIMIT_BACKEND: redis
  #     GARRISON_REDIS_URL: redis://redis:6379
  #   depends_on:
  #     redis:
  #       condition: service_healthy
  #
  # redis:
  #   image: redis:7-alpine
  #   container_name: garrison-redis
  #   restart: unless-stopped
  #   ports:
  #     - "6379:6379"
  #   healthcheck:
  #     test: ["CMD", "redis-cli", "ping"]
  #     interval: 5s
  #     timeout: 3s
  #     retries: 12
  #   volumes:
  #     - redis-data:/data
#
# volumes:
#   redis-data: