Help us learn about your current experience with the documentation. Take the survey.

GitLab Duo 自托管支持工程师手册

  • Tier: Premium, Ultimate
  • Add-on: GitLab Duo Enterprise
  • Offering: GitLab Self-Managed

支持工程师手册和常见问题

本节为支持工程师提供调试 GitLab Duo 自托管问题的基本命令和故障排除步骤。

基本调试命令

显示 AI Gateway 环境变量

检查所有 AI Gateway 环境变量以验证配置：

docker exec -it <ai-gateway-container> env | grep AIGW

需要验证的关键变量：

  • AIGW_CUSTOM_MODELS__ENABLED - 必须为 true
  • AIGW_GITLAB_URL - 应与您的 GitLab 实例 URL 匹配
  • AIGW_GITLAB_API_URL - 应该可以从容器访问
  • AIGW_AUTH__BYPASS_EXTERNAL - 应仅在故障排除期间为 true

验证用户权限

检查用户是否具有使用自托管模型的 Code Suggestions 的正确权限：

# 在 GitLab Rails 控制台中
user = User.find_by_id("<user_id>")
user.allowed_to_use?(:code_suggestions, service_name: :self_hosted_models)

检查 AI Gateway 客户端日志

查看 AI Gateway 客户端日志以识别连接问题：

docker logs <ai-gateway-container> | grep "Gitlab::Llm::AiGateway::Client"

查看 AI Gateway 请求的 GitLab 日志

要查看发送到 AI Gateway 的实际请求，请使用：

# 查看实时日志
sudo gitlab-ctl tail | grep -E "(ai_gateway|llm\.log)"

# 查看带有 JSON 格式的特定日志文件
sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq '.'

# 过滤特定请求类型
 sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq 'select(.message)'

 sudo cat /var/log/gitlab/gitlab-rails/llm.log | grep Llm::CompletionWorker | jq '.'

查看 AI Gateway 模型请求日志

要查看发送到模型的实际请求：

# 查看 AI Gateway 容器日志
docker logs <ai-gateway-container> 2>&1 | grep -E "(model|litellm|custom_openai)"

# 如果有结构化日志
docker logs <ai-gateway-container> 2>&1 | grep "model_endpoint"

常见配置问题和解决方案

模型端点缺少 /v1 后缀

症状：向 vLLM 或 OpenAI 兼容模型发出请求时出现 404 错误

如何在日志中发现：

# 在 AI Gateway 日志中查找 404 错误
docker logs <ai-gateway-container> | grep "404"

解决方案：确保模型端点包含 /v1 后缀：

  • 错误：http://localhost:4000
  • 正确：http://localhost:4000/v1

证书验证问题

症状：SSL 证书错误或连接失败

如何在日志中发现：

# 查找 SSL/TLS 错误
sudo cat /var/log/gitlab/gitlab-rails/llm.log | grep -i "ssl\|certificate\|tls"

验证：验证证书状态 - GitLab 服务器必须使用可信证书，因为不支持自签名证书。

解决方案：

  • 为 GitLab 实例使用可信证书
  • 如果使用自签名证书，请在 AI Gateway 容器中配置正确的证书路径

网络连接问题

症状：超时或连接被拒绝错误

如何在日志中发现：

# 查找网络相关错误
docker logs <ai-gateway-container> | grep -E "(timeout|connection|refused|unreachable)"

验证命令：

# 从 AI Gateway 容器测试到 GitLab 的连接
docker exec -it <ai-gateway-container> curl "$AIGW_GITLAB_API_URL/projects"

# 从 AI Gateway 容器测试到模型端点的连接
docker exec -it <ai-gateway-container> curl "<model_endpoint>/health"

身份验证和授权问题

症状：401 未授权或 403 禁止访问错误

如何在日志中发现：

# 查找身份验证错误
sudo cat /var/log/gitlab/gitlab-rails/llm.log | jq 'select(.status == 401 or .status == 403)'

常见原因：

  • 用户未分配 GitLab Duo Enterprise 许可
  • 许可证问题
  • AI Gateway URL 配置不正确

