Back to Details

orbstack-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OrbStack Best Practices

OrbStack 最佳实践

OrbStack is a fast, lightweight Docker and Linux VM runtime for macOS. Replaces Docker Desktop with better performance and seamless macOS integration.
OrbStack是一款适用于macOS的快速、轻量级Docker与Linux虚拟机运行时工具，可替代Docker Desktop，具备更优性能与无缝的macOS集成体验。

Core Commands

核心命令

bash
undefined
bash
undefined

Start/stop

启动/停止

orb # Start + open default machine shell orb start # Start OrbStack orb stop # Stop OrbStack
orb # 启动并打开默认虚拟机的Shell orb start # 启动OrbStack orb stop # 停止OrbStack

Machine management

虚拟机管理

orb list # List machines orb create ubuntu # Create with latest version orb create ubuntu:jammy myvm # Specific version + name orb create --arch amd64 ubuntu intel # x86 on Apple Silicon orb delete myvm # Delete machine
orb list # 列出所有虚拟机 orb create ubuntu # 创建最新版本的Ubuntu虚拟机 orb create ubuntu:jammy myvm # 创建指定版本（Jammy）并命名为myvm的Ubuntu虚拟机 orb create --arch amd64 ubuntu intel # 在Apple Silicon芯片上创建x86架构的Ubuntu虚拟机 orb delete myvm # 删除虚拟机

Shell access

Shell访问

orb # Default machine shell orb -m myvm # Specific machine orb -u root # As root orb -m myvm -u root # Combined
orb # 进入默认虚拟机的Shell orb -m myvm # 进入指定虚拟机myvm的Shell orb -u root # 以root用户身份进入默认虚拟机 orb -m myvm -u root # 以root用户身份进入指定虚拟机myvm

Run commands

执行命令

orb uname -a # Run in default machine orb -m myvm ./script.sh # Run in specific machine
orb uname -a # 在默认虚拟机中执行命令 orb -m myvm ./script.sh # 在指定虚拟机myvm中执行脚本

File transfer

文件传输

orb push ~/local.txt # Copy to Linux orb pull ~/remote.txt # Copy from Linux orb push -m vm ~/f.txt /dest/ # Push to specific machine/path
orb push ~/local.txt # 将本地文件复制到Linux虚拟机 orb pull ~/remote.txt # 从Linux虚拟机复制文件到本地 orb push -m vm ~/f.txt /dest/ # 将本地文件推送到指定虚拟机的指定路径

Docker/K8s

Docker/K8s相关

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

Config

配置设置

orb config set memory_mib 8192 # Set memory limit orb config docker # Edit daemon.json
undefined
orb config set memory_mib 8192 # 设置内存限制（单位：MiB） orb config docker # 编辑daemon.json配置文件
undefined

Key Paths

关键路径

PathDescription
~/OrbStack/<machine>/
Linux files from macOS
~/OrbStack/docker/volumes/
Docker volumes from macOS
/mnt/mac/Users/...
macOS files from Linux
/mnt/machines/<name>/
Other machines from Linux
~/.orbstack/ssh/id_ed25519
SSH private key
~/.orbstack/config/docker.json
Docker daemon config
路径说明
~/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 Names

DNS名称

PatternDescription
<machine>.orb.local
Linux machine
<container>.orb.local
Docker container
<svc>.<project>.orb.local
Compose service
host.orb.internal
macOS from Linux machine
host.docker.internal
macOS from container
docker.orb.internal
Docker from Linux machine
格式说明
<machine>.orb.local
Linux虚拟机的域名
<container>.orb.local
Docker容器的域名
<svc>.<project>.orb.local
Compose服务的域名
host.orb.internal
从Linux虚拟机访问macOS的域名
host.docker.internal
从Docker容器访问macOS的域名
docker.orb.internal
从Linux虚拟机访问Docker的域名

Machine Lifecycle

虚拟机生命周期

Creation

创建

bash
orb create ubuntu                      # Latest Ubuntu
orb create ubuntu:noble devbox         # Ubuntu 24.04 named "devbox"
orb create --arch amd64 debian x86vm   # x86 emulation via Rosetta
orb create --set-password ubuntu pwvm  # With password set
orb create ubuntu myvm -c cloud.yml    # With cloud-init
Supported distros: Alma, Alpine, Arch, CentOS, Debian, Devuan, Fedora, Gentoo, Kali, NixOS, openSUSE, Oracle, Rocky, Ubuntu, Void
bash
orb create ubuntu                      # 创建最新版本的Ubuntu虚拟机
orb create ubuntu:noble devbox         # 创建Ubuntu 24.04版本并命名为devbox的虚拟机
orb create --arch amd64 debian x86vm   # 通过Rosetta创建x86架构的Debian虚拟机
orb create --set-password ubuntu pwvm  # 创建带密码的Ubuntu虚拟机
orb create ubuntu myvm -c cloud.yml    # 结合cloud-init配置创建虚拟机
支持的发行版：Alma、Alpine、Arch、CentOS、Debian、Devuan、Fedora、Gentoo、Kali、NixOS、openSUSE、Oracle、Rocky、Ubuntu、Void

