gVisor 安装指南：apt 仓库、tarball 手动安装与 release 渠道详解

gVisor 安装指南：apt 仓库、tarball 手动安装与 release 渠道详解

【免费下载链接】gvisorApplication Kernel for Containers项目地址: https://gitcode.com/GitHub_Trending/gv/gvisor

本篇指南基于 gVisor（Application Kernel for Containers）官方安装文档展开，系统讲解从apt仓库安装、手动下载 tarball 安装、Docker 运行时注册，到 2026 年多文件（multi-file）发布模式迁移，以及 HEAD / Nightly / Latest / Specific / Point 五类 release 渠道的完整选择与用法。读完本文，你将掌握在 x86_64 与 ARM64、Linux 5.6+ 主机上正确安装并验证runsc的每一步操作，并理解gvisor-bin/sidecar 二进制目录的底层机制与迁移要求。

安装前的环境要求

gVisor 对宿主机的软硬件有明确约束：

• CPU 架构：支持x86_64和ARM64（aarch64）两种架构；
• 内核版本：要求Linux 5.6 及以上。

gVisor 的用户态内核（sentry）依赖宿主内核提供的特定系统调用与内存管理特性（例如io_uring相关能力、fexecve等），Linux 5.6 是官方支持的下限版本。如果宿主机内核低于该版本，安装后容器将无法正常启动，建议先升级内核再继续。

安装完成后，runsc需要被放置在所有用户可读、可执行的路径下（例如/usr/local/bin），因为runsc出于安全考虑可能需要以非特权用户身份重新执行自身。这一点在 tarball 安装部分会再次强调。

方式一：通过apt仓库安装（推荐）

对于 Debian / Ubuntu 系发行版，官方维护了 gVisor 的apt仓库。这是最省心、最面向未来的安装方式，也是官方明确推荐的路径——后续小节会解释原因。

第一步：安装依赖

apt需要借助 HTTPS 从仓库拉取软件包，因此先安装对应依赖：

sudo apt-get update && \ sudo apt-get install -y \ apt-transport-https \ ca-certificates \ curl \ gnupg

第二步：配置签名密钥与仓库源

gVisor 的归档文件使用 GPG 密钥签名，需要先把公钥下载并去装甲化（dearmor）为 keyring 文件，再写入仓库源：

curl -fsSL https://gvisor.dev/archive.key | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null

注意：签名密钥已于2021-07-13更新以替换过期密钥。如果安装时出现"密钥已过期（key expired）"之类的报错，重新执行上面第一条curl命令刷新 keyring 即可。

仓库行中的release是发布渠道名，可以按需替换为master、nightly或具体日期（详见下文"版本与 release 渠道"一节）；$(dpkg --print-architecture)会自动展开为当前机器的 Debian 架构名。

第三步：安装runsc软件包

sudo apt-get update && sudo apt-get install -y runsc

安装完成时，如果系统里已经装有 Docker，安装脚本会自动完成 Docker 运行时注册，之后即可直接使用docker run --runtime=runsc。若未自动注册，可手动执行后续的runsc install步骤。

方式二：手动安装最新 release（tarball）

apt方式不可用（例如使用非 Debian 系发行版）时才建议走手动安装。官方明确提醒：只要能装 Debian 包就优先用apt方式，因为它更能跟上未来的发布形态变化。

下载与解压

以下命令会下载最新 release 的压缩包并校验 SHA-512 校验和：

( set -e ARCH=$(uname -m) URL=https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH} wget ${URL}/gvisor.tar.zstd ${URL}/gvisor.tar.zstd.sha512 sha512sum -c gvisor.tar.zstd.sha512 sudo tar --zstd -xf gvisor.tar.zstd -C /usr/local/bin rm -f gvisor.tar.zstd gvisor.tar.zstd.sha512 )

• $(uname -m)在 x86_64 机器上返回x86_64，在 ARM64 机器上返回aarch64，与 release URL 的架构组件一一对应；
• sha512sum -c会校验下载文件与官方校验和是否一致，任何不匹配都会导致命令失败（set -e保证脚本立即退出），避免安装被篡改的二进制。

如果机器上没有安装zstd，可以改用gvisor.tar.bz2（Bzip2 压缩格式），把上面命令中的gvisor.tar.zstd与gvisor.tar.zstd.sha512分别替换为gvisor.tar.bz2与gvisor.tar.bz2.sha512即可。

tarball 的内容与目录布局

gvisor.tar.zstd压缩包内包含：

• runsc：gVisor 的 OCI 运行时主二进制；
• containerd-shim-runsc-v1：供 containerd 使用的 shim 二进制；
• gvisor-bin/目录：sidecar 二进制（sidecar binaries）存放目录，runsc在运行时按需执行其中的子进程。

runsc会在自身二进制所在目录旁边查找gvisor-bin/目录来定位这些 sidecar。因此，如果移动runsc，必须连同gvisor-bin/一起移动，二者必须始终保持相邻。

