Incus 安装及使用

2026 年 5 月 31 日

安装#

安装 lxc 容器：

# emerge --ask app-containers/lxc

安装 incus 管理器：

# emerge --ask app-containers/incus

添加用户到 incus 组：

# usermod --append --groups incus king

配置 idmaps：

# echo "root:1000000:1000000000" | tee -a /etc/subuid /etc/subgid

若不配置 idmaps，普通用户执行 incus 命令报错：Get "http://unix.socket/1.0?project=user-1000": read unix @->/var/lib/incus/unix.socket.user: read: connection reset by peer。

OpenRC 启动 incus：

# rc-update add incus default         系统级守护进程
# rc-update add incus-user default    用户级守护进程，普通用户执行 incus 命令

# rc-service incus start
# rc-service incus-user start

OpenRC 开机启动 incus-user 失败，开机后执行 sudo rc-service incus-user restart 能成功启动。
解决办法：编辑 /etc/init.d/incus-user，在 start() 中添加 sleep 2 。

Incus 首次使用需初始化（交互式配置存储、网络等）：

# incus admin init

也可使用最小的默认配置 incus admin init --minimal 来跳过交互步骤。

镜像#

远程镜像#

列出所有服务器：

$ incus remote list
|      NAME       |                URL                 |   PROTOCOL    |  AUTH TYPE  | PUBLIC | STATIC | GLOBAL |
| images          | https://images.linuxcontainers.org | simplestreams | none        | YES    | NO     | NO     |
| local (current) | unix://                            | incus         | file access | NO     | YES    | NO     |

images 为默认的公共镜像服务器，由社区或官方维护。
local 为本地的镜像服务器，包含已下载并缓存的镜像、已创建的实例等。

添加 Simple Streams 镜像服务器：

$ incus remote add <自定义名称> <镜像站URL> --protocol=simplestreams

添加清华大学镜像服务器：

$ incus remote add tuna https://mirrors.tuna.tsinghua.edu.cn/lxc-images/ --protocol=simplestreams --public

命令	说明
`incus remote list`	列出所有远程服务器。
`incus remote add <服务器名称> <地址>`	添加一个新的远程服务器。
`incus remote remove <服务器名称>`	移除一个已配置的远程服务器。
`incus remote switch <服务器名称>`	切换当前默认的远程服务器。
`incus remote get-default`	查看当前默认的远程服务器名称。
`incus remote set-url <服务器名称> <新地址>`	修改指定服务器的 URL 地址。
`incus remote rename <旧名称> <新名称>`	重命名服务器。

镜像管理#

查看镜像服务器上的所有镜像

$ incus image list <服务器名称>:
|         ALIAS          | FINGERPRINT  | PUBLIC |     DESCRIPTION      | ARCHITECTURE |      TYPE       |   SIZE    |
| debian/13/cloud        | c54b95d46de6 | yes    | Debian trixie amd64  | x86_64       | VIRTUAL-MACHINE | 340.82MiB |

镜像 TYPE 类型：

CONTAINER：与宿主机共享内核，利用 Linux 内核的命名空间和 Cgroups 进行软件隔离。
VIRTUAL-MACHINE：独立的内核，借助 QEMU 进行硬件虚拟化。

筛选镜像，过滤词用于匹配 ALIAS 和 FINGERPRINT 属性中的内容（多个词用空格分隔）：

$ incus image list <服务器名称>: [过滤词]

$ incus image list images: debian/13
$ incus image list images: c54b95d46de6
$ incus image list images: debian/13 amd64

按其它属性筛选，使用 <键>=<键值> 的形式（必须小写）：

$ incus image list images: debian/13 architecture=x86_64 type=container

引用镜像

使用 <服务器>:<别名|指纹>，冒号后不要加空格：

$ incus launch images:debian/13 my-debian
$ incus launch images:c54b95d46de6 my-debian

导出 / 导入镜像

导出容器镜像文件，会生成 .tar.xz 元数据文件和 .squashfs 根文件系统文件：

$ incus image export [<服务器>:]<镜像> [<输出目录>]

如果要导出虚拟机镜像文件，添加 --vm 参数，会生成 .tar.xz 元数据文件和 .qcow2 磁盘镜像文件。

导入镜像文件（如果存在指纹相同的镜像将无法导入）：

$ incus image import <元数据文件> <根文件系统文件> [<目标服务器>:] --alias <别名>

