隔离网络安装

对于无法连接互联网的网络，使用离线包进行安装。在能连接互联网的一侧获取（或刻录）离线包， 验证签名后转移到存储介质，再带入隔离网络中解压导入。

请先确定架构

离线包分为两套 —— arm64（GB10 系列）· amd64（AWS g7e 等）。请在目标服务器上执行 uname -m 确认后再选择（aarch64 → arm64，x86_64 → amd64）。架构不符的离线包无法启动镜像。导入脚本会在安装 Docker 之前，将离线包中 MANIFEST.txt 记录的架构与本主机进行比对，如不一致则停止执行。

离线包体积较大 —— 约 25GB

主要是 vLLM 镜像。请提前确认用于转移的存储介质和目标磁盘的可用空间。

步骤 1 —— 获取离线包（联网环境）

从分发服务器下载正文及四个附属文件，共五个文件。

ARCH=arm64   # 또는 amd64
B=plantpulse-ai-images-latest-$ARCH.tar.gz
for f in "$B" "$B.sha256" "$B.sha256.sig" "$B.pub" "$B.cosign.sha256"; do
  curl -fL -C - --retry 10 --retry-delay 5 --retry-all-errors \
    -O "https://product.kopens.io/plantpulse-ai/$f"
done

文件	内容
`<번들>.tar.gz`	正文
`.sha256`	正文的校验和
`.sha256.sig`	针对该校验和的 cosign 签名 —— 签名附加在校验和文件上，而不是几十 GB 的正文上
`.pub`	用于验证的公钥
`.cosign.sha256`	离线包内所含 cosign 可执行文件的 sha256（见下文「离线包内的 cosign」）

中断后重新执行相同命令即可

-C - 负责断点续传，--retry-all-errors 负责重试。大文件偶尔会因 CDN 侧错误中断，重新执行时会从已下载的部分继续。

步骤 2 —— 验证签名

未经验证的离线包不得使用。 将下载的五个文件放在同一目录下解压并验证。

sudo -i
mkdir -p /opt/kopens && tar -xzf "$B" -C /opt/kopens
bash /opt/kopens/plantpulse-ai-images/repo/bin/verify-bundle.sh "$B"

verify-bundle.sh 会依次检查以下内容。任一项不符都会在此中止。

能否执行 cosign —— 优先级依次为 COSIGN_BIN → PATH 中的 cosign → 离线包内的 tools/cosign-linux-<arch>
附属文件（.sha256 · .sha256.sig · 公钥）是否与离线包放在一起。若仓库的公钥与接收到的 .pub 两者都存在，则必须逐字节一致
签名对校验和文件是否有效
校验和文件中记录的名称是否与该离线包的名称一致
离线包的字节内容是否与已签名的校验和匹配

退出码	含义
`0`	已验证
`1`	验证失败 —— 请勿使用该离线包
`2`	无法验证（缺少工具或附属文件）—— 并非通过

离线包内的 cosign 及其信任边界

隔离网络中没有 cosign，因此离线包会携带一个版本已锁定的 tools/cosign-linux-<arch>。但是，离线包内的 cosign 本身不受离线包签名的保证 —— 因为它正是用来验证签名的工具本身。因此，该文件的 sha256 会被放置在三个地方。

位置	性质
离线包 `MANIFEST.txt` 中的 `tools-cosign` 行	我方制作的副本
CDN 上的 `<번들>.cosign.sha256`	我方制作的副本。放在离线包旁边时 `verify-bundle.sh` 会自动比对，不一致则失败
上游 sigstore 的 `cosign_checksums.txt`	唯一的独立比对来源

前两者对于能够同时篡改离线包和 CDN 的攻击者来说毫无意义。请在联网环境中先与上游校验和比对一次，再带入隔离网络。如有自行信任的 cosign，可通过 COSIGN_BIN=/경로/cosign 指定使用。

步骤 3 —— 转移到隔离网络并导入

将离线包的正文和附属文件一起转移 —— 导入脚本会在加载前重新验证。

sudo -i
mkdir -p /opt/kopens && tar -xzf "$B" -C /opt/kopens
cd /opt/kopens/plantpulse-ai-images/repo/bin
BUNDLE_TARBALL="/경로/$B" ./airgap-import.sh

解压后的结构如下。两个兄弟仓库一同包含在离线包内，因此无需单独准备（具体是哪个提交记录在 MANIFEST.txt 的 sibling 行中）。

/opt/kopens/plantpulse-ai-images/
├── repo/                                  ← 설치 본체 (bin · compose)
├── plantpulse-ai-inference-server/        ← 형제 저장소
├── plantpulse-timeseries-insight-server/  ← 형제 저장소
├── images/                                ← 이미지마다 docker save 한 파일 하나씩
├── pkgs/{rpm,deb}/                        ← Docker CE 오프라인 설치 패키지
├── tools/cosign-linux-<arch>
└── MANIFEST.txt

