mcpField
O
orbstack-best-practices

orbstack-best-practices

github.com/alleneubank云与 DevOps50277 次安装18 周前更新
代码仓库

关于 orbstack-best-practices

orbstack-best-practices 是面向 macOS 上 OrbStack 用户的实践指南，涵盖 Linux 虚拟机、Docker、网络和 SSH 的常用操作及排障。

主要功能

  1. 01管理 Linux 虚拟机生命周期
  2. 02配置 Docker 与容器网络
  3. 03通过 SSH 访问虚拟机
  4. 04从 Linux 调用 macOS 命令
  5. 05生成诊断报告并排障

适用场景

  1. 01创建和管理 OrbStack 虚拟机
  2. 02从 macOS 访问容器或服务
  3. 03排查 Docker 守护进程连接问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/alleneubank/claude-code --skill orbstack-best-practices

安装后在 Claude Code 中输入/orbstack-best-practices确认已加载。

详细介绍

OrbStack 最佳实践

OrbStack 是一款适用于 macOS 的快速 Docker 和 Linux VM 运行时。它能以更出色的性能和无缝的 macOS 集成取代 Docker Desktop。

核心命令

# Machine lifecycle
orb list                               # List machines
orb create ubuntu:noble myvm           # Create (distro:version name)
orb create --arch amd64 ubuntu x86vm  # x86 emulation via Rosetta
orb create ubuntu myvm -c cloud.yml   # With cloud-init
orb start/stop/restart/delete myvm
orb default myvm                       # Set default machine

# Shell and exec
orb                           # Shell into default machine
orb -m myvm -u root           # Specific machine + user
orb -m myvm ./script.sh       # Run command in machine

# File transfer
orb push ~/local.txt          # Copy to default machine home
orb pull ~/remote.txt         # Copy from default machine
orb push -m vm ~/f.txt /tmp/  # Specific machine + path

# Docker/K8s
orb restart docker            # Restart Docker engine
orb logs docker               # Docker engine logs
orb start k8s / orb delete k8s

# Config
orb config set memory_mib 8192
orb config set cpu 4
orb config set rosetta true
orb config set network_proxy http://proxy:8080

关键路径

位置路径
从 macOS 访问 Linux 文件~/OrbStack/<machine>/
从 macOS 访问 Docker 卷~/OrbStack/docker/volumes/
从 Linux 访问 macOS 文件/mnt/mac/Users/...（也可直接通过相同路径访问）
从 Linux 访问其他计算机/mnt/machines/<name>/
SSH 密钥~/.orbstack/ssh/id_ed25519
Docker 守护进程配置~/.orbstack/config/docker.json

网络（OrbStack 专属）

Linux 计算机中的服务器会自动在 macOS 的 localhost 上可用，无需端口映射。

DNS 名称：

模式解析到
<machine>.orb.localLinux VM
<container>.orb.localDocker 容器
<svc>.<project>.orb.localCompose 服务
host.orb.internalmacOS 主机（从 Linux 计算机访问）
host.docker.internalmacOS 主机（从容器访问）

所有 .orb.local 域名都会自动获得零配置 HTTPS。

自定义容器域名：docker run -l dev.orbstack.domains=myapp.local nginx

兼容 VPN；会自动遵循 macOS 代理设置。

SSH 访问

使用单个多路复用 SSH 服务器，无需逐台计算机设置：

ssh orb                    # Default machine
ssh myvm@orb               # Specific machine
ssh user@myvm@orb          # Specific user + machine

IDE 配置：VS Code「Remote - SSH」→ orb 或 myvm@orb。JetBrains：主机 localhost，端口 32222，密钥 ~/.orbstack/ssh/id_ed25519。SSH Agent 转发会自动启用。

与 Docker Desktop 的区别

  • 容器域名无需端口映射即可解析（使用 web.orb.local，而非 localhost:8080）。
  • 优先使用命名卷，而非绑定挂载——数据保留在 Linux 中，无跨文件系统开销。
  • Apple Silicon 上运行 x86 镜像：docker run --platform linux/amd64 ubuntu 或 export DOCKER_DEFAULT_PLATFORM=linux/amd64。
  • 在容器中使用 SSH Agent：-v /run/host-services/ssh-auth.sock:/agent.sock -e SSH_AUTH_SOCK=/agent.sock。
  • Kubernetes：无需 kubectl port-forward，即可从 macOS 访问所有服务类型；cluster.local DNS 可直接使用。

从 Linux 运行 macOS 命令

mac open https://example.com   # Open in macOS browser
mac notify "Build done"        # macOS notification
ORBENV=AWS_PROFILE:EDITOR orb ./deploy.sh  # Forward env vars

故障排除

orb report              # Generate diagnostic report
orb logs myvm           # Machine boot logs
orb restart docker      # Restart Docker engine
orb reset               # Factory reset (deletes everything)
docker context use orbstack  # Fix "cannot connect to Docker daemon"

Rosetta x86 错误：sudo dpkg --add-architecture amd64 && sudo apt install libc6:amd64

Cloud-init 调试：orb -m myvm cloud-init status --long 或 orb -m myvm cat /var/log/cloud-init-output.log

评论

支持 Markdown