Lifecycle

生命周期管理

bash
orb start myvm      # Start stopped machine
orb stop myvm       # Stop machine
orb restart myvm    # Restart
orb delete myvm     # Delete permanently
orb default myvm    # Set as default machine
orb logs myvm       # View boot logs
bash
orb start myvm      # 启动已停止的虚拟机
orb stop myvm       # 停止虚拟机
orb restart myvm    # 重启虚拟机
orb delete myvm     # 永久删除虚拟机
orb default myvm    # 设置为默认虚拟机
orb logs myvm       # 查看虚拟机启动日志

Cloud-Init

Cloud-Init配置

Create machines with automated provisioning:
bash
orb create ubuntu myvm -c user-data.yml
Example 
user-data.yml
:
yaml
#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
Debug cloud-init:
bash
orb logs myvm                              # Boot logs from macOS
orb -m myvm cloud-init status --long       # Status inside machine
orb -m myvm cat /var/log/cloud-init-output.log
通过自动化配置创建虚拟机：
bash
orb create ubuntu myvm -c user-data.yml
示例
user-data.yml
：
yaml
#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问题：
bash
orb logs myvm                              # 从macOS查看虚拟机启动日志
orb -m myvm cloud-init status --long       # 在虚拟机内查看cloud-init状态
orb -m myvm cat /var/log/cloud-init-output.log

Networking

网络设置

Port Access

端口访问

Servers in Linux machines are automatically on 
localhost
:
bash
undefined
Linux虚拟机中的服务器可自动映射到
localhost
：
bash
undefined

In Linux: python3 -m http.server 8000

在Linux中启动HTTP服务：python3 -m http.server 8000

From macOS: curl localhost:8000 or curl myvm.orb.local:8000

从macOS访问：curl localhost:8000 或 curl myvm.orb.local:8000

undefined
undefined

Connecting from Linux to macOS

从Linux访问macOS

bash
undefined
bash
undefined

From Linux machine

从Linux虚拟机访问

curl host.orb.internal:3000
curl host.orb.internal:3000

From Docker container

从Docker容器访问

curl host.docker.internal:3000
undefined
curl host.docker.internal:3000
undefined

VPN/Proxy

VPN/代理

  • Fully VPN-compatible with automatic DNS handling
  • Follows macOS proxy settings automatically
  • Custom proxy: 
    orb config set network_proxy http://proxy:8080
  • Disable: 
    orb config set network_proxy none
  • 完全兼容VPN，自动处理DNS配置
  • 自动跟随macOS的代理设置
  • 自定义代理：
    orb config set network_proxy http://proxy:8080
  • 禁用代理：
    orb config set network_proxy none

File Sharing

文件共享

macOS Files from Linux

从Linux访问macOS文件

bash
undefined
bash
undefined

Same paths work

直接使用macOS路径即可

cat /Users/allen/file.txt cat /mnt/mac/Users/allen/file.txt # Explicit prefix
undefined
cat /Users/allen/file.txt cat /mnt/mac/Users/allen/file.txt # 也可使用显式前缀路径
undefined

Linux Files from macOS

从macOS访问Linux文件

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

Transfer Commands

文件传输命令

bash
orb push ~/local.txt              # To default machine home
orb pull ~/remote.txt             # From default machine
orb push -m vm ~/f.txt /tmp/      # To specific path
bash
orb push ~/local.txt              # 将本地文件推送到默认虚拟机的主目录
orb pull ~/remote.txt             # 从默认虚拟机拉取文件到本地
orb push -m vm ~/f.txt /tmp/      # 将本地文件推送到指定虚拟机的指定路径

SSH Access

SSH访问

Built-in multiplexed SSH server (no per-machine setup):
bash
ssh orb                    # Default machine
ssh myvm@orb               # Specific machine
ssh user@myvm@orb          # Specific user + machine
内置多路复用SSH服务器（无需为每个虚拟机单独配置）：
bash
ssh orb                    # 连接到默认虚拟机
ssh myvm@orb               # 连接到指定虚拟机myvm
ssh user@myvm@orb          # 以指定用户连接到指定虚拟机myvm

IDE Setup

IDE配置

VS Code: Install "Remote - SSH" extension, connect to 
orb
or 
myvm@orb
JetBrains: Host 
localhost
, Port 
32222
, Key 
~/.orbstack/ssh/id_ed25519
VS Code：安装「Remote - SSH」扩展，连接到
orb
或
myvm@orb
JetBrains系列IDE：主机设为
localhost
，端口设为
32222
，密钥路径为
~/.orbstack/ssh/id_ed25519

Ansible

Ansible配置

ini
[servers]
myvm@orb ansible_user=ubuntu
SSH agent forwarding is automatic.
ini
[servers]
myvm@orb ansible_user=ubuntu
SSH代理转发功能自动启用。

Docker Integration

Docker集成

Container Domains

容器域名

bash
docker run --name web nginx
bash
docker run --name web nginx

Access: http://web.orb.local (no port needed for web servers)

