OrbStack 数据恢复完整指南

环境信息

• 操作系统: macOS (Darwin 24.6.0)

• OrbStack版本: 已安装并运行

• 备份文件: data.img.raw (原始大小: 297GB)

• 备份文件系统: Btrfs

• 分区类型: GPT

准备工作

1. 确认备份文件位置

 ls -lh /path/to/orbstack_data_backup_20260203_104139/data.img.raw

2. 检查磁盘可用空间

 df -h /path/to/backup/location

注意: 扩展镜像时会使用稀疏文件技术，不会占用大量实际磁盘空间。

3. 启动OrbStack

 orb start
 orb status

恢复步骤

1. 创建Alpine恢复容器

创建一个特权Alpine容器用于挂载和操作备份镜像。

 # 创建Alpine容器
 orb create alpine alpine-recovery
 ​
 # 安装必要工具
 orb run -m alpine-recovery -u root apk add \
     util-linux parted e2fsprogs file \
     lvm2 gptfdisk btrfs-progs \
     multipath-tools kpartx rsync jq

2. 探索备份镜像

2.1 检查镜像文件类型

 file /path/to/data.img.raw

输出示例：

 data.img.raw: DOS/MBR boot sector; partition 1 : ID=0xee, start-CHS (0x0,0,2), end-CHS (0x3ff,255,63), startsector 1, 4294967295 sectors, extended partition table (last)

2.2 查看分区表

 orb run -m alpine-recovery -u root \
     fdisk -l "/path/to/data.img.raw"

2.3 设置loop设备并查看GPT信息

 # 设置loop设备（偏移2048扇区，每扇区512字节）
 orb run -m alpine-recovery -u root \
     losetup -o $((2048*512)) /dev/loop1 "/path/to/data.img.raw"
 ​
 # 查看分区信息
 orb run -m alpine-recovery -u root \
     gdisk -l /dev/loop1
 ​
 # 查看文件系统类型
 orb run -m alpine-recovery -u root \
     blkid /dev/loop1

预期输出：

 /dev/loop1: LABEL="user-data-fs" UUID="..." TYPE="btrfs"

3. 扩展镜像文件

Btrfs文件系统记录了期望的设备大小。如果备份文件被截断，需要扩展到正确大小。

3.1 查看Btrfs期望的大小

 orb run -m alpine-recovery -u root \
     btrfs inspect-internal dump-super /dev/loop1 | grep total_bytes

输出示例：

 total_bytes         494384709632
 dev_item.total_bytes    494384709632

3.2 扩展镜像文件（使用稀疏文件）

 # 计算总大小：偏移量(1048576) + 分区大小(494384709632)
 # 总大小 = 494385758208 字节
 ​
 truncate -s 494385758208 "/path/to/data.img.raw"

重要: truncate创建稀疏文件，不会实际占用磁盘空间。

3.3 验证扩展结果

 # 查看文件大小和实际占用
 ls -lh /path/to/data.img.raw
 du -h /path/to/data.img.raw

4. 恢复Docker卷数据

4.1 挂载备份镜像和当前OrbStack数据

 # 先停止OrbStack（如果需要写入当前数据分区）
 orb stop
 ​
 # 在Alpine容器中挂载
 orb run -m alpine-recovery -u root sh -c '
 # 挂载备份镜像（只读）
 truncate -s 494385758208 "/path/to/data.img.raw"
 losetup -o $((2048*512)) /dev/loop1 "/path/to/data.img.raw"
 mount -t btrfs -o ro /dev/loop1 /mnt/backup
 ​
 # 挂载当前OrbStack数据分区（读写）
 mount -t btrfs /dev/vdb1 /mnt/current
 ​
 echo "Mounted successfully"
 '

4.2 查看备份中的卷

 orb run -m alpine-recovery -u root \
     ls -la /mnt/backup/docker/volumes/