命令	说明
`incus image list [<服务器>:] [过滤词...]`	列出镜像。
`incus image info <镜像>`	显示镜像的详细元数据。
`incus image show <镜像>`	显示镜像的完整属性配置（YAML 格式）。
`incus image get-property <镜像> <键>`	获取单项属性。
`incus image set-property <镜像> <键> <键值>`	设置单项属性。
`incus image unset-property <镜像> <键>`	删除单项属性。
`incus image edit <镜像>`	编辑完整属性。
`incus image delete <镜像>`	删除镜像。
`incus image alias create <别名> <指纹>`	为指纹创建别名。
`incus image copy [<源服务器>:]<镜像> [<目标服务器>:]`	在不同远程服务器之间直接复制镜像。
`incus image refresh [<服务器>:]<镜像>`	强制检查并更新本地缓存的远程镜像。

实例#

Incus 支持以下类型的实例：

系统容器。
应用程序容器（OCI 镜像，如 Dockerhub 上的镜像）。
虚拟机。

管理实例#

创建实例

$ incus launch <选项> <服务器>:<镜像> <实例名称>

选项	说明
`--vm`	创建虚拟机而不是容器。
`-c`	配置实例选项，如 `-c limits.cpu=2 -c limits.memory=4GiB`。
`-p`	指定配置文件，如 `-p profile1 -p profile2`。
`-d`	用于覆盖配置文件中的设备选项，如 `--device root,size=30GiB`。
`-e`	容器停止后自动删除。
`--console`	启动后马上连接到控制台。

列出实例

$ incus list

显示实例信息 / 日志

$ incus info <实例名称>
$ incus info <实例名称> --show-log

启动 / 停止实例

$ incus start <实例名称>
$ incus stop <实例名称>

删除实例

$ incus delete <实例名称>

重建实例

如果想擦除和重新初始化实例的根磁盘，但保留实例配置，可以重建实例。

使用不同的镜像重建实例：

$ incus rebuild <镜像名称> <实例名称>

清空根磁盘重建实例：

$ incus rebuild <实例名称> --empty

Config 实例配置#

查看实例配置

$ incus config show <实例名称> --expanded
architecture: x86_64                     [属性]
config:
  limits.memory: 2GiB                    [选项]
  security.privileged: "true"            [选项]
description: My first container          [属性]
name: my-container                       [属性]

配置实例选项

$ incus config set <实例名称> <键>=<键值>
$ incus config unset <实例名称> <键>

例如：

$ incus config set my-container limits.memory=8GiB

可配置的键参考Instance options。

配置实例属性

$ incus config set <实例名称> <键>=<键值> --property
$ incus config unset <实例名称> <键> --property

参考Instance properties。

配置设备

所有的设备类型参考Devices。

添加磁盘设备：

$ incus config device add <实例名称> <设备名称> disk source=<主机路径> path=<容器内路径>

配置磁盘设备（参考Disk device options）：

$ incus config device set <实例名称> <设备名称> <键>=<键值>

编辑完整实例配置

$ incus config edit <实例名称>

Profile 配置文件#

查看配置文件

$ incus profile list
$ incus profile show <配置名称>

Profile 与 Config 的区别：Profile 是可以复用的配置模板，Config 是单个实例的专属配置。

将配置文件应用于实例

$ incus profile add <实例名称> <配置文件名称>

运行命令#

在实例内部运行命令：

$ incus exec <实例名称> <选项> -- <命令>

选项	说明
`--env`	传递环境变量，例如 `incus exec debian --env MY_VAR="hello" -- env` 。
`--cwd`	指定工作目录，例如 `incus exec debian --cwd=/usr -- ls -l` 。
`--user`	指定用户 ID，例如 `incus exec debian --user=0 -- whoami` 。
`--group`	指定组 ID。
`-t`	强制分配伪终端（模拟真实登录环境），适用于交互式程序（top, vim, bash）。
`-T`	强制非交互模式（纯文本管道模式），适用于自动化脚本、管道输入 / 输出。

访问控制台#

$ incus console <实例名称>
To detach from the console, press: <ctrl>+a q
root
Password: 
...
Linux debian 6.18.33-gentoo-r1 ...
...
root@debian:~#

要显示 console 日志输出，添加 --show-log 选项：