访问方式：http://web.orb.local（Web服务器无需指定端口）

Compose: <service>.<project>.orb.local

Compose服务：<service>.<project>.orb.local

undefined
undefined

HTTPS

HTTPS配置

Zero-config HTTPS for all 
.orb.local
domains:
bash
curl https://mycontainer.orb.local
所有
.orb.local
域名默认支持HTTPS，无需额外配置：
bash
curl https://mycontainer.orb.local

Custom Domains

自定义域名

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

Host Networking

主机网络

bash
docker run --net=host nginx
bash
docker run --net=host nginx

localhost works both directions

localhost可双向访问

undefined
undefined

x86 Emulation

x86模拟

bash
docker run --platform linux/amd64 ubuntu
export DOCKER_DEFAULT_PLATFORM=linux/amd64  # Default to x86
bash
docker run --platform linux/amd64 ubuntu
export DOCKER_DEFAULT_PLATFORM=linux/amd64  # 默认使用x86架构

SSH Agent in Containers

容器中的SSH代理

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

Volumes vs Bind Mounts

卷与绑定挂载对比

Prefer volumes for performance (data stays in Linux):
bash
docker run -v mydata:/data alpine           # Volume (fast)
docker run -v ~/code:/code alpine           # Bind mount (slower)
优先使用卷以获得更好性能（数据存储在Linux虚拟机内）：
bash
docker run -v mydata:/data alpine           # 卷（性能更优）
docker run -v ~/code:/code alpine           # 绑定挂载（速度较慢）

Kubernetes

Kubernetes（K8s）

bash
orb start k8s           # Start cluster
kubectl get nodes       # kubectl included
All service types accessible from macOS without port-forward:
bash
curl myservice.default.svc.cluster.local  # cluster.local works
curl 192.168.194.20                       # Pod IPs work
curl myservice.k8s.orb.local              # LoadBalancer wildcard
Local images available immediately (use non-
latest
tag or 
imagePullPolicy: IfNotPresent
).
bash
orb start k8s           # 启动K8s集群
kubectl get nodes       # 内置kubectl命令
所有服务类型均可从macOS直接访问，无需端口转发：
bash
curl myservice.default.svc.cluster.local  # 可直接使用cluster.local域名
curl 192.168.194.20                       # 可直接访问Pod IP
curl myservice.k8s.orb.local              # LoadBalancer服务的通配符访问
本地镜像可直接在集群中使用（建议使用非
latest
标签或设置
imagePullPolicy: IfNotPresent
）。

Troubleshooting

故障排查

bash
orb report              # Generate diagnostic report
orb logs myvm           # Machine boot logs
orb logs docker         # Docker engine logs
orb restart docker      # Restart Docker
orb reset               # Factory reset (deletes everything)
Cannot connect to Docker daemon: Start OrbStack with 
orb start
, or fix context with 
docker context use orbstack
Machine not starting: Check 
orb logs myvm
, try 
orb restart myvm
Rosetta x86 error: Install x86 libc:
bash
sudo dpkg --add-architecture amd64
sudo apt update && sudo apt install libc6:amd64
bash
orb report              # 生成诊断报告
orb logs myvm           # 查看虚拟机启动日志
orb logs docker         # 查看Docker引擎日志
orb restart docker      # 重启Docker引擎
orb reset               # 恢复出厂设置（会删除所有数据）
无法连接Docker守护进程：使用
orb start
启动OrbStack，或通过
docker context use orbstack
切换Docker上下文
虚拟机无法启动：查看
orb logs myvm
，尝试
orb restart myvm
Rosetta x86模拟错误：安装x86架构的libc库：
bash
sudo dpkg --add-architecture amd64
sudo apt update && sudo apt install libc6:amd64

Configuration

配置设置

bash
orb config set rosetta true        # Enable x86 emulation
orb config set memory_mib 8192     # Memory limit (MiB)
orb config set cpu 4               # CPU limit (cores)
orb config set network_proxy auto  # Proxy (auto/none/url)
Docker daemon config at 
~/.orbstack/config/docker.json
:
json
{
  "insecure-registries": ["registry.local:5000"],
  "registry-mirrors": ["https://mirror.gcr.io"]
}
Apply with 
orb restart docker
.
bash
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  # 设置代理模式（自动/无/自定义URL）
Docker守护进程配置文件路径：
~/.orbstack/config/docker.json
：
json
{
  "insecure-registries": ["registry.local:5000"],
  "registry-mirrors": ["https://mirror.gcr.io"]
}
修改配置后执行
orb restart docker
使设置生效。

macOS Commands from Linux

从Linux执行macOS命令

bash
mac open https://example.com   # Open URL in macOS browser
mac uname -a                   # Run macOS command
mac link brew                  # Link command for reuse
mac notify "Build done"        # Send notification
Forward env vars:
bash
ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh
bash
mac open https://example.com   # 在macOS浏览器中打开URL
mac uname -a                   # 执行macOS命令
mac link brew                  # 链接命令以便重复使用
mac notify "Build done"        # 向macOS发送通知
转发环境变量：
bash
ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh