软件需求
1. 说明
CSGHUB 依赖云原生技术栈构建，核心运行环境包括：
- 操作系统（Linux）
- 容器运行时（Docker / containerd）
- Kubernetes 集群（推荐）
- 存储系统（CSI / 对象存储）
- 可选 AI / 调度组件
👉 软件版本兼容性会直接影响：
- 部署成功率
- 系统稳定性
- 后续升级能力
2. 操作系统
2.1 支持的操作系统
| 发行版 | 版本要求 |
|---|---|
| Ubuntu | ≥ 20.04（推荐 22.04，长期支持版，稳定性更优） |
| CentOS | ≥ 7.9（建议替换为 Rocky / AlmaLinux 8+，CentOS 7 即将停止维护，安全性无保障） |
| Debian | ≥ 11（推荐 12，适配最新云原生组件版本） |
| openSUSE / SLES | 较新版本（≥ 15 SP4，确保与容器运行时、Kubernetes 兼容性） |
2.2 系统配置
| 项目 | 要求 |
|---|---|
| 架构 | x86_64 / ARM64（x86_64 适配性更完善，ARM64 需验证组件兼容性） |
| Kernel | ≥ 4.18（推荐 ≥ 5.x，支持更多云原生特性、CSI 驱动及 GPU 加速功能） |
| 文件系统 | ext4 / xfs（推荐 xfs，支持更大容量、更高 IO 性能，适配大规模存储场景） |
| 时间同步 | 必须开启（NTP / chrony），误差≤1s，避免因时间偏差 导致证书失效、任务调度异常 |
2.3 不建议
- 精简系统（缺少基础工具如 curl、wget、vim 等，会导致部署脚本执行失败）
- 关闭 cgroup / namespace（容器运行时、Kubernetes 核心依赖，关闭会导致服务无法启动）
- 非标准 Linux 发行版（如国产定制精简版、非主流发行版，组件兼容性无法保障）
- 混合架构部署（同一集群内同时存在 x86_64 和 ARM64 节点，需额外适配，不推荐）
3. 容器运行时
3.1 Docker（适用于单机 / 简单环境）
| 项目 | 要求 |
|---|---|
| Docker | ≥ 20.10（推荐 24.0+，修复多个安全漏洞，提升容器运行稳定性） |
| Docker Compose | ≥ 2.x（推荐 2.20+，支持更丰富的编排功能，适配多容器联动场景） |
3.2 Containerd（推荐生产）
| 项目 | 要求 |
|---|---|
| containerd | ≥ 1.6（推荐 1.7+，与 Kubernetes 1.30+ 兼容性最优，支持容器镜像加密、镜像加速） |
| runc | 较新稳定版（≥ 1.1.7，与 containerd 版本匹配，保障容器运行安全） |
3.3 说明
- Kubernetes 默认使用 containerd，生产环境优先选择，稳定性、性能优于 Docker
- Docker 仅用于以下场景，不推荐生产部署：
- 本地开发调试
- 快速验证平台功能
- 小规模单机部署（≤3 节点，无高可用需求）
- 容器运行时需开启镜像加速（如阿里云、华为云加速器），避免镜像拉取超时
4. Kubernetes 要求（核心）
4.1 版本要求
| 项目 | 要求 |
|---|---|
| Kubernetes | ≥ 1.30（推荐 1.30~1.32，适配最新 CSI 驱动、GPU 插件及平台组件，避免版本过旧导致兼容性问题） |
| Helm | ≥ 3.12（推荐 3.14+，支持 Helm Chart 多环境部署、 滚动更新，适配平台组件安装需求） |
4.2 必须能力
| 组件 | 要求 | 说明 |
|---|---|---|
| CNI 插件 | 必须安装 | 支持 Calico、Flannel、Cilium 等；AI 场景推荐 Cilium，支持 eBPF 加速，低延迟更适配高并发任务 |
| CSI 驱动 | 必须支持 | 用于动态存储卷管理，适配分布式存储、对象存储，保障数据持久化，需与存储方案匹配 |
| LoadBalancer | 生产环境推荐 | 可使用云厂商 LB 或 MetalLB（物理机部署），实现外部访问负载均衡，提升平台可用性 |
4.3 额外要求
- 集群节点数量：测试/开发环境 ≥ 1 节点，生产环境 ≥ 3 节点（保障高可用）
- API Server 可访问性：集群内所有节点可正常访问 API Server，无网络拦截
- RBAC 权限：开启 RBAC 权限控制，为平台组件分配最小必要权限，保障集群安全
- etcd 集群：生产环境需部署 etcd 集群（≥3 节点），确保数据高可用，避免单点故障
5. 存储组件依赖
5.1 必备能力
- CSI 插件：与 Kubernetes 版本兼容，支持动态卷创建、删除、扩容
- 动态卷创建：支持根据 StorageClass 自动创建 PV、PVC，适配平台动态存储需求
- StorageClass：配置默认 StorageClass，确保平台组件可自动获取存储资源
5.2 推荐存储方案
| 类型 | 推荐软件 |
|---|---|
| 分布式块存储 | Longhorn / Ceph（推荐 Longhorn，部署简单、轻量，适配中小规模生产；Ceph 适合大规模高负载场景） |
| 文件存储（RWX） | NFS / CephFS（NFS 部署简单，适合中小规模；CephFS 性能更优，适合大规模、高并发场景） |
| 对象存储 | MinIO / S3（MinIO 可私有化部署，兼容 S3 协议，适合存储模型、数据集等大文件） |
5.3 特殊要求
- 支持 RWX（ReadWriteMany）：多个 Pod 可同时读写同一存储卷，适配平台多组件共享数据场景（如模型共享、日志共享）
- 支持高 IO（SSD / NVMe）：AI 场景（模型训练、推理）需高 IO 存储，避免 IO 瓶颈拖慢任务进度
适用于：
- 模型推理：需快速读取模型文 件，对存储 IO 延迟要求高
- AI 训练：大规模数据集读写，需高带宽、高并发存储支撑
5.4 NVIDIA 组件
| 组件 | 要求 |
|---|---|
| NVIDIA Driver | ≥ 580+（需与 GPU 型号匹配，支持最新 CUDA 版本，适配 AI 训练/推理需求） |
| CUDA | 与驱动匹配（推荐 12.2+，确保与 AI 框架、模型兼容性） |
| NVIDIA Container Toolkit | 必须安装，用于容器内 GPU 资源调度，确保 Pod 可正常调用 GPU |
| NVIDIA Device Plugin | Kubernetes 插件，用于集群 GPU 资源管理与调度，需与 Kubernetes 版本兼容 |
6. 组件依赖（可选）
CSGHUB 依赖以下云原生组件，根据业务场景选择部署，非必选但推荐生产环境配置：
6.1 AI / ML相关组件
| 组件名称 | 推荐版本 | 功能说明 | 自动部署支持 |
|---|---|---|---|
| Volcano Device Plugin | v1.11.0 | 负责更高级的 GPU 调度策略（如 GPU 分片、共享、优先级调度），适配多租户 AI 场景，详细配置请咨询工程师 | ❌ |
| TensorFlow / PyTorch | 较新版本 | AI 训练/推理框架，需与 CUDA 版本匹配，平台支持一键部署相关镜像 | ✅ |
6.2 观测（可选）
| 组件 | 用途 | 自动部署支持 |
|---|---|---|
| Grafana | 监控指标可视化，支持 GPU、网络、存储、容器等指标展示，便于问题排查 | ❌ |
| Prometheus | 监控数据采集与存储，与 Grafana 配合使用，支持告警配置 | ❌ |
| ELK Stack | 日志收集、分析与可视化，便于排查平台组件、任务执行过程中的异常日志 | ❌ |
6.3 安全组件（可选）
- NetworkPolicy：通过 CNI 插件实现，限制 Pod 间通信，提升集群网络安全
- Secrets 管理：使用 Kubernetes Secrets 或外部密钥管理工具（如 Vault），存储敏感信息（如数据库密码、API 密钥）
- 镜像安全扫描：部署镜像扫描工具，检测容器镜像中的安全漏洞，避免恶意镜像部署
7. 验证检查
部署 CSGHUB 前，建议执行以下命令检查软件环境是否满足要求，避免部署失败：
# 检查 kubernetes 集群状态（节点就绪、版本符合要求）
kubectl get nodes
kubectl version --short
# 检查 helm 版本
helm version
# 检查存储配置（存在默认 StorageClass）
kubectl get sc
# 检查 GPU 环境（AI 场景必做）
nvidia-smi
# 检查容器运行时（Docker/containerd 状态）
# Docker 检查
systemctl status docker
docker --version
# containerd 检查
systemctl status containerd
containerd --version
# 检查时间同步状态
timedatectl status
# 检查内核版本
uname -r
👉 若检查过程中出现异常，需先修复对应问题，再进行 CSGHUB 部署。
8. 常见问题与解决方案
8.1 版本不兼容
核心表现：部署脚本执行失败、组件启动报错、功能异常
解决方案： 严格按照要求升级软件版本，避免跨版本跳跃（如 Kubernetes 从 1.28 升级至 1.30，需先升级至 1.29）升级前备份集群数据（尤其是 etcd 数据），避免升级失败导致数据丢失若无法升级，可降低 CSGHUB 版本，确保与现有软件环境兼容
8.2 GPU 无法识别
核心表现：Pod 无法调度到 GPU 节点、nvidia-smi 命令报错、GPU 资源显示为 0
解决方案： 检查 NVIDIA Driver 版本与 GPU 型号匹配，重新安装驱动确认 NVIDIA Container Toolkit 已正确安装，重启容器运行时检查 NVIDIA Device Plugin 部署状态，重启插件 Pod
8.3 存储挂载失败
核心表现：PVC 一直处于 Pending 状态、Pod 挂载存储时报错、存储读写异常
解决方案：检查 CSI 驱动部署状态，确保驱动正常运行确认 StorageClass 配置正确，存在可用的 PV 资源检查存储网络连通性，避免网络隔离导致存储无法访问
9. 总结建议
- 部署环境优先级：生产环境优先选择 Kubernetes + containerd，测试/开发环境可选用 Docker 简化部署
- 版本选择原则：软件版本需严格遵循要求，优先使用推荐版本，避免使用测试版、预览版，保障稳定性
- AI 场景准备：提前部署 GPU 相关组件，确认驱动、CUDA、GPU 插件兼容性，避免影响 AI 任务执行
- 存储优化：根据业务场景选择合适的存储方案，AI 场景优先使用高 IO 存储，开启 RWX 支持
- 环境检查：部署前务必执行验证检查，提前排查版本、组件、网络等问题，提升部署成功率
- 后续维护：定期升级软件版本、修复安全漏洞，监控组件运行状态，确保平台长期稳定运行