Ubuntu 22.04 安装 Kubescape v4.0.16 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 Kubescape CLI（v4.0.16），覆盖官方脚本在线安装、deb 离线包安装、裸二进制手动安装三种方案，并沉淀校验、升级、卸载与受限网络下的实测排障过程。全部命令与回显均在 Ubuntu 22.04（x86_64）实测取得。

一、环境信息

• 操作系统：Ubuntu 22.04.4 LTS（内核 6.8.0-138-generic，x86_64，12 核，31GB 内存）
• 安装对象：Kubescape CLI v4.0.16（2026-10-14 发布，撰写时官方最新稳定版）
• 安装产物：单个 Go 静态二进制（约 295MB，内嵌 Rego 规则引擎与策略）
• 官方发布物：GitHub Releases 提供 raw 二进制、.deb、.rpm、.apk、.tar.gz 及 checksums.sha256 校验清单（本篇实测 raw 二进制与 .deb 两条路径）
• 网络：服务器可经 HTTP 代理访问 GitHub（实测代理 http://192.168.1.62:7897；直连 GitHub 慢或失败时使用）

二、前置条件

1. 一台可登录的 Ubuntu 22.04 服务器，具备 root 或 sudo 权限（本篇以 root 实测）。
2. 基础工具：curl、sha256sum（coreutils 自带，用于完整性校验）。确认命令：

curl --version | head -1
sha256sum --version | head -1

实测回显：

curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.1.1 brotli/1.0.9 nghttp2/1.43.0 librtmp/2.3
sha256sum (GNU coreutils) 8.32

3. 扫描本地 manifest 文件不需要 Kubernetes 集群；若后续要扫描活集群，才需要 kubeconfig（/etc/rancher/k3s/k3s.yaml 或 ~/.kube/config）与可连通的 API Server。
4. 磁盘余量：二进制约 295MB，加上规则缓存与漏洞库建议预留 2GB。

⚠️ 注意：Kubescape CLI 是一次性运行的可执行程序，不注册 systemd 服务；「systemd 托管」不适用于本工具，守护进程形态由 Kubescape Operator（Helm 部署进集群）承担，不在本篇范围。

三、版本选型说明

版本实查 GitHub Releases（查询日期 2026-10-24，releases.atom 源）：

v4.0.16 的发布资产（checksums.sha256 清单实测共 28 项，与 linux_amd64 相关条目）：

关键差异/如何选型：能联网且想一条命令装好选方案 A（官方脚本，自带 sha256 校验）；Ubuntu/Debian 上想纳入 dpkg 管理（dpkg -r 可干净卸载）选方案 B；完全离线或不想引入包管理器选方案 C。rpm/apk 资产对应 RHEL/Alpine 系，流程与 B 同理（rpm -i/apk add）。

四、方案 A：官方安装脚本在线安装（推荐）

4.1 方案说明

官方推荐路径：curl 拉取 master 分支的 install.sh 交给 bash 执行。脚本自动探测 OS/架构 → 从 GitHub API 取最新版本号 → 下载对应 raw 二进制 → 对照发布件里的 checksums.sha256 清单校验完整性（不匹配即失败退出） → 移入安装目录。root 用户安装到 /usr/local/bin，非 root 用户安装到 ~/.kubescape/bin。

4.2 下载并审阅脚本

cd /opt/data/quzuo/tmp/kubescape
export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897
curl -s https://raw.githubusercontent.com/kubescape/kubescape/master/install.sh -o install.sh
wc -l install.sh

实测回显：

225 install.sh

💡 说明：向 bash 直接管道执行第三方脚本前建议先落盘审阅。本脚本 225 行，核心逻辑清晰：get_latest_version 查询 GitHub API 最新 tag；verify_checksum 用 sha256sum 对照官方清单，校验失败即 exit 1；-v 参数可锁定指定版本。

4.3 执行安装

bash install.sh 2>&1 | sed 's/\x1b\[[0-9;]*m//g'

实测回显（去除终端颜色码；sed 仅为记录日志时去色，安装本身无需）：

Installing Kubescape...
Latest version: v4.0.16
Downloading from: https://github.com/kubescape/kubescape/releases/download/v4.0.16/kubescape_4.0.16_linux_amd64
######################################################################## 100.0%
Verifying checksum...
Checksum verified.
Finished Installation.

Run:
$ kubescape scan

行为细节（来自脚本源码与实测观察）：

1. 输出末尾打印 Run: $ kubescape scan 而不是版本号，是因为脚本最后执行 kubectl get nodes 探测集群连通性——本机无可用集群（或 kubectl 未装）时走此分支。已连通集群的服务器上会改打印 Finished Installation. 与 kubescape version 的输出。
2. 脚本会自动清理 /usr/local/bin/kubescape 与 ~/.kubescape/bin/kubescape 两处旧安装后覆盖，重复执行天然是升级。
3. 非 root 用户安装后脚本会提示 export PATH=$PATH:$HOME/.kubescape/bin。

4.4 验证

which kubescape
ls -la /usr/local/bin/kubescape
kubescape version

实测回显：

/usr/local/bin/kubescape
-rwxr-xr-x 1 root root 295188782 10月 24 04:42 /usr/local/bin/kubescape
Your current version is: v4.0.16
Build commit: d0ea07bcd9d7ab1640dcd6527d0e68a34f10da0e
Build date: 2026-10-14T12:44:34Z

版本行与 Build commit/Build date 均为实测原文；Build commit 与官方 v4.0.16 发布版一致即安装成功。

五、方案 B：deb 离线包安装（纳入 dpkg 管理）

5.1 方案说明

GitHub Releases 同时发布 .deb 资产，Ubuntu/Debian 服务器可下载后 dpkg -i 安装，安装内容登记进 dpkg 数据库，dpkg -r kubescape 即可干净卸载；产物落在 /usr/bin/kubescape。

5.2 下载与校验

cd /opt/data/quzuo/tmp/kubescape
curl -sL -x http://192.168.1.62:7897 "https://github.com/kubescape/kubescape/releases/download/v4.0.16/checksums.sha256" -o checksums.sha256
curl -sL -x http://192.168.1.62:7897 "https://github.com/kubescape/kubescape/releases/download/v4.0.16/kubescape_4.0.16_linux_amd64.deb" -o kubescape_4.0.16_linux_amd64.deb
sha256sum kubescape_4.0.16_linux_amd64.deb
grep 'kubescape_4.0.16_linux_amd64.deb' checksums.sha256

实测回显：

4c69c829a2b667b87c23e079d65ab754432d1b0403ae07055194653a27119020  kubescape_4.0.16_linux_amd64.deb
4c69c829a2b667b87c23e079d65ab754432d1b0403ae07055194653a27119020  kubescape_4.0.16_linux_amd64.deb

两行哈希一致，下载完整（deb 包实测 121110118 字节 ≈ 115MB，比裸二进制小是包格式压缩）。

5.3 安装

dpkg -i kubescape_4.0.16_linux_amd64.deb

实测回显：

正在选中未选择的软件包 kubescape。
(正在读取数据库 ... 系统当前共安装有 225907 个文件和目录。)
准备解压 .../kubescape_4.0.16_linux_amd64.deb  ...
正在解压 kubescape (4.0.16) ...
正在设置 kubescape (4.0.16) ...

5.4 验证

dpkg -L kubescape
dpkg -s kubescape | grep -E 'Package|Version|Installed-Size'
/usr/bin/kubescape version

实测回显：

/usr
/usr/bin
/usr/bin/kubescape
Package: kubescape
Installed-Size: 288270
Version: 4.0.16
Your current version is: v4.0.16
Build commit: d0ea07bcd9d7ab1640dcd6527d0e68a34f10da0e4
Build date: 2026-10-14T12:44:34Z

Installed-Size: 288270（KB）与版本号确认 deb 安装生效。

⚠️ 注意：方案 A 装在 /usr/local/bin、方案 B 装在 /usr/bin，两者可并存且互不覆盖，实际执行哪个取决于 PATH 顺序。排查命令 which -a kubescape（实测输出 /usr/local/bin/kubescape、/usr/bin/kubescape 两行）。保留一套、卸载另一套，避免「改了 A 的配置却跑着 B 的二进制」的错位。

六、方案 C：裸二进制手动安装（完全离线环境）

6.1 方案说明

不依赖脚本与包管理器：在外网机下载 raw 二进制与校验清单，传递到内网服务器后手工校验、赋权、放到 PATH。方案 A 的脚本本质就是本流程的自动化版本，本篇 sha256 值为实测值，可直接对照。

6.2 安装步骤

在外网机（或带代理的服务器）下载两个文件：

