#安装前配置

#准备 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. 生成新令牌

要为管理员 生成 impersonation 令牌：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Overview > Users。
3. 选择管理员用户（例如 Administrator）。
4. 在顶部导航栏中，选择 Impersonation Tokens。
5. 选择 Add new token。
6. 在弹出的表单中：
   1. 为 Alauda AI 输入一个 Token name（例如 aml-root）。
   2. 移除 Expiration Date（选择 “x” 图标以移除过期时间）。
   3. 在 Select scopes 中勾选 所有 scopes（尤其是 api scope）。
7. 选择 Create impersonation token。
8. 在 Your new impersonation token 下 保存 新生成的令牌，后续需要使用。

#3. 为管理员令牌创建 Kubernetes Secret

然后我们在 cpaas-system 命名空间下创建名为 aml-gitlab-admin-token 的 GitLab 管理员令牌 Secret：

# Please replace ${TOKEN} with real token saved previously
kubectl create secret generic aml-gitlab-admin-token \
  --from-literal="password=${TOKEN}" \
  -n cpaas-system

#准备 Harbor 服务

如果您计划使用 Model Catalog 功能，请在安装 Alauda AI 之前准备一个 Alauda Build of Harbor 服务。该镜像仓库必须满足以下要求：

• 以生产模式运行。生产环境部署请使用 HTTPS。
• 允许推理集群节点在无需 image pull 凭据的情况下拉取 Model Catalog 镜像。

如果目标环境中无法部署 HTTPS 镜像仓库，可以使用 HTTP 镜像仓库作为备用方案，但在部署模型之前，必须先配置推理集群的容器运行时。关于详细的 containerd 配置，请参阅在创建 Alauda AI 实例时设置 Model OCI Registry Address 的说明。

有关安装步骤，请参阅 部署 Alauda Build of Harbor。

#常见问题（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 Custom Resource（CR）来应用这些优化。

1. 通过 kubectl patch 命令应用

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

# Update GitLabOfficial CR with optimized ingress annotations
# [!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:
  # ... other specs ...
  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"