container-notes/container-setup.md

Apple container 安裝與使用筆記

工具：apple/container — 在 macOS 上以輕量虛擬機執行 Linux 容器 安裝日期：2026-06-20 安裝版本：v1.0.0

---

環境

項目	值
機器	Apple Silicon（arm64）
macOS	15.5（Sequoia）
安裝方式	Homebrew formula

⚠️ 版本注意：官方文件標示 container 只支援 macOS 26+，因為它依賴 macOS 26 對虛擬化與網路的新功能。 Homebrew formula 的需求較寬鬆（arm64 + macOS >= 15），因此可在 macOS 15.5 上安裝執行。 但在 macOS 15 上網路功能受限（例如多容器各自取得獨立 IP 的功能無法運作），且官方不受理 macOS 15 的問題回報。 一般本機測試容器（build / run）可正常使用。

---

安裝步驟（實際採用：Homebrew）

brew install container

• 安裝路徑：/opt/homebrew/bin/container
• 不需要 sudo（裝在 /opt/homebrew）
• 驗證版本：

  container --version
  # container CLI version 1.0.0
  

替代方案：官方簽章安裝器

若改用官方 .pkg（會裝到 /usr/local，需管理員密碼）：

1. 從 Releases 下載 container-1.0.0-installer-signed.pkg
2. 雙擊安裝，或：

   sudo installer -pkg container-1.0.0-installer-signed.pkg -target /
   

---

啟動服務

# 方式 A：本 session 啟動（手動）
container system start

# 方式 B：背景常駐 + 開機自動啟動（建議長期使用）
brew services start container

首次啟動需設定 kernel

第一次啟動會要求安裝預設 Linux kernel。若互動提示無法回應，改用明確指令：

container system kernel set --recommended

• 會從 kata-containers releases 下載推薦 kernel（本次為 Kata 3.28.0 arm64）
• 下載約數十 MB，需稍候

---

驗證安裝

container system status
# status: running

container run --rm docker.io/library/alpine echo "hello from container"
# → hello from container

首次執行某個 image 時會額外下載 init image（約 64MB），之後會被快取。

---

常用指令

# 跑一個容器（用完即刪）
container run --rm docker.io/library/alpine echo hello

# 互動式 shell
container run -it --rm docker.io/library/alpine sh

# 列出執行中的容器
container ls

# 列出本機映像檔（注意是單數 image，或縮寫 i）
container image ls

# 停止系統服務
container system stop

---

疑難排解

症狀	原因 / 解法
default kernel not configured for architecture arm64	kernel 未設定 → 執行 container system kernel set --recommended
failed to read user input	互動提示無法回應 → 改用對應的非互動指令（如上面的 kernel set）
網路相關異常	macOS 15 的已知限制，非設定錯誤；需 macOS 26 才完整支援

---

移除

brew uninstall container

（若以官方 .pkg 安裝，則使用 repo 內的 uninstall-container.sh，加 -k 可保留使用者資料。）