安全#

用户必须在安装发行版后升级软件包，以确保存在所有最新的错误修复和安全补丁。

我们目录中发行版的根文件系统存档根据需求更新。实际上，这意味着新安装的发行版可能已经过时几个月了。

请记住，proot（proot-distro 的核心）不像 docker、firejail 和其他类似的知名工具那样提供高级别隔离。

对于 ARMv9 用户#

符合 ARMv9 标准的 SoC 不包含对 32 位指令集的支持。这是与 ARMv8 的主要区别。

由于某些用户可能没有预料到 32 位支持在硬件级别被丢弃，当检测到缺少 32 位指令时，proot-distro 会显示红色警告。一旦 ARMv9 变得更加普遍，我们将移除该警告。

在具有 ARMv9 架构的设备上，32 位发行版将被视为外来架构，你需要 qemu-user-arm 模拟器软件包。

访问内置帮助#

命令：help

此命令将显示有关 proot-distro 用法的帮助信息。

• proot-distro help - 主页面。
• proot-distro <command> --help - 查看特定命令的帮助。

备份发行版#

命令：backup

别名：bak、bkp

将指定发行版及其插件备份到 tar 存档。备份的内容可以打印到 stdout 进行进一步处理或写入文件。

压缩方式根据文件扩展名确定，例如 .tar.gz 将使用 GZip 压缩，.tar.xz 将使用 XZ。管道备份数据始终不压缩，以便用户自由进行进一步处理。

使用示例：

1
proot-distro backup debian | xz | ssh example.com 'cat > /backups/pd-debian-backup.tar.xz'
2
proot-distro backup --output backup.tar.gz debian

此命令是通用的。所有额外处理（如加密）应由用户通过外部命令完成。

安装发行版#

命令：install

别名：add、i、in、ins

安装由别名指定的发行版 - 一个指向所选发行版插件的短名称。

使用示例：

1
proot-distro install alpine

默认情况下，已安装的发行版将与命令行中指定的别名相同。这意味着你将无法同时安装多个副本。你可以在安装时使用选项 --override-alias 重命名发行版，这将创建发行版插件的副本。

使用示例：

1
proot-distro install --override-alias alpine-test alpine
2
proot-distro login alpine-test

复制的插件具有以下命名格式 <name>.override.sh，并存储在与其他插件相同的目录中（$PREFIX/etc/proot-distro）。

你可以通过环境变量 PD_OVERRALL_TARBALL_URL 指定自定义 URL 来下载 rootfs 存档，例如：

1
export PD_OVERRIDE_TARBALL_URL="http://localhost:8080/debian.tar.gz"
2
proot-distro install debian

也可以选择指定 PD_OVERRIDE_TARBALL_STRIP_OPT 来定义提取 tarball 时应剥离多少路径组件。如果未在发行版的插件脚本中定义，默认值为 1。如果 rootfs 未存储在子目录中，则指定为 0。

请注意，不检查自定义下载的 rootfs 的完整性。

可以强制指定要安装的发行版的自定义 CPU 架构。为此，你需要将 DISTRO_ARCH 环境变量设置为以下值之一：aarch64、arm、i686、riscv64、x86_64。示例：

1
DISTRO_ARCH=arm proot-distro install alpine

通常，如果你的主机是 64 位，同一架构的 32 位发行版应该可以无缝工作，但这不能保证。因此，如果你在 AArch64 主机上使用 ARM 版本系统时遇到问题，这应该是 proot 工具的 bug 或与主机支持的 CPU 指令不兼容。

使用外来架构（如 AArch64 主机上的 x86_64 目标）总是需要 QEMU 用户模式软件包。

使用一条命令安装所有支持的 QEMU 用户模式软件包：

1
pkg install qemu-user-aarch64 qemu-user-arm qemu-user-i386 qemu-user-x86-64

x86_64 目标还支持 Blink 用户模式 CPU 模拟器（实验性）。使用详情请参阅下文。

列出发行版#

命令：list

别名：li、ls

显示可用发行版列表、它们的别名、安装状态和注释。

启动 shell 会话#

命令：login

别名：sh

在给定发行版中执行 shell。例如：

1
proot-distro login debian

以指定用户在给定发行版中执行 shell：

1
proot-distro login --user admin debian

你也可以运行自定义命令：

1
proot-distro login debian -- /usr/local/bin/mycommand --sample-option1

参数 -- 作为 proot-distro login 选项处理的终止符。它后面的所有参数都不会被视为 PRoot Distro 的选项。

Login 命令支持以下行为修改选项：

• --user <username>

  使用自定义登录用户而不是默认的 root。你需要通过 useradd -U -m username 创建用户，然后才能使用此选项。

• --fix-low-ports

  强制将低网络端口重定向到高端口号（2000 + 端口）。将此选项与需要低端口的软件一起使用，而这些端口没有真正的 root 权限是无法使用的。

  例如，此选项会将端口 80 重定向到类似 2080 的端口。