curl -sL -x http://192.168.1.62:7897 "https://github.com/kubescape/kubescape/releases/download/v4.0.16/kubescape_4.0.16_linux_amd64" -o kubescape
curl -sL -x http://192.168.1.62:7897 "https://github.com/kubescape/kubescape/releases/download/v4.0.16/checksums.sha256" -o checksums.sha256

在内网服务器校验并安装（假定两个文件已复制到 /opt/install/）：

cd /opt/install
grep 'kubescape_4.0.16_linux_amd64$' checksums.sha256 | sha256sum -c -
chmod +x kubescape
mv kubescape /usr/local/bin/kubescape
kubescape version

校验步骤的预期输出格式（哈希行 + OK；哈希实测值 fcf172f0d1fb5683379586bcf8875091da4d0d815bd304f8098d58be65ecab0d，与第三节清单一致即文件未损坏）：

kubescape_4.0.16_linux_amd64: OK

kubescape version 应输出与本篇 4.4 节一致的 Your current version is: v4.0.16 与 Build 信息；若不一致说明复制过程损坏，重新校验传输。

💡 说明：Release 侧还提供 cosign 签名与 SLSA 构建证明（gh attestation verify kubescape --repo kubescape/kubescape）两种更强的供应链校验，脚本源码注释中给出了完整命令；两者需要额外安装 cosign/gh 工具，普通场景 sha256 清单校验已足够，高安全场景建议叠加。

七、方案对比与选择建议

选择建议：一次性评估选 A；服务器群统一交付用 B（配合内网 apt 仓库分发）；安全域隔离的内网选 C（U 盘/堡垒机摆渡 + 手工校验）。

八、配置说明

Kubescape CLI 无配置文件常驻项，配置围绕「缓存目录、网络代理、规则包」三件事：

1. 缓存目录 ~/.kubescape/：首次扫描/下载时把框架规则、例外策略、漏洞库缓存在此（实测首次运行 NSA 扫描后生成 nsa.json，192310 字节）。可用全局参数 --cache-dir 或环境变量 KS_CACHE_DIR 重定向，例如多实例共用一个大容量盘：

export KS_CACHE_DIR=/data/kubescape-cache

2. 网络代理：kubescape 是 Go 程序，遵循标准 HTTPS_PROXY/HTTP_PROXY 环境变量。实测在不设代理时 kubescape download artifacts 出现多条 failed to get ... from github release, loading ... from cache 降级告警（见 10.1 节）；设置代理后同一命令完整成功：

export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897

3. 规则包离线化：断网环境先在能联网的机器执行 kubescape download artifacts --output <目录>（实测生成 controls-inputs.json、exceptions.json、16 个框架 json、attack-tracks.json 等），把目录拷到内网后扫描时指定 --use-artifacts-from <目录>，扫描全程不再联网。详见本专栏《Kubescape v4.0.16 配置参数详解》篇的离线扫描节。

九、升级、降级与多版本管理

9.1 自更新子命令

kubescape update

实测回显（受限网络下）：

{"level":"info","ts":"2026-10-24T04:58:44+08:00","msg":"Failed to check for updates"}

⚠️ 注意：该输出为实测原文——update 子命令的更新检查失败时只打一行 info 日志且退出码为 0（UPDATE_EXIT=0），不会报错中断。因此不能凭「命令没报错」认定已是最新版，务必以 kubescape version 与 Releases 页比对确认。本机实测即便设置代理该检查仍失败，生产环境建议直接用方案 A 重跑脚本升级。

9.2 脚本重跑升级/降级（可靠路径）

官方脚本天然支持版本锁定与覆盖安装：

# 升级到最新
bash install.sh
# 锁定版本安装/降级（-v 指定 tag）
bash install.sh -v v4.0.16

脚本行为（源码实测确认）：-v 缺省时查询 GitHub API 取最新 tag；资产 URL 形如 kubescape_4.0.16_linux_amd64；安装前自动删除 /usr/local/bin/kubescape 与 ~/.kubescape/bin/kubescape 旧文件后覆盖，因此重复执行即升级/降级，无需先卸载。

9.3 多版本并存

Kubescape 不提供内建多版本切换，二进制即版本。需要并存时按「改名的裸二进制」管理：

cp /usr/local/bin/kubescape /opt/kubescape/v4.0.16
/opt/kubescape/v4.0.16 version

实测回显：

Your current version is: v4.0.16
Build commit: d0ea07bcd9d7ab1640dcd6527d0e68a34f10da0e4
Build date: 2026-10-14T12:44:34Z

十、常见问题（FAQ）