从源码结构看，这一约定实现在 runsc/gvisorbinaries/gvisorbinaries.go 中：包注释明确规定"sidecar 存放在主二进制旁边的gvisor-bin/目录中"（binDirName = "gvisor-bin"），resolveDir()通过filepath.Join(filepath.Dir(ExePath), binDirName)解析目录，并在runsc是符号链接时使用EvalSymlinks解析真实路径后再定位。标准安装中的 sidecar 共四个，在源码中以常量列出：

此外还有仅在启用 plugin 网络栈的安装中存在的gvisor_sentry_plugin_stack（plugin-enabled installations，不属于标准All列表）。

注册为 Docker 运行时并验证

sudo /usr/local/bin/runsc install sudo systemctl reload docker docker run --rm --runtime=runsc hello-world

runsc install会自动向 Docker 守护进程配置（默认路径/etc/docker/daemon.json）写入名为runsc的 runtime 条目，其具体行为可在 runsc/cmd/install.go 中确认：命令读取现有 JSON 配置，将runtimes["runsc"]设置为{"path": "<runsc 可执行文件路径>", "runtimeArgs": [...]}，默认clobber=true（覆盖已有同名 runtime），写入前还会把原配置备份为daemon.json~。systemctl reload docker让守护进程重新加载配置后，docker run --runtime=runsc hello-world即可验证安装是否成功。

注意：务必把runsc复制到所有用户都可读可执行的目录（如/usr/local/bin），因为runsc可能需要以非特权用户身份重新执行自身以提升安全性；gvisor-bin/目录必须随之一起移动。

安装后验证

运行一个交互容器并在容器内执行dmesg，如果看到类似下面的输出，即表示容器确实运行在 gVisor 沙箱中：

$ docker run --runtime=runsc -it ubuntu dmesg [ 0.000000] Starting gVisor... [ 0.354495] Daemonizing children... ... [ 2.613217] Ready!

官方文档同时提示：dmesg输出很容易被攻击者伪造，在安全敏感场景下不要依赖dmesg来验证运行时。更全面的使用指引见 Docker Quick Start、Containerd Quick Start 与 OCI Quick Start；若要用于生产环境，请务必先阅读 Production guide。

带自定义参数的 runtime 注册

runsc install支持把额外参数透传给 runtime。例如注册一个开启调试的runsc-debugruntime：

sudo runsc install --runtime runsc-debug -- \ --debug \ --debug-log=/tmp/runsc-debug.log \ --strace \ --log-packets

--之后的所有参数会被写入daemon.json的runtimeArgs字段，Docker 每次调用该 runtime 时都会带上。注意：启用调试前请确保宿主机的 SELinux 处于关闭状态。install子命令还提供--config_file（Docker 配置路径，默认/etc/docker/daemon.json）、--cgroupdriver（Docker cgroup 驱动）等参数。

从旧版"仅 runsc 二进制"安装迁移

2026 年 7 月之前，gVisor 的 release 只包含两个二进制（runsc和containerd-shim-runsc-v1），所有附带材料都打包内嵌在runsc内部。此后发布形态转变为多文件（multi-file）模式，即上文的gvisor-bin/sidecar 机制（背景见 gVisor issue #13718）。

自动下载机制与迁移期限

• 如果runsc旁边缺失某个 sidecar，runsc install会尽力（best-effort）自动下载缺失二进制到自身旁边的gvisor-bin/子目录中；
• 该自动下载功能将于 2026 年 9 月底被移除，在此之前你需要自行更新安装流程。

自动下载依赖三个前提条件：

1. 能访问storage.googleapis.com网络；
2. 在runsc install执行时，对runsc所在父目录有写权限；
3. 系统装有curl或wget（由于技术限制，runsc目前无法链接net/http库，只能借助外部下载工具）。

自动下载的实现细节可在 runsc/cmd/install_sidecars.go 中确认：installSidecars()遍历gvisorbinaries.All检查缺失项，然后从由runsc自身版本推导出的 release URL 下载gvisor.tar.bz2及其.sha512校验文件，用 SHA-512 校验后仅抽取其中的gvisor-bin/成员，通过临时目录 + 原子重命名的方式替换旧目录；下载与解压全部失败即报错退出。install.go中还提供--download-sidecars与--require-sidecars两个临时开关（取值NEVER/ALWAYS/IF_RELEASE_BUILD，默认IF_RELEASE_BUILD）控制该行为——这些标志本身也是临时的，会随自动下载功能一并移除。

迁移到新安装方式

官方给出的迁移路径有两条，任选其一：

• 使用 Debianapt仓库（见上文"方式一"）——最面向未来，官方首选；
• 从 tarball 手动安装（见上文"方式二"）——tarball 内含完整的gvisor-bin/目录。

sidecar 相关的运行时策略参数

仓库中同时引入了两个运行时配置项（见 runsc/config/config.go 与 runsc/config/flags.go）：

• --sidecar-usage-policy：sidecar 缺失时的处理策略，取值：
  • STRICT：sidecar 必须存在，缺失即报错（DEFAULT 策略将于 2026 年 9 月后切换为 STRICT）；
  • LEGACY_DEPRECATED_SLOW_EMBEDDED_FALLBACK：回退使用内嵌副本（已废弃，会拖慢启动，2026 年 10 月后失效）；
  • DEFAULT：当前默认值，缺失时回退内嵌副本并给出弃用警告。
• --sidecar-release-enforcement-policy：sidecar 与runsc的 release 版本一致性校验策略，取值NEVER/ALWAYS/IF_RELEASE_BUILD。若两侧 release 不一致，runsc会通过环境变量GVISOR_ENFORCE_RELEASE让 sidecar 在启动时 panic，避免"版本错配导致难以排查的问题"（VerifyMatchingRelease校验逻辑见 runsc/gvisorbinaries/gvisorbinaries.go）。

版本与 release 渠道

runsc二进制与apt仓库提供多个版本与发布渠道。选择原则很简单：实验探索用 nightly，生产环境用 latest release。

选定渠道后，再回到上面的安装方式：tarball 手动安装时把 URL 中的release/latest替换为对应渠道；apt安装则把仓库行中的渠道名替换为对应值。

注意：较老版本的 release URL 可能没有${ARCH}组件——这些版本仅提供x86_64架构。

HEAD（master 分支最新提交）

master分支上的每次提交都会产出二进制：

• tarball URL：https://storage.googleapis.com/gvisor/releases/master/latest/${ARCH}
• apt仓库行：

sudo add-apt-repository "deb [arch=amd64,arm64] https://storage.googleapis.com/gvisor/releases master main"

Nightly（每日构建）

Nightly release 大多在每晚从 master 分支构建：

• tarball URL：https://storage.googleapis.com/gvisor/releases/nightly/latest/${ARCH}
• 特定日期的构建：https://storage.googleapis.com/gvisor/releases/nightly/${yyyy-mm-dd}/${ARCH}（并非每天都有构建）
• apt仓库行：

sudo add-apt-repository "deb [arch=amd64,arm64] https://storage.googleapis.com/gvisor/releases nightly main"

Latest release（最新正式版）

• tarball URL：https://storage.googleapis.com/gvisor/releases/release/latest/${ARCH}
• apt仓库行：

sudo add-apt-repository "deb [arch=amd64,arm64] https://storage.googleapis.com/gvisor/releases release main"

Specific release（指定日期的正式版）

特定 release 是某个日期对应的最新 point release：

• tarball URL：https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}/${ARCH}
• apt安装时用该日期作为仓库渠道名（可能包含 point 更新）：

sudo add-apt-repository "deb [arch=amd64,arm64] https://storage.googleapis.com/gvisor/releases yyyymmdd main"

注意：只有较新的 release 才提供apt仓库形式。

Point release（打标签的发布版）

Point release 对应 GitHub 仓库中打了 tag 的正式发布，每个发布都附带 release notes / changelog，以及各架构的可下载 tarball（gvisor-x86_64.tar.bz2、gvisor-aarch64.tar.bz2）与校验文件（SHA256SUMS、SHA512SUMS）。也可以直接从发布存储桶获取：

• tarball URL：https://storage.googleapis.com/gvisor/releases/release/${yyyymmdd}.${rc}/${ARCH}

注意：apt不支持安装特定 point release。

安装后的下一步

安装并验证runsc后，可以按需选择运行时集成方式继续深入：

• Docker Quick Start：把runsc注册为 Docker runtime 后运行容器（docker run --runtime=runsc --rm hello-world），还包含带--link、-v、-p、--cpus等参数的组合示例；
• Containerd Quick Start：通过containerd-shim-runsc-v1与 containerd runtime handler 集成（要求 containerd 最低版本 1.3.9 / 1.4.3，在/etc/containerd/config.toml中声明runtime_type = "io.containerd.runsc.v1"）；
• OCI Quick Start：不依赖容器引擎，直接构造 OCI bundle 后以runsc spec -- /hello生成规范、sudo runsc run hello启动沙箱。

小结

• 优先apt：Debian/Ubuntu 上用apt仓库安装最省心，且能自动完成 Docker 注册；
• tarball 兜底：非 Debian 系或需要精确控制版本时手动安装，务必让runsc与gvisor-bin/保持相邻；
• 警惕迁移期限：2026 年 9 月底自动下载功能将下线、2026 年 10 月内嵌 fallback 将失效，请在此之前切换到含gvisor-bin/的新式安装；生产环境选择release渠道，并参考 Production guide 完成部署前评估。

【免费下载链接】gvisorApplication Kernel for Containers项目地址: https://gitcode.com/GitHub_Trending/gv/gvisor