Proxmox离线镜像工具（Proxmox Offline Mirror）

1.简介

何为Proxmox离线镜像工具？

Proxmox离线镜像工具（Proxmox Offline Mirror）用于管理Proxmox及Debian项目相关软件包更新的本地APT镜像仓库。通过此本地镜像仓库，您可创建外部介质（如U盘或网络共享），以更新无法直接通过互联网访问官方软件源的系统。此类系统可能受策略限制无法连接公共互联网，或处于完全物理隔离环境。此外，您还可通过此工具为受限主机管理订阅服务。

该工具包含两个可执行程序：

proxmox-offline-mirror
镜像管理工具，用于创建及管理包含软件仓库的镜像与介质。
proxmox-offline-mirror-helper
辅助工具，用于在离线环境下的Proxmox VE、Proxmox Mail Gateway或Proxmox Backup Server系统中使用外部介质，并管理这些系统的订阅。

1.1术语

本工具支持配置三种基础实体类型：

密钥（keys）
订阅密钥可作用于镜像系统自身或离线系统。
配置命令：proxmox-offline-mirror key ...
镜像（mirrors）
镜像包含上游仓库的元数据及本地存储路径（用于保存上游仓库的快照）。
配置命令：proxmox-offline-mirror config mirror ...
使用命令：proxmox-offline-mirror mirror ...
快照（snapshots）
镜像的某一时间点视图。快照通过硬链接指向底层存储池中的文件，以减少磁盘空间占用。
介质（media）
由本地镜像组成的介质，其路径用于同步镜像内容。
配置命令：proxmox-offline-mirror config medium ...
使用命令：proxmox-offline-mirror medium ...

技术概述

在底层实现中，系统通过一个或多个存储池管理仓库内容（即镜像的“快照”），以高效利用存储空间。每个存储池包含：

池目录（pool directory）：存放校验和文件（如 sha256/3dc7bc5f82cdcc4ea0f69dd30d5f6bb19e0ccc36f4a79c865eed0e7a370cd5e4）。
链接目录（link directory）：包含指向池目录中校验和文件的硬链接。

文件添加流程：

将校验和文件添加至池目录。
通过硬链接将其映射至一个或多个路径。

垃圾回收机制：

遍历链接目录中的所有文件，删除不再指向任何校验和文件的硬链接。
删除池目录中无外部硬链接引用的校验和文件。

存储池共享：
多个镜像可共享同一存储池，以实现跨镜像的文件去重。例如，建议为所有Proxmox仓库镜像使用单一池目录（即镜像基础目录）。

配置文件路径：
默认配置文件为 /etc/proxmox-offline-mirror.cfg，但可通过以下方式覆盖：

命令行选项 --config
环境变量 PROXMOX_OFFLINE_MIRROR_CONFIG

此功能支持以非root用户身份运行工具。

获取支持

企业级支持
持有Proxmox离线镜像订阅的用户可访问Proxmox客户门户，提交与离线镜像管理及密钥处理相关的问题（前提是离线系统具备高于“社区版”的有效订阅）。客户门户提供由Proxmox开发团队直接响应的技术支持服务，并保障响应时效。

如需了解更多信息或获取批量折扣，请联系：sales@proxmox.com。

社区支持论坛
我们始终鼓励用户通过Proxmox社区论坛交流知识与经验。该论坛由Proxmox支持团队管理，汇聚全球用户，是获取信息的绝佳平台。

邮件列表
Proxmox离线镜像工具为完全开源项目，欢迎贡献代码！开发者可通过以下邮件列表参与沟通：

PVE开发邮件列表：PVE Development List

缺陷追踪系统
Proxmox运营公开的缺陷追踪系统：https://bugzilla.proxmox.com。您可在此提交漏洞报告、功能请求或改进建议。系统将跟踪问题状态，并在解决后发送通知。

许可协议

本软件由Proxmox Server Solutions GmbH（support@proxmox.com）开发。

Proxmox离线镜像工具为自由开源软件：您可自由使用、分发或修改其代码，但需遵守GNU Affero通用公共许可证（由自由软件基金会发布）的条款。许可证版本为第3版或您选择的任何后续版本。

本程序按“原样”分发，无任何明示或暗示的担保（包括适销性或特定用途适用性）。详情请参阅GNU Affero通用公共许可证。

若未随程序收到许可证副本，请访问：AGPLv3。

安装

Proxmox离线镜像工具以标准Debian软件包形式发布，并集成于Proxmox VE、Proxmox Backup Server及Proxmox Mail Gateway的软件仓库中。

系统要求

CPU：64位架构（x86-64或AMD64），建议双核及以上
操作系统：基于Debian的系统（物理主机、虚拟机或容器）
存储空间：本地镜像需充足空间，基础Debian与Proxmox VE组合建议至少预留150 GiB
文件系统：本地主机与外部介质均需支持硬链接。注：多数Linux派生文件系统（如ext4、XFS）支持硬链接，而Windows派生文件系统（如*FAT）不支持。

