OFFSET偏移
中EN
← 文章目录OFFSET / FIELD NOTESNO. 131
SYSTEMS / INFRASTRUCTURE技术笔记整理

Distrobox 声明式清单与高级工作流

保留 assemble、GPU、多容器协作及平台实践，并区分清单和服务管理契约。

容器与基础设施Linux容器Distrobox
所在专题Distrobox：用户空间、桌面集成与可恢复环境 ↗
约 42 分钟阅读开始阅读

本文的命令接口按 Distrobox 1.8.2.5 官方脚本核对；镜像标签与发行版包名是示例，使用前确认镜像仍受支持、仓库可用及本机实际版本。示例未做运行验证。

本文定位 本篇覆盖 Distrobox 的高级工作流：声明式批量管理、init 容器运行 systemd 服务、GPU 加速与硬件直通、多容器协作架构，以及桌面环境 / 虚拟化 / ChromeOS 等特殊场景。适合已经熟悉基本 distrobox-create / distrobox-enter 操作的读者。

1. distrobox-assemble：声明式容器管理#

distrobox-assemble 相当于 Docker Compose 之于 Docker，允许你通过一个 INI 格式的 manifest 文件批量创建/销毁容器。manifest 默认路径为当前工作目录的 ./distrobox.ini；用户配置目录的文件要用 --file 指定，也支持本地自定义路径或远程 URL。

1.1 Manifest 全字段示例

# ~/.config/distrobox/distrobox.ini

[dev]
image=archlinux:latest
pull=true
init=false
entry=true
start_now=false
additional_packages="base-devel git neovim zsh bat ripgrep"
hostname="arch-dev"
exported_bins="/usr/bin/nvim"
exported_bins="/usr/bin/bat"
exported_bins="/usr/bin/rg"

[server]
image=ubuntu:22.04
pull=true
init=true
entry=false
start_now=false
additional_packages="nginx certbot python3-certbot-nginx postgresql systemd"
init_hooks="systemctl enable nginx && systemctl enable postgresql"
volume="/opt/data:/data"

[llvm-toolchain]
image=registry.fedoraproject.org/fedora:41
pull=false
init=false
additional_packages="clang lldb llvm cmake ninja-build gdb"

[cuda-dev]
image=nvidia/cuda:12.0-devel-ubuntu22.04
pull=false
init=false
nvidia=true
additional_packages="python3 python3-pip cmake"
hostname="cuda-box"

[libvirt-host]
image=registry.opensuse.org/opensuse/distrobox:latest
pull=true
init=true
root=true
unshare_all=true
additional_flags="-p 2222:22"
exported_apps="virt-manager"

1.2 Manifest 字段速查表

类型说明：

  • bool：true 或 false
  • string：单行字符串，如 home="/home/user/dbox"
  • string_list：空格分隔的多个字符串，如 additional_packages="htop vim git"。可多次声明自动叠加：
[ubuntu]
additional_packages="git vim tmux"
additional_packages="htop iftop iotop"   # 自动合并
字段 类型 说明
image string OCI 镜像地址（必填）
pull bool 每次 create 前强制拉取最新镜像（默认 false）
init bool 启用 init 系统（systemd / OpenRC）
entry bool 自动生成 desktop entry（应用启动器）
root bool 以 rootful 模式运行容器
start_now bool 创建后立即启动容器
replace bool 强制替换同名容器
clone string 复制已有容器的文件系统状态
include string 继承另一个 manifest entry 的属性
additional_packages string_list 空格分隔的额外安装包
additional_flags string_list 传给底层容器引擎的额外 flag
init_hooks string_list 容器初始化后执行的 shell 命令（按 && 串联）
pre_init_hooks string_list 初始化前执行的命令
home string 自定义 HOME 目录路径
hostname string 设置容器 hostname
volume string_list 额外 volume 挂载（host_path:guest_path）
exported_apps string_list 自动导出桌面应用
exported_bins string_list 自动导出二进制
exported_bins_path string 导出二进制存放路径（默认 $HOME/.local/bin）
nvidia bool 启用 NVIDIA GPU 支持
unshare_all bool 启用支持的 unshare 选项（设备/sysfs、附加组、IPC、网络、进程）；不是撤销所有挂载
unshare_netns bool 仅解绑网络 namespace
unshare_devsys bool 仅解绑 /dev
unshare_ipc bool 仅解绑 IPC namespace
unshare_process bool 仅解绑 PID namespace
unshare_groups bool 不共享宿主机附加用户组

