#安装前配置

#准备 GitLab 服务

在 Alauda AI 中，GitLab 是模型管理的核心组件。部署 Alauda AI 之前，您必须准备一个 GitLab 服务。

#部署选项

#1. GitLab 服务要求

无论采用何种部署方式，所有 GitLab 实例必须满足：

• 版本：必须是 v15 或更高版本。
• 协议：必须使用 HTTPS。配置说明请参见 配置 HTTPS。
• Git LFS：必须启用。配置说明请参见 使用 LFS 管理大文件。
• 托管方式：必须是自托管（不支持公有云托管的 GitLab 服务）。
• 访问令牌：禁用访问令牌的过期时间。

#2. 使用平台提供的插件

使用 ‘Alauda Build of GitLab’ 插件部署新的 GitLab 服务。操作指南请参见：部署 Alauda Build of GitLab。

#3. 使用自有 GitLab 服务

您也可以使用自管理的 GitLab 实例，但必须满足 GitLab 服务要求。

#GitLab 配置

在部署 Alauda AI 之前，获取服务后请完成以下 GitLab 配置步骤。

#1. 禁用访问令牌过期时间

如果 GitLab 版本为 v17.0 或更高版本，需要禁用访问令牌的过期时间。

禁用新访问令牌过期时间的步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > General。
3. 展开 Account and limit。
4. 取消选中 Personal / Project / Group access token expiration 复选框。
5. 选择 Save changes。

#2. 生成新令牌

生成管理员的模拟令牌步骤：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Overview > Users。
3. 选择管理员用户（例如 Administrator）。
4. 在顶部导航栏选择 Impersonation Tokens。
5. 选择 Add new token。
6. 在弹出表单中：
   1. 输入 Alauda AI 的 令牌名称（例如 aml-root）。
   2. 移除 过期时间（点击“x”图标移除过期时间）。
   3. 选择 所有 权限（特别是 api 权限）作为 Select scopes。
7. 选择 Create impersonation token。
8. 保存弹窗中显示的新生成令牌，后续需要使用。

#3. 为管理员令牌创建 kubernetes secret

接着，在 cpaas-system 命名空间下创建名为 aml-gitlab-admin-token 的 gitlab 管理员令牌 secret：

# 请将 ${TOKEN} 替换为之前保存的真实令牌
kubectl create secret generic aml-gitlab-admin-token \
  --from-literal="password=${TOKEN}" \
  -n cpaas-system

#常见问题 (FAQ)

#1. 如何优化 GitLab 18.5 及以上版本以支持大容量 LFS 对象？

问题描述：
向 GitLab 18.5 及以上版本推送大容量 LFS 对象时，可能遇到 HTTP 413 错误。AI 模型管理中，常需通过 LFS 上传大模型文件，文件大小超过了 Nginx ingress controller 默认的 proxy-body-size 限制（通常为 512M）（这些 Nginx ingress 注解通常与版本无关，也适用于其他遇到 LFS 上传大小限制的 GitLab 版本）。

以下为 Git LFS 客户端的真实诊断输出，%!!(string=...) 片段为 Go 语言格式化残留，可忽略，重点关注 HTTP 413 响应错误。

❯ git push origin main
Locking support detected on remote "origin". Consider enabling it with:
  $ git config lfs.https://gitlab-18-5-aml.alaudatech.net/mlops-demo-ai-test/amlmodels/qa.git/info/lfs.locksverify true
LFS: Client error &{%!!(string=https) %!!(string=) %!!(*url.Userinfo=<nil>) %!!(string=gitlab-18-5-aml.alaudatech.net) %!!(string=/mlops-demo-ai-test/amlmodels/qa.git/gitlab-lfs/objects/fdf756fa7fcbe7404d5c60e26bff1a0c8b8aa1f72ced49e7dd0210fe288fb7fe/988097824) %!!(string=) %!!(bool=false) %!!(bool=false) %!!(string=) %!!(string=) %!!(string=)}s(MISSING) from HTTP 413
Uploading LFS objects:   0% (0/1), 0 B | 0 B/s, done.
error: failed to push some refs to 'https://gitlab-18-5-aml.alaudatech.net/mlops-demo-ai-test/amlmodels/qa.git'

解决方案：
为支持大文件上传并提升整体性能，需要在 GitLab 服务上配置特定的 Nginx Ingress 注解。

#Ingress 注解参数

以下为推荐的 Ingress 参数及其功能说明：

#配置步骤

您可以通过更新 GitLabOfficial 自定义资源（CR）来应用这些优化。

1. 通过 kubectl patch 命令应用

使用以下命令直接更新 GitLabOfficial CR 中的 ingress 注解：

# 更新 GitLabOfficial CR，添加优化的 ingress 注解
# [!code callout:1,2]
kubectl patch gitlabofficial your-instance-name -n your-instance-namespace --type=merge -p '{
  "spec": {
    "helmValues": {
      "global": {
        "ingress": {
          "annotations": {
            "nginx.ingress.kubernetes.io/proxy-body-size": "0",
            "nginx.ingress.kubernetes.io/proxy-buffering": "off",
            "nginx.ingress.kubernetes.io/proxy-read-timeout": "3600",
            "nginx.ingress.kubernetes.io/proxy-request-buffering": "off",
            "nginx.ingress.kubernetes.io/proxy-send-timeout": "3600"
          }
        }
      }
    }
  }
}'

2. YAML 层级结构参考

以下为 GitLabOfficial CR spec 中 ingress.annotations 的层级结构示例：

apiVersion: gitlab.alauda.io/v1alpha1
kind: GitLabOfficial
metadata:
  name: gitlab-aml
  namespace: gitlab-system-aml
spec:
  # ... 其他 spec ...
  helmValues:
    global:
      ingress:
        annotations:
          nginx.ingress.kubernetes.io/proxy-body-size: "0"
          nginx.ingress.kubernetes.io/proxy-buffering: "off"
          nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
          nginx.ingress.kubernetes.io/proxy-request-buffering: "off"
          nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"