Q1：下载 295MB 二进制很慢或中途失败怎么办？

先给会话设置代理再重跑（脚本内的 curl 会继承环境变量）：

export https_proxy=http://192.168.1.62:7897 http_proxy=http://192.168.1.62:7897
bash install.sh

实测该代理下 295MB 资产约半分钟完成。若必须直连，改用方案 B 的 deb（115MB）减小体积，或从内网镜像中转。

Q2：download artifacts 报 failed to get ... loading from cache 是什么问题？

实测现象（无代理直连 GitHub 超时场景）：

{"level":"warn",...,"msg":"failed to get config inputs from github release, loading config inputs from cache"}
{"level":"warn",...,"msg":"error downloading","artifact":"controls-inputs","error":"error opening controls-inputs.json file, \"controls-config\" will be downloaded from ARMO management portal"}
Error: error opening controls-inputs.json file, "controls-config" will be downloaded from ARMO management portal
open /root/.kubescape/exceptions.json: no such file or directory

定位：各 artifact 逐个从 GitHub Release 下载，任一失败即降级（用缓存或报错），末尾 Error 汇总列出失败清单。解决：设置 https_proxy 环境变量后重跑，实测 4 项全部变为 {"level":"info",...,"msg":"Downloaded",...}（controls-inputs/exceptions/16 个框架/attack-tracks 全量成功）。

Q3：扫描时提示 Scan Coverage Warning 与 degraded config？

实测现象：

Scan coverage score: 90% (20/20 controls evaluated)
The following policy inputs could not be loaded and were served from bundled defaults:
  • controlInputs: error opening controls-inputs.json file, ...

原因：controls-inputs（控件配置）未能从网络获取，CLI 用内置默认值兜底，合规分可能失真。解决：补网络/代理，或用 --use-artifacts-from 指向离线规则包；强制失败而非兜底可加 --fail-on-degraded-config。

Q4：装了脚本版又装了 deb，执行的是哪个？

which -a kubescape 看全部位置，kubescape version 看 Build commit 是否一致。两处并存不会互相覆盖（路径不同），建议保留一套（deb 用 dpkg -r kubescape 卸载，脚本版直接 rm）。

Q5：非 root 服务器怎么装？

直接跑方案 A 脚本即可：非 root 自动装入 ~/.kubescape/bin 并提示补 PATH（脚本源码按 id -u 判断，无需 sudo）。方案 C 同理把 mv 目标换成用户可写目录并加 PATH。

十一、卸载与清理

按安装来源清理（三条路径均实测可行）：

# 方案 A / C（裸二进制）
rm -f /usr/local/bin/kubescape

# 方案 B（deb）
dpkg -r kubescape

实测回显（dpkg 卸载）：

(正在读取数据库 ... 系统当前共安装有 225908 个文件和目录。)
正在卸载 kubescape (4.0.16) ...

再清理缓存与规则包（扫描会重建，删前确认无需保留历史报告）：

rm -rf ~/.kubescape

验证卸载干净：

which -a kubescape; echo "WHICH_EXIT=$?"
ls ~/.kubescape

实测回显（本篇完整清理后实取）：

WHICH_EXIT=1
ls: cannot access '/root/.kubescape': No such file or directory

which -a 无任何输出且退出码 1（未找到命令）、缓存目录报不存在，即卸载彻底。实测过程记录：deb 卸载（dpkg -r kubescape）后 which -a kubescape 由两行（/usr/local/bin/kubescape、/usr/bin/kubescape）收敛为仅剩脚本版一行，再 rm -f /usr/local/bin/kubescape 与 rm -rf ~/.kubescape 后归零。

十二、参考链接

1. 官方 Releases（版本与资产）：https://github.com/kubescape/kubescape/releases
2. 官方安装脚本：https://github.com/kubescape/kubescape/blob/master/install.sh
3. 官方文档安装章节：https://kubescape.io/docs/install-cli/
4. v4.0.16 校验清单：https://github.com/kubescape/kubescape/releases/download/v4.0.16/checksums.sha256
5. 同系列文档：《Kubescape 介绍与选型指南》（认知与选型）；本专栏另含《Kubescape v4.0.16 配置参数详解》（scan 参数与离线规则包）与《Kubescape v4.0.16 常用 CLI 命令详解》（子命令全解）两篇

站内相关：《Ubuntu 22.04 安装 Kubescape v4.0.16 指南》、《Kubescape v4.0.16 常用 CLI 命令详解》