From aa97083f65769232e83ff895d28689c5f786bb3b Mon Sep 17 00:00:00 2001
From: Acbox <acbox0328@gmail.com>
Date: Sat, 7 Feb 2026 17:19:19 +0800
Subject: [PATCH] docs: update trouble solution about lima and containerd in
 CONTRIBUTING.md

---
 CONTRIBUTING.md | 56 +++++++++++++++++++++++++++++++++++++++++++++++++
 mise.toml       |  2 +-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d3371d3d..624d8036 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,6 +44,62 @@ Copy config.toml.example to config.toml and configure:
 cp config.toml.example config.toml
 ```
 
+## Containerd (macOS)
+
+本项目依赖 containerd 运行容器。macOS 上通过 [Lima](https://lima-vm.io/) 在虚拟机中运行 containerd。
+
+### 安装与启动 Lima VM
+
+```bash
+# 安装 Lima（如果尚未安装）
+brew install lima
+
+# 启动默认 VM（脚本也会自动执行）
+mise run containerd-install
+```
+
+### 启动 containerd 服务
+
+Lima VM 启动后，containerd 不一定会自动运行，需要手动启用：
+
+```bash
+limactl shell default -- sudo systemctl enable --now containerd
+```
+
+### Socket 转发
+
+Go 应用运行在 macOS 宿主机上，但 containerd socket (`/run/containerd/containerd.sock`) 位于 Lima VM 内部，宿主机无法直接访问。
+
+由于 containerd socket 权限为 `root:root rw-rw----`，SSH 转发以普通用户身份无法直接访问。需要先在 VM 内安装 `socat` 并以 root 权限创建代理 socket，再通过 SSH 转发到宿主机：
+
+```bash
+# 1. 安装 socat（仅首次需要）
+limactl shell default -- sudo apt-get install -y socat
+
+# 2. 在 VM 内创建代理 socket（以 root 权限运行，普通用户可访问）
+limactl shell default -- sudo bash -c \
+  'rm -f /tmp/containerd-proxy.sock; nohup socat UNIX-LISTEN:/tmp/containerd-proxy.sock,fork,mode=0666 UNIX-CONNECT:/run/containerd/containerd.sock > /dev/null 2>&1 &'
+
+# 3. SSH 转发代理 socket 到宿主机
+rm -f /tmp/containerd-lima.sock
+ssh -nNT -L /tmp/containerd-lima.sock:/tmp/containerd-proxy.sock \
+  -F ~/.lima/default/ssh.config lima-default &
+```
+
+然后在 `config.toml` 中配置转发后的 socket 路径：
+
+```toml
+[containerd]
+socket_path = "/tmp/containerd-lima.sock"
+```
+
+### 常见问题
+
+- **Lima VM 状态为 Broken**：运行 `limactl stop default && limactl start default` 重启 VM。
+- **连接超时 (`dial unix:///run/containerd/containerd.sock: timeout`)**：检查 VM 是否运行、containerd 是否启动、socket 转发是否建立。
+- **gRPC EOF 错误 (`error reading server preface: EOF`)**：通常是 socket 权限问题，确认使用了 socat 代理（步骤 2），而非直接转发 `/run/containerd/containerd.sock`。
+- **转发断开**：socat 代理和 SSH 转发均为后台进程，重启电脑或 VM 后需要重新执行步骤 2 和 3。
+
 ## Development
 
 Start development environment:
diff --git a/mise.toml b/mise.toml
index abb5ec83..e80f09ec 100644
--- a/mise.toml
+++ b/mise.toml
@@ -81,7 +81,6 @@ run = "scripts/compile-mcp.sh"
 description = "Start development environment"
 depends = [
   "//:swagger-generate",
-  "//:sqlc-generate",
   "//agent:dev",
   "//cmd/agent:start",
   "//packages/web:dev",
@@ -90,6 +89,7 @@ depends = [
 [tasks.setup]
 description = "Setup development environment"
 depends = [
+  "//:sqlc-generate",
   "//:db-up",
   "//:pnpm-install",
   "//:go-install",