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 拉取***镜像：

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

4.3 基本部署（Docker Run）

4.3.1 最小化部署命令

bash
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 带配置文件的部署（推荐）

bash
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：

yaml
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 环境变量说明

环境变量名	必选	描述	示例值
`GITLAB_URL`	是	GitLab 实例基础 URL（自托管或 SaaS）	`[***]`
`GITLAB_API_TOKEN`	是	GitLab 个人访问令牌（需具备 `api` 和 `read_user` 权限）	`glpat-abc123def456`
`PORT`	否	服务监听端口（默认：8080）	`8080`
`LOG_LEVEL`	否	日志级别（debug/info/warn/error，默认：info）	`info`
`LOG_FORMAT`	否	日志格式（json/text，默认：text）	`json`
`METRICS_ENABLED`	否	是否启用 metrics 接口（默认：true）	`true`
`METRICS_PORT`	否	metrics 接口端口（默认：9090）	`9090`
`CONFIG_FILE_PATH`	否	自定义配置文件路径（容器内路径，默认：/etc/ai-gateway/config.yaml）	`/etc/ai-gateway/custom.yaml`

4.6 配置文件说明

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

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

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 挂载本地配置文件：

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

4.7 启动与验证

启动服务：

bash
docker start gitlab-ai-gateway

验证运行状态：

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

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

4.8 升级与维护

升级镜像：

bash
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 即可。