镜像格式¶

镜像包含一个根文件系统和一个描述镜像的元数据文件。它们还可以包含用于在使用该镜像的实例中创建文件的模板。

镜像可以打包为统一镜像（单个文件）或拆分镜像（两个文件）。

内容¶

容器的镜像具有以下目录结构

metadata.yaml
rootfs/
templates/

虚拟机的镜像具有以下目录结构

metadata.yaml
rootfs.img
templates/

对于这两种实例类型，templates/ 目录是可选的。

元数据¶

metadata.yaml 文件包含与在 Incus 中运行镜像相关的信息。它包含以下信息

architecture: x86_64
creation_date: 1424284563
properties:
  description: Ubuntu 22.04 LTS Intel 64bit
  os: Ubuntu
  release: jammy 22.04
templates:
  ...

architecture 和 creation_date 字段是必需的。 properties 字段包含一组镜像的默认属性。 os、release、name 和 description 字段是常用的，但不是必需的。

templates 字段是可选的。有关如何配置模板的信息，请参阅模板（可选）。

根文件系统¶

对于容器，rootfs/ 目录包含容器中根目录（/）的完整文件系统树。

虚拟机使用 rootfs.img qcow2 文件而不是 rootfs/ 目录。该文件将成为主磁盘设备。

模板（可选）¶

您可以使用模板动态地在实例内部创建文件。为此，请在 metadata.yaml 文件中配置模板规则，并将模板文件放在 templates/ 目录中。

一般来说，您永远不应该模板由包拥有的文件，也不应该模板在实例正常操作期间预计将被覆盖的文件。

模板规则¶

对于每个应该生成的文件，请在 metadata.yaml 文件中创建一个规则。例如

templates:
  /etc/hosts:
    when:
      - create
      - rename
    template: hosts.tpl
    properties:
      foo: bar
  /etc/hostname:
    when:
      - start
    template: hostname.tpl
  /etc/network/interfaces:
    when:
      - create
    template: interfaces.tpl
    create_only: true
  /home/foo/setup.sh:
    when:
      - create
    template: setup.sh.tpl
    create_only: true
    uid: 1000
    gid: 1000
    mode: 755

when 键可以是以下一个或多个

create - 在从镜像创建新实例时运行
copy - 在从现有实例创建实例时运行
start - 在每次实例启动时运行

template 键指向 templates/ 目录中的模板文件。

您可以通过 properties 键将用户定义的模板属性传递给模板文件。

如果您希望 Incus 创建不存在的文件，但不要覆盖现有文件，请设置 create_only 键。

uid、gid 和 mode 键可用于控制文件所有权和权限。

模板文件¶

模板文件使用 Pongo2 格式。

它们始终接收以下上下文

变量	类型	描述
`trigger`	`string`	触发模板的事件名称
`path`	`string`	使用模板的文件的路径
`instance`	`map[string]string`	实例属性的键值映射（名称、架构、特权和短暂）
`config`	`map[string]string`	实例配置的键值映射
`devices`	`map[string]map[string]string`	分配给实例的设备的键值映射
`properties`	`map[string]string`	在 `metadata.yaml` 中指定的模板属性的键值映射

为了方便起见，以下函数导出到 Pongo2 模板

config_get("user.foo", "bar") - 返回 user.foo 的值，如果未设置则返回 "bar"。

镜像压缩包¶

Incus 支持两种 Incus 特定的镜像格式：统一压缩包和拆分压缩包。

这些压缩包可以被压缩。 Incus 支持压缩包的多种压缩算法。但是，为了兼容性，您应该使用 gzip 或 xz。

统一压缩包¶

统一压缩包是一个包含镜像全部内容的单个压缩包（通常为 *.tar.xz），包括元数据、根文件系统和可选的模板文件。

这是 Incus 本身在发布镜像时使用的格式。它通常更容易使用；因此，在创建 Incus 特定的镜像时，您应该使用统一格式。

此类镜像的镜像标识符是压缩包的 SHA-256。

分割压缩包¶

分割镜像由两个文件组成。第一个是包含元数据和可选模板文件（通常为 *.tar.xz）的压缩包。第二个可以是包含实际实例数据的压缩包、squashfs 或 qcow2 镜像。

对于容器，第二个文件最常见的是 SquashFS 格式的文件系统树，但也可以是相同树的压缩包。对于虚拟机，第二个文件始终是 qcow2 格式的磁盘镜像。

压缩包可以进行外部压缩（.tar.xz、.tar.gz 等），而 squashfs 和 qcow2 可以通过各自的原生压缩选项进行内部压缩。

这种格式旨在方便从已有的非 Incus 根文件系统压缩包构建镜像，这些压缩包已经存在。如果您想创建可被 Incus 和其他工具使用的镜像，也应该使用这种格式。

此类镜像的镜像标识符是元数据文件和数据文件（按此顺序）连接后的 SHA-256 哈希值。