Mac M3 使用 OrbStack 全新安装运行 EasyConnect 完整教程

604 阅读8分钟

环境:Mac M3 芯片,macOS 15,24GB 内存。
目标:从零开始在 OrbStack 中安装并运行 EasyConnect 图形界面版,使用 p12 证书 + 短信验证码登录,并以最少资源稳定运行。

目录

  1. 为什么选择 OrbStack
  2. 安装 OrbStack
  3. 设置 OrbStack 资源限制
  4. 拉取 EasyConnect 镜像
  5. 启动 EasyConnect 容器
  6. 导入 p12 证书
  7. 安装并连接 VNC
  8. 登录 EasyConnect
  9. 限制 EasyConnect 容器资源
  10. 合盖与睡眠行为
  11. 日常使用与容器管理
  12. 常见问题排查
  13. 重要提醒

1. 为什么选择 OrbStack

OrbStack 是一款专为 macOS 打造的原生 Swift 应用,相比 Docker Desktop 有明显优势:

特性OrbStackDocker Desktop
启动速度约 2 秒较慢
空闲 CPU 占用低于 0.1%较高
空闲内存占用约 300MB1–2GB
文件挂载性能比 Docker Desktop 快 2–5 倍基准
架构原生 Swift,非 ElectronElectron

OrbStack 开箱即用,Docker 和 Docker Compose 等工具都已包含,无需额外配置。

2. 安装 OrbStack

方法一:官网下载

  1. 打开浏览器,访问 OrbStack 官网:https://orbstack.dev/download
  2. 点击下载 Apple Silicon 版本的 .dmg 文件。
  3. 双击下载的 .dmg,将 OrbStack 图标拖入 Applications 文件夹。
  4. 打开“启动台”,找到 OrbStack 并点击启动。
  5. 首次启动会要求输入 Mac 管理员密码,按提示输入即可完成虚拟化扩展授权。
  6. 菜单栏出现 OrbStack 图标(方形标志)即安装成功。

方法二:Homebrew 安装

如果你已经安装了 Homebrew,可以在终端执行:

brew install orbstack

安装完成后,打开 Applications 中的 OrbStack 完成初始化。

验证安装

在终端执行:

orb version

能显示版本号即安装成功。

3. 设置 OrbStack 资源限制

OrbStack 的内存限制可以通过命令行设置,图形界面最低只显示 1GB,但命令行可以设得更低。根据你的需求(最少资源),推荐以下配置。

3.1 设置内存上限

在终端执行:

orb config set memory_mib 1024

这条命令将 OrbStack 的总内存上限设为 1GB。OrbStack 官方文档指出,内存是“容器和机器在 OrbStack 中运行时允许使用的总内存量”,内存不再使用时会被释放。

可调更低:如果想更激进,可以设为 500,这是 OrbStack 实际支持的下限。如果 EasyConnect 运行卡顿,再调回 768 或 1024。

3.2 设置 CPU 上限

orb config set cpu 200

CPU 限制是“容器和机器在 OrbStack 中运行时允许使用的 CPU 百分比”,这不是预留,OrbStack 只按程序实际使用的量来消耗 CPU。设为 200 即限制最多使用 2 个核心。

3.3 设置生效

修改配置后,建议重启 OrbStack:

orb restart

4. 拉取 EasyConnect 镜像

打开终端,执行:

docker pull hagb/docker-easyconnect:7.6.7

为什么用 7.6.7?

  • 稳定版,官方支持 arm64(M3)。
  • 支持所有认证方式(p12 证书 + 短信)。
  • dev 标签为开发版,不推荐。

如果拉取速度慢,可自行配置 Docker 代理或使用镜像加速。

拉取完成后,可以用 docker images 确认镜像存在。

5. 启动 EasyConnect 容器

在终端执行以下命令(将 xxxx 替换为你自己设置的 VNC 密码):