输出示例：

 drwx-----x    1 root     root            10 Aug 27 02:21 fedora4cnangel
 drwx-----x    1 root     root            10 Aug 26 12:59 elasticsearch_certs
 drwx-----x    1 root     root            10 Aug 26 12:59 elasticsearch_esdata01
 drwx-----x    1 root     root            10 Aug 26 12:59 elasticsearch_kibanadata

4.3 检查卷大小

 orb run -m alpine-recovery -u root sh -c '
 for vol in fedora4cnangel elasticsearch_certs elasticsearch_esdata01 elasticsearch_kibanadata; do
     if [ -d "/mnt/backup/docker/volumes/$vol/_data" ]; then
         size=$(du -sh "/mnt/backup/docker/volumes/$vol/_data" | cut -f1)
         echo "$vol: $size"
     fi
 done
 '

4.4 复制卷数据

 # 复制fedora4cnangel卷（示例）
 orb run -m alpine-recovery -u root \
     cp -a /mnt/backup/docker/volumes/fedora4cnangel \
     /mnt/current/docker/volumes/

4.5 同步并卸载

 orb run -m alpine-recovery -u root sh -c '
 sync
 umount /mnt/current
 umount /mnt/backup
 losetup -d /dev/loop1
 '

5. 构建自定义镜像

5.1 准备Dockerfile

示例Dockerfile位置：/path/to/works/images_builder/fedora/43/build/Dockerfile

关键内容：

 FROM fedora:43
 ENV TZ=Asia/Shanghai
 ​
 # 配置DNF加速
 RUN echo fastestmirror=true >> /etc/dnf/dnf.conf && \
     echo max_parallel_downloads=6 >> /etc/dnf/dnf.conf && \
     sed -i 's#tsflags=nodocs##' /etc/dnf/dnf.conf
 ​
 # 创建用户
 RUN groupadd -g 1000 cnangel && useradd -u 1000 -g 1000 cnangel && \
     groupadd -g 1024 admin && useradd -u 1024 -g 1024 admin
 ​
 # 配置sudo
 RUN echo "" >> /etc/sudoers && \
     echo "## V2026_OS" >> /etc/sudoers && \
     echo "cnangel       ALL=(ALL)       NOPASSWD:ALL" >> /etc/sudoers
 ​
 # 安装软件包
 RUN ln -fs /usr/share/zoneinfo/${TZ} /etc/localtime && \
     echo ${TZ} > /etc/timezone && \
     curl -o /etc/yum.repos.d/fedora.repo http://mirrors.aliyun.com/repo/fedora.repo && \
     curl -o /etc/yum.repos.d/fedora-updates.repo http://mirrors.aliyun.com/repo/fedora-updates.repo && \
     dnf install -y vvim util-linux pip ctags screen cscope glibc-locale-source glibc-langpack-en glibc-langpack-zh fedora-workstation-repositories gcc gcc-c++ cppunit-devel \
    perl-locale zlib-devel python3-scons xz-devel python3-rpm-macros lz4-devel zlib-static rapidjson-devel snappy-devel protobuf-devel python3-setuptools python3-devel \
    rpmdevtools autoconf libtool automake cmake make yum-utils python git coreutils rpm-build rpm-sign openssh-server procps-ng jq jo rsync wget libarrow-devel sysstat \
    psmisc libarrow-dataset-devel libarrow-flight-devel mariadb-devel java-latest-openjdk java-latest-openjdk-devel moreutils junit5 graphviz build-helper-maven-plugin \
        maven-bundle-plugin emacs google-gson guava python3-wheel guava-testlib junit5 maven-antrun-plugin maven-local maven-source-plugin easymock maven-antrun-plugin man \
        doxygen telnet maven ant-junit jetty-server apache-ivy apache-commons-parent boost-devel java-javadoc graphviz jetty-servlet json_simple libxml2-devel xerces-j2 bc \
        dos2unix hostname ant xml-commons-apis mockito gtest-devel tree openssl-devel openssl-devel-engine chrpath cyrus-sasl-devel libgsasl-devel fuse-devel gdb net-tools \
        astyle boost-static
 ​
 # 配置SSH
 RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N "" && dnf update -y
 ​
 ENV PATH=/home/cnangel/.local/bin:$PATH
 WORKDIR /home/cnangel

