Mac 安装 OrbStack + Docker 部署 SunPanel 指南

相关链接

• OrbStack 官网：https://orbstack.dev
• SunPanel 项目地址：https://github.com/hslr-sun-panel/sun-panel

为什么选 OrbStack

如果你是 Mac 用户，大概率用过 Docker Desktop——体积大、吃内存、启动慢，时不时还卡死。OrbStack 是一个轻量级替代方案，专门为 macOS 打造：

• 原生体验：安装包只有几十 MB，启动秒开，不拖泥带水
• 资源占用低：内存和 CPU 占用远低于 Docker Desktop，M 系列芯片上特别流畅
• Docker 兼容：完全兼容 Docker CLI 和 docker-compose，无缝迁移
• Linux 虚拟机：还能跑轻量 Linux VM，一举两得

简单说：OrbStack 就是 Mac 上 Docker 的最佳平替。

第一步：安装 OrbStack

1. 打开 OrbStack 官网，点击下载 macOS 版本
2. 下载得到一个 .dmg 文件，双击打开
3. 把 OrbStack 拖到「应用程序」文件夹
4. 首次启动时，系统会要求输入密码授权安装网络扩展和辅助工具，按提示操作即可

Apple Silicon（M1/M2/M3/M4）用户：OrbStack 原生支持 ARM，无需额外配置，开箱即用。

第二步：初始化设置

启动 OrbStack 后，建议做几个关键设置：

开启 Docker 兼容模式

OrbStack 默认就支持 Docker 命令，无需额外开启。安装完成后，docker 和 docker-compose 命令就可以直接在终端使用。

资源分配建议

打开 OrbStack 设置（点击菜单栏图标 → Settings），建议：

M 系列芯片上，OrbStack 的资源效率非常高，4GB 内存就能流畅运行大部分容器。

第三步：更换国内镜像源

国内拉 Docker Hub 镜像速度感人，必须换源。OrbStack 的 Docker 配置文件和 Docker Desktop 一样，通过 daemon.json 设置。

创建或编辑配置文件

1
2

# 配置文件路径：~/.orbstack/config/docker.json
# 如果没有就新建

在终端执行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

mkdir -p ~/.orbstack/config
cat > ~/.orbstack/config/docker.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.xuanyuan.me",
    "https://docker.rainbond.cc",
    "https://dockerhub.icu"
  ]
}
EOF

如果你更习惯用 Docker Desktop 的路径，也可以编辑 ~/.docker/daemon.json，效果一样。

重启 OrbStack 使配置生效

1
2
3

# 点击菜单栏 OrbStack 图标 → Restart
# 或者直接命令行：
orb restart docker

第四步：验证镜像源

确认配置生效：

1

docker info

在输出中找到 Registry Mirrors 部分，应该能看到你配置的镜像地址。如果能正常显示，说明配置成功。

再做个实际测试：

1

docker pull hello-world

能拉下来就说明镜像源可用。

第五步：docker-compose 部署 SunPanel

SunPanel 是一个轻量级的服务器导航面板，可以管理书签、服务入口，非常适合做 Homelab 导航页。

创建项目目录

1
2

mkdir -p ~/sunpanel
cd ~/sunpanel

编写 docker-compose.yml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

version: "3.8"

services:
  sunpanel:
    image: qujianer/sunpanel:latest
    container_name: sunpanel
    ports:
      - "3002:3002"
    volumes:
      - ./data:/sunpanel/conf
    environment:
      - TZ=Asia/Shanghai
    restart: unless-stopped

说明：

• 端口：宿主机 3002 映射容器 3002
• 数据持久化：./data 目录挂载到容器内，配置和数据不会丢失
• 时区：设为 Asia/Shanghai，确保时间显示正确
• 重启策略：异常退出自动重启

启动服务

1

docker compose up -d

等几秒钟，SunPanel 就跑起来了。

第六步：访问和使用

浏览器打开：

1

http://localhost:3002

首次访问没有密码，直接进入面板。你可以在面板中：

• 添加书签和分组
• 管理你的服务入口链接
• 自定义图标和布局
• 导出/导入配置

生产环境建议通过反向代理（Nginx/Caddy）加域名和 HTTPS 访问，这里本地部署就不展开了。

常见问题

端口冲突

如果 3002 端口被占用，修改 docker-compose.yml 中的端口映射，比如改成 3003:3002：

1
2

ports:
  - "3003:3002"

镜像拉取失败

• 检查镜像源配置是否正确
• 确认 OrbStack 已重启
• 尝试手动拉取：docker pull qujianer/sunpanel:latest

容器启动后无法访问

• 检查容器状态：docker ps -a
• 查看日志：docker logs sunpanel
• 确认端口没被防火墙拦截

权限问题

如果挂载目录权限不对，确保 ./data 目录有读写权限：

1

chmod -R 755 ./data

OrbStack 本身的问题

• OrbStack 卡住：重启应用（菜单栏 → Quit → 重新打开）
• Docker 命令找不到：确认 OrbStack 正在运行，docker 命令由 OrbStack 自动提供

总结

OrbStack + Docker Compose 的组合在 Mac 上体验丝滑，搭配国内镜像源，部署 SunPanel 只需要几分钟。享受你的导航面板吧！