KnoAI 技术站

主题

05 运维手册 ​

常用命令 ​

bash
export KUBECONFIG=~/.kube/config-122.31
KCTL=../jenkins/tools/kubectl   # 或 /tmp/bin/kubectl

$KCTL -n gitlab get pods
$KCTL -n gitlab logs deploy/gitlab-webservice-default -c webservice --tail=100
$KCTL -n gitlab exec deploy/gitlab-toolbox -- gitlab-rails runner 'puts User.count'
# root 密码
$KCTL -n gitlab get secret gitlab-initial-root-password -o jsonpath='{.data.password}' | base64 -d; echo

Praefect / Gitaly HA 运维 ​

bash
# praefect 元数据与副本状态
$KCTL -n gitlab exec statefulset/gitlab-praefect -c praefect -- /opt/gitlab/embedded/bin/praefect -config /etc/gitaly/praefect.toml sql-ping
$KCTL -n gitlab exec statefulset/gitlab-praefect -c praefect -- /opt/gitlab/embedded/bin/praefect -config /etc/gitaly/praefect.toml dataloss
# HA 演练：删掉一个 gitaly，push 应不受影响
$KCTL -n gitlab delete pod gitlab-gitaly-default-0
# 查看 virtual storage 节点状态
$KCTL -n gitlab exec statefulset/gitlab-praefect -c praefect -- /opt/gitlab/embedded/bin/praefect -config /etc/gitaly/praefect.toml verify

Gitaly on NFS 官方不推荐（延迟敏感）；当前内部小规模使用可接受。若出现 git 操作缓慢，备选方案：gitaly PVC 改节点本地盘（local-path），NFS 仅保留 deps/备份。

备份与恢复 ​

  • 备份 CronJob：gitlab-toolbox-backup，每天 01:00（UTC），上传 MinIO bucket gitlab-backups
  • 手动触发：$KCTL -n gitlab create job --from=cronjob/gitlab-toolbox-backup gitlab-backup-manual-$(date +%s)
  • 查看：mc ls local/gitlab-backups（用 deploy/deps/31 的 mc 镜像临时 pod）
  • 恢复流程参考官方文档 backup-utility restore（toolbox pod 内 backup-utility --restore）
  • 另需备份：secret 清单（deploy/deps/00-secrets.yaml）、rails-secret（$KCTL -n gitlab get secret gitlab-rails-secret -o yaml）

升级流程 ​

  1. 查 GitLab 升级路径（gitlab 版本必须逐级），改 deploy/gitlab/values.yaml 的 global.gitlabVersion 与 chart 版本
  2. 更新 scripts/sync-images.sh 的 tag 并重跑同步
  3. helm pull oci://192.168.122.156:30000/charts/gitlab --version <new> 后 push
  4. 重新生成 gitlab.yml 覆盖 ConfigMap：
    bash
    helm template gitlab charts/gitlab-<new> -n gitlab -f deploy/gitlab/values.yaml > /tmp/new.yaml
# 取 ConfigMap/gitlab-webservice 的 gitlab.yml.erb，插入 `port: 9020`（在 https: true 之后）
# 与 deploy/gitlab/30-gitlab-yml-override-cm.yaml 对比，更新差异
  5. 备份后 helm upgrade gitlab ... -f deploy/gitlab/values.yaml --post-renderer ./scripts/post-render.sh --timeout 15m（migrations hook 自动跑）
  6. PostgreSQL 版本要求：GitLab 19.x 要求 PG >= 17。若当前 PG < 17，需先升级 PG（见 docs/06-故障修复记录.md）

扩缩容 ​

  • webservice/sidekiq/shell：改 values 里 minReplicas/maxReplicas 后 helm upgrade --post-renderer ./scripts/post-render.sh
  • gitaly 副本数：global.praefect.virtualStorages[0].gitalyReplicas（扩到 >3 需praefect 重新平衡，操作前备份）

Post-Renderer（port: 9020 注入） ​

Helm chart 不支持非标准 HTTPS 端口（chart 只有 host/https，无 port 字段）。早期方案用 extraEnv 注入 CONFIG_TEMPLATE_DIRECTORY 指向自定义模板目录，但 extraEnv 在 helm upgrade 时触发 strategic merge patch 冲突（重复键）。

当前方案：使用 Helm post-renderer（scripts/post-render.sh → post-render.py）：

  1. Helm 正常渲染所有资源
  2. post-renderer 读取 deploy/gitlab/30-gitlab-yml-override-cm.yaml 中的 gitlab.yml.erb（含 port: 9020）
  3. 将渲染后的 gitlab-webservice ConfigMap 中的 gitlab.yml.erb 替换为 override 版本
  4. 输出修改后的 YAML 供 Helm 部署

使用方式（install 和 upgrade 都需要）：

bash
helm upgrade gitlab oci://192.168.122.156:30000/charts/gitlab --version 10.2.2 --plain-http \
  -n gitlab -f deploy/gitlab/values.yaml \
  --post-renderer ./scripts/post-render.sh \
  --timeout 15m

注意事项：

  • gitlab-templates-override ConfigMap 挂载到 /opt/gitlab-templates-override（不能挂 /etc/）
  • 升级 chart 后需重新生成 override CM（对比新旧 gitlab.yml.erb，仅加 port: 9020）
  • post-render.py 依赖 pyyaml，确保运行 helm 的机器已安装

故障排查速查 ​

现象排查
Pod ImagePullBackOff镜像是否已同步（docs/02 验证）；节点 containerd mirror 配置
postgres 启动极慢首次 initdb 在 NFS 上 fsync 慢，等 5-10 分钟；查宿主机 /mnt/xfs/rancher/gitlab/gitlab-postgres-data-*
webservice 502workhorse→puma 尚未 ready；查 $KCTL -n gitlab logs <pod> -c webservice 迁移是否完成
clone URL 端口不对gitlab-yml-override CM 是否与当前 values 渲染一致（本手册「升级流程」第 4 步）
praefect 连不上 PG检查 secret gitlab-praefect-dbsecret 值 = PG gitlab 用户密码；库 xxx 是否存在
备份 CronJob 失败gitlab-backup-storage 必须是 s3cmd ini 格式；MinIO bucket gitlab-backups/tmp 是否存在
migrations CrashLoop / PG version mismatchGitLab 19.x 要求 PG >= 17；检查 deploy/deps/10-postgres.yaml 镜像 tag 为 17-alpine；需删旧 PVC 重建（见 docs/06）
dependencies init 容器 Init:ErrorRKE2/containerd 下 /etc/ 为只读 rootfs，ConfigMap 不能挂到 /etc/gitlab/，改用 /opt/ 路径（见 docs/06）
helm upgrade strategic merge patch 冲突extraEnv 中重复键（如 CONFIG_TEMPLATE_DIRECTORY）触发冲突；改用 post-renderer（--post-renderer ./scripts/post-render.sh）直接修改 CM（见 docs/06）
helm release 卡在 pending-install/upgradehelm list -a -n gitlab 查看状态；删卡住的 release secret：$KCTL -n gitlab delete secret sh.helm.release.v1.gitlab.v<N>
API Server 短暂不可达RKE2 多 CP 节点时切换到其他 CP 节点的 kubeconfig（如 config-122.23）

资源参考用量 ​

  • webservice×2：req 500m/1.5Gi each
  • sidekiq×2：req 300m/650Mi
  • gitaly×3：req 200m/512Mi，PVC 100Gi each
  • praefect×2：req 100m/256Mi
  • postgres：req 100m/256Mi，PVC 20Gi；redis：PVC 5Gi；minio：PVC 100Gi