KB0044. 搭建 DoraCloud 私有镜像仓库

镜像仓库工作原理

DoraCloud 镜像仓库本质上是一个 Web 服务器，通过 HTTP/HTTPS 协议对外提供模板镜像文件的下载服务。不同虚拟化平台和架构的模板按目录组织，形成了清晰的分类结构：

├── hyperv/          # Hyper-V 平台模板
├── libvirt/         # libvirt/KVM 平台模板
│   ├── aarch64/     # ARM 架构模板
│   └── x86_64/      # Intel/AMD 架构模板
├── pve/             # Proxmox VE 平台模板
└── vmware/          # VMware 平台模板

工作流程：

连接仓库：DoraCloud 通过预配置的 URL 访问镜像仓库 Web 服务器
读取索引：系统自动读取各平台目录下的 json.dr 索引文件，获取可用模板列表及详细元数据
下载部署：用户选择模板后，系统根据索引中的文件路径信息下载对应的镜像文件到本地部署

这种集中式的架构使得模板管理、版本控制和批量分发变得高效统一。

核心文件解析

1. 仓库索引文件 (`json.dr`)

每个平台目录下都必须包含此文件，它是一个 JSON 格式的索引，集中记录该目录下所有模板的信息。

示例 - 包含两个 Windows 7 模板的 json.dr：

[
  {
    "name": "win7x64base",
    "versions": "win7x64basev1a95bd5",
    "fileSize": "7217",
    "fileName": "vzdump-qemu-288-2023_01_01-21_18_33.vma.zst",
    "imgSize": "61440",
    "guestos": "Microsoft Windows 7",
    "createtime": "2023-01-01 09:18:33",
    "agentver": "2.4.0",
    "md5": "4c7e5a7cc3228e509516e2396453a9eb",
    "username": "administrator",
    "password": "123456",
    "description": "win7 64位系统，未安装软件"
  },
  {
    "name": "win7x64pro",
    "versions": "win7x64prov1b701ae",
    "fileSize": "5814",
    "fileName": "vzdump-qemu-717-2024_09_14-00_24_03.vma.zst",
    "imgSize": "61440",
    "guestos": "Microsoft Windows 7",
    "createtime": "2024-09-14 12:24:01",
    "agentver": "2.5.0",
    "md5": "57c20ebd6f391e1a07a8832c76acc5b0",
    "username": "administrator",
    "password": "123456",
    "description": "Windows 7 x64 pro"
  }
]

关键字段说明：

fileName：镜像文件的实际名称，DoraCloud 据此下载文件
md5：文件校验码，确保下载完整性
username/password：模板内置的默认登录凭证

2. 模板备份机制

DoraCloud 支持模板备份功能，执行备份时会生成两个关键文件：

A. Proxmox VE 平台示例 备份 UOSCloudV3 模板后，在 /var/lib/vz/dump 目录生成：

UOSCloudV3.dr (描述文件)
vzdump-qemu-1058-2025_11_28-18_17_20.vma.zst (镜像文件)

{
  "name": "UOSCloudV3",
  "versions": "UOSCloudV3v1c0b0d6",
  "fileSize": "6169",
  "fileName": "vzdump-qemu-1058-2025_11_28-18_17_20.vma.zst",
  "guestos": "Linux",
  "createtime": "2025-11-28 18:17:19",
  "md5": "1fdee9c2ab8b971d92a4b90fcaf0e2a9",
  "username": "administrator",
  "password": "123456",
  "description": "1、支持音频。2、修正Cloud-Init无法配置DNS的问题"
}

B. Hyper-V 平台示例 备份 win10LTSC2021V3 模板后，在 Hyper-V 模板存储池中创建专属文件夹：

win10LTSC2021V3.dr (描述文件)
win10LTSC2021V3.zip (镜像文件)

Hyper-V备份文件结构

{
  "name": "win10LTSC2021V3",
  "versions": "win10LTSC2021V3v1c006bc,win10LTSC2021V3v1bb14db",
  "fileSize": "9668",
  "fileName": "win10LTSC2021V3",
  "imgSize": "102400",
  "guestos": "Windows 10 Enterprise LTSC 2021",
  "createtime": "2025-10-29 12:38:26",
  "agentver": "2.5.0",
  "md5": "DDD89AFC7F768C24322A6C223E8AAF16",
  "description": ""
}

核心要点总结

仓库即Web服务：镜像仓库是一个标准的 Web 服务器，通过 HTTP/HTTPS 提供文件访问
双文件备份机制：模板备份时同时生成 .dr 描述文件和对应的镜像文件，这两个文件是构建仓库的基础材料
集中索引管理：仓库中的 json.dr 文件通过聚合所有独立 .dr 文件的信息，形成完整的模板索引，供 DoraCloud 统一读取

完整工作流程：