通过APT安装

若目标主机已配置Proxmox解决方案的软件仓库，可直接通过APT安装离线镜像工具：

apt update  
apt install proxmox-offline-mirror

若未配置Proxmox VE、Proxmox Backup Server或Proxmox Mail Gateway的软件仓库，请先参考《SecureApt》及《在非Proxmox系统设置仓库》章节完成配置，再执行上述命令。

Debian软件仓库

基于Debian的系统均使用APT作为包管理工具，其仓库列表定义于/etc/apt/sources.list及/etc/apt/sources.d/目录下的.list文件。更新操作可通过APT命令行工具或GUI界面直接执行。

APT的sources.list文件中，每行定义一个软件仓库（优先级按从上至下递减）。空行将被忽略，#符号后的内容视为注释。执行apt update后，系统将从配置的仓库源获取信息。

SecureApt

仓库中的Release文件使用GnuPG签名，APT通过验证签名确保软件包来源可信。

提示：

若在现有Proxmox VE、Proxmox Backup Server或Proxmox Mail Gateway上安装Proxmox离线镜像工具，验证密钥已预置。

若在Debian Bookworm系统上安装，需手动下载并安装密钥：

wget https://enterprise.proxmox.com/debian/proxmox-release-bookworm.gpg \
  -O /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg

随后验证SHA512校验和（预期输出如下）：

sha512sum /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg  
7da6fe34168adc6e479327ba517796d4702fa2f8b4f0a9833f5ea6e6b48f6507a6da403a274fe201595edc86a84463d50383d07f64bdde2e3658108db7d6dc87  /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg

或验证MD5校验和（预期输出如下）：

md5sum /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg  
41558dc019ef90bd0f6067644a51cf5b  /etc/apt/trusted.gpg.d/proxmox-release-bookworm.gpg

在非Proxmox系统设置仓库

若需在无互联网连接的Proxmox解决方案环境或专用系统中部署Proxmox离线镜像工具，需先配置仓库。此方法适用于任何基于APT的Linux发行版（如Debian、Ubuntu及其衍生版本）。

步骤：

配置Proxmox发布密钥（参考《SecureApt》章节）。
添加仓库URL至APT源列表。

推荐方案：
在非Proxmox系统上安装时，建议复用pbs-client仓库以避免依赖冲突。

说明：

尽管可使用Proxmox VE、Proxmox Backup Server或Proxmox Mail Gateway仓库，但这些仓库包含部分Debian原生软件包的更新版本，可能导致不必要的依赖引入。

Debian 12（Bookworm）系统仓库配置

以下为通用Debian 12（Bookworm）系统的配置步骤：

编辑文件/etc/apt/sources.list.d/pbs-client.list，添加以下内容：
文件： /etc/apt/sources.list.d/pbs-client.list
```
deb http://download.proxmox.com/debian/pbs-client bookworm main  
```
完成配置后，即可安装proxmox-offline-mirror软件包（参考《通过APT安装》章节）。

离线订阅密钥

proxmox-offline-mirror 工具可用于管理物理隔离系统或无法访问公共互联网的系统的订阅密钥。使用此功能需持有 Proxmox离线镜像工具自身的订阅密钥。

离线镜像工具将负责在Proxmox商店中注册订阅密钥。若密钥有效，系统将返回签名数据块。随后可将签名响应导出至离线介质，以在无需主机联网的情况下为Proxmox解决方案传输并设置订阅密钥。

离线激活的最低版本要求

订阅密钥的离线激活需对应Proxmox解决方案提供支持。下表列出各产品支持离线激活的最低版本：

解决方案	软件包	最低版本
Proxmox VE	`pve-manager`	7.2-11
Proxmox Backup Server	`proxmox-backup-server`	2.2.6-1
Proxmox Mail Gateway	`pmg-api`	7.1-7

配置离线镜像密钥

添加镜像密钥
使用命令 proxmox-offline-mirror key add-mirror-key <key> 添加 pom-<keyid> 镜像密钥。此操作将激活镜像系统的订阅。

注意：
- 购买Proxmox离线镜像订阅密钥请联系 sales@proxmox.com。
- 若您的Proxmox VE、Proxmox Backup Server或Proxmox Mail Gateway主机已拥有大量标准版（Standard）或高级版（Premium）订阅，可能有资格免费获取离线镜像订阅。详情请邮件咨询 sales@proxmox.com。

收集服务器ID

需获取目标离线系统的服务器ID。可通过以下方式查看：

Proxmox VE：Web界面订阅面板或命令 pvesubscription get
Proxmox Backup Server：命令 proxmox-backup-manager subscription get
Proxmox Mail Gateway：命令 pmgsubscription get

