Incus 存储、内存与网络限制的单位解析指南:十进制与二进制后缀的完整用法

原创2026-10-09 13:22:311,417 阅读
文章标签:云原生容器运行时虚拟化集群管理存储网络后端CLI运维

Incus 存储、内存与网络限制的单位解析指南:十进制与二进制后缀的完整用法

导读

在 Incus 中配置实例的 CPU、内存、磁盘和网络带宽限制时,几乎所有表示字节或比特的数值都可以附带后缀单位,从而让限制值一目了然。本文以 doc/reference/instance_units.md 为核心,系统梳理 Incus 支持的十进制(SI)与二进制(kibi/IEC)单位全集、各自的适用场景与推荐用法,并结合 shared/units/units.go 中的解析实现,讲解这些单位在 limits.memory、网络 limits.ingress/egress、存储池 size 等配置项中是如何被校验与换算的。读完本文,你将能在创建实例、配置网卡限速、规划存储池时准确写出不会引发歧义的大小值,并理解单位误用可能带来的实际后果。

一、为什么 Incus 需要一套统一的单位系统

实例的资源限制(resource limits)散落在多个配置键上,例如:

这些配置横跨字节(byte,用于内存和磁盘)与比特(bit,用于网络带宽)两类量纲。如果不统一后缀规则,1G 到底代表 1000³ 还是 1024³ 就会产生歧义——这正是 SI 十进制单位与 IEC 二进制单位并存的根源。Incus 的选择是:两种进制体系都支持,但区分使用场景,并依靠同一套解析函数在服务端进行严格校验,任何无法识别的后缀都会被直接拒绝。

二、网络限制支持的比特(bit)后缀全集

任何表示比特(bits)的值都可以使用下列后缀。网络限速配置(例如 incus config device override 中的 limits.ingress、limits.egress 以及网卡的 limits.max)通常采用这些单位。

后缀 数值
bit 1
kbit 1000
Mbit 1000²(1,000,000)
Gbit 1000³
Tbit 1000⁴
Pbit 1000⁵
Ebit 1000⁶
Kibit 1024
Mibit 1024²(1,048,576)
Gibit 1024³
Tibit 1024⁴
Pibit 1024⁵
Eibit 1024⁶

这些后缀在源码中由 shared/units/units.go 的 ParseBitSizeString 逐一匹配:"kbit" 对应乘数 1000,"Mbit" 对应 1000×1000,"Kibit" 对应 1024,"Mibit" 对应 1024×1024,依此类推。同时该函数也接受裸数值(空后缀),此时乘数为 1,即直接以 bit 为单位。

网络限速的实际解析路径

在服务端,网卡设备的速率限制由 nicParseLimits 统一解析,见 internal/server/device/device_utils_network.go。该函数对 limits.ingress、limits.egress、limits.ingress.burst、limits.egress.burst、limits.ingress.bucket、limits.egress.bucket 等键逐一调用 units.ParseBitSizeString:

// parseValue parses a single bit or bit/s value, the max key taking precedence over the per-direction one.
parseValue := func(key string, maxKey string) (int64, error) {
    value := config[key]

    if config[maxKey] != "" {
        key = maxKey
        value = config[maxKey]
    }

    if value == "" {
        return 0, nil
    }

    size, err := units.ParseBitSizeString(value)
    if err != nil {
        return -1, fmt.Errorf("Invalid %s value %q: %w", key, value, err)
    }

    return size, nil
}

由此可以看出两个细节:

  1. 解析失败会直接报错,配置不会静默生效;
  2. limits.max 优先于分方向的 limits.ingress / limits.egress,当 limits.max 存在时,它同时覆盖双向限速。

因此,在配置网卡限速时,例如将下行带宽限制为 1 Gbit/s,可以写作 limits.ingress=1Gbit;如果希望同时约束双向,则直接设置 limits.max=1Gbit。

三、存储与内存限制支持的字节(byte)后缀全集

任何表示字节(bytes)的值都可以使用下列后缀。内存限制(limits.memory)与磁盘限制(存储池/存储卷的 size、实例的根磁盘 size 等)主要采用这套单位体系。

后缀 数值
B 或 bytes 1
kB 1000
MB 1000²
GB 1000³
TB 1000⁴
PB 1000⁵
EB 1000⁶
KiB 1024
MiB 1024²
GiB 1024³
TiB 1024⁴
PiB 1024⁵
EiB 1024⁶