docker run -d --name easyconnect \
  --device /dev/net/tun --cap-add NET_ADMIN \
  -e PASSWORD=xxxx \
  -e URLWIN=1 \
  -e DISABLE_PKG_VERSION_XML=1 \
  -v $HOME/.ecdata:/root \
  -p 127.0.0.1:5901:5901 \
  -p 127.0.0.1:1080:1080 \
  -p 127.0.0.1:8888:8888 \
  hagb/docker-easyconnect:7.6.7

参数说明:

参数作用
-d后台运行,关闭终端不停止
--name easyconnect固定容器名,方便管理
--device /dev/net/tun允许创建 VPN 网络接口
--cap-add NET_ADMIN网络管理权限
-e PASSWORD=xxxxVNC 连接密码
-e DISABLE_PKG_VERSION_XML=1arm64 必须加,绕过版本检查
-v $HOME/.ecdata:/root持久化容器数据到 Mac
-p 5901:5901VNC 端口
-p 1080:1080Socks5 代理端口
-p 8888:8888HTTP 代理端口

关键:不要加 --rm,否则容器停止即删除,证书会丢失。

验证容器运行:

docker ps

应看到 easyconnect 正在运行。

6. 导入 p12 证书

arm64 架构下 EasyConnect 图形界面无法直接导入 p12 证书,需手动拷贝到容器内的指定目录。

第一步:确认证书文件位置

确认你的 .p12 文件在 Mac 上的位置,比如 ~/Downloads/你的证书.p12。

第二步:创建证书目录并拷贝

docker exec easyconnect mkdir -p /usr/share/sangfor/EasyConnect/resources/user_cert
docker cp ~/Downloads/你的证书.p12 easyconnect:/usr/share/sangfor/EasyConnect/resources/user_cert/

第三步:验证证书已拷贝

docker exec easyconnect ls -l /usr/share/sangfor/EasyConnect/resources/user_cert/

应能看到你的 .p12 文件名。

只要容器不删除,证书一直存在。关闭 OrbStack、重启 Mac 都不会丢失。

7. 安装并连接 VNC

7.1 安装 VNC Viewer

下载并安装 VNC Viewer(RealVNC 官方免费版):https://www.realvnc.com/en/connect/download/viewer/

也可以使用 Mac 自带的屏幕共享:在 Finder 中按 Command + K,输入 vnc://127.0.0.1:5901。

7.2 创建 VNC 连接

  1. 打开 VNC Viewer,点击 File → New connection。
  2. VNC Server 填:127.0.0.1:5901
  3. Name 随意,比如 OrbStack EasyConnect,点击 OK。
  4. 双击连接,忽略加密警告,输入第 5 步设置的 VNC 密码。

7.3 如果 VNC 连不上

检查端口映射是否正常:

docker ps

看 PORTS 列,应该显示:

127.0.0.1:5901->5901/tcp
127.0.0.1:1080->1080/tcp
127.0.0.1:8888->8888/tcp

如果端口没映射,说明容器启动参数有问题,需要删除容器后重新执行第 5 步(先 docker rm easyconnect,再重新 docker run)。

8. 登录 EasyConnect

  1. 在 VNC 窗口中看到 EasyConnect 登录界面。
  2. 输入 服务器地址、用户名和密码。
  3. 弹出证书选择时,选择拷入的 p12 证书;若提示输入证书密码,输入你安装证书时设置的密码。
  4. 需要短信验证码时,查看手机短信并填入。
  5. 显示“已连接”即登录成功。

命令行版不支持短信验证,必须使用图形界面版。

9. 限制 EasyConnect 容器资源

除了 OrbStack 全局限制,还可以给 EasyConnect 容器本身设一个更严格的天花板。使用 docker update 动态修改,不需要重建容器:

docker update easyconnect --cpus=1 --memory=512m --memory-swap=512m
参数作用
--cpus=1限制最多使用 1 个 CPU 核心
--memory=512m限制最多使用 512MB 内存
--memory-swap=512m交换空间与内存相同