模型配置问题

症状：模型无响应或返回错误

如何在日志中发现：

# 查找模型特定错误
docker logs <ai-gateway-container> | grep -E "(model_name|model_endpoint|litellm)"

验证：

# 直接从 AI Gateway 容器测试模型
docker exec -it <ai-gateway-container> sh
curl --request POST "<model_endpoint>/v1/chat/completions" \
     --header 'Content-Type: application/json' \
     --data '{"model": "<model_name>", "messages": [{"role": "user", "content": "Hello"}]}'

日志分析工作流程

步骤 1：启用详细日志记录

在 GitLab Rails 控制台中检查是否启用了 捕获有关 AI 相关活动和请求的详细信息 实例设置：

::Ai::Setting.instance.enabled_instance_verbose_ai_logs

如果返回 false，请使用以下命令启用标志：

::Ai::Setting.instance.update!(enabled_instance_verbose_ai_logs: true)

要启用日志记录，请使用 enabled_instance_verbose_ai_logs 实例设置。不要使用 expanded_ai_logging 功能标志。仅在 GitLab.com 上使用 expanded_ai_logging 功能标志进行调试。不要在 GitLab 自托管实例中使用此功能标志，包括运行 GitLab Duo 自托管的实例。

步骤 2：重现问题

让用户在监控日志时重现问题：

# 终端 1：监控 GitLab 日志
sudo gitlab-ctl tail | grep -E "(ai_gateway|llm\.log)"

# 终端 2：监控 AI Gateway 日志
docker logs -f <ai-gateway-container>

步骤 3：分析请求流程

  1. GitLab 到 AI Gateway：检查请求是否到达 AI Gateway
  2. AI Gateway 到模型：验证是否调用了模型端点
  3. 响应路径：确保响应格式正确并已返回

步骤 4：常见错误模式

错误模式 位置 可能原因
Connection refused GitLab 日志 AI Gateway 不可访问
404 Not Found AI Gateway 日志 模型端点缺少 /v1
401 Unauthorized GitLab 日志 身份验证/许可证问题
Timeout 任意位置 网络或模型性能问题
SSL certificate verify failed GitLab 日志 证书验证问题

快速诊断命令

AI Gateway 实例命令：

1. 测试 AI Gateway 健康状态：

curl --silent --output /dev/null --write-out "%{http_code}" "<ai-gateway-url>/monitoring/healthz"

2. 检查 AI Gateway 环境变量：

docker exec <ai-gateway-container> env | grep AIGW

3. 检查 AI Gateway 错误日志：

docker logs <ai-gateway-container> 2>&1 | grep --ignore-case error | tail --lines=20

GitLab 自托管实例命令：

4. 检查用户权限（GitLab Rails 控制台）：

sudo gitlab-rails console

然后在控制台中：

User.find_by_id('<user_id>').can?(:access_code_suggestions)

5. 检查 GitLab LLM 错误日志：

sudo tail --lines=100 /var/log/gitlab/gitlab-rails/llm.log | grep --ignore-case error

6. 检查功能标志：

sudo gitlab-rails console

然后：

Feature.enabled?(:expanded_ai_logging)

7. 测试从 GitLab 到 AI Gateway 的连接性：

curl --verbose "<ai-gateway-url>/monitoring/healthz"

紧急诊断单行命令

用于快速问题识别：

# 一次性检查所有关键组件
docker exec <ai-gateway-container> env | grep AIGW_CUSTOM_MODELS__ENABLED && \
curl --silent "<ai-gateway-url>/monitoring/healthz" && \
sudo tail --lines=10 /var/log/gitlab/gitlab-rails/llm.log | jq '.level'

升级标准

在以下情况下升级到自定义模型团队：

  1. 完成所有基本故障排除步骤后仍未解决问题
  2. 模型集成问题需要深厚的技术知识
  3. 功能未列出在自托管模型单元基元中
  4. 疑似 GitLab Duo 平台错误影响多个用户
  5. 特定模型配置的性能问题

其他资源