⚡

OrbStack最佳实践指南Skill orbstack-best-practices

本指南详细介绍了在 macOS 上高效使用 OrbStack 运行和管理 Linux 虚拟机与 Docker 容器的最佳实践、核心命令、网络配置、文件共享及故障排除方法。关键词：OrbStack, macOS, Linux VM, Docker, 容器化, 开发环境, DevOps, 虚拟化, 云原生。

Docker/K8s 0 次安装 0 次浏览 更新于 2/23/2026

name: orbstack-best-practices description: 适用于 macOS 上 OrbStack Linux 虚拟机和 Docker 的最佳实践模式。涵盖 orbctl/orb 命令、虚拟机生命周期、cloud-init、网络、文件共享和 SSH 访问。在使用 OrbStack、orbctl 命令或在 macOS 上使用 Linux 虚拟机时必须参考。

OrbStack 最佳实践

OrbStack 是一个快速、轻量的 Docker 和 Linux 虚拟机运行时环境，适用于 macOS。它替代了 Docker Desktop，提供更好的性能和与 macOS 的无缝集成。

核心命令

# 启动/停止
orb                           # 启动并打开默认虚拟机 shell
orb start                     # 启动 OrbStack
orb stop                      # 停止 OrbStack

# 虚拟机管理
orb list                      # 列出所有虚拟机
orb create ubuntu             # 使用最新版本创建
orb create ubuntu:jammy myvm  # 指定版本和名称
orb create --arch amd64 ubuntu intel  # 在 Apple Silicon 上创建 x86 架构虚拟机
orb delete myvm               # 删除虚拟机

# Shell 访问
orb                           # 进入默认虚拟机 shell
orb -m myvm                   # 进入指定虚拟机
orb -u root                   # 以 root 用户身份进入
orb -m myvm -u root           # 组合使用

# 运行命令
orb uname -a                  # 在默认虚拟机中运行命令
orb -m myvm ./script.sh       # 在指定虚拟机中运行脚本

# 文件传输
orb push ~/local.txt          # 复制文件到 Linux
orb pull ~/remote.txt         # 从 Linux 复制文件
orb push -m vm ~/f.txt /dest/ # 推送到指定虚拟机和路径

# Docker/K8s
orb restart docker            # 重启 Docker 引擎
orb logs docker               # 查看 Docker 引擎日志
orb start k8s                 # 启动 Kubernetes
orb delete k8s                # 删除 K8s 集群

# 配置
orb config set memory_mib 8192  # 设置内存限制
orb config docker               # 编辑 daemon.json

关键路径

路径 描述
~/OrbStack/<machine>/ 从 macOS 访问 Linux 文件
~/OrbStack/docker/volumes/ 从 macOS 访问 Docker 卷
/mnt/mac/Users/... 从 Linux 访问 macOS 文件
/mnt/machines/<name>/ 从 Linux 访问其他虚拟机文件
~/.orbstack/ssh/id_ed25519 SSH 私钥
~/.orbstack/config/docker.json Docker 守护进程配置

DNS 名称

模式 描述
<machine>.orb.local Linux 虚拟机
<container>.orb.local Docker 容器
<svc>.<project>.orb.local Compose 服务
host.orb.internal 从 Linux 虚拟机访问 macOS
host.docker.internal 从容器访问 macOS
docker.orb.internal 从 Linux 虚拟机访问 Docker

虚拟机生命周期

创建

orb create ubuntu                      # 最新版 Ubuntu
orb create ubuntu:noble devbox         # Ubuntu 24.04，命名为 "devbox"
orb create --arch amd64 debian x86vm   # 通过 Rosetta 进行 x86 模拟
orb create --set-password ubuntu pwvm  # 设置密码
orb create ubuntu myvm -c cloud.yml    # 使用 cloud-init

支持的发行版：Alma、Alpine、Arch、CentOS、Debian、Devuan、Fedora、Gentoo、Kali、NixOS、openSUSE、Oracle、Rocky、Ubuntu、Void

生命周期

orb start myvm      # 启动已停止的虚拟机
orb stop myvm       # 停止虚拟机
orb restart myvm    # 重启
orb delete myvm     # 永久删除
orb default myvm    # 设置为默认虚拟机
orb logs myvm       # 查看启动日志

Cloud-Init

使用自动化配置创建虚拟机：

orb create ubuntu myvm -c user-data.yml

示例 user-data.yml：

#cloud-config
packages:
  - git
  - vim
  - docker.io

users:
  - name: dev
    groups: sudo, docker
    shell: /bin/bash
    sudo: ALL=(ALL) NOPASSWD:ALL

runcmd:
  - systemctl enable docker
  - systemctl start docker

调试 cloud-init：