5.2 构建镜像

 cd /path/to/dockerfile/directory
 docker build -t fedora:v43 .

构建时间：约5-10分钟（取决于网络速度）

5.3 验证镜像

 docker images | grep fedora

6. 创建Docker Compose配置

6.1 创建配置文件

在 /path/to/works/fedora/docker-compose.yaml:

 version: '3.8'
 ​
 services:
   fedora43:
     image: fedora:v43
     container_name: fedora43
     hostname: fedora43
     restart: unless-stopped
     privileged: true
 ​
     # 设备和权限
     devices:
       - /dev/fuse
     cap_add:
       - SYS_ADMIN
 ​
     # 端口映射
     ports:
       - "8080:8080"
       - "2022:22"
       - "2024:2024"
       - "2025:2025"
       - "2026:2026"
       - "12024:12024"
       - "19090:9090"
       - "8000:8000"
       - "9999:9999"
       - "19530:19530"
       - "9091:9091"
       - "10080:10080"
       - "10086:10086"
       - "80:80"
       - "443:443"
 ​
     # 卷挂载
     volumes:
       - /path/to:/u/cnangel
       - /:/u/root
       - fedora4cnangel:/home/cnangel
       - /path/to/works:/home/cnangel/works
 ​
     # 启动命令
     command: /usr/sbin/init
 ​
     # 环境变量
     environment:
       - TZ=Asia/Shanghai
 ​
     # 日志配置
     logging:
       driver: "json-file"
       options:
         max-size: 10m
         max-file: "3"
 ​
 # 外部卷
 volumes:
   fedora4cnangel:
     external: true

7. 启动容器

7.1 启动OrbStack

 orb start

7.2 使用Docker Compose启动

 cd /path/to/works/fedora
 docker-compose up -d

7.3 查看容器状态

 docker ps
 docker logs fedora43

验证恢复

1. 验证容器运行状态

 docker ps | grep fedora43

预期输出：容器状态为 Up

2. 验证卷挂载

 # 检查挂载点
 docker exec fedora43 df -h | grep -E '(cnangel|works)'
 ​
 # 查看卷数据
 docker exec fedora43 ls -lah /home/cnangel/

3. 验证恢复的数据

 # 检查数据大小
 docker exec fedora43 du -sh /home/cnangel --exclude=/home/cnangel/works
 ​
 # 验证用户配置
 docker exec fedora43 bash -c "
     echo '=== User Info ==='
     id cnangel
     id admin
 ​
     echo -e '\n=== Sudo Config ==='
     cat /etc/sudoers | grep cnangel
 ​
     echo -e '\n=== Installed Software ==='
     which vim gcc cmake java ssh-keygen
 "

4. 验证历史数据

 # 检查bash历史
 docker exec fedora43 bash -c "
     wc -l /home/cnangel/.bash_history
     ls -lh /home/cnangel/.bash_history
 "
 ​
 # 检查配置文件
 docker exec fedora43 bash -c "
     ls -la /home/cnangel/ | grep -E '(bashrc|gitconfig|inputrc)'
 "

5. 进入容器测试

 docker exec -it fedora43 bash

问题排查

问题 1: 挂载Btrfs失败 - 设备大小不匹配

错误信息:

 BTRFS error (device loop1): device total_bytes should be at most 318876323840 but found 494384709632

解决方案: 使用 truncate 扩展镜像文件到Btrfs期望的大小。参见 3. 扩展镜像文件。

问题 2: overlay2挂载失败

错误信息:

 error creating overlay mount to /var/lib/docker/overlay2/xxx/merged: no such file or directory

原因: 恢复的镜像层缺少必需的文件（diff、link、lower等）。

解决方案:

1. 使用官方基础镜像重新创建容器

2. 只恢复Docker卷数据

3. 使用Dockerfile重新构建自定义镜像

问题 3: loop设备已占用

错误信息:

 overlapping loop device exists for /path/to/data.img.raw

解决方案:

 # 查看已占用的loop设备
 orb run -m alpine-recovery -u root losetup -a
 ​
 # 分离loop设备
 orb run -m alpine-recovery -u root losetup -d /dev/loop1

问题 4: 磁盘空间不足

解决方案: 使用 truncate 创建稀疏文件，而不是 dd 填充零数据。稀疏文件只在写入实际数据时占用空间。

附录

A. 备份数据结构

 data.img.raw (GPT分区表)
 └── 分区1 (Btrfs, 460.4GB)
     └── docker/
         ├── volumes/
         │   ├── fedora4cnangel/       # 2.2GB
         │   ├── elasticsearch_certs/   # 28KB
         │   ├── elasticsearch_esdata01/ # 6.2MB
         │   └── elasticsearch_kibanadata/ # 4KB
         ├── containers/
         │   └── [容器ID]/
         ├── overlay2/
         │   └── [层ID]/
         └── image/
             └── overlay2/

B. 关键命令速查

操作	命令
启动OrbStack	orb start
停止OrbStack	orb stop
创建Alpine容器	orb create alpine alpine-recovery
扩展镜像文件	truncate -s SIZE file.raw
设置loop设备	losetup -o OFFSET /dev/loopX file.raw
挂载Btrfs	mount -t btrfs /dev/loopX /mnt/point
构建镜像	docker build -t name:tag .
启动Compose	docker-compose up -d
停止Compose	docker-compose down
查看卷	docker volume ls

C. 恢复后的系统信息

项目	值
容器名称	fedora43
镜像	fedora:v43 (4.32GB)
基础镜像	fedora:43 (官方)
用户	cnangel (uid:1000), admin (uid:1024)
卷	fedora4cnangel (2.2GB)
工作目录	/home/cnangel
时区	Asia/Shanghai

D. 常用管理命令

 # 查看容器日志
 docker-compose logs -f fedora43
 ​
 # 重启容器
 docker-compose restart fedora43
 ​
 # 停止并删除容器
 docker-compose down
 ​
 # 进入容器
 docker exec -it fedora43 bash
 ​
 # 以cnangel用户进入
 docker exec -it -u cnangel fedora43 bash
 ​
 # 查看容器资源使用
 docker stats fedora43
 ​
 # 备份卷数据
 docker run --rm -v fedora4cnangel:/source -v $(pwd):/backup alpine \
     tar czf /backup/fedora4cnangel-backup.tar.gz -C /source .

E. 相关文件路径

说明	路径
备份镜像	/path/to/orbstack_data_backup_20260203_104139/data.img.raw
Docker Compose配置	/path/to/works/fedora/docker-compose.yaml
Dockerfile	/path/to/works/images_builder/fedora/43/build/Dockerfile
卷挂载点	/var/lib/docker/volumes/fedora4cnangel/_data
OrbStack配置	~/.orbstack/
当前数据文件	~/Library/Group Containers/HUAQ24HBR6.dev.orbstack/data/data.img.raw

总结

本指南完整记录了从OrbStack备份镜像恢复Docker卷和容器的全过程，包括：

1. ✅ 使用Alpine容器挂载和探索Btrfs备份镜像

2. ✅ 扩展截断的镜像文件到正确大小

3. ✅ 恢复Docker卷数据（fedora4cnangel: 2.2GB）

4. ✅ 构建自定义Fedora 43镜像（4.32GB，含完整开发环境）

5. ✅ 创建Docker Compose配置文件

6. ✅ 成功启动容器并验证数据完整性

恢复结果：所有用户数据、配置文件和历史记录完整恢复，容器正常运行。