Helm 实战指南（四）：生产环境 Helm 部署 CVAT 全记录：Ceph 存储、GPU 节点污点调度与 HTTPS 指南

前言

刚好！最近公司业务需求，需要搭建一套CVAT (Computer Vision Annotation Tool)计算机视觉标注系统，开源标注工具。

虽然官方提供了 Helm Chart，但在面对内网环境、老版本 K8s (v1.21)、Ceph 存储以及特定节点调度等现实需求时，官方文档过于 “简洁” 了。

本文完整记录了从 Chart 下载到最终成功登录的全过程，重点分析了部署过程中遇到的OPA 服务连接拒绝、浏览器安全策略报错等“深坑”及其解决方案。

• 官方 GitHub: cvat-ai/cvat
• Helm 版本: v3.19
• CVAT Chart 版本: 2.56.0
• Kubernetes 版本: 1.21.10 (注：官方要求 >=1.23，本文包含强行兼容方案)

---

一、 背景与硬性需求

在开始之前，明确一下我们的部署环境限制，这也是后续修改配置的依据：

1. 节点调度限制：

• CVAT 必须运行在名为gpusrv14的特定节点上。
• 难点：该节点被打上了污点（Taint）dedicated=ceph:NoSchedule，普通 Pod 无法调度上去。我们需要配置容忍度（Tolerations）。

2. 持久化存储：

• 必须对接公司现有的Ceph集群（StorageClass:rook-cephfs），且容量要求大。

3. 内网环境：

• 服务器无法直接连接公网，依赖 HTTP Proxy。

---

二、 部署准备与 Chart 处理

1. 下载 Chart

首先拉取官方 Chart 包并解压：

helm pull oci://registry-1.docker.io/cvat/cvat --version2.55.0tar-xzf cvat-2.55.0.tgzcdcvat

2. 解决 K8s 版本兼容性问题（K8s 1.21 版本）

官方 Chart 的Chart.yaml里硬性规定了kubeVersion: '>= 1.23.0-0'。如果你像我一样还在用 K8s 1.21，直接 install 安装会报错。

解决方案：
修改Chart.yaml，强行降低版本要求。虽然有风险，但实测 CVAT 2.56 在 1.21 上核心 API 依然兼容。

# Chart.yamldescription:A Helm chart for KuberneteskubeVersion:'>= 1.21.0-0'# 修改此处

3. 初始化配置文件

为了保持原文件整洁，我们复制一份配置进行覆盖：

cpvalues.yaml values.override2.yaml# 或(一样)helm show values.>values.override2.yaml

---

三、 核心配置修改（values.yaml）

1. 存储配置：对接 Ceph

默认的 PVC 只有 20Gi 且不指定 StorageClass。我们需要修改cvat和kvrocks(Redis) 两处的存储配置。

修改values.override2.yaml：

defaultStorage:enabled:truestorageClassName:rook-cephfs# 重点：指定你的 Ceph SC 名称accessModes:-ReadWriteMany# 建议多读写模式，方便扩展size:1000Gi# 生产环境，给大点

2. 调度配置：亲和性与污点容忍（重点）

这是最复杂的一步。我们要把 Pod 钉死在gpusrv14节点上，并且要能“忍受”它的污点。

步骤 A：给节点打标签

kubectl labelnodegpusrv14.aa.com -n gpu cvat-node=true

步骤 B：检查节点污点

kubectl describe node/gpusrv14.aa.com -n gpu|grepTaints# 输出: dedicated=ceph:NoSchedule# 这意味着如果没有对应的 toleration，Pod 无法调度上来。

步骤 C：修改 Helm 配置
找到cvat.backend部分。CVAT Chart 设计比较好的一点是，backend 下的配置会被 worker 等子组件继承，所以不需要每个微服务都改一遍。

cvat:backend:# 1. 强行指定节点（双重保险）affinity:nodeAffinity:requiredDuringSchedulingIgnoredDuringExecution:nodeSelectorTerms:-matchExpressions:-key:kubernetes.io/hostnameoperator:Invalues:-gpusrv14.aa.com# 2. 简单的节点选择器nodeSelector:cvat-node:true# 3. 污点容忍（必须配置，否则 Pending）tolerations:-key:"group"# 多余的operator:"Equal"value:"gpu"effect:"NoSchedule"-key:"dedicated"# 对应 dedicated=ceph:NoScheduleoperator:"Equal"value:"ceph"effect:"NoSchedule"

---

四、 启动安装与踩坑实录

执行安装命令：

helminstallgpu-cvat.-n gpu-cvat --create-namespace -f values.yaml -f values.override2.yaml

安装命令下去后，并没有想象中的“一键成功”，而是迎来了两个深坑。

坑一：OPA 服务无限重启 (Connection refused)

现象：
gpu-cvat-opaPod 状态异常，查看日志发现健康检查失败：

requests.exceptions.ConnectionError: HTTPConnectionPool(host='opa', port=8181): ... Connection refused

原因分析：
OPA (Open Policy Agent) 是 CVAT 的权限策略引擎。

• 默认情况下，OPA 启动时只监听localhost(127.0.0.1)。
• K8s 的 Liveness Probe（探针）是通过 Pod IP 访问的，属于“外部”访问。
• 因为监听地址限制，探针连接被拒绝，K8s 判定服务不健康，导致无限重启。

解决方案（临时暴力有效）：
尝试通过 Helm--set传参失败（可能是 Chart 里的参数映射有问题），直接修改 Deployment 最快。

kubectl edit deployment gpu-cvat-opa -n gpu-cvat

找到args部分，手动添加--addr=0.0.0.0:8181，强制监听所有网络接口：

containers:-args:-run---server---addr=0.0.0.0:8181# 【关键修改】让它监听所有IP---bundle

修改保存后，Pod 重启，状态瞬间变为 Running。

其中，尝试过 upgrade 这些服务，但不生效：

helm upgrade... --set cvat.opa.extraArgs="{--addr=0.0.0.0:8181}"--reuse-values

可能某些版本的 CVAT Helm Chart 中，extraArgs 的传递方式或者 OPA 的默认启动命令（Entrypoint）优先级更高，导致修改根本没有生效。

永久解决方案（未验证）：
手动编辑的配置会在下一次helm upgrade时丢失。为了让配置持久化，需要将参数写入values.override2.yaml。

在配置文件中找到cvat.opa部分，加入extraArgs：

cvat:opa:# 强制让 OPA 监听所有接口，解决健康检查不通的问题extraArgs:-"--addr=0.0.0.0:8181"

这样下次执行 Helm 更新时，这个参数就会自动带上，不用再手动改 Deployment 了。

坑二：浏览器白屏与 405 报错 (HTTP vs HTTPS)

现象：
配置好 Nginx HTTP 转发后，访问页面出现白屏或报错（F12）：

1. API 请求报405 Not Allowed或401 Unauthorized。
2. 控制台报错：The Cross-Origin-Opener-Policy header has been ignored...
3. JS 报错：ReferenceError: structuredClone is not defined。

原因分析：
这是现代浏览器的安全机制。CVAT 是一个重型前端应用，使用了SharedArrayBuffer等特性来实现多线程处理。
浏览器规定：这些高级特性必须在“安全上下文” (Secure Context) 下才能运行。
所谓安全上下文，要么是localhost，要么必须是HTTPS。如果是 HTTP，这些 API 直接被禁用，导致代码崩盘。

解决方案（配置 Nginx SSL + 安全头）：
我们必须配置 HTTPS，并且在 Nginx 中显式添加 COOP/COEP 响应头。

Nginx 配置参考：