airgap-import.sh 会依次处理以下步骤。任一步骤失败都会在此中止。

步骤	内容
0	比对架构 · 验证离线包签名（`verify-bundle.sh`）
1	离线安装 Docker —— 仅在未安装 Docker 时执行。若已安装，则保留现有仓库与配置，不重启（可通过 `ALLOW_DOCKER_RECONFIGURE=1` 允许）
2	加载镜像 —— 全部执行 `docker load` 后，确认离线包中引用的镜像是否全部可按名称解析
3	调用 `install.sh` —— `SKIP_LOGIN=1`。不连接镜像仓库，也跳过镜像 pull 与模型自动接收

找不到离线包时会中止

由于签名是通过离线包旁边的附属文件进行验证的，导入时必须存在 tar.gz 文件。会在解压目录的上级目录（/opt/kopens）中查找一个，若不存在或存在多个，则提示用 BUNDLE_TARBALL 指定路径后中止。虽然存在可跳过验证继续执行的 ALLOW_UNVERIFIED=1，但请勿使用 —— 这是加载未经验证离线包的开关。

默认行为是「准备就绪即止」

install.sh 只会生成 /etc/kopens/plantpulse-ai.env 后停止。若想一次性直接启动，请先执行 export START=1，再运行 airgap-import.sh。若只完成了准备工作，请按照下文「导入后的启动顺序」操作 —— 安装程序结尾也会打印相同的顺序说明。

自 2026.10 起，需要填写的值中新增了获取平台凭据的设置（PP_DATALAKE_ADMIN_URL · PP_DATALAKE_ADMIN_API_KEY）以及平台信任锚点 /etc/kopens/ca/root.crt。即便在隔离网络内，AI 主机也必须能访问平台主机的 :4950 → 安装概览

导入后的启动顺序

填写剩余的占位符。 导入输出会打印以 CHANGE_ME_* 标记的剩余键（管理员 · Neo4j 密码、平台令牌、平台凭据密钥等）。使用 sudo 修改 /etc/kopens/plantpulse-ai.env，权限保持 0600 不变。
放置 vLLM 模型 —— 见下文「模型不包含在离线包中」。
使用 bin/up.sh 启动。

cd /opt/kopens/plantpulse-ai-images/repo
sudo bin/up.sh

只要仍有占位符未填写，bin/up.sh 便不会启动（2026.10）

旧版本仅在 START=1 路径中拦截占位符，未考虑隔离网络等后续通过 compose-up.sh 启动的情况。因此管理控制台和 Neo4j 可能会以公开模板中的密码暴露在 LAN 端口上。现在 bin/up.sh 也会打印剩余的键名并拒绝启动。

请勿使用 bin/update.sh —— 它会尝试先拉取镜像，在没有镜像仓库的隔离网络中会失败。

主机全局设置遵循 HOST_TUNING

install.sh 会修改区域设置 · 时区（PP_TZ）· 交换分区 · chrony · limits · sysctl · tmpfiles · 防火墙。若主机上已运行其他服务的容器，默认为 plan，因此仅输出将要变更的内容。查看输出后如有需要可用 HOST_TUNING=apply 重新执行 → 安装概览

模型不包含在离线包中

🔴 vLLM 模型（LLM · 嵌入 · 重排序器，合计超过 20GB）不包含在离线包中。 在线安装会在 START=1 阶段自动下载模型，但隔离网络的导入会跳过该步骤。

vLLM 模型 —— 请在能联网的设备上通过 bin/fetch-models.sh 下载。这与在线安装下载的发布版本权重（model.kopens.ai）相同，需与 SHA256SUMS 比对后再解压（需要 zstd）。下载位置为 MODEL_BASE，名称为 MODELS。
```
MODEL_BASE=/mnt/usb/models MODELS="Aura-Lite-NVFP4 Aura-Embedding-4B Aura-Reranker-0.6B" \
    bash /opt/kopens/plantpulse-ai-images/repo/bin/fetch-models.sh
```
通过存储介质转移，在隔离网络设备上以相同名称的目录放置到 /opt/kopens/models 下（如更改了位置，需在主机 env 中设置 LLM_MODEL_PATH · EMB_MODEL_PATH · RERANK_MODEL_PATH）。
时序推理模型 —— 无需导入。 已包含在 plantpulse-timeseries-insight-server 镜像内。
语音转写模型（Aura-ASR-Turbo，约 1.5 GB） —— 仅在需要使用视频 · 音频采集及语音提问功能的安装中导入。转写镜像（plantpulse-asr-audio，转写用 vLLM 与生成用 vLLM 为同一镜像）始终包含在离线包中，因此只需转移模型本身即可。在联网设备上通过 shell 环境变量开启该开关，即可随 vLLM 模型一并下载（下载目标位置已存在的文件会被跳过）。
```
PI_MEDIA_ENABLED=true MODEL_BASE=/mnt/usb/models \
    bash /opt/kopens/plantpulse-ai-images/repo/bin/fetch-models.sh
```
通过存储介质转移，放置到隔离网络设备的 /opt/kopens/models/Aura-ASR-Turbo 下后，在主机 env 中设置 PI_MEDIA_ENABLED=true 并启动 → 视频 · 音频采集。若只需下载名称，也可用 MODELS="Aura-ASR-Turbo" 设置。旧版指南中设置 COMPOSE_PROFILES=media 执行的也依然会下载该模型。

