企业官网建设流程全解析

• 后端
• 虚拟化
• 容器运行时

导读

IPAM（IP Address Management，IP 地址管理）是对网络中 IP 地址空间进行规划、跟踪与维护的方法。在 Incus 中，你可以通过incus network list-allocations命令查看整个部署的 IP 分配全景：哪些 IP 被实例、网络接口、网络转发（forward）和负载均衡器（load balancer）占用，以及这些地址是否处于 NAT 模式。本文以 doc/howto/network_ipam.md 为骨架，结合客户端命令与服务端 API 源码，完整讲解该命令的用法、输出字段语义、高级参数以及底层数据聚合原理，帮助你快速定位流量丢失、地址冲突等网络故障。

IPAM 在 Incus 中的定位

IP 地址管理（IPAM）是网络运维的基础能力，其核心诉求是回答三个问题：哪个实体占用了哪个地址？地址落在哪个网段？是否经过 NAT？

在 Incus 部署中，网络地址的消费方不止实例本身，还包括：

• network：管理网桥（如incusbr0）自身使用的子网地址（IPv4/IPv6 网段）；
• instance：从网络 DHCP 租约中获取地址的实例；
• network-forward：网络转发（端口转发）的监听地址；
• network-load-balancer：网络负载均衡器的监听地址。

当出现"实例之间无法互通""流量莫名丢失"等问题时，先列出当前的 IPAM 信息，往往比逐个检查实例配置更快。这正是本文介绍的查询命令的典型应用场景。

基本用法：列出全部网络分配

执行以下命令即可查看当前 Incus 部署的 IPAM 信息：

incus network list-allocations

该命令默认展示default项目的 IPAM 信息。若你的环境启用了多项目，可通过--project标志切换到指定项目，或用--all-projects一次查看所有项目的分配情况：

# 查看指定项目 incus network list-allocations --project myproject # 查看所有项目 incus network list-allocations --all-projects

注意：--project与--all-projects不能同时使用。客户端源码 cmd/incus/network_allocations.go 中对此有显式校验，会直接报错 "Can't specify --project with --all-projects"。

典型的输出如下（表格形式）：

┌────────────────────────┬─────────────────┬──────────┬──────────┬─────┬───────────────────┐ │ USED BY │ ADDRESS │ NETWORK │ TYPE │ NAT │ MAC ADDRESS │ ├────────────────────────┼─────────────────┼──────────┼──────────┼─────┼───────────────────┤ │ /1.0/networks/incusbr0 │ 192.0.2.0/24 │ incusbr0 │ network │ YES │ │ │ ├─────────────────┼──────────┼──────────┼─────┼───────────────────┤ │ │ 2001:db8::/32 │ incusbr0 │ network │ YES │ │ ├────────────────────────┼─────────────────┼──────────┼──────────┼─────┼───────────────────┤ │ /1.0/instances/u1 │ 192.0.2.2/32 │ incusbr0 │ instance │ YES │ 10:66:6a:04:f0:95 │ │ ├─────────────────┼──────────┼──────────┼─────┼───────────────────┤ │ │ 2001:db8::1/128 │ incusbr0 │ instance │ YES │ 10:66:6a:04:f0:95 │ └────────────────────────┴─────────────────┴──────────┴──────────┴─────┴───────────────────┘ ...

输出字段与实体类型详解

每一行代表一条网络分配记录，字段含义如下：

数据类型定义位于 shared/api/network_allocation.go，对应 JSON 字段为addresses、hwaddr、nat、type、used_by、network。

理解各类型的行为差异有助于诊断问题：

• network（网段条目）：ADDRESS是该网络配置的完整子网（如192.0.2.0/24），NAT取决于网络配置中的ipv4.nat/ipv6.nat键。
• instance（实例条目）：来自网络 DHCP 租约，包含静态（static）和动态（dynamic）两类租约；同一实例的 IPv4 与 IPv6 地址会作为独立行展示，并附带 MAC 地址。
• network-forward / network-load-balancer：这两类属于入口（ingress）流量，因此源码中其NAT字段固定为false——注释明确说明 "Network forwards are ingress and so aren't affected by SNAT"（见 cmd/incusd/network_allocations.go）。

高级选项：自定义列、输出格式与摘要视图

除默认表格外，incus network list-allocations还提供三个实用选项（定义见 cmd/incus/network_allocations.go）。

--columns（或-c）自定义列

默认列布局为uaNtnm，预定义的列简写字符如下：

用法示例：只看实例用到的地址、类型和 MAC：

incus network list-allocations --columns atn