$ incus restart debian
$ incus console debian --show-log
Queued start job for default target graphical.target.
[  OK  ] Created slice system-getty.slice - Slice /system/getty.
[  OK  ] Created slice system-modprobe.slice - Slice /system/modprobe.
[  OK  ] Created slice user.slice - User and Session Slice.
[  OK  ] Started systemd-ask-password-console.path - Dispatch Password Requests to Console Directory Watch.
...

访问图形控制台（适用于虚拟机）：

$ incus console <实例名称> --type vga

启动具有图形输出的 VGA 控制台，必须安装 SPICE 客户端。Incus 支持两个常见的客户端 remote-viewer 和 spicy。

在实例启动时立即连接到控制台：

$ incus start <实例名称> --console
$ incus start <实例名称> --console=vga

访问文件#

命令	说明
`incus file edit <实例名称>/<实例内文件路径>`	从本地机器编辑实例中的文件。
`incus file delete <实例名称>/<实例内文件路径>`	从实例中删除文件。
`incus file pull <实例名称>/<实例内文件路径> <本地文件路径>`	从实例中拉取文件到本地机器，选项 `-r` 拉取目录。
`incus file pull <实例名称>/<实例内文件路径> -`	将实例中的文件拉取到标准输出，效果等同 `cat 文件`。
`incus file push <本地文件路径> <实例名称>/<实例内文件路径>`	将文件从本地机器推送到实例，选项 `-r` 推送目录。
`incus file mount <实例名称>/<实例内路径> <本地路径>`	将实例文件系统挂载到本地机器上的路径，依赖 `sshfs`。

对于虚拟机，必须在虚拟机内部运行 incus-agent 进程才能使以上命令工作。

网络#

创建网桥（选项参考nic configuration options）：

# incus network create <网络名称> --type=bridge [选项]

设置网桥静态 IP：

# incus network set <网络名称> ipv4.address=192.168.20.1/24 ipv4.nat=true

设置实例中的 nic 设备为静态 IP：

$ incus config device override <实例名称> eth0 ipv4.address=192.168.20.100

执行 incus config edit <实例名称> 查看实例设备：
若 device 中不含 nic 设备，则实例的 nic 设备从 profile 继承而来，使用 incus config device override。
若 device 中包含 nic 设备，使用 incus config device set。

项目#

Project 用于逻辑隔离，相当于将整个 Incus 服务器划分为多个独立的、互不干扰的 “工作区”。

用户可以为不同的 Project 配置特性，参考Project configuration。

存储#

存储池：每个存储池使用一个存储驱动（如 dir、zfs、lvm）。所有卷和桶都存在于某个池中。
存储卷：存储池中的结构化存储单元，例如作为实例的根磁盘，或作为额外磁盘挂载到实例上。
存储桶：是一种对象存储，不附加到实例，应用通过网络和 S3 协议直接访问。

管理存储卷#

存储卷有以下内容类型：
- filesystem：可以附加到容器和虚拟机，并且可以在实例之间共享。
- block：只能附加到虚拟机（作为 /dev 下的块设备）。不能在实例之间共享。
- iso：只能通过 incus import 导入 ISO 文件来创建。只能附加到虚拟机（可多台），始终只读。

filesystem 内容类型	说明
`incus storage volume create <存储池> <卷名> [键=键值]`	创建卷
`incus storage volume attach <存储池> <卷名> <实例名称> [<实例配置内的设备名>] <实例内路径>`	将卷附加到实例
`incus storage volume detach <存储池> <卷名> <实例名称>`	将卷从实例中移除

block 内容类型
`incus storage volume create <存储池> <卷名> --type=block [键=键值]`	创建卷
`incus storage volume attach <存储池> <卷名> <实例名称>`	将卷附加到实例

iso 内容类型
`incus storage volume import <存储池> <iso文件路径> <卷名> --type=iso`	创建卷

对于 [键=键值] 不同的驱动有不同的配置选项，参考Storage drivers。

其它#

命令帮助#

直接执行 incus 或其子命令如 incus images --help 即可查看该命令的用法。

禁止实例自动启动#

boot.autorestart 是否在实例意外退出时自动重启。
boot.autostart 是否在守护进程启动时始终启动实例。

设置指定实例：

$ incus config set <实例名称> boot.autostart=false

或者设置全局配置文件：

$ incus profile set <配置名称> boot.autostart=false