请勿使用 download-model.sh 下载

推理服务器仓库中的 tools/download-model.sh 会下载上游原始权重，仅附加 Aura-* 名称。由于名称相同，任何校验都无法识别差异，但这并非发布版本权重。 请务必使用 bin/fetch-models.sh。

未放置模型启动时，整个堆栈会显示为绿色，仅 LLM 无法使用。 启动前请确认模型就位。

自行构建离线包的情况

仅在需要代替分发服务器的离线包、自行在内部构建时使用。需在与目标架构相同的设备上执行 —— 不支持交叉构建。

cd /opt/kopens/plantpulse-ai-docker/bin
./airgap-export.sh

环境变量	默认值	含义
`ARCH`	本主机	`arm64` · `amd64`。与主机比对，不一致则中止
`OS_TARGET`	跟随架构 —— `arm64` → `deb`，`amd64` → `rpm`	`rpm` · `deb` · `both` —— 将要打包的 Docker 离线安装包
`EXPORT_TAG`	当天日期	仅用于产物命名
`OUT_DIR`	`<저장소>/dist`	产物存放位置

产物为 dist/plantpulse-ai-images-<태그>-<아키텍처>.tar.gz 与 .sha256。镜像列表通过 docker compose config --images 提取，因此无需手动编写 —— 即便更换模型或升级 vLLM 版本，也无需修改脚本。两个兄弟仓库也会按照构建时所使用的检出状态一并打包。

自行构建的离线包没有签名

签名（.sha256.sig）由发布流水线添加，手动构建会跳过签名步骤（日志中会打印「跳过签名」）。无签名的离线包无法通过导入步骤 0 的验证，因此若无特殊原因，请使用分发服务器提供的离线包。

安装之后

顺序	操作	命令 · 文档
1	修改默认密码	修改初始密码
2	检查堆栈是否正常运行	`bin/status.sh` · `bin/health.sh`
3	定位受阻环节	`bin/doctor.sh`

常见坑点

现象	原因	处理方法
`verify-bundle.sh` 返回退出码 2	缺少 cosign 或附属文件缺失	并非通过。将四个附属文件放在离线包旁重新验证
导入时提示「未找到离线包」而中止	tar.gz 未转移或位于其他位置	使用 `BUNDLE_TARBALL=/경로/<번들>.tar.gz` 指定路径
导入因架构不匹配而中止	离线包架构不符	获取与 `uname -m` 相匹配的离线包
加载后出现「无法按名称解析的镜像」而中止	离线包存在缺陷	不要使用该离线包，重新获取新的离线包
堆栈为绿色但仅 LLM 无法使用	未导入模型	参见上文「模型不包含在离线包中」
已用 `PI_MEDIA_ENABLED=true` 启动，但仅 `plantpulse-asr` 未启动	未导入语音转写模型（`Aura-ASR-Turbo`）	参见上文「模型不包含在离线包中」的语音转写模型部分
堆栈仅处于准备状态未启动	未执行 `START=1`	属正常现象。按上文「导入后的启动顺序」填写值后用 `bin/up.sh` 启动
`bin/up.sh` 因「still has template placeholders」而中止	仍有占位符（`CHANGE_ME_*`）未填写	填写打印出的键后重新启动
`bin/update.sh` 在拉取镜像时失败	隔离网络中没有镜像仓库	使用 `bin/up.sh`
主机设置未发生变化	因主机上已运行其他容器而处于 `HOST_TUNING=plan` 状态	查看输出，如有需要用 `HOST_TUNING=apply` 重新执行

步骤 1 —— 获取离线包（联网环境）​

步骤 2 —— 验证签名​

离线包内的 cosign 及其信任边界​

步骤 3 —— 转移到隔离网络并导入​

导入后的启动顺序​

模型不包含在离线包中​

自行构建离线包的情况​

安装之后​

常见坑点​

相关文档​