1.3 Clone 与 Include 示例

Clone（复制已有、已初始化的容器）：

[ubuntu]
additional_packages="git vim tmux"
image=ubuntu:latest
init=false

[deno_ubuntu]
clone=ubuntu
pre_init_hooks=curl -fsSL https://deno.land/install.sh | sh;

[bun_ubuntu]
clone=ubuntu
pre_init_hooks=curl -fsSL https://bun.sh/install | bash;

pre-init bootstrap 示例会在 guest 初始化早期运行下载脚本；应先审查并固定上游脚本，不能假定所有工具或用户 HOME 已准备好。被 clone 的容器必须已初始化并停止；克隆不是只复制 manifest，也不是跨发行版替换 image 的工具。若要 LLVM Fedora 环境，应直接创建 Fedora 容器，不设置 clone=dev。

Include（继承另一个 entry 的属性）：

[ubuntu]
image=ubuntu:latest
additional_packages="git vim tmux nodejs htop zsh fish"

[ubuntu-nvidia]
include=ubuntu
nvidia=true

include 将被引用 entry 的字段插入当前定义，支持递归并检测循环。重复 key 采用累积处理，不等于常见配置语言的“子项覆盖父项”；list 字段可合并，image/bool 等单值字段应避免重复并检查 dry-run。

自定义登录 Shell：

[ubuntu]
image=ubuntu:latest
pre_init_hooks="export SHELL=/bin/bash;"

1.4 assemble 命令

# 从当前目录 ./distrobox.ini 创建全部容器
distrobox assemble create

# 指定自定义 manifest 文件
distrobox assemble create --file ./my-distrobox.ini

# 从远程 URL 拉取 manifest 并创建（v1.8.0+）
distrobox assemble create --file https://example.com/distrobox.ini

# 只创建 manifest 中名为 "dev" 的容器
distrobox assemble create --name dev

# 预览模式：只打印将要执行的操作，不实际执行
distrobox assemble create --dry-run

# 强制替换已存在的同名容器
distrobox assemble create --replace

# 删除 manifest 中定义的全部容器
distrobox assemble rm

# 列出 manifest 中定义的容器及其当前状态
distrobox list

多个 exported_bins 可以用官方文档支持的空格列表或重复字段，重复写法便于逐项审查。这里不沿用未经证实的“1.16.x 多路径 bug”说法：

exported_bins="/usr/bin/typst"
exported_bins="/usr/bin/julia"

导出需要初始化后的容器内存在相应程序。exported_services 不是支持的字段，后台服务需单独管理。

manifest 可版本管理 将 distrobox.ini 放入 dotfiles 仓库，配合 distrobox assemble create --file 可以重建同一份容器意图，但镜像 tag、包仓库与下载脚本会变动。远程 manifest 与 hooks 都是可信代码输入，建议先下载审阅、固定版本后再使用本地 --file。

2. Init 容器：在容器内跑 systemd#

--init flag 在容器内启用一个可工作的 init 系统，使你可以运行需要进程管理、socket 激活、定时任务的长期服务。

2.1 支持的 Init 系统

Init 系统 典型发行版
systemd Ubuntu, Debian, Fedora, Arch, openSUSE 等
OpenRC Alpine Linux

--init 让 guest 内运行其发行版 init 系统，并启用独立进程命名空间；它不只是 OCI 后端 --init 的轻量 reaper。基础镜像可能不含 systemd/OpenRC，需选兼容镜像并安装相应包。第一次初始化完成后再验证 PID 1 与 unit 状态。

2.2 Init Hooks 使用

--init-hooks 中的命令在包安装与用户设置等初始化步骤之后执行；不能据此保证 systemd 已在线。多个命令用 && 串联：

distrobox create --name dbserver --image ubuntu:22.04 --init \
  --additional-packages "postgresql nginx systemd" \
  --init-hooks "systemctl enable postgresql && systemctl enable nginx"

--pre-init-hooks 则在基础包配置之前执行，此时 additional_packages 尚未安装。涉及已安装软件配置文件的工作应放到后面的 init hook，例如：

distrobox create --name webdev --image fedora:41 --init \
  --additional-packages "httpd php php-fpm mariadb-server systemd" \
  --init-hooks "printf 'ServerName localhost\n' >> /etc/httpd/conf/httpd.conf; systemctl enable httpd mariadb"

2.3 让 Init 容器在宿主机启动时自动运行

使用用户级 systemd 服务控制容器启停：

# ~/.config/systemd/user/distrobox-dbserver.service
[Unit]
Description=Distrobox Container: dbserver
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/podman start dbserver
ExecStop=/usr/bin/podman stop dbserver
RemainAfterExit=yes

[Install]
WantedBy=default.target
# 启用服务
systemctl --user enable distrobox-dbserver.service
systemctl --user start distrobox-dbserver.service

Init 容器的限制

  • 部分 systemd 功能（如 PrivateTmp、ProtectSystem）需要额外权限，可能在容器内失败
  • systemctl 操作需要 root 或 --user mode，rootless --init 容器也可用 guest sudo 管理容器内 system services；宿主 user unit 与 guest system unit 是不同层次
  • 某些需要内核模块的 systemd 单元（如 systemd-networkd）通常无法在容器内工作

2.4 典型应用场景

场景 示例
本地 Web 开发栈 nginx + php-fpm + mariadb，全部在一个 init 容器内
CI 模拟环境 GitLab Runner / Jenkins agent 在容器内，通过 systemd 管理
数据库服务 PostgreSQL / MySQL 作为常驻服务，宿主机通过 socket 连接
消息队列 Redis / RabbitMQ 在 init 容器内运行
虚拟化宿主 libvirt/QEMU 在容器内管理虚拟机（见第 5 节）

3. GPU 加速与硬件直通#

3.1 NVIDIA GPU

NVIDIA GPU 直通是 Distrobox 最成熟的 GPU 加速方案，--nvidia 尝试集成宿主驱动；CDI 是另一条路径，需要 NVIDIA Container Toolkit 生成可用 CDI 配置。

# 方式一：使用 --nvidia flag（推荐）
distrobox create --name cuda-dev \
  --image nvidia/cuda:12.0-devel-ubuntu22.04 \
  --nvidia \
  --additional-packages "python3 python3-pip cmake"

# 方式二：通过 --additional-flags 手动指定
distrobox create --name ml-workspace \
  --image pytorch/pytorch:2.0-cuda11.7-cudnn8-devel \
  --additional-flags "--device nvidia.com/gpu=all" \
  --additional-packages "jupyter python3-pip"

验证 GPU 是否可用：

# 进入容器后执行
distrobox enter cuda-dev

# NVIDIA 官方工具
nvidia-smi
# 应显示 GPU 型号、驱动版本、CUDA 版本

# OpenGL 验证
glxinfo | grep "OpenGL renderer"
# 应显示 NVIDIA 相关信息

# CUDA 可用性测试
python3 -c "import torch; print(torch.cuda.is_available())"

NVIDIA 前置条件需要分层验证：宿主驱动正常、容器设备可见、用户空间驱动库匹配、CUDA/框架版本兼容。CDI 示例要求先依照 NVIDIA 官方文档配置 toolkit/CDI；--nvidia 并不普遍以 toolkit 为必需依赖。nvidia-smi 可用也不代表已完成 Torch 计算验证，上面的 Torch 测试还要求先安装兼容的 PyTorch。

3.2 AMD / Intel GPU

AMD 和 Intel GPU 的直通相对简单，因为开源驱动（Mesa）直接通过宿主设备共享到容器：

# AMD ROCm（AI/ML 计算）
distrobox create --name rocm-dev \
  --image rocm/dev-ubuntu-22.04:latest \
  --additional-flags "--device /dev/kfd --device /dev/dri" \
  --additional-packages "rocm-libs miopen-hip rocblas"

# Intel GPU（QSV 编解码 / OpenCL）
distrobox create --name intel-gpu \
  --image ubuntu:22.04 \
  --additional-flags "--device /dev/dri" \
  --additional-packages "intel-media-va-driver intel-opencl-icd"

验证 AMD GPU：

# OpenGL
glxinfo | grep "OpenGL renderer"

# ROCm
rocm-smi
# 应显示 AMD GPU 信息

# Vulkan
vulkaninfo | grep "deviceName"

Wayland / X11 图形加速 Distrobox 默认自动共享宿主机的 Wayland socket ($XDG_RUNTIME_DIR/$WAYLAND_DISPLAY) 和 X11 socket (/tmp/.X11-unix)，因此 socket 集成只解决显示连接；图形加速还需 guest 图形库、设备权限和驱动兼容，ROCm/oneAPI 支持尤其需核对具体硬件。

3.3 GPU 支持对比总览

GPU 厂商 计算加速 图形加速 额外配置
NVIDIA CUDA, cuDNN, TensorRT GLX/EGL（匹配宿主驱动库） --nvidia 或 --device nvidia.com/gpu=all
AMD ROCm, HIP, OpenCL Mesa（自动共享 /dev/dri） 设备权限 + 受支持硬件/ROCm 版本
Intel oneAPI, OpenCL Mesa（自动共享 /dev/dri） 设备权限 + 兼容 oneAPI/OpenCL 运行时

4. 多容器协作模式#

4.1 默认隔离与共享语义

Distrobox 容器的默认行为奠定了协作基础：

资源 默认行为 含义
$HOME 共享（bind mount） 所有容器看到同一份家目录，天然文件共享
网络 共享宿主机网络栈 容器间通过 localhost 直接通信
进程 普通容器默认共享 PID；--init/--unshare-process 独立 ps aux 能看到宿主和所有容器的进程
显示 共享 X11/Wayland socket 任何容器的 GUI 应用可直接显示在宿主桌面
音频 共享 PulseAudio/PipeWire socket 容器应用可直接播放声音

4.2 三种经典协作模式

graph TB
    subgraph Host["宿主机 Host OS"]
        HOME["/home/$USER （共享）"]
        DISPLAY["X11/Wayland Display"]
        NET["Host Network Stack"]
        PULSE["PulseAudio / PipeWire"]
    end

    subgraph Pattern1["模式一：Dev 容器 + Service 容器"]
        DEV["dev-box<br/>Arch Linux<br/>neovim / tmux / git"]
        DB["db-box<br/>Ubuntu 22.04 --init<br/>PostgreSQL :5432<br/>Redis :6379"]
        DEV -->|"localhost:5432"| DB
    end

    subgraph Pattern2["模式二：按发行版分工"]
        AUR["aur-box<br/>Arch Linux<br/>yay / AUR packages"]
        APT["deb-box<br/>Ubuntu<br/>apt packages"]
        COPR["rpm-box<br/>Fedora<br/>copr / dnf packages"]
    end

    subgraph Pattern3["模式三：按项目隔离构建环境"]
        PROJ1["proj-alpha<br/>gcc-12 / cmake-3.25"]
        PROJ2["proj-beta<br/>clang-16 / bazel-6"]
        PROJ3["proj-gamma<br/>rustc-1.78 / cargo"]
    end

    HOME --> DEV
    HOME --> DB
    HOME --> AUR
    HOME --> APT
    HOME --> COPR
    HOME --> PROJ1
    HOME --> PROJ2
    HOME --> PROJ3

    DISPLAY --> DEV
    DISPLAY --> AUR
    DISPLAY --> APT
    DISPLAY --> COPR

    NET --> DEV
    NET --> DB
    NET --> AUR
    NET --> APT
    NET --> COPR
    NET --> PROJ1
    NET --> PROJ2
    NET --> PROJ3

    PULSE --> DEV
    PULSE --> AUR

模式一：Dev 容器 + Service 容器

将一个 init 容器专用于运行后台服务（数据库、缓存、消息队列），另一个容器用于开发编辑，二者通过 localhost 通信：

# 创建服务容器（init，后台运行 PostgreSQL 和 Redis）
distrobox create --name svc-stack --image ubuntu:22.04 --init \
  --additional-packages "postgresql redis-server systemd" \
  --init-hooks "systemctl enable postgresql && systemctl enable redis-server"

# 创建开发容器（轻量，装编辑器/工具链）
distrobox create --name dev-box --image archlinux:latest \
  --additional-packages "neovim git tmux nodejs python"

# 开发时
distrobox enter dev-box
# 在 dev-box 内通过 localhost:5432 连接 svc-stack 的 PostgreSQL
psql -h localhost -U postgres

模式二：按发行版分工

不同发行版擅长的领域不同，可以为每种"包管理器生态"建立独立容器：

# Arch Linux：AUR 天堂
distrobox create --name aur-box --image archlinux:latest \
  --additional-packages "base-devel git"
# 首次进入后，审查 AUR PKGBUILD，以普通 guest 用户构建 yay/paru

# Ubuntu：Deb 生态与企业软件
distrobox create --name deb-box --image ubuntu:22.04 \
  --additional-packages "software-properties-common"

# Fedora：Copr 与前沿 RPM
distrobox create --name rpm-box --image fedora:41 \
  --additional-packages "dnf-plugins-core"

模式三：按项目隔离构建环境

按项目分离包环境可减少版本冲突，但固定版本包必须在所选仓库中实际存在；以下名称与版本表达式仅展示意图，不能保证历史仓库仍提供这些包：

# 项目 A：GCC 12 + CMake 3.25
distrobox create --name proj-alpha --image ubuntu:22.04 \
  --additional-packages "gcc-12 g++-12 cmake=3.25*"

# 项目 B：Clang 16 + Bazel 6
distrobox create --name proj-beta --image fedora:41 \
  --additional-packages "clang16 lld bazel6"

# 项目 C：Rust nightly
distrobox create --name proj-gamma --image archlinux:latest \
  --additional-packages "rustup"
# 进容器后
rustup default nightly

容器间共享环境变量 因为 $HOME 共享，你可以将公共环境变量写入 ~/.profile 或 ~/.bashrc，所有容器都能读取。Distrobox 不会自动把任意 *.conf 当逐容器配置读取；可在 hooks、实际支持的后端参数或 shell 的 CONTAINER_ID 分支中显式设置。

5. 特殊场景#

5.1 在 Distrobox 中运行完整桌面环境（DE）

可以在容器中运行最新的 GNOME / KDE Plasma / Hyprland，以 display manager 会话的方式登录：

# 创建 init 容器（必须有 systemd）
distrobox create --name fedora-rawhide \
  --init \
  --additional-packages "systemd" \
  --image registry.fedoraproject.org/fedora:rawhide
distrobox enter fedora-rawhide

# 安装 GNOME
sudo dnf group install gnome-desktop

# 安装 KDE Plasma
# sudo dnf group install kde

在宿主机上创建 display manager 会话入口（以 GNOME 为例）：

# /usr/local/share/wayland-sessions/distrobox-gnome.desktop
[Desktop Entry]
Name=GNOME on Wayland (distrobox fedora-rawhide)
Comment=This session logs you into GNOME in a Distrobox container
Exec=/usr/local/bin/distrobox-enter -n fedora-rawhide -- /usr/bin/gnome-session
Type=Application
DesktopNames=GNOME
X-GDM-SessionRegisters=true

