NVX网络策略配置指南：如何用Egress出口白名单精确控制Micro-VM上网权限（IPv4/IPv6与L3-L4端口全解析）-育师

【免费下载链接】nvx

Cross-Platform Micro-VM Sandbox for Agentic Workloads

项目地址：https://gitcode.com/gh_mirrors/nvx/nvx

NVX 是一个跨平台的 Micro-VM 沙箱，专为 Agent 类工作负载设计。它的网络策略系统让你用一组简单的Egress（出口）白名单规则，精确决定沙箱里的程序能访问哪些 IPv4/IPv6 地址、哪些 L3-L4 协议与端口——默认全放行还是默认全拒绝、只开 HTTPS 443 还是屏蔽某段内网 IP，都可以一行命令搞定。本指南面向新手，带你从零理解 NVX 网络策略的匹配机制，并给出可直接复制的配置示例。

1. 先搞懂：NVX 的出口流量是怎么被拦截的

NVX 的虚拟机没有物理网卡、TAP 或网桥。Guest 里的 virtio-net 驱动发出的数据帧，会先交给 VMM 进程内的网络端点做逐字节授权，再转成宿主的普通 socket 连接发出去。这意味着：

策略在发出前生效：每个出站帧都要过一遍 Egress 策略，不匹配的流量直接被丢弃；
TCP 是代理转发：VMM 终结 Guest 侧连接，由宿主内核发起远端连接，远端看到的是宿主的网络身份；
入站默认拒绝：Guest 主动发起的连接有回复通道，但外部无法主动连入 Guest（除非显式开启 ingress）。

完整数据路径见官方设计文档 doc/design/3.5-network.md 中的 "Egress Policy" 一节。

2. 五个核心参数速查：控制上网权限的命令行开关

NVX 的网络策略由 5 个参数组成（完整说明见 doc/usage.md 的参数表）：

参数	作用	默认值
`--network-egress {allow,deny}`	设定出口流量的默认动作（兜底规则）	`allow`
`--network-egress-allow CIDR[:PROTOCOL[:PORT[-PORT]]]`	追加白名单规则，可重复	无
`--network-egress-deny CIDR[:PROTOCOL[:PORT[-PORT]]]`	追加黑名单规则，可重复	无
`--network-egress-policy-file PATH`	从 JSON 文件批量加载规则	无
`--network-proxy IPV4:PORT`	切换为仅代理模式：只允许走指定的 HTTP/HTTPS 代理	无

📌 三个关键机制（来自 doc/run.md）：

Deny 优先：一个包先匹配 deny 规则，再匹配 allow 规则，都不中才看默认动作；
家族隔离：IPv4 规则永远不匹配 IPv6 流量，反之亦然；
规则必须有显式默认：--network-egress-allow/--deny要求同时给出--network-egress的取值。

3. 三种最常用配置：一键上手示例

3.1 默认拒绝 + 白名单只放行 HTTPS

这是 Agent 沙箱最经典的"最小权限"姿势——Guest 只能访问微软 CDN 的 443 端口，其余全部拒绝：

nvx-rs/target/release/nvx-rs run \ --net 10.0.0.2/24 \ --network-egress deny \ --network-egress-allow 140.82.112.0/20:tcp:443 \ --network-egress-deny 140.82.114.0/24:tcp:443

注意最后一条 deny 规则的妙处：即使 443 整体被 allow，140.82.114.0/24这个子网里的 443 依然被拦死。

3.2 默认放行 + 屏蔽特定目标

反过来，如果你只是想在默认放行的基础上禁掉某些地址（比如某个内网段、某个端口）：

--network-egress allow \ --network-egress-deny 192.0.2.1:tcp:8005

3.3 仅代理模式（Proxy-only）

彻底关掉直连，让所有流量只能走你指定的 HTTP/HTTPS 代理：

--net 10.0.0.2/24 \ --network-egress deny \ --host-loopback deny \ --network-proxy 10.0.0.1:3128

代理必须监听在宿主127.0.0.1:3128，Guest 通过网关地址10.0.0.1:3128访问它。此模式要求端口不能是 53（那是网关 DNS 代理保留的），也不允许再叠加任何 egress 规则——"直连"和"纯代理"是两种互斥的连通模型。

4. 规则语法详解：IPv4/IPv6 与 L3-L4 端口怎么匹配

每条规则的格式是三段可选结构：CIDR[:PROTOCOL[:PORT[-PORT]]]。

① 地址段（L3 层）

