KB0044. 搭建 DoraCloud 私有镜像仓库

镜像仓库工作原理

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

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

工作流程：

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

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

核心文件解析

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": ""
}

核心要点总结

  1. 仓库即Web服务：镜像仓库是一个标准的 Web 服务器，通过 HTTP/HTTPS 提供文件访问
  2. 双文件备份机制：模板备份时同时生成 .dr 描述文件和对应的镜像文件，这两个文件是构建仓库的基础材料
  3. 集中索引管理：仓库中的 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 步：创建虚拟机

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

第 3 步：配置网络

  1. 初始访问：启动虚拟机后：

    • 通过控制台登录（用户名：root，密码：dora@cloud）
    • 若未获取 IP，使用 nmtui 命令配置静态地址

  2. Web 管理：

    • 浏览器访问 https://<虚拟机IP>:9090/
    • 登录 Cockpit 面板（相同凭据）
    • 在 网络 菜单中调整配置
    • 在 终端 菜单执行命令 Cockpit 管理面板

第 4 步：验证服务

  1. 执行索引更新测试：

    update_repo.sh /var/www/html

  2. 浏览器访问 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

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

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

配置步骤：

  1. SSH 免密配置：

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

  2. 配置定时同步：

    # 编辑定时任务
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

  3. 确认自动索引更新： 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

自动同步脚本工作原理：

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

维护方法对比

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

完成状态检查清单

✅ 基础服务：

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

✅ 管理功能：

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

✅ 维护配置：

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

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