跳到主要内容

使用指引

1. 概述​

csghub-airgap 是 CSGHub 提供的命令行工具,用于创建和部署 CSGHub 离线包。create 只能在可联网的环境中执行,用于打包 K3s、Helm Chart 和容器镜像;将产物传入隔离网络后,在内网机器上执行 deploy 完成部署。该工具为纯 CLI,不运行任何后台守护进程。

适用场景:

  • 部署到完全隔离的内网环境;
  • 需要在少量机器上快速完成 CSGHub 及其依赖的离线交付;
  • 需要复用已有 K3s 集群,仅导入镜像或安装 Chart。

2. 下载安装​

从 GitHub Releases 获取对应平台的二进制文件:

平台架构下载地址
Linuxamd64下载
Linuxarm64下载
macOSamd64(Intel)下载
macOSarm64(Apple Silicon)下载

校验文件:checksums.txt

以 Linux amd64 为例:

# 下载二进制和校验文件
curl -fL -O https://github.com/OpenCSGs/csghub-airgap/releases/latest/download/csghub-airgap-linux-amd64
curl -fL -O https://github.com/OpenCSGs/csghub-airgap/releases/latest/download/checksums.txt

# 校验完整性
sha256sum -c checksums.txt --ignore-missing

# 安装
chmod +x csghub-airgap-linux-amd64
sudo mv csghub-airgap-linux-amd64 /usr/local/bin/csghub-airgap
csghub-airgap --version

需要固定版本时,在 Releases 页面选择对应标签(如 v2.2.5),将地址中的 latest/download 替换为 download/<版本>。

3. 快速开始​

3.1 在可联网机器上创建离线包​

sudo csghub-airgap create --output /opt/csghub-bundle

create 会下载 K3s、Helm Chart、容器镜像等组件。处理 csghub 图表时会显示 runtime 镜像选择界面,确认后导出选中的镜像。完成后默认在同级目录生成 /opt/csghub-bundle.tar(使用 --skip tar 时不生成)。

3.2 传入内网并部署​

# 将离线包复制到内网机器
scp /opt/csghub-bundle.tar user@airgap-host:/root/

# 在内网机器上部署(会自动解包)
sudo csghub-airgap deploy \
--input /opt/csghub-bundle.tar \
--domain csghub.internal.example.com

4. 命令说明​

命令说明
create在可联网机器上创建离线包
deploy在内网机器上从离线包部署 CSGHub
cleanup卸载 K3s 并清理所有已部署服务
list-images查询 csghub-server 提供的 runtime 镜像

4.1 create​

sudo csghub-airgap create [options]
参数说明
--output, -o离线包输出目录,默认 ./csghub-airgap-<日期>
--arch目标架构(amd64、arm64),默认取本机架构
--skip跳过组件:k3s、charts、image、runtime、package、tar,或图表名 csghub、longhorn、nvdp
--proxy对 GitHub 下载使用 ghfast.top 代理前缀
--force-pull忽略本地镜像缓存,始终从仓库重新拉取
--quiet, -q跳过交互式提示(不选择任何 runtime 镜像)
--set, -s设置 Helm values(如 csghub.key=value,可多次)
--k3s-arg / --k3s-env追加 K3s 启动参数或环境变量
--dry-run只打印将要执行的操作而不实际执行

4.2 deploy​

sudo csghub-airgap deploy [options]
参数说明
--input, -i离线包目录或 .tar 文件,默认 ./csghub-airgap-<日期>
--domainCSGHub 访问域名,默认 csghub.example.com
--data, -DK3s 与 Longhorn 的数据目录
--skip与 create 相同的类别和图表名
--quiet, -q跳过交互式提示,自动停止并禁用 multipathd
--set, -s部署时覆盖 Helm values
--dry-run只打印将要执行的操作而不实际执行

部署前会检查系统平台与离线包架构是否一致,并在未检测到 NVIDIA GPU 时自动禁用 nvdp 图表。

4.3 cleanup​

sudo csghub-airgap cleanup [--yes]

警告:cleanup 会删除整台机器的 k3s 及其所有数据,包括 /var/lib/rancher/k3s、/var/lib/kubelet、k3s 二进制和 systemd 服务,而不只是 CSGHub 资源。若该机器上的 k3s 是自行安装的,也会一并删除,请谨慎操作。交互式模式下需输入 yes 确认。

4.4 list-images​

csghub-airgap list-images [options]
参数说明
--source配置来源:github(在线)或 local(本地目录,用于离线场景)
--version, -vcsghub-server 的 Git 分支或标签,默认 main
--local-path本地 csghub-server 配置目录(配合 --source local)
--category, -c按类别过滤:evaluation、finetune、inference、job、notebook、space
--compute按计算类型过滤:cpu、gpu、dcu
--format, -f输出格式:table 或 json

5. 常见场景​

5.1 GPU 环境​

# 打包(包含 nvdp 与 NVIDIA 软件包)
sudo csghub-airgap create --output /opt/csghub-gpu

# 部署(检测到 GPU 时自动安装 nvdp,无 GPU 时自动禁用)
sudo csghub-airgap deploy \
--input /opt/csghub-gpu \
--domain csghub.gpu.example.com

5.2 仅导入镜像(复用已有 K3s)​

# 联网机器:只导出镜像
sudo csghub-airgap create --output /opt/csghub-img --skip k3s,charts,package

# 目标机器:已有 K3s,只导入镜像
sudo csghub-airgap deploy --input /opt/csghub-img --skip k3s,charts

5.3 重新部署​

sudo csghub-airgap cleanup --yes
sudo csghub-airgap deploy --input /opt/csghub-bundle --domain csghub.example.com

6. 注意事项​

  • deploy 与 cleanup 需要 root 权限;在 Linux 上下载 NVIDIA 软件包时,create 也需要 root。
  • 打包配置保存在离线包的 metadata.yaml 中,部署时自动应用;命令行参数可在部署时覆盖。
  • 拉取的镜像会缓存在用户缓存目录下的 csghub-airgap/images:Linux 为 ~/.cache/csghub-airgap/images,macOS 为 ~/Library/Caches/csghub-airgap/images。中断重试时可直接复用;需要强制刷新时使用 --force-pull。
  • 离线包可能包含敏感配置,请妥善保管并在部署前校验完整性。

7. 相关链接​