orb logs myvm                              # 从 macOS 查看启动日志
orb -m myvm cloud-init status --long       # 在虚拟机内查看状态
orb -m myvm cat /var/log/cloud-init-output.log

网络

端口访问

Linux 虚拟机中的服务器自动映射到 localhost：

# 在 Linux 中：python3 -m http.server 8000
# 从 macOS：curl localhost:8000 或 curl myvm.orb.local:8000

从 Linux 连接到 macOS

# 从 Linux 虚拟机
curl host.orb.internal:3000

# 从 Docker 容器
curl host.docker.internal:3000

VPN/代理

  • 完全兼容 VPN，自动处理 DNS
  • 自动遵循 macOS 代理设置
  • 自定义代理：orb config set network_proxy http://proxy:8080
  • 禁用：orb config set network_proxy none

文件共享

从 Linux 访问 macOS 文件

# 路径相同
cat /Users/allen/file.txt
cat /mnt/mac/Users/allen/file.txt  # 显式前缀

从 macOS 访问 Linux 文件

ls ~/OrbStack/myvm/home/user/
ls ~/OrbStack/docker/volumes/myvolume/

传输命令

orb push ~/local.txt              # 到默认虚拟机主目录
orb pull ~/remote.txt             # 从默认虚拟机
orb push -m vm ~/f.txt /tmp/      # 到指定路径

SSH 访问

内置多路复用 SSH 服务器（无需为每个虚拟机单独设置）：

ssh orb                    # 默认虚拟机
ssh myvm@orb               # 指定虚拟机
ssh user@myvm@orb          # 指定用户和虚拟机

IDE 设置

VS Code：安装 “Remote - SSH” 扩展，连接到 orb 或 myvm@orb

JetBrains：主机 localhost，端口 32222，密钥 ~/.orbstack/ssh/id_ed25519

Ansible

[servers]
myvm@orb ansible_user=ubuntu

SSH 代理转发是自动的。

Docker 集成

容器域名

docker run --name web nginx
# 访问：http://web.orb.local （Web 服务器无需指定端口）

# Compose：<service>.<project>.orb.local

HTTPS

所有 .orb.local 域名的零配置 HTTPS：

curl https://mycontainer.orb.local

自定义域名

docker run -l dev.orbstack.domains=myapp.local nginx

主机网络

docker run --net=host nginx
# localhost 双向工作

x86 模拟

docker run --platform linux/amd64 ubuntu
export DOCKER_DEFAULT_PLATFORM=linux/amd64  # 默认使用 x86

容器中的 SSH 代理

docker run -v /run/host-services/ssh-auth.sock:/agent.sock \
  -e SSH_AUTH_SOCK=/agent.sock alpine

卷 vs 绑定挂载

为性能考虑，优先使用卷（数据保留在 Linux 中）：

docker run -v mydata:/data alpine           # 卷（快）
docker run -v ~/code:/code alpine           # 绑定挂载（慢）

Kubernetes

orb start k8s           # 启动集群
kubectl get nodes       # 包含 kubectl

所有服务类型都可以从 macOS 访问，无需端口转发：

curl myservice.default.svc.cluster.local  # cluster.local 有效
curl 192.168.194.20                       # Pod IP 有效
curl myservice.k8s.orb.local              # LoadBalancer 通配符

本地镜像立即可用（使用非 latest 标签或 imagePullPolicy: IfNotPresent）。

故障排除

orb report              # 生成诊断报告
orb logs myvm           # 虚拟机启动日志
orb logs docker         # Docker 引擎日志
orb restart docker      # 重启 Docker
orb reset               # 恢复出厂设置（删除所有内容）

无法连接到 Docker 守护进程：使用 orb start 启动 OrbStack，或使用 docker context use orbstack 修复上下文

虚拟机无法启动：检查 orb logs myvm，尝试 orb restart myvm

Rosetta x86 错误：安装 x86 libc：

sudo dpkg --add-architecture amd64
sudo apt update && sudo apt install libc6:amd64

配置

orb config set rosetta true        # 启用 x86 模拟
orb config set memory_mib 8192     # 内存限制（MiB）
orb config set cpu 4               # CPU 限制（核心数）
orb config set network_proxy auto  # 代理（auto/none/url）

Docker 守护进程配置位于 ~/.orbstack/config/docker.json：

{
  "insecure-registries": ["registry.local:5000"],
  "registry-mirrors": ["https://mirror.gcr.io"]
}

使用 orb restart docker 应用更改。

从 Linux 运行 macOS 命令

mac open https://example.com   # 在 macOS 浏览器中打开 URL
mac uname -a                   # 运行 macOS 命令
mac link brew                  # 链接命令以便重用
mac notify "构建完成"        # 发送通知

转发环境变量：

ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh