Distrobox 核心原理：用户空间与宿主集成

flowchart LR
    A["Host OS<br/>(不可变 / 任意发行版)"]
    B["Distrobox CLI<br/>(POSIX Shell)"]
    C["OCI Runtime<br/>(Podman / Docker / Lilipod)"]
    D["Guest Container<br/>(Ubuntu 24.04)"]
    E["Host Integration"]
    F["HOME 目录<br/>X11/Wayland<br/>PipeWire/PulseAudio<br/>D-Bus / SSH Agent<br/>GPU / USB / udev<br/>Network"]

    A --> B --> C --> D
    D --> E --> F

    style D fill:#2d6,stroke:#333
    style E fill:#da0,stroke:#333
    style F fill:#28f,stroke:#333,color:#fff

flowchart TD
    subgraph "Host Userspace"
        CLI["distrobox CLI<br/>(distrobox 入口与独立辅助脚本)"]
        MOUNT["Host Integration Layer<br/>自动挂载/转发"]
        subgraph "共享资源（自动配置）"
            HOME_HOST["🏠 HOME 目录 (rw)"]
            GFX["🎨 X11 / Wayland socket"]
            AUDIO["🔊 PipeWire / PulseAudio socket"]
            DBUS["🔗 D-Bus session bus"]
            SSH_A["🔑 SSH agent socket"]
            GPU["🎮 GPU device nodes (/dev/dri)"]
            USB["💾 udev / removable devices"]
            NET["🌐 宿主机网络 (host network)"]
            ULIMIT["⚙️ ulimits / tty 共享"]
        end
    end

    subgraph "Container Runtime"
        PODMAN["Podman (推荐, rootless)"]
        DOCKER["Docker (备选, rootful by default)"]
        LILIPOD["Lilipod (轻量, 实验性)"]
    end

    subgraph "Guest Containers"
        C1["container: ubuntu:24.04<br/>HOME → 共享<br/>GPU → 可访问<br/>pipewire → 可播放"]
        C2["container: archlinux:latest<br/>HOME → 共享<br/>GPU → 可访问<br/>pipewire → 可播放"]
    end

    CLI --> PODMAN
    CLI --> DOCKER
    CLI --> LILIPOD
    PODMAN --> C1
    PODMAN --> C2
    MOUNT -.- C1
    MOUNT -.- C2
    HOME_HOST -.- C1 & C2
    GFX -.- C1 & C2
    AUDIO -.- C1 & C2
    DBUS -.- C1 & C2
    SSH_A -.- C1 & C2
    GPU -.- C1 & C2
    USB -.- C1 & C2
    NET -.- C1 & C2
    ULIMIT -.- C1 & C2

    style CLI fill:#e90,stroke:#333,color:#fff
    style PODMAN fill:#06c,stroke:#333,color:#fff

distrobox                  主入口与命令分发
distrobox-create           创建与挂载配置
distrobox-enter            启动、初始化与进入
distrobox-list / stop / rm  生命周期操作
distrobox-upgrade          发行版包升级
distrobox-assemble         INI 清单处理
distrobox-export           在容器内生成宿主 app/bin 入口
distrobox-host-exec        从容器调用宿主命令
distrobox-ephemeral        临时容器流程
distrobox-generate-entry   容器终端入口
distrobox-init             容器内部初始化

# ========== 纯 podman run（你要手动写所有参数）==========
podman run --rm -it \
  --name my-ubuntu \
  --hostname my-ubuntu \
  --network host \
  --volume /home/user:/home/user:rslave \
  --volume /tmp/.X11-unix:/tmp/.X11-unix:ro \
  --volume $XDG_RUNTIME_DIR/$WAYLAND_DISPLAY:$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY \
  --volume $XDG_RUNTIME_DIR/pipewire-0:$XDG_RUNTIME_DIR/pipewire-0 \
  --volume /dev/dri:/dev/dri \
  --volume /run/udev:/run/udev:ro \
  --env DISPLAY=$DISPLAY \
  --env WAYLAND_DISPLAY=$WAYLAND_DISPLAY \
  --env XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR \
  --security-opt label=disable \
  --ulimit host \
  docker.io/library/ubuntu:24.04 \
  /bin/bash

# ========== Distrobox（全自动）==========
distrobox create --name my-ubuntu --image ubuntu:24.04
distrobox enter my-ubuntu

# 在普通用户的宿主终端检查 rootless 后端
podman info --format '{{.Host.Security.Rootless}}'
podman unshare cat /proc/self/uid_map
podman unshare cat /proc/self/gid_map

# ❌ Docker 思维：每次跑一个命令
docker exec my-container apt install neovim
docker exec my-container nvim /home/user/code/main.py

# ✅ Distrobox 思维：进入容器，把它当成一个"shell 环境"
distrobox enter my-ubuntu
# 现在你在容器内，和宿主机的 shell 没区别：
$ sudo apt install neovim
$ nvim ~/code/main.py       # HOME 共享，直接编辑宿主文件
$ firefox                    # GUI 应用直接显示在宿主机
$ exit                       # 退出回宿主机

# Distrobox 自动修改了容器内的 prompt：
📦[my-ubuntu] $ pwd
/home/user                    # ← 就是你的宿主 HOME
📦[my-ubuntu] $ cat /etc/os-release
NAME="Ubuntu"
VERSION_ID="24.04"
📦[my-ubuntu] $ exit
logout

$ pwd                         # 回到宿主机
/home/user

# 查看容器存储根目录
podman info --format '{{.Store.GraphRoot}}'
# 输出通常是：/home/用户/.local/share/containers/storage

flowchart LR
    A["~/.local/share/containers/storage"] --> B["overlay/"]
    A --> C["overlay-containers/"]
    A --> D["overlay-images/"]
    A --> E["volumes/"]
    B --> B1["容器可写层<br/>你在容器里 pacman/apt 装的包<br/>改动都在这里"]
    C --> C1["容器运行时元数据<br/>每个容器一个 hash 目录"]
    D --> D1["拉取的基础镜像层<br/>arch-toolbox / ubuntu:latest"]
    E --> E1["命名数据卷<br/>Distrobox 默认很少用"]

podman ps -a                        # 列出容器及其 hash ID
podman inspect arch --format '{{.GraphDriver.Data.UpperDir}}'  # 查看可写层绝对路径

podman system df              # 查看镜像/容器/卷占用
podman image prune -a         # 删除未被任何容器使用的镜像
podman system prune           # 综合清理