• --isolated

  不要在 proot 环境中挂载主机卷。如果给出此选项，以下挂载点将不可访问：

  • /apex（仅 Android 10+）
  • /data/dalvik-cache
  • /data/data/com.termux
  • /sdcard
  • /storage
  • /system
  • /vendor

  你将无法在 proot 环境中使用 Termux 实用程序。

• --termux-home

  将 Termux 主目录挂载为 proot 环境中的用户主目录。

  此选项优先于选项 --isolated。

• --shared-tmp

  与 proot 环境共享 Termux 临时目录。优先于选项 --isolated。

• --bind path:path

  创建自定义文件系统路径绑定。选项期望以下格式的参数：

  1
  <host path>:<proot path>
  

  优先于选项 --isolated。

• --no-link2symlink

  禁用 PRoot link2symlink 扩展。这将禁用硬链接模拟。只有在 SELinux 禁用或处于 permissive 模式时才能使用此选项。

• --no-sysvipc

  禁用 PRoot System V IPC 模拟。如果遇到崩溃，请尝试此选项。

• --no-kill-on-exit

  当 shell 会话终止时不要终止进程。如果你有任何后台进程运行，通常会导致会话挂起。

• --no-arch-warning

  抑制关于 CPU 不支持 32 位指令的警告。

• --kernel

  自定义 uname -r 命令显示的 Linux 内核版本字符串。

• --hostname

  自定义系统主机名。

• --work-dir

  将工作目录设置为给定值。默认工作目录与用户主目录相同。

卸载发行版#

命令：remove

别名：rm

此命令完全删除给定系统的安装。小心，因为它不会要求确认。删除的数据无法恢复。

使用示例：

1
proot-distro remove debian

重命名发行版#

命令：rename

别名：mv

通过更改别名名称、重命名其插件和根文件系统目录来重命名发行版。如果要重命名默认发行版，将创建插件的副本。

使用示例：

1
proot-distro rename ubuntu ubuntu-test01

只能重命名已安装的发行版。

重新安装发行版#

命令：reset

别名：-

删除指定发行版并重新安装。这是以下操作的快捷方式：

1
proot-distro remove <dist> && proot-distro install <dist>

使用示例：

1
proot-distro reset debian

与命令 remove 一样，删除的数据将无法恢复。小心。

从备份恢复#

命令：restore

别名：-

从给定的 proot-distro 备份（tar 存档）恢复发行版。

恢复操作执行对存档中备份状态的完整回滚。小心，因为此命令会不可恢复地删除以前的数据。

压缩方式根据文件扩展名自动确定。管道数据在提供给 proot-distro 之前必须始终解压缩。

使用示例：

1
ssh example.com 'cat /backups/pd-debian-backup.tar.xz' | xz -d | proot-distro restore
2
proot-distro restore ./pd-debian-backup.tar.xz

复制文件到发行版或从发行版复制#

命令：copy

别名：cp

从/向发行版复制给定的文件或目录。

使用示例：

1
proot-distro copy ./localfile.txt ubuntu:/home/user/targetfile.txt

如果传递了选项 --move，则可以移动文件而不是复制。

不支持 glob。源和目标路径只能指定一次。

清除下载缓存#

命令：clear-cache

别名：clear、cl

这将删除所有缓存的根文件系统存档。

插件变量参考#

DISTRO_ARCH：指定要安装的发行版的 CPU 架构变体。

通常这个变量是自动确定的，你不应该设置它。典型的用例是在 QEMU 模拟器（用户模式）下设置自定义架构来运行发行版。

支持的架构有：aarch64、arm、i686、riscv64、x86_64。

DISTRO_NAME：发行版的名称，类似于”Alpine Linux (3.14.1)”。

DISTRO_TYPE：发行版的类型，可以是以下之一：

• normal：默认，用于常规发行版
• termux：特殊，用于打包的 Termux 引导环境

DISTRO_COMMENT：当前发行版的注释。

通常不需要此变量。使用它来通知用户某些功能不工作或启动此发行版需要额外步骤。

TARBALL_STRIP_OPT：提取 rootfs 存档时应剥离多少前导路径组件。默认值为 1，因为所有默认 rootfs tarball 都将内容存储在子目录中。

TARBALL_URL：根文件系统 tarball URL 的 Bash 关联数组。

至少应该为你的 CPU 架构定义。有效架构名称与 DISTRO_ARCH 相同。应以正确的协议方案开头。 例如，https://、file://、ftp:// 等，用于访问本地或远程文件。

TARBALL_SHA256：每个 rootfs 变体的 SHA-256 校验和的 Bash 关联数组。

必须为 TARBALL_URL 中的每个 tarball 集合定义。

运行额外的安装步骤#

可以配置插件在安装发行版后执行指定命令。这是通过函数 distro_setup 完成的。

示例：

1
distro_setup() {
2
  run_proot_cmd apt update
3
  run_proot_cmd apt upgrade -yq
4
}

run_proot_cmd 用于在 rootfs 内执行命令。