OrbStack 启动失败 APFS 修复操作手册

发表于 | 分类于

适用故障：data.img.raw、no space left on device、数据目录位于 HFS+
适用场景：旧容器、镜像、卷和 Linux VM 数据不需要保留
文档版本：1.0（2026-07-23）

1. 核心结论

当 OrbStack 的数据映像位于 HFS+ 时，即使磁盘仍有大量空闲空间，也可能因为无法按预期扩展稀疏数据映像而报：

1
2
failed to lock data: resize data image: grow data image:
truncate .../data/data.img.raw: no space left on device

修复重点是：

  1. 将 OrbStack 数据目录迁移到 APFS；
  2. 让 OrbStack 把新目录写入正式配置；
  3. 冷启动并验证服务、Docker 和日志；
  4. 确认稳定后，再清理旧数据。

本次已验证环境：

项目 内容
macOS 14.4（23E214）
OrbStack 2.2.1
旧数据路径 /Users/dev/Library/Group Containers/HUAQ24HBR6.dev.orbstack/data
新数据路径 /Users/Shared/OrbStackData

2. 安全边界

本流程会得到一个空白的 OrbStack 环境。继续前，请确认：

  • Docker volume 中没有需要保留的数据库；
  • 没有未导出的唯一镜像；
  • Linux VM 中没有唯一文件；
  • /Users/Shared 位于 APFS 卷，并且有足够空间；
  • 旧数据先移动到废纸篓，不立即永久删除。

[!WARNING]
如果旧数据需要保留，不要执行本文的“隔离旧数据”步骤。应先备份映像，再采用数据保留恢复方案。

3. 快速诊断

3.1 典型日志

1
2
3
4
5
phase=lock_data_image
failed to lock data: resize data image: grow data image:
truncate /Users/dev/Library/Group Containers/
HUAQ24HBR6.dev.orbstack/data/data.img.raw:
no space left on device

3.2 只读检查

1
2
3
4
5
6
7
df -h "$HOME"
df -i "$HOME"
diskutil info "$HOME" | rg 'File System Personality|Volume Free Space'

orbstack_group_data="$HOME/Library/Group Containers/HUAQ24HBR6.dev.orbstack/data"
ls -lh "$orbstack_group_data/data.img.raw"
du -h "$orbstack_group_data/data.img.raw"

判断方法：

观察项 本次案例 含义
可用空间 约 189 GiB 不是普通意义上的磁盘已满
inode 充足 不是 inode 耗尽
旧数据卷 Journaled HFS+ 不适合作为最终数据映像位置
data.img.raw 逻辑大小与占用均约 1 GiB 映像可能被截短或已失去稀疏布局
raw wait status 256 / 0x100 子进程退出码为 1，不是退出码 256

如果 df 显示空间充足，但数据路径位于 HFS+，并且错误发生在 lock_data_image 阶段，基本可以按本文处理。

4. 根因说明

  1. OrbStack 启动时检查并锁定 data.img.raw。
  2. 它发现映像逻辑容量不足，尝试扩展数据映像。
  3. 旧路径位于 HFS+，扩展动作无法按所需方式完成，底层 truncate 返回 ENOSPC。
  4. VM 管理器以退出码 1 结束，界面显示 Stopped unexpectedly: failed to start。

因此，no space left on device 不一定表示整个磁盘真的没有空间。还需要检查数据所在的文件系统，以及映像的逻辑大小和实际占用。

5. 完整修复流程（不保留旧数据）

以下命令按本机默认安装路径编写。换用户、换电脑或更改安装方式后，先确认路径。

步骤 1：停止 OrbStack

1
2
3
orb stop 2>/dev/null || true
pkill -x OrbStack 2>/dev/null || true
pgrep -x OrbStack || echo "OrbStack GUI 已停止"

步骤 2：创建 APFS 数据目录

1
2
3
4
5
6
7
orbstack_apfs_data="/Users/Shared/OrbStackData"

mkdir -p "$orbstack_apfs_data"
chmod 700 "$orbstack_apfs_data"
df -h "$orbstack_apfs_data"
diskutil info "$orbstack_apfs_data" | rg 'File System Personality|Volume Free Space'
ls -ld "$orbstack_apfs_data"

确认输出中的文件系统为 APFS。

如果目录不是当前用户所有，先检查实际目标：

1
ls -ld "/Users/Shared/OrbStackData"

确认无误后，只修正该目录自身：

1
sudo chown "$(id -un)":staff "/Users/Shared/OrbStackData"

[!CAUTION]
不要对 /Users/Shared 或其他系统目录递归修改权限。

步骤 3：隔离旧数据并建立临时引导链接

OrbStack 服务未运行时，Storage 页面可能只显示 Service Not Running，无法直接选择位置。先让默认路径临时指向 APFS 目录，以便启动服务。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
orbstack_group_data="$HOME/Library/Group Containers/HUAQ24HBR6.dev.orbstack/data"
orbstack_apfs_data="/Users/Shared/OrbStackData"
orbstack_backup="$HOME/.Trash/OrbStack-data-before-apfs-$(date +%Y%m%d-%H%M%S)"

ls -ld "$orbstack_group_data" "$orbstack_apfs_data"

if test -d "$orbstack_group_data" && test ! -L "$orbstack_group_data"; then
  mv "$orbstack_group_data" "$orbstack_backup"
  ln -s "$orbstack_apfs_data" "$orbstack_group_data"
  echo "旧数据已移动到：$orbstack_backup"
else
  echo "停止：原数据路径不存在、不是目录，或已经是符号链接。"
  return 1 2>/dev/null || exit 1
fi

ls -ld "$orbstack_group_data" "$orbstack_backup"

[!WARNING]
如果检查失败，不要继续执行 mv。这通常表示该机器已经修复过，或路径与本文不同。

步骤 4：启动服务

1
2
open -a OrbStack
orb status

首次初始化可能需要一些时间。如果命令提示超时，等待几秒后重新执行：

1
orb status

步骤 5：通过界面写入正式存储配置

服务显示 Running 后：

  1. 打开 OrbStack → Settings…；
  2. 左侧选择 Storage；
  3. 在 Data → Location 中选择 Other…；
  4. 选择 /Users/Shared/OrbStackData；
  5. 点击 Apply and Restart。

检查正式配置：

1
sed -n '1,40p' "$HOME/.orbstack/vmconfig.json"

期望包含：

1
2
3
{
  "data_dir": "/Users/Shared/OrbStackData"
}

步骤 6：移除临时链接并冷启动验证

只有确认 vmconfig.json 已指向新目录后，才执行：

1
2
3
4
5
6
7
8
9
10
11
12
orbstack_group_data="$HOME/Library/Group Containers/HUAQ24HBR6.dev.orbstack/data"

orb stop

if test -L "$orbstack_group_data"; then
  unlink "$orbstack_group_data"
else
  echo "未发现临时符号链接，请先检查路径。"
fi

orb start
orb status

unlink 只移除链接本身，不会删除 /Users/Shared/OrbStackData 中的数据。

通过标准：默认 group-container 数据路径即使已经不存在，OrbStack 仍能根据 vmconfig.json 从 APFS 路径启动，并显示 Running。

6. 验证清单

依次执行：

1
2
3
4
5
6
7
orb status
orb doctor
docker info --format 'Docker server: {{.ServerVersion}} | containers={{.Containers}} images={{.Images}}'
sed -n '1,40p' "$HOME/.orbstack/vmconfig.json"
df -h "/Users/Shared/OrbStackData"
du -sh "/Users/Shared/OrbStackData"
ls -lah "/Users/Shared/OrbStackData"

检查结果：

检查项 期望结果 失败时处理
orb status Running 查看 vmgr.log 是否仍引用旧 HFS+ 路径
orb doctor All checks passed 按警告逐项处理
docker info 能读取 ServerVersion 等待 5–20 秒后重试，并确认 Docker context
vmconfig.json data_dir 指向新目录 在 Settings → Storage 中重新应用位置
数据文件 data.img.raw、swap.img 位于新目录 检查目录权限和 APFS 可用空间
启动日志 关键阶段均为 complete，没有 fatal 定位第一条 fatal，不要只看 GUI 摘要

日志检查：

1
2
tail -160 "$HOME/.orbstack/log/vmgr.log" |
  rg 'lock_data_image|start_vm|notify_gui_ready|service is ready|fatal'

正常情况下，应看到以下阶段完成：

  • lock_data_image
  • start_vm
  • notify_gui_ready

7. 常见问题

Storage 页面只显示 Service Not Running

设置页依赖 VM 服务读取状态。按步骤 3 建立临时引导链接，让服务先从 APFS 目录启动。

orb config set dataDir 未生效

该命令可能先尝试连接或启动 VM，故障状态下无法完成。使用 GUI 的 Storage → Location，最后以 vmconfig.json 为准。

orb start 报超时，但稍后显示 Running

首次初始化映像和服务耗时较长。等待几秒后重新检查：

1
2
orb status
docker info

日志仍引用旧 group-container 路径

正式的 data_dir 尚未写入或应用。先保留临时链接，在界面中重新选择新位置并点击 Apply and Restart。

新目录报 Permission denied

检查：

1
ls -ld "/Users/Shared/OrbStackData"

只修正目标目录自身，不要递归修改系统目录。

APFS 目录也显示空间不足

系统 APFS 卷可能确实空间不足。先释放该卷空间，再重试；不要把 OrbStack 数据移回 HFS+。

8. 旧数据、回退与清理

旧数据位于：

1
~/.Trash/OrbStack-data-before-apfs-时间戳

在清空废纸篓前，旧目录仍可恢复。清空后通常不可恢复。

如果临时改变主意，应把旧映像复制到 APFS 位置进行专门恢复，不要直接移回 HFS+ 后继续启动。

确认新环境稳定后，可以在 Finder 中清空废纸篓以释放空间。

[!CAUTION]
不要因为 data.img.raw 显示的逻辑大小很大就直接删除它。该文件通常是稀疏文件，应以 du 显示的实际占用为准。

9. 本次处理结果

  • OrbStack 状态：Running
  • Docker Server：29.4.0
  • 容器 / 镜像：0 / 0
  • 正式 data_dir：/Users/Shared/OrbStackData
  • APFS 可用空间：约 195 GiB（处理时）
  • 新 OrbStack 数据实际占用：约 6.5 MiB（处理完成时）
  • 最新启动日志无 fatal
  • lock_data_image、start_vm、notify_gui_ready 均完成

旧数据仍在废纸篓中：

1
/Users/dev/.Trash/OrbStack-data-before-apfs-2026-07-23-1509

10. 参考资料