使用指引
1. 概述
csghub-airgap 是 CSGHub 提供的命令行工具,用于创建和部署 CSGHub 离线包。create 只能在可联网的环境中执行,用于打包 K3s、Helm Chart 和容器镜像;将产物传入隔离网络后,在内网机器上执行 deploy 完成部署。该工具为纯 CLI,不运行任何后台守护进程。
适用场景:
- 部署到完全隔离的内网环境;
- 需 要在少量机器上快速完成 CSGHub 及其依赖的离线交付;
- 需要复用已有 K3s 集群,仅导入镜像或安装 Chart。
2. 下载安装
从 GitHub Releases 获取对应平台的二进制文件:
- 版本列表:Releases 页面
- 最新版本:Latest Release
| 平台 | 架构 | 下载地址 |
|---|---|---|
| Linux | amd64 | 下载 |
| Linux | arm64 | 下载 |
| macOS | amd64(Intel) | 下载 |
| macOS | arm64(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-<日期> |
--domain | CSGHub 访问域名,默认 csghub.example.com |
--data, -D | K3s 与 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, -v | csghub-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 |