Incus 存储、内存与网络限制的单位解析指南:十进制与二进制后缀的完整用法
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)散落在多个配置键上,例如:
limits.memory:内存限制,见 internal/instance/config.go;limits.cpu:CPU 数量或拓扑,见 internal/instance/config.go;- 网络设备的
limits.ingress/limits.egress/limits.max等速率限制; - 存储池与存储卷的
size配置。
这些配置横跨字节(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
}
由此可以看出两个细节:
- 解析失败会直接报错,配置不会静默生效;
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
},
可见两条规则:
- 以
%结尾的值按百分比解析,且不允许为0%; - 其他值交给
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,这在各存储驱动中得到了普遍使用,例如:
- Btrfs:driver_btrfs.go 中
size, err := units.ParseByteSizeString(d.config["size"]); - LVM:driver_lvm.go 中同样的解析模式;
- ZFS:driver_zfs.go 解析
d.config["size"]; - Ceph:driver_ceph.go 除池大小外,还用它解析
ceph.osd.pg_num等参数。
此外,存储卷创建与扩容(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 换算出的精确字节数。
八、单位使用注意事项与常见误区
综合原文档与源码实现,实际使用中有几个高频易错点:
-
G与GiB、GB的区别:Incus 的解析器要求完整后缀,1G这类不完整写法无法匹配任何case,会触发Invalid value/Unsupported suffix错误。务必写全1GB、1GiB、1Gbit等。 -
大小写敏感:后缀区分大小写。
kb、mb、gib等小写变体均不被接受(kB、MB、GiB才是合法形式)。错误后缀会在配置校验阶段直接返回错误,例如ParseByteSizeString对无法识别的后缀返回Invalid value: ...,ParseBitSizeString返回Unsupported suffix: ...。 -
十进制与二进制不要混用比较:
1000MB(10⁹ 字节)与1GiB(约 1.074×10⁹ 字节)并不相等,相差约 7.3%。在跨工具比对容量(例如与df -h、lsblk的输出核对)时,务必先确认对方的进制口径。 -
bit 与 byte 不能互换:网络限速使用
bit体系,存储/内存使用byte体系。1Mbit表示 10⁶ 比特(约 0.125 兆字节),而1MB表示 10⁶ 字节;若在网卡限速中误写limits.ingress=1MB,实际带宽会远超预期。解析函数按配置类别分开调用(网卡走ParseBitSizeString,存储/内存走ParseByteSizeString),但不会替你做量纲转换。 -
单位前后是否带空格:数值与后缀之间不要加空格,
2 GiB这类写法会因数字部分无法完整解析而被拒绝;唯一例外是bytes后缀本身允许带一个前导空格(case " bytes"),但这属于兼容旧格式的保留行为,新配置仍建议使用B。 -
裸数值的含义:不带任何后缀时,按对应体系的最小单位处理——内存/存储配置的裸数字按字节计,网络限速配置的裸数字按比特计。
结语
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 之间明确选择并保持一致。