软件需求
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 支持
- 环境检查：部署前务必执行验证检查，提前排查版本、组件、网络等问题，提升部署成功率
- 后续维护：定期升级软件版本、修复安全漏洞，监控组件运行状态，确保平台长期稳定运行