server { listen 443 ssl; server_name gpu-cvat.aa.com; # 统一使用一个域名 ssl_certificate /etc/nginx/conf.d/sans_crt2/server.crt; ssl_certificate_key /etc/nginx/conf.d/sans_crt2/server.key; # 1. 后端 API 转发 location ~ ^/(api|auth|admin|django-static)/ { proxy_pass http://gpu-cvat-backend-service.gpu-cvat.svc.cluster.local:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } # 2. 前端页面转发 location / { proxy_pass http://gpu-cvat-frontend-service.gpu-cvat.svc.cluster.local:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 必须加上这两个 Header，否则 CVAT 内部 JS 会报错 add_header Cross-Origin-Opener-Policy 'same-origin'; add_header Cross-Origin-Embedder-Policy 'require-corp'; } }

关于Nginx 转发规则，虽然官方文档未明说后端路径，但通过 F12 开发者工具观察网络请求，并参考 Chart 源码中 templates/ingress.yaml 的分流定义，可以明确 /api、/auth、/admin 及 /django-static 这类涉及到数据交互和 Django 后台的请求必须精准转发至后端 Service，而其余流量则指向前端。

---

五、 创建管理员

部署成功且页面能打开后，发现——没有账号登录。
CVAT 默认不创建任何账号，需要手动进入容器执行 Django 命令来创建超级管理员（教程下一步）。

一键创建命令：

# 你部署 CVAT 的命名空间exportHELM_RELEASE_NAMESPACE="gpu-cvat"# 你给这个 Helm 实例起的名称exportHELM_RELEASE_NAME="gpu-cvat"BACKEND_POD_NAME=$(kubectl get pod --namespace $HELM_RELEASE_NAMESPACE -ltier=backend,app.kubernetes.io/instance=$HELM_RELEASE_NAME,component=server -ojsonpath='{.items[0].metadata.name}')kubectlexec-it --namespace$HELM_RELEASE_NAMESPACE$BACKEND_POD_NAME-c cvat-backend -- python manage.py createsuperuser

按照提示输入用户名、邮箱和密码即可。

创建好后，就可以使用这个账号登录系统。

---

六、 存储验证

前面在values.yaml中配置了storageClassName: rook-cephfs后，并且已经部署完成了，现在验证一下是不是用了 ceph 的存储。

1. 查看集群内 PVC 状态

通过kubectl get pv命令可以看到，CVAT 的后端数据（backend-data）和 kvrocks 已经成功绑定了我们预设的1000Gi大容量存储，且状态均为Bound。

# 查看 CVAT 相关的持久化卷kubectl getpv|grepgpu-cvat

注意：可以看到gpu-cvat-backend-data的模式是RWX(ReadWriteMany)，这对于多副本部署至关重要。

2. 追踪底层的 Ceph Subvolume

为了确认数据确实落在了 CephFS 上，我们可以随机挑选一个 PV 进行describe，查看它在 Ceph 内部的subvolumePath：

kubectl describe pv/pvc-ec561f53-c54b-47d7-9ddb-6e01850046df|grepsubvolumePath# 输出结果：# subvolumePath=/volumes/csi/csi-vol-cee516.../de776093...

3. Ceph 后台验证

最后，登录Ceph Dashboard或直接在 Ceph 节点查看文件系统，可以看到该路径已经自动创建并开始记录数据。

---

总结

这次 Helm 部署过程暴露了 CVAT Chart 的几个痛点：

1. 微服务拆分过细：虽然架构先进，但运维成本高。如果不是backend配置支持继承，单独配置每个 Pod 的调度策略会非常痛苦。
2. 默认配置不合理：OPA 默认只监听localhost导致健康检查失败，这是一个非常低级的默认配置坑，迫使我们必须手动介入。
3. 文档缺失：官方文档未强调 HTTPS 对于前端功能的强制性，导致很容易在 HTTP 环境下浪费时间排查 JS 报错。
4. 内网友好度低：内网环境下，Grafana 插件下载、依赖包拉取都需要自己在values.yaml里注入 Proxy 环境变量。

感觉这个 Helm-Chart 做得不够完善，并且加上公司内网原因，导致没法一键部署。