IPv4 示例：192.0.2.1（单个主机，等价/32）、192.0.2.0/24、0.0.0.0/0（所有 IPv4 目标）
IPv6 示例：2001:db8::/32:tcp:443、::/0（所有 IPv6 目标）
规则只匹配自己家族的目标地址，所以想全面封禁 IPv6，直接加一条--network-egress-deny ::/0即可（在--network-egress deny的默认下，未被 IPv6 allow 规则覆盖的 IPv6 目标本来就会被拒绝）

② 协议（L4 层）

tcp/udp：可继续指定端口或端口范围
icmp：仅匹配 ICMP（IPv6 目标则匹配 ICMPv6），不能带端口
省略协议时，deny/allow匹配该目标的所有协议

③ 端口

单个端口：192.0.2.1:tcp:8005
闭区间范围：192.0.2.1:tcp:8000-8010（含 8000 与 8010，不含边界外）
范围上限不能低于下限；合法端口为1–65535

DNS 的小知识：网关会在 53 端口提供 DNS 代理。只有当你的策略允许 Guest 向网关访问 TCP/UDP 53 时，Guest 才会被配置使用该 DNS 服务器；否则在 deny 默认下 Guest 根本拿不到 DNS 地址。

5. 进阶：用 JSON 策略文件批量管理规则

命令行规则数量多、或需要"一个网段内挖掉一个子网"这种复杂拓扑时，改用策略文件。文件是严格的 RFC 8259 JSON，最大 1 MiB，根对象只允许allow和deny两个数组（格式定义见 nvx-rs/src/host/network/policy/mod.rs）：

{ "allow": [ { "to": [{ "cidr": "192.0.2.0/24", "except": ["192.0.2.128/25"] }], "ports": [{ "protocol": "tcp", "port": 8000, "endPort": 8010 }] }, { "to": [{ "cidr": "2001:db8::/48" }], "ports": [{ "protocol": "tcp", "port": 443 }] } ], "deny": [ { "to": [{ "cidr": "192.0.2.0/24" }], "ports": [{ "protocol": "tcp", "port": 8005 }] } ] }

要点：

except是规则内排除：192.0.2.0/24减去192.0.2.128/25，且排除项必须落在父网段内；它只影响当前规则，不会变成全局 deny；
省略字段即"全匹配"：不写to匹配两个家族的所有目标，不写ports匹配所有协议和端口；
any协议 + 端口= 同时展开为 TCP 和 UDP 两条规则（不含 ICMP）;
上限校验：每个动作（allow/deny）编译后最多 256 条原生规则，超限会在启动前直接报错拒绝，而不是悄悄截断；
文件选项不能与--network-egress-allow/deny混用，但仍需显式--network-egress默认值。

使用方式：--network-egress-policy-file policy.json。托管沙箱（sandbox provision）会把编译后的规则持久化进沙箱状态，后续启动不会重读可变的源文件。

6. 常见疑问 FAQ

Q1：deny 默认下，Guest 还能动吗？Guest 与网关之间的 ARP/邻居发现等基础协议在 allow 默认或存在 IPv6 allow 规则时可用；纯deny+--host-loopback deny+ 无任何 allow 规则时，NVX 干脆不挂网卡。

Q2：allow 默认 + 一条 deny 覆盖整个 allow 会怎样？可以挂网卡但什么都通不了——这正是 NVX 允许的"合法的空洞策略"。

Q3：IPv6 怎么单独管控？写 IPv6 规则即可，如--network-egress-allow 2001:db8::/32:tcp:443。Guest 的 IPv6 地址由 IPv4 地址派生（内嵌于fd00::/96），无需额外配置。

Q4：快照恢复会影响策略吗？快照记录的是策略摘要，恢复要求网络 profile 与策略完全一致；在途 TCP/UDP 流不会被序列化，恢复后流量重新建连。

7. 延伸阅读：文档与源码路径

想深入原理，建议按这个顺序阅读：

网络架构与 Egress 策略设计：doc/design/3.5-network.md
命令参数与完整示例（含策略文件语法）：doc/run.md
所有 CLI 参数速查表：doc/usage.md
策略类型与上限常量（MAX_RULES等）：nvx-rs/src/host/network/mod.rs
策略文件解析与编译：nvx-rs/src/host/network/policy/mod.rs
方向性网络策略回归测试脚本：scripts/nvx_tools/microvm_test_scripts/directional-network-policy.sh.in、scripts/nvx_tools/microvm_test_scripts/l3-l4-egress-policy.sh.in

掌握egress 默认 + allow/deny 规则 + 策略文件这套组合，你就能给 NVX 沙箱里的 Agent 工作负载划出"刚好够用"的网络边界了。 🚀