用户备份模板 → 生成 [模板名.dr] + [镜像文件] → 上传至仓库对应目录 → 
运行 update_repo.sh 脚本 → 生成/更新 json.dr 索引 → 
DoraCloud 读取索引 → 用户选择部署 → 系统下载镜像

搭建镜像仓库服务器

DoraCloud 提供了一个预配置的 ImageRepo 模板，可快速部署私有镜像仓库服务。该模板基于 RockyLinux 9.6，已预装 Nginx 及必要的管理工具。

模板结构：

Web 根目录：/var/www/html (Nginx 默认目录)
仓库目录：包含三个平台子目录
管理脚本：位于 /usr/local/bin/

[root@localhost ~]# tree -d /var/www/html
/var/www/html
├── hyperv      # Hyper-V 模板目录
├── pve         # Proxmox VE 模板目录
└── vmware      # VMware 模板目录

部署步骤（以 Proxmox VE 平台为例）

第 1 步：获取模板

在 DoraCloud 管理后台，从在线仓库下载 ImageRepo 模板。下载 ImageRepo 模板

第 2 步：创建虚拟机

登录 Proxmox VE 管理界面
基于 ImageRepo 模板创建新虚拟机
建议使用 完整克隆 方式
命名为 ImageRepo 或易识别的名称

第 3 步：配置网络

初始访问：启动虚拟机后：
- 通过控制台登录（用户名：root，密码：dora@cloud）
- 若未获取 IP，使用 nmtui 命令配置静态地址
Web 管理：
- 浏览器访问 https://<虚拟机IP>:9090/
- 登录 Cockpit 面板（相同凭据）
- 在网络菜单中调整配置
- 在终端菜单执行命令

第 4 步：验证服务

执行索引更新测试：
```
update_repo.sh /var/www/html
```
浏览器访问 http://<虚拟机IP>，确认页面正常显示（初始无模板）

仓库维护方法

方法一：手动上传（适合小批量操作）

操作流程：备份模板 → 上传文件 → 更新索引

A. Proxmox VE 平台上传示例：

# 在 PVE 主机执行（假设仓库 IP: 192.168.1.158）
cd /var/lib/vz/dump

# 1. 查看模板描述文件
cat UbuntuServer2404.dr

# 2. 上传描述文件
scp UbuntuServer2404.dr root@192.168.1.158:/var/www/html/pve/

# 3. 上传镜像文件（根据 .dr 中的 fileName 字段）
scp vzdump-qemu-2204-2025_02_26-20_59_06.vma.zst root@192.168.1.158:/var/www/html/pve/

B. Hyper-V 平台上传示例（Windows 环境）：

# 使用 pscp（PuTTY SCP 工具）
pscp RockyLinux96Mini.* root@192.168.1.158:/var/www/html/hyperv/

C. 更新索引：

# 登录仓库服务器执行
update_repo.sh /var/www/html

方法二：自动同步（推荐用于生产环境）

实现模板备份后自动同步到仓库，无需人工干预。

配置步骤：

SSH 免密配置：

# 在仓库服务器执行，建立到 PVE 主机的信任关系
ssh-copy-id root@192.168.1.15

配置定时同步：

# 编辑定时任务
crontab -e

# 添加以下行（根据实际情况修改）
# 每分钟同步一次，从 PVE 备份目录同步到本地仓库
* * * * * /usr/local/bin/sync_pve_backup.sh 192.168.1.15 /var/lib/vz/dump /var/www/html/pve > /dev/null 2>&1

确认自动索引更新： ImageRepo 模板默认已配置索引自动更新：

[root@localhost ~]# crontab -l
* * * * * /usr/local/bin/update_repo.sh /var/www/html/ > /var/log/update_repo.log

# 已添加的同步任务也会显示
* * * * * /usr/local/bin/sync_pve_backup.sh 192.168.1.15 /var/lib/vz/dump /var/www/html/pve > /dev/null 2>&1

自动同步脚本工作原理：

扫描源主机的 .dr 文件列表
解析每个 .dr 文件获取对应的镜像文件名
同步 .dr 文件和镜像文件到仓库目录
保持文件完整性校验

维护方法对比

特性	手动上传	自动同步
操作频率	按需手动执行	定时自动运行
即时性	有延迟	近实时（分钟内）
复杂性	需登录多台机器	一次性配置
适用场景	测试环境、小批量更新	生产环境、持续部署
错误率	依赖人工，易出错	脚本处理，可靠性高
维护成本	高	低

完成状态检查清单

✅ 基础服务：

Nginx Web 服务正常运行
仓库目录结构就绪（hyperv/pve/vmware）
可通过 HTTP 访问仓库首页

✅ 管理功能：

update_repo.sh 脚本可用
Cockpit 管理面板可访问（端口 9090）
SSH 服务正常

✅ 维护配置：

已测试手动上传流程
已配置自动同步（如适用）
定时任务正常运行

完成以上步骤后，您的私有镜像仓库已可正常使用。用户备份的模板将自动或手动同步到仓库，并在 DoraCloud 系统中可见可用。