源码实现同样在 shared/units/units.go 的 ParseByteSizeString 中:case "", "B", " bytes": 乘数为 1;"kB"、"MB"、"GB"、"TB"、"PB"、"EB" 分别对应 1000 的 1~6 次幂;"KiB"、"MiB"、"GiB"、"TiB"、"PiB"、"EiB" 分别对应 1024 的 1~6 次幂。值得注意的兼容细节是:后缀可以写作 B,也可以写作带前导空格的 bytes,即 1 bytes 与 1B 等价。

溢出保护:数值乘法的安全性

两个解析函数最终都会调用 shared/units/units.go 的 handleOverflow,在乘法溢出时返回错误而非静默截断:

func handleOverflow(val int64, mult int64) (int64, error) {
	result := val * mult
	if val == 0 || mult == 0 || val == 1 || mult == 1 {
		return result, nil
	}

	if val != 0 && (result/val) != mult {
		return -1, fmt.Errorf("Overflow multiplying %d with %d", val, mult)
	}

	return result, nil
}

例如 1EiB 换算为 1024⁶ 字节,已经非常接近 int64 的上限,超出范围的大数会被明确拒绝,避免了在底层驱动中出现回绕导致配额错误。

四、最常用单位与选择建议

原文档 doc/reference/instance_units.md 明确给出了实践中最高频的三种组合,这也是绝大多数 Incus 部署的实际做法:

场景 推荐单位
网络限制 kbit / Mbit / Gbit
内存与大多数磁盘限制 MiB / GiB / TiB
部分磁盘限制(机械硬盘时代遗留) MB / GB / TB

选择建议背后的原因:

  • 网络带宽本身是十进制概念(运营商速率、网卡标称均以 10³ 进制标注),因此使用 kbit/Mbit/Gbit 与常识一致;
  • 内存在硬件与操作系统层面以 1024 为进制(如 1 GiB = 1024 MiB),limits.memory 的默认值在源码注释中即为 1GiB(虚拟机的默认值,见 internal/instance/config.go),因此 MiB/GiB/TiB 是内存配置的绝对主流;
  • 磁盘领域两者并存:MiB/GiB/TiB 用于绝大多数逻辑卷/文件系统场景,而 MB/GB/TB 仍保留在部分偏向传统磁盘容量的配置路径中。

五、内存限制中的百分比与单位校验

limits.memory 在 internal/instance/config.go 中的校验逻辑除了字节单位外,还额外支持百分比形式——以 % 结尾的值表示占宿主机内存的比例:

"limits.memory": func(value string) error {
	if value == "" {
		return nil
	}

	before, ok := strings.CutSuffix(value, "%")
	if ok {
		num, err := strconv.ParseInt(before, 10, 64)
		if err != nil {
			return err
		}

		if num == 0 {
			return errors.New("Memory limit can't be 0%")
		}

		return nil
	}

	num, err := units.ParseByteSizeString(value)
	if err != nil {
		return err
	}

	if num == 0 {
		return errors.New("Memory limit can't be 0")
	}

	return nil
},

可见两条规则:

  1. 以 % 结尾的值按百分比解析,且不允许为 0%;
  2. 其他值交给 ParseByteSizeString 按字节单位解析,且不允许换算结果为 0(例如裸写 0 会被拒绝)。

因此下面这些写法都是合法的:

# 内存限制:固定值(推荐 MiB/GiB/TiB 体系)
incus config set <instance> limits.memory 2GiB

# 内存限制:占宿主机内存百分比
incus config set <instance> limits.memory 25%

# 内存限制:十进制单位同样可用(1GB = 1000³ 字节,与 1GiB 有约 7.3% 的差异)
incus config set <instance> limits.memory 1GB

六、存储池与存储卷中的单位换算

存储层的 size 配置同样依赖 ParseByteSizeString,这在各存储驱动中得到了普遍使用,例如:

此外,存储卷创建与扩容(incus storage volume create、incus storage volume resize)也会经过 ParseByteSizeString,例如 Ceph 卷的扩容路径 driver_ceph_volumes.go、TrueNAS 卷的块大小解析 driver_truenas_volumes.go。

实操示例:

# 创建 50GiB 的存储池
incus storage create mypool btrfs size=50GiB

# 创建一个 10GiB 的存储卷
incus storage volume create mypool vol1 size=10GiB

# 将存储卷扩容到 20GiB
incus storage volume resize mypool vol1 20GiB