不要通过递归 chown /tmp/.X11-unix 修复桌面会话；它是宿主 X server 管理的共享目录。应检查 DISPLAY、XAUTHORITY、实际 socket 权限与 display manager 日志，优先使用宿主会话的正确授权。以上入口的 distrobox-enter 路径需替换为本机 command -v distrobox-enter 的结果，NixOS 路径由声明式配置提供。

实验性支持 在容器内运行完整 DE 是实验性特性。部分 DE 组件（如蓝牙、电源管理、Wi-Fi 面板）依赖宿主级 dbus 或硬件访问，可能不可用。不推荐在关键生产环境使用。

5.2 在 Distrobox 中运行 libvirt/QEMU 虚拟化

以下是一个需要较高权限的 libvirt system 连接方案，须先准备 /dev/kvm 权限、guest 包和服务。qemu session 等其他方案并不都需要 rootful；--unshare-all 也不会撤销所有宿主文件共享：

distrobox create --name libvirtd \
  --root \
  --init \
  --unshare-all \
  --image registry.opensuse.org/opensuse/distrobox:latest \
  --additional-flags "-p 2222:22" \
  --init-hooks "zypper in -y --no-recommends openssh-server \
    patterns-server-kvm_server patterns-server-kvm_tools \
    qemu-arm qemu-ppc qemu-s390x qemu-extra && \
    systemctl enable sshd.service && \
    systemctl enable virtqemud.socket virtnetworkd.socket \
      virtstoraged.socket virtnodedevd.socket && \
    usermod -aG libvirt \$USER" \
  --additional-packages "virt-manager"

# 导出 virt-manager 到宿主机应用菜单
distrobox enter --root libvirtd -- distrobox-export --app virt-manager

对应的 assemble manifest：

[libvirt]
image=registry.opensuse.org/opensuse/distrobox:latest
pull=true
init=true
root=true
unshare_all=true
additional_flags="-p 2222:22"
exported_apps="virt-manager"

qemu:///session vs qemu:///system rootful 容器内 qemu:///system 可能遇到 /dev/ptmx 冲突（Issue # 1129）。若遇到此问题，使用 qemu:///session 级别通常可以绕过。

5.3 Steam Deck / SteamOS

SteamOS 根文件系统是只读的（A/B 更新机制），Distrobox 是安装额外软件的首选方案：

# SteamOS 图形访问依赖实际桌面会话，先检查 DISPLAY/XAUTHORITY
# 不要把无条件 xhost 放入每次读取的配置文件

distrobox create --name arch-extras \
  --image docker.io/archlinux:latest \
  --additional-packages "firefox vlc gimp"

# 导出到宿主应用菜单；Steam Game Mode 另需手动添加非 Steam 游戏入口
distrobox enter arch-extras -- distrobox-export --app firefox

Steam Deck 用户常用 Distrobox 安装：

  • 桌面应用（Firefox、VLC、LibreOffice）
  • 开发工具（VS Code、Go、Rust toolchain）
  • 系统工具（htop、neofetch、rsync）
  • 模拟器（通过 RetroArch flatpak 或原生安装）

5.4 ChromeOS (Crostini) 环境

在 ChromeOS 的 Linux 开发环境（Crostini）中，Distrobox 可以在默认的 Debian 容器内再嵌套其他发行版：

# ChromeOS 先启用 Linux 开发环境（设置 > 开发者 > Linux）
# 默认得到 Debian 容器，在其中安装 distrobox
sudo apt update && sudo apt install podman distrobox

# 再套一层 Arch / Ubuntu / Fedora
distrobox create --name arch-on-chromeos --image archlinux:latest
distrobox enter arch-on-chromeos

5.5 immutable OS（Fedora Silverblue / Kinoite / openSUSE MicroOS）

不可变发行版是 Distrobox 的最佳搭档：

# 在 Silverblue 上无需 rpm-ostree layer，直接用容器
distrobox create --name toolbox \
  --image registry.fedoraproject.org/fedora-toolbox:41 \
  --additional-packages "gcc gcc-c++ make git neovim"

# 日常使用就进容器
distrobox enter toolbox

不可变 OS 用户的典型容器划分：