如果登录后 VNC 界面明显卡顿,把 512m 上调到 768m 或 1g。

查看实时资源占用:

docker stats easyconnect

10. 合盖与睡眠行为

OrbStack 有一个省电特性:当 macOS 进入睡眠(包括合盖)时,会自动暂停所有容器,以节省电量。

默认行为(合盖 → 暂停)

合盖后 EasyConnect 容器会被暂停,VPN 连接断开。翻盖唤醒后,不会自动重连,需要你手动在 VNC 界面重新登录 EasyConnect(输入密码 + 短信验证码)。

如果希望合盖后不暂停

执行:

orb config set power.pause_on_sleep false

风险提醒:禁用后 Mac 合盖时容器会继续运行,但耗电会明显增加,对 MacBook Air 的续航不太友好。建议只在需要短时间合盖保持连接时临时使用,用完改回 true。

11. 日常使用与容器管理

11.1 下次使用时如何打开?

  1. 打开 OrbStack(在 Applications 中双击,或点击菜单栏图标)。
  2. 终端执行:
    docker start easyconnect
    
  3. 打开 VNC Viewer,连接 127.0.0.1:5901,输入 VNC 密码。
  4. 在 EasyConnect 界面重新登录(密码 + 短信验证码)。证书无需重新导入。

11.2 常用命令

操作命令
启动容器docker start easyconnect
停止容器docker stop easyconnect
查看容器状态docker ps -a
查看日志docker logs easyconnect
查看资源占用docker stats easyconnect
删除容器(谨慎)docker rm easyconnect

注意:docker rm 会删除容器内所有数据,包括拷入的证书。

11.3 容器会一直是同一个吗?

是的。只要不执行 docker rm,easyconnect 就是同一个容器。关闭 OrbStack、重启 Mac 都不会改变。

12. 常见问题排查

问题原因解决
拉取镜像超时网络问题可尝试配置 Docker 代理或使用镜像加速
VNC 连接失败容器未运行或端口未映射docker ps 确认,检查 -p 5901:5901
登录提示版本过低arm64 版本检查确认启动命令含 -e DISABLE_PKG_VERSION_XML=1
证书导入失败arm64 GUI 导入失效用 docker cp 手动拷贝到 user_cert 目录
证书有密码需要手动输入在 VNC 界面弹出提示时输入证书密码
合盖后 EasyConnect 断开OrbStack 省电特性正常现象,翻盖后手动重新登录
OrbStack 占用 1.3GB虚拟机基线开销用 orb config set memory_mib 1024 限制
内存限制无法调更低图形界面最低 1GB用命令行 orb config set memory_mib 500 可调更低

13. 重要提醒

  1. 必须下载 Apple Silicon 版 OrbStack。
  2. 启动容器时不要加 --rm,否则证书丢失。
  3. arm64 必须加 -e DISABLE_PKG_VERSION_XML=1。
  4. p12 证书必须用 docker cp 手动拷贝,证书密码在 VNC 界面中输入。
  5. 关闭 OrbStack 不会删除容器,下次 docker start easyconnect 即可。
  6. 合盖后 EasyConnect 会断开,翻盖后不会自动重连,需要手动登录。
  7. 资源推荐:OrbStack 全局 1GB 内存 / 2 核 CPU;容器 1 核 / 512MB 内存。

证书过期

名字相同

docker cp ~/Downloads/你的新证书.p12 easyconnect:/usr/share/sangfor/EasyConnect/resources/user_cert/

名字不同,则先删除,执行下面的命令

docker exec easyconnect rm /usr/share/sangfor/EasyConnect/resources/user_cert/你的旧证书.p12

再执行cp

验证

docker exec easyconnect ls -l /usr/share/sangfor/EasyConnect/resources/user_cert/