注册与刷新密钥

注：

为访问并镜像产品的企业版仓库，需同时配置 有效的产品订阅密钥 和 Proxmox离线镜像订阅。

操作步骤：

使用 proxmox-offline-mirror setup 或 proxmox-offline-mirror key add 注册主机（需订阅密钥及服务器ID）：
```
proxmox-offline-mirror key add pve2p-12345... ABCDEF0123...  
```
默认情况下，此命令将从Proxmox订阅服务器获取最新订阅信息。
刷新订阅信息：
- 单密钥：proxmox-offline-mirror key refresh --key XX
- 全部密钥：proxmox-offline-mirror key refresh

部署密钥

订阅信息将同步至介质（参见《同步介质》章节），随后可通过以下任一命令在离线系统激活：

proxmox-offline-mirror-helper offline-key
proxmox-offline-mirror-helper setup

注意事项：

此流程需至少每年执行一次，或在订阅密钥到期前完成（以较早者为准）。
密钥到期后，需重新生成签名响应并部署至离线系统以维持订阅有效性。

离线仓库镜像

离线仓库镜像指向APT仓库（如Proxmox VE、Proxmox Backup Server或Debian的仓库）。初始配置完成后，您可将所有可用软件包本地化镜像，并通过创建仓库的时间点快照（snapshot）进行组织。这些快照随后可导出至已配置的介质。

配置镜像

操作方式：

运行设置向导：proxmox-offline-mirror setup
使用 config mirror add 命令

提示：

为快速配置Proxmox解决方案相关仓库，建议使用设置向导。添加镜像时选择对应产品，并在提示时确认自动添加Debian基础仓库。

注意：

要访问并镜像产品的企业版仓库，需同时配置 有效的产品订阅密钥 和 Proxmox离线镜像订阅（参见《配置离线镜像密钥》章节）。

示例：手动添加Debian Bookworm安全仓库镜像条目

proxmox-offline-mirror config mirror add \  
 --id debian-bookworm-security \  
 --architectures amd64 \  
 --architectures all \  
 --repository 'deb http://deb.debian.org/debian-security bookworm-security main contrib non-free' \  
 --key-path /etc/apt/trusted.gpg.d/debian-archive-bookworm-security-automatic.gpg \  
 --sync true \  
 --verify true \  
 --base-dir /path/to/mirror/base-dir

说明：

base-dir 目录：可为多个镜像共享，避免重复存储相同内容。建议为所有Proxmox仓库镜像使用单一基础目录。
all 架构：表示架构无关的软件包（非全架构支持），通常需与主机架构（如 amd64）同时添加。

同步镜像

创建初始及后续快照，执行以下命令：

proxmox-offline-mirror mirror snapshot create debian-bookworm-security

注意：

根据参数及原始仓库大小，创建快照可能耗时较长且占用大量磁盘空间。初始快照尤为显著，后续快照将复用未更改的文件与索引。

缩小镜像范围

可通过以下机制缩小镜像范围（减少同步流量及存储占用）：

架构过滤
组件过滤（作为仓库定义的一部分）
软件包名称与分类过滤

默认行为：仅同步 all 和 amd64 架构的软件包。

可选过滤配置：

--skip-packages：跳过指定二进制/源码包（支持通配符）。
- 示例：--skip-packages 'linux-image-*' 跳过所有以 linux-image- 开头的包。
--skip-sections：跳过指定分类（匹配完整值或带组件前缀的值）。
- 示例：--skip-sections 'games' 跳过 games 分类（包括 non-free/games）。

参考：

Debian仓库分类及内容详见 https://packages.debian.org/bookworm/。

存储空间管理

使用 proxmox-offline-mirror mirror snapshot remove 删除快照后，需执行以下命令触发垃圾回收以释放底层硬链接池中不再需要的内容：

proxmox-offline-mirror mirror gc

环境变量

ALL_PROXY
设置此变量后，proxmox-offline-mirror 将为所有HTTP(s)连接使用指定代理（当前仅支持HTTP代理）。有效格式为：