容器名 镜像 用途
toolbox fedora-toolbox 日常 CLI 工具、编译
aur archlinux AUR 包（如 paru、yay）
ubuntu-dev ubuntu:22.04 特定版本 lib 依赖的项目构建
ml-gpu nvidia/cuda GPU 加速的 AI/ML 训练

6. 容器生命周期自动化#

6.1 自动更新全部容器

通过 systemd timer 周期升级所有容器内的包，先确认可接受自动变更并有备份。路径是传统发行版示例，NixOS 用配置生成的 store/profile 路径。升级日志保留在 journal，失败应查看 unit 状态：

# ~/.config/systemd/user/distrobox-upgrade.service
[Unit]
Description=distrobox-upgrade: Automatic Container Update

[Service]
Type=oneshot
ExecStart=/usr/bin/distrobox-upgrade --all

# ~/.config/systemd/user/distrobox-upgrade.timer
[Unit]
Description=distrobox-upgrade: Weekly Update Trigger

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target
systemctl --user daemon-reload
systemctl --user enable distrobox-upgrade.timer
systemctl --user start distrobox-upgrade.timer

6.2 Podman Quadlet 与 assemble 的边界

Podman Quadlet 从声明式 .container 文件生成 systemd 单元，但不会自动重建 Distrobox 的 guest 初始化、挂载和导出流程。不能只写 Exec=distrobox-init 就认为得到等价的 Distrobox。以下是独立的普通 Podman 开发容器示例，使用前创建 projects 目录，并查已安装 Podman 版本支持的 Quadlet 字段：

# ~/.config/containers/systemd/plain-dev.container
[Container]
Image=docker.io/library/alpine:latest
ContainerName=plain-dev
Volume=%h/projects:/projects
WorkingDir=/projects
Exec=sleep infinity

[Service]
Restart=on-failure

[Install]
WantedBy=default.target

不要把宿主 Podman graphroot ~/.local/share/containers/storage 挂载为 guest 开发目录，否则可能损坏宿主容器存储。Quadlet 的生成单元在 daemon-reload 后由 systemd 管理，具体启动与日志检查按官方文档进行。

assemble 还是 Quadlets？

  • assemble：专为 Distrobox 设计，自动处理 HOME 共享、显示转发、包安装和导出，减少重复配置
  • Quadlet：Podman 原生方案，控制粒度更细；若要求 Distrobox 体验，需自行完整实现其契约

关键要点总结#

你应该掌握的

  • distrobox.ini manifest 的完整字段集及 assemble create/rm 与 distrobox list 命令
  • --init 容器的生命周期、init hooks 时机和 systemd 服务联动
  • NVIDIA / AMD / Intel 三种 GPU 直通方案的区别与验证方法
  • 三种多容器协作模式（Dev+Service / 按发行版分工 / 按项目隔离）
  • 桌面环境、libvirt、Steam Deck / ChromeOS / immutable OS 等特殊场景的基本命令

参考与延伸

  1. Distrobox security implications ↗
  2. Distrobox create ↗
  3. Distrobox enter ↗
  4. Distrobox assemble ↗
  5. Podman Quadlet ↗
  6. NVIDIA CDI ↗

根据技术笔记重新整理，示例使用通用名称。

沿专题继续阅读

Distrobox：用户空间、桌面集成与可恢复环境

  1. 01Distrobox 核心原理：用户空间与宿主集成
  2. 02Distrobox 安装与后端配置
  3. 03Distrobox 镜像与容器生命周期
  4. 04Distrobox 导出的，到底是什么？
  5. 05Distrobox 桌面发现与后台服务集成
  6. 06Distrobox 声明式清单与高级工作流
  7. 07NixOS 上的 Distrobox：包环境与宿主路径
  8. 08Distrobox 备份：镜像、包清单与共享数据
  9. 09Distrobox 内部机制：包、配置与命令解析
CONTINUE READING / 下一篇NixOS 上的 Distrobox：包环境与宿主路径

在声明式宿主上配置 rootless 后端，诊断 Nix profile、图形与传统用户空间的边界。