GitLab AI Gateway 自托管版镜像文档

一、镜像概述和主要用途

GitLab AI Gateway 自托管版是 GitLab 官方提供的容器化部署方案，用于在私有基础设施中部署 AI 请求管理网关。该网关作为 GitLab 实例与各类 AI 模型服务（如 OpenAI、Anthropic、Google Vertex AI 等）之间的中间层，提供请求路由、认证授权、流量控制、日志监控等核心能力，支持企业级 GitLab 环境的 AI 功能私有化部署与管控。

二、核心功能和特性

2.1 核心功能

• 多模型集成与路由
  支持对接主流 AI 模型服务商（OpenAI、Anthropic、Google Gemini 等），可根据请求类型自动路由至指定模型。
• GitLab 原生集成
  与 GitLab 身份认证系统深度整合，支持基于 GitLab 用户/组权限的访问控制，确保 AI 请求来源可追溯。
• 流量管控与成本优化
  提供请求限流、配额管理、成本预估功能，支持按用户/项目设置 AI 资源使用上限。
• 数据隐私与合规
  所有 AI 请求在私有网络内处理，避免敏感数据外流，满足 GDPR、HIPAA 等合规要求。
• 可观测性
  内置 metrics 接口（Prometheus 兼容）和结构化日志，支持与 GitLab Monitor 或第三方监控系统集成。
• 动态配置管理
  支持通过环境变量或配置文件动态调整路由规则、模型参数和访问策略，无需重启服务。

三、使用场景和适用范围

3.1 典型使用场景

• 企业 GitLab 实例的 AI 功能私有化部署
  将 GitLab 内置 AI 功能（如代码解释、提交信息生成）的后端请求路由至私有部署的 AI 模型或第三方 API。
• 多团队共享 AI 资源的协作环境
  统一管理企业内多团队的 AI 请求，通过配额分配避免资源滥用，降低总体使用成本。
• 高合规性要求的行业场景
  金融、医疗、政务等对数据隐私有严格要求的领域，通过自托管网关确保 AI 交互数据不经过第三方服务器。
• 混合云 AI 资源管理
  同时对接私有 AI 模型（如本地部署的 Llama 系列）和公有云 AI 服务，实现流量智能调度。

3.2 适用范围

• 已部署 GitLab 自托管实例（Community/Enterprise Edition 16.0+）的组织
• 需要对 AI 功能访问权限、成本、数据流向进行严格管控的企业
• 具备基础 Docker 容器化部署能力的 IT 团队

四、使用方法和配置说明

4.1 前提条件

• 运行环境：Docker 20.10+ 或 Kubernetes 1.21+
• 网络要求：可访问 GitLab 实例（自托管或 SaaS）及目标 AI 模型服务（如 OpenAI API）
• 权限要求：具备 GitLab 管理员权限（用于配置 API 访问令牌）

4.2 获取镜像

从 GitLab Container Registry 拉取官方镜像：

docker pull registry.gitlab.com/gitlab-org/ai-gateway:latest

4.3 基本部署（Docker Run）

4.3.1 最小化部署命令

docker run -d \
  --name gitlab-ai-gateway \
  -p 8080:8080 \
  -e GITLAB_URL="[***]" \
  -e GITLAB_API_TOKEN="glpat-xxxxxx" \
  -e LOG_LEVEL="info" \
  registry.gitlab.com/gitlab-org/ai-gateway:latest

4.3.2 带配置文件的部署（推荐）

docker run -d \
  --name gitlab-ai-gateway \
  -p 8080:8080 \
  -e GITLAB_URL="[***]" \
  -e GITLAB_API_TOKEN="glpat-xxxxxx" \
  -v /path/to/local/config.yaml:/etc/ai-gateway/config.yaml \
  registry.gitlab.com/gitlab-org/ai-gateway:latest

4.4 Docker Compose 配置示例

创建 docker-compose.yml：

version: '3.8'
services:
  ai-gateway:
    image: registry.gitlab.com/gitlab-org/ai-gateway:latest
    container_name: gitlab-ai-gateway
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - GITLAB_URL=[***]
      - GITLAB_API_TOKEN=glpat-xxxxxx
      - LOG_LEVEL=info
      - PORT=8080
      - METRICS_ENABLED=true
      - METRICS_PORT=9090
    volumes:
      - ./config.yaml:/etc/ai-gateway/config.yaml  # 挂载自定义配置文件
      - ./logs:/var/log/ai-gateway  # 挂载日志目录
    networks:
      - gitlab-network

networks:
  gitlab-network:
    external: true  # 假设已存在与 GitLab 实例互通的网络

4.5 环境变量说明

4.6 配置文件说明

4.6.1 配置文件结构（config.yaml）

通过挂载配置文件可实现复杂路由规则和模型配置，示例：

# 模型服务配置
models:
  - name: "openai-gpt4"
    type: "openai"
    base_url: "[***]"
    api_key: "sk-xxxxxx"  # 或通过环境变量 OPENAI_API_KEY 注入
    timeout: 30s
    rate_limit:
      requests_per_minute: 1000  # 全局限流

  - name: "anthropic-claude"
    type: "anthropic"
    base_url: "[***]"
    api_key: "sk-ant-xxxxxx"
    timeout: 60s

# 路由规则（与 GitLab 项目/用户关联）
routes:
  - match:
      gitlab_project_id: "123"  # 仅允许项目 ID 123 访问
      model_name: "openai-gpt4"
    destination: "openai-gpt4"
    rate_limit:
      requests_per_minute: 200  # 项目级限流

  - match:
      gitlab_group_id: "456"  # 允许组 ID 456 下所有项目访问
      model_name: "anthropic-claude"
    destination: "anthropic-claude"

# GitLab 集成配置
gitlab:
  timeout: 10s
  verify_tls: true  # 禁用自签名证书时设为 false

4.6.2 配置文件挂载

在 docker run 或 docker-compose 中通过 -v 挂载本地配置文件：

-v /local/path/to/config.yaml:/etc/ai-gateway/config.yaml

4.7 启动与验证

1. 启动服务：

   docker start gitlab-ai-gateway
   

2. 验证运行状态：

   docker logs -f gitlab-ai-gateway  # 查看启动日志，确认无报错
   curl http://localhost:8080/health  # 健康检查接口，返回 {"status":"ok"}
   

3. 验证 GitLab 集成：
   通过 GitLab 实例的 AI 功能（如代码建议）发起请求，在网关日志中查看请求记录。

4.8 升级与维护

• 升级镜像：

  docker pull registry.gitlab.com/gitlab-org/ai-gateway:latest
  docker stop gitlab-ai-gateway && docker rm gitlab-ai-gateway
  # 重新执行 docker run 或 docker-compose up -d
  

• 数据备份：
  定期备份配置文件（config.yaml）和日志目录（/var/log/ai-gateway）。

五、常见问题

• Q：如何排查请求失败？
  A：查看容器日志（docker logs），开启 LOG_LEVEL=debug 获取详细请求信息，检查网络连通性和 API 密钥有效性。

• Q：能否对接私有部署的 AI 模型（如本地 Llama）？
  A：支持，在 models 配置中设置 type: "generic" 并指定 base_url 为私有模型服务地址。

• Q：如何限制单个用户的 AI 请求配额？
  A：在 routes 配置中通过 gitlab_user_id 匹配用户，并设置 rate_limit 即可。