对于存储场景,建议优先使用 GiB/TiB 等 IEC 单位:文件系统、卷管理器和绝大多数后端驱动都以 1024 进制计算容量,使用 GB 声明 10GB 实际得到的字节数会少于多数人预期的 10GiB。

七、显示端:如何把字节数格式化回人类可读单位

单位系统不仅用于解析用户输入,也用于输出格式化。incus list 等命令在展示内存与磁盘使用量时,调用的是 shared/units/units.go 的 GetByteSizeStringIEC,例如 cmd/incus/list.go 中:

return units.GetByteSizeStringIEC(cInfo.State.Memory.Usage, 2)
// GetByteSizeStringIEC takes a number of bytes and precision and returns a
// human representation of the amount of data using IEC units.
func GetByteSizeStringIEC(input int64, precision uint) string {
	if input < 1024 {
		return fmt.Sprintf("%dB", input)
	}

	value := float64(input)

	for _, unit := range []string{"KiB", "MiB", "GiB", "TiB", "PiB", "EiB"} {
		value = value / 1024
		if value < 1024 {
			return fmt.Sprintf("%.*f%s", precision, value, unit)
		}
	}

	return fmt.Sprintf("%.*fEB", precision, value)
}

对应的还有十进制版本的 GetByteSizeString(shared/units/units.go),按 1000 进制逐级换算。incus list 的磁盘使用量展示同样使用 IEC 格式化(cmd/incus/list.go)。这意味着:输入端按文档后缀自由解析,输出端统一以 IEC 单位呈现,用户看到 incus list 中约 1.50GiB 的内存占用时,对应的正是配置中 limits.memory 换算出的精确字节数。

八、单位使用注意事项与常见误区

综合原文档与源码实现,实际使用中有几个高频易错点:

  1. G 与 GiB、GB 的区别:Incus 的解析器要求完整后缀,1G 这类不完整写法无法匹配任何 case,会触发 Invalid value / Unsupported suffix 错误。务必写全 1GB、1GiB、1Gbit 等。

  2. 大小写敏感:后缀区分大小写。kb、mb、gib 等小写变体均不被接受(kB、MB、GiB 才是合法形式)。错误后缀会在配置校验阶段直接返回错误,例如 ParseByteSizeString 对无法识别的后缀返回 Invalid value: ...,ParseBitSizeString 返回 Unsupported suffix: ...。

  3. 十进制与二进制不要混用比较:1000MB(10⁹ 字节)与 1GiB(约 1.074×10⁹ 字节)并不相等,相差约 7.3%。在跨工具比对容量(例如与 df -h、lsblk 的输出核对)时,务必先确认对方的进制口径。

  4. bit 与 byte 不能互换:网络限速使用 bit 体系,存储/内存使用 byte 体系。1Mbit 表示 10⁶ 比特(约 0.125 兆字节),而 1MB 表示 10⁶ 字节;若在网卡限速中误写 limits.ingress=1MB,实际带宽会远超预期。解析函数按配置类别分开调用(网卡走 ParseBitSizeString,存储/内存走 ParseByteSizeString),但不会替你做量纲转换。

  5. 单位前后是否带空格:数值与后缀之间不要加空格,2 GiB 这类写法会因数字部分无法完整解析而被拒绝;唯一例外是 bytes 后缀本身允许带一个前导空格(case " bytes"),但这属于兼容旧格式的保留行为,新配置仍建议使用 B。

  6. 裸数值的含义:不带任何后缀时,按对应体系的最小单位处理——内存/存储配置的裸数字按字节计,网络限速配置的裸数字按比特计。

结语

Incus 的单位系统设计兼顾了两套行业标准:网络限速遵循十进制 bit 体系,内存与磁盘遵循以 MiB/GiB/TiB 为主、MB/GB/TB 为辅的字节体系。所有解析与格式化逻辑统一收敛在 shared/units/units.go 中,并在内存校验(internal/instance/config.go)、网卡限速(internal/server/device/device_utils_network.go)与各存储驱动(internal/server/storage/drivers)中被反复调用。掌握这些后缀的精确含义与适用边界,既能避免配置被服务端拒绝的返工,也能防止因进制混淆导致的配额偏差。最稳妥的实践是:网络用 Mbit/Gbit,内存用 MiB/GiB/TiB,磁盘按后端类型在 IEC 与 SI 之间明确选择并保持一致。

登录后查看全文
incus