简写字符之间可省略逗号，也可以写成a,t,n。源码中 parseColumns 会对每个字符查表解析，未知字符会报错Unknown column shorthand char。

--format切换输出格式

支持csv、json、table、yaml、compact、markdown六种格式，便于直接交给脚本或监控系统处理，例如：

incus network list-allocations --format json incus network list-allocations --format csv incus network list-allocations --format markdown

格式值可加后缀,noheader去掉表头、,header强制显示表头（如csv,header）。该选项还受全局默认列表格式影响。

--summary子网占用汇总

从 Incus 7.x 起，命令增加了--summary标志，用于按子网汇总已占用的 IP 地址：

incus network list-allocations --summary

输出包含NETWORK、SUBNET、USED三列。USED列会将已占用地址压缩为紧凑的地址区间（如192.0.2.2-192.0.2.10），并按网段归类；不属于任何已配置子网的地址归入external行。这非常适合回答"某个网段还剩多少地址可用"这类容量规划问题。

注意：--summary不能与自定义列-c同时使用，源码 run 中对此有明确校验。汇总逻辑实现在 renderSummary，内部使用netip.Prefix/netip.Addr做子网归属判定与区间压缩（compactRanges）。

底层原理：数据从何而来

incus network list-allocations的查询链路非常清晰：

1. 客户端调用GetNetworkAllocations()/GetNetworkAllocationsAllProjects()（见 client/incus_network_allocations.go），这两个方法会先检查服务端 API 扩展network_allocations，然后向GET /1.0/network-allocations（或带?all-projects=true）发起请求。

2. 服务端在 cmd/incusd/network_allocations.go 的networkAllocationsGet处理器中聚合数据，聚合顺序为：

   • 解析project查询参数（支持项目级网络重定向，即network project特性）；
   • 若指定all-projects，先从数据库读取全部项目名（GetProjectNames）；
   • 对每个项目、每个网络依次：
     1. 读取网络配置中的ipv4.address/ipv6.address，生成network类型的网段条目，并依据ipv4.nat/ipv6.nat标记 NAT；
     2. 调用网络的 Leases 方法获取 DHCP 租约，过滤出static与dynamic租约生成instance条目（IP 会被规范化为/32或/128形式），MAC 地址来自租约；
     3. 从数据库加载该网络的 forwards，为每个监听地址生成network-forward条目；
     4. 从数据库加载该网络的 load-balancers，为每个监听地址生成network-load-balancer条目。

3. 返回结构为api.NetworkAllocations数组（shared/api/network_allocation.go），客户端再按用户选择的列、格式渲染输出（cmd/incus/network_allocations.go#L182-L199）。

Leases的具体实现在各网络驱动中：桥接网络见 internal/server/network/driver_bridge.go，OVN 网络见 internal/server/network/driver_ovn.go，公共实现在 internal/server/network/driver_common.go。这意味着不同网络驱动（bridge / OVN / 物理网卡等）对 IPAM 查询的支持程度可能不同，不支持的驱动会返回ErrNotImplemented，服务端会跳过租约采集而不报错（见 cmd/incusd/network_allocations.go）。

该功能通过 API 扩展network_allocations引入（见 doc/api-extensions.md），后续又通过network_allocations_network扩展在响应中增加了network字段。

实战：用 IPAM 信息排查网络故障

结合命令的输出语义，可以设计出几条直接的排查路径：

1. 定位流量丢失点当实例u1的 IPv4 地址意外变化或与预期不符时，先执行：

incus network list-allocations | grep u1

对比ADDRESS是否仍落在预期网段（如192.0.2.0/24）内。若地址显示为外部网段（summary 视图下归入external行），说明租约来源异常。

2. 判断端口转发是否生效转发和负载均衡器条目恒定显示NAT: NO。如果发现某条network-forward条目消失，说明该转发配置被删除或网络被重建，此时应检查 network_forwards 相关配置。

3. 多项目地址冲突检查启用多项目后，用--all-projects全量导出并检查是否存在相同ADDRESS被不同USED BY占用：

incus network list-allocations --all-projects --format csv

4. 容量规划用--summary查看各子网已用区间，快速评估是否需要扩容网段或收紧租约时间。

小结

incus network list-allocations是 Incus 内置的 IPAM 观测入口，一条命令即可汇总网络、实例、转发与负载均衡器的地址占用全貌。掌握其默认输出、--project/--all-projects范围控制、--columns/--format输出定制以及--summary汇总视图，配合本文所述的底层聚合原理，可以显著提升日常网络排障与规划效率。更多网络管理操作可参考 doc/howto/network_configure.md 与 doc/howto/network_forwards.md。

• 后端
• 虚拟化
• 容器运行时