[http://][user:password@]<host>[:port]

默认端口：未指定时为 1080。

注意：

代理服务器需允许对镜像仓库所用端口（如HTTP仓库的80端口）的HTTP CONNECT请求。
Squid配置示例：http_access allow CONNECT <acl>（默认仅允许443端口）。详情参见 Squid文档。

离线介质

介质指文件系统中的存储位置，用于保存镜像仓库及订阅信息，供离线Proxmox系统访问。介质可为外部便携磁盘（如U盘）或本地网络共享。

配置介质

可通过以下任一方式创建介质：

重新运行设置向导
使用 config media add 命令

示例：定义包含 proxmox-ve-bookworm-no-subscription 和 debian-bookworm 镜像的新介质

proxmox-offline-mirror config media add \  
 --id pve-bookworm \  
 --mirrors proxmox-ve-bookworm-no-subscription \  
 --mirrors debian-bookworm \  
 --sync true \  
 --verify true \  
 --mountpoint /path/where/medium/is/mounted

同步介质

将本地镜像同步至介质，执行以下命令：

proxmox-offline-mirror medium sync pve-bookworm

此命令将关联此介质的所有镜像同步至介质挂载点，并同步离线订阅密钥供目标系统的 proxmox-offline-mirror-helper 处理。

使用介质

同步完成后，可通过以下方式在离线目标系统访问介质：

物理介质转移：从镜像主机卸载介质，插入目标系统并挂载。
网络共享：通过本地网络（NFS、CIFS/SMB或HTTP）直接（镜像主机）或间接（其他主机）暴露介质。

随后可按常规方式升级主机（通过控制台或Web界面），具体操作参见各项目的官方文档。

注意事项：

升级完成后需禁用或移除APT源配置片段，避免自动刷新导致错误。
可通过Proxmox VE、Proxmox Backup Server或Proxmox Mail Gateway的Web界面动态启用/禁用仓库。

示例：本地挂载点

假设介质已在目标主机挂载，可选择以下任一方式配置：

引导式设置

运行 proxmox-offline-mirror-helper setup，选择镜像与快照后生成APT源配置片段。默认保存路径为 /etc/apt/sources.list.d/offline-mirror.list。

手动设置

直接指向介质上的同步快照目录，创建APT源条目（示例）：

deb [check-valid-until=false] file:///mnt/mirror-path/<mirror-name>/<snapshot-timestamp> <codename> <suite>

<codename>：通常为Debian代号（如 bookworm）
<suite>：可为Debian或Proxmox项目套件（如 pve-enterprise、main）

完成升级后需禁用此条目，待下次使用时重新启用。

示例：本地HTTP服务器

可通过HTTP服务器在内网提供快照访问。以下为Nginx最小化配置示例：

# 对应APT源条目示例：  
# deb [check-valid-until=false] http://proxmox-offline-mirror.domain.example/<mirror-name>/<snapshot-timestamp> <codename> <suite>  
server {  
	listen 80 default_server;  
	listen [::]:80 default_server;  

	server_name proxmox-offline-mirror.domain.example;  

	root /path/to/medium;  
	disable_symlinks off;  
	autoindex on;  

	error_log /var/log/nginx/proxmox-offline-mirror.error.log;  
	access_log /var/log/nginx/proxmox-offline-mirror.access.log;  

	location / {  
	        try_files $uri $uri/ =404;  
	}  
}

对应的APT源文件（/etc/apt/sources.list.d）需包含：

deb [check-valid-until=false] http://proxmox-offline-mirror.domain.example/<mirror-name>/<snapshot-timestamp> <codename> <suite>

<codename> 与 <suite> 取值参考手动设置示例。

激活订阅密钥

离线激活或更新订阅密钥，可选择以下方式：

直接运行 proxmox-offline-mirror-helper offline-key
在引导式设置（proxmox-offline-mirror-helper setup）中执行对应步骤

第 4 章图形用户界面

第三章主机系统管理

Proxmox离线镜像工具（Proxmox Offline Mirror）

1.简介

1.1术语

技术概述

获取支持

许可协议

安装

系统要求

通过APT安装

Debian软件仓库

SecureApt

在非Proxmox系统设置仓库

Debian 12（Bookworm）系统仓库配置

离线订阅密钥

离线激活的最低版本要求

配置离线镜像密钥

收集服务器ID

注册与刷新密钥

部署密钥

离线仓库镜像

配置镜像

同步镜像

缩小镜像范围

存储空间管理

环境变量

离线介质

配置介质

同步介质

使用介质

示例：本地挂载点

引导式设置

手动设置

示例：本地HTTP服务器

激活订阅密钥

第 4 章 图形用户界面

第三章 主机系统管理

Proxmox离线镜像工具（Proxmox Offline Mirror）

1.简介

1.1术语

技术概述

获取支持

许可协议

安装

系统要求

通过APT安装

Debian软件仓库

SecureApt

在非Proxmox系统设置仓库

Debian 12（Bookworm）系统仓库配置

离线订阅密钥

离线激活的最低版本要求

配置离线镜像密钥

收集服务器ID

注册与刷新密钥

部署密钥

离线仓库镜像

配置镜像

同步镜像

缩小镜像范围

存储空间管理

环境变量

离线介质

配置介质

同步介质

使用介质

示例：本地挂载点

引导式设置

手动设置

示例：本地HTTP服务器

激活订阅密钥

第 4 章图形用户界面

第三章主机系统管理