diff --git a/Tailscale + SSH 远程开发操作指南.md b/Tailscale + SSH 远程开发操作指南.md index e896270..66569e2 100644 --- a/Tailscale + SSH 远程开发操作指南.md +++ b/Tailscale + SSH 远程开发操作指南.md @@ -1842,10 +1842,250 @@ git push -u origin main --- -文档版本: 3.1 -最后更新: 2026-04-22 +# 第九部分：Mac 本地 + 虚拟机编译 的双端开发工作流（2026-04-23 落地，推荐） + +## 9.1 为什么采用这种方案 + +### 背景：虚拟机内用 Claude CLI 不可行 + +实测发现（2026-04-23）： +- **Anthropic 对中国机场 IP 做了 API 级风控**，`api.anthropic.com` 对机场 IP 返回 ECONNRESET 或静默丢包（但 HTTPS 握手能成功、`console.anthropic.com` 也能通，仅 `/v1/messages` 被精准拉黑） +- 尝试过多种节点（美国 IEPL / 香港 / 新加坡），机场共享 IP 段都被 Ban +- 虚拟机内装 Claude CLI（Node 20 + `@anthropic-ai/claude-code` 2.1.118）后，启动永远卡在 "Checking connectivity..." 或 ECONNRESET +- 新版 Claude CLI（2.1.118+）打包成独立二进制，屏蔽 `NODE_OPTIONS` 等代理注入手段 + +### 解决方向 + +**Mac 能连 Anthropic（你已在用），Linux 虚拟机保留编译能力。让两边各司其职**： + +``` +Mac GitHub Linux 虚拟机 +Claude Code + 代码仓库 ──push──▶ dev/mac ◀──pull── 完整 SDK + 编译工具链 +(读写/改/grep/Edit) 分支 (./make.sh 编译) + ▲ │ + └─────────── Claude 通过 SSH 直接操作虚拟机编译 ────────────┘ +``` + +Claude 可以**通过 Bash 工具 SSH 到虚拟机自动编译**，实现全自动闭环，**不需要用户在两端手动搬运错误信息**。 + +## 9.2 Mac 端一次性环境配置 + +### 9.2.1 创建 case-sensitive APFS 卷（关键，否则会踩大坑） + +Linux 内核源码含**同名但大小写不同的文件**（如 `xt_CONNMARK.h` / `xt_connmark.h`），macOS 默认 APFS 是 case-insensitive，会把这些文件合并成一个，导致 `git status` 永远脏且无法还原。 + +**解决**：建一个专门的 case-sensitive 卷放 Linux 项目。 + +1. 打开 **磁盘工具** +2. 左侧选 **Container disk3**（Macintosh HD 的父容器） +3. 菜单「编辑 → 添加 APFS 卷...」 +4. 弹窗中： + - 名称：`LinuxDev` + - **格式：APFS（区分大小写）** ← 关键 + - 大小：不限制（APFS 容器自动共享空间） +5. 确认 / 添加 + +验证成功： +```bash +diskutil info /Volumes/LinuxDev | grep Personality +# 应输出: File System Personality: Case-sensitive APFS + +# 实验创建大小写同名文件 +touch /Volumes/LinuxDev/_test_a /Volumes/LinuxDev/_test_A +ls /Volumes/LinuxDev/_test_* +# 应输出两行（_test_A 和 _test_a） +rm /Volumes/LinuxDev/_test_* +``` + +从此 Linux 项目都放 `/Volumes/LinuxDev/` 下。 + +### 9.2.2 Mac 端 Git 配置 + +```bash +# 只需要配一次，以后所有项目都复用 +git config --global user.name "你的名字" +git config --global user.email "你的邮箱" +git config --global credential.helper osxkeychain # PAT 存钥匙串 +``` + +### 9.2.3 首次克隆到 case-sensitive 卷 + +```bash +cd /Volumes/LinuxDev +git clone https://github.com/Leo-z8/OrangePi_CM5_Project.git +cd OrangePi_CM5_Project +# 首次弹出凭证提示： +# Username: Leo-z8 +# Password: 粘贴 PAT (ghp_xxx...) +# 之后 PAT 存钥匙串永久免密 +``` + +> **重要：不要用 GitHub Web 下载 ZIP**（文件夹带 `-main` 后缀那种） +> ZIP 不含 `.git/` 元数据，无法 push。必须 `git clone`。 + +### 9.2.4 创建开发分支 + +```bash +cd /Volumes/LinuxDev/OrangePi_CM5_Project +git checkout -b dev/mac +git push -u origin dev/mac +``` + +## 9.3 虚拟机端一次性环境配置 + +如果之前已按本文档 8.7 配好 SSH ed25519 over 443，这步跳过。否则见 8.7。 + +确认： +```bash +ssh linux-vm "cd ~/OrangePi_CM5/Aandroid_OrangePi/merged/Android_13 && git remote -v" +# 应该显示 origin git@github.com:Leo-z8/OrangePi_CM5_Project.git +``` + +## 9.4 日常开发闭环（Claude 自主执行） + +Claude 收到开发任务后会自动执行： + +``` +┌──────────────────────────────────────────────────────────┐ +│ Claude 在 Mac 端工作 │ +│ 1. cd /Volumes/LinuxDev/OrangePi_CM5_Project │ +│ 2. 读源码 / grep / 分析 │ +│ 3. Edit 修改代码 │ +│ 4. git add xxx │ +│ 5. git commit -m "描述" │ +│ 6. git push origin dev/mac │ +└──────────────────┬───────────────────────────────────────┘ + │ + ▼ +┌──────────────────────────────────────────────────────────┐ +│ Claude 通过 Bash 工具 SSH 到虚拟机 │ +│ ssh linux-vm 'cd ~/OrangePi_CM5/.../Android_13 && \ │ +│ git fetch origin && \ │ +│ git checkout dev/mac && git pull && \ │ +│ ./make.sh -F -b orangepicm5' │ +│ │ +│ 编译输出直接进 Claude 的上下文 │ +└──────────────────┬───────────────────────────────────────┘ + │ + ▼ + ┌─────────────────────┐ + │ 编译成功？ │ + └──────┬──────────────┘ + │ 失败 │ 成功 + ▼ ▼ + Claude 读错误 通知用户烧录 + 分析 → 修代码 (物理操作) + 再 push 再编 + （自循环） +``` + +### 用户只在三个场景介入 +1. 提需求（"给 NFC 加 PN532 驱动"） +2. 烧录到开发板（USB 接线、按 Loader 键） +3. 判断结果（"这效果对不对"） + +## 9.5 分支策略 + +``` +main ← 保护分支，只接受编译+烧录测试通过的代码 + ├─ dev/mac ← Mac 端 Claude 日常开发推这里 + ├─ feature/lcd-st77916-mipi ← 可选：大功能单独拉 feature 分支 + └─ feature/nfc-pn532 +``` + +**合并原则**： +- dev/mac 的改动在虚拟机编译通过 + 烧录验证 OK 后，才合并回 main +- 合并命令（在虚拟机端或 Mac 端都行）： + ```bash + git checkout main + git merge dev/mac --no-ff -m "集成 NFC PN532 驱动" + git push origin main + ``` + +## 9.6 项目级 CLAUDE.md（关键） + +在仓库根目录放一个 `CLAUDE.md`，**新的 Claude 对话打开项目时自动加载**，无需用户再解释工作流。 + +CLAUDE.md 内容要点（完整版见仓库）： +- 项目本质（硬件、内核版本、开发类型） +- 双端架构（Mac 路径 + VM 路径） +- 关键命令（git push、SSH、编译） +- 全自动闭环流程 +- 只可修改的目录清单 +- 环境约束（case-sensitive 卷、不能 >100MB 文件等） +- 踩坑速查 +- 用户偏好（中文、代码风格、响应风格） + +## 9.7 本方案踩过的大坑总结 + +### 坑 1：ClashX 增强模式对 SSH 协议干扰 + +Mac 上 ClashX Pro 的 TUN 模式把 `ssh.github.com:443` 劫持到 fake-ip（`198.18.x.x`），但 **SSH 协议在 banner exchange 阶段被切**（`Connection timed out during banner exchange`），而 HTTPS 到同一域名却能通。 + +原因推测：某些节点对非 HTTP/HTTPS 流量做 DPI 过滤。 + +**规避**：Mac 端 Git 操作**只用 HTTPS + PAT**，不用 SSH。 +虚拟机端没这问题（Tailscale 直连，没经过 Mac ClashX）。 + +### 坑 2：ClashX 的 7890 端口虽然开着但实际不转发 + +Mac ClashX Pro 当前配置下： +- ✅ TUN 透明代理工作（fake-ip 路径） +- ❌ 7890 HTTP 代理端口虽然能 `nc -z` 成功但不实际转发（curl -x 超时） +- ❌ 7891 SOCKS5 没开 + +意味着所有"显式指定代理"的方案（`git config http.proxy`、SSH ProxyCommand、proxychains）都不能用。 + +**规避**：依赖 TUN 透明路径，不用显式代理。 + +### 坑 3：default APFS 与 Linux 内核大小写冲突 + +macOS 主盘默认 APFS 是 case-insensitive，Linux 内核源码（netfilter 等）有大小写同名文件，checkout 时后者覆盖前者，`git status` 永远显示 8 个 .h 文件 modified 且不可还原。 + +**规避**：case-sensitive APFS 卷。见 9.2.1。 + +### 坑 4：GitHub ZIP 下载不含 .git + +用户若因网络问题改用 GitHub Web 下载 ZIP（带 `-main` 后缀），后续无法 git push。必须 `git clone` 才有 `.git/`。 + +### 坑 5：SMB 挂载 Mac Finder 污染 `._*` 和 `.DS_Store` + +Mac Finder 访问 SMB 共享时会写入 AppleDouble 元数据。 +**规避**：`.gitignore` 已加规则 `._*` + `.DS_Store`。 + +### 坑 6：虚拟机 mihomo TUN 无法访问 Anthropic + +即使在虚拟机内装 mihomo 跑 TUN 模式（透明代理），Anthropic 对机场 IP 的 API 级风控仍生效（TLS 握手成功但 POST 请求静默被丢）。 + +**规避**：根本不在虚拟机用 Claude。用本节方案。 + +## 9.8 性能参考（2026-04-23 实测） + +| 指标 | 数值 | +|------|------| +| 仓库 clone 大小 | ~640 MB（.git） + ~2.3 GB（work tree）= 2.9 GB | +| Mac 端 clone 速度 | 17.5 MiB/s（走 ClashX TUN，GitHub HTTPS）| +| Mac → GitHub push 延迟 | 秒级（小改动）| +| 虚拟机 git pull 速度 | MB/s 级（Tailscale + SSH ed25519 over 443 直连）| +| VS Code 打开 case-sensitive 卷项目 | 索引 < 30 秒（本地速度）| + +--- + +文档版本: 3.2 +最后更新: 2026-04-23 适用系统: Ubuntu 20.04/22.04 LTS (x86_64), macOS 网络环境: 跨网络远程开发（Tailscale + ClashX Pro 共存 + GitHub SSH 443） +主要变更（v3.2）: +- **新增第九部分：Mac 本地 + 虚拟机编译 的双端开发工作流**（推荐，规避 Anthropic 对机场 IP 的风控） +- 9.1 分析为什么不能在虚拟机内用 Claude +- 9.2 Mac 端环境配置：**case-sensitive APFS 卷**（避免 Linux 内核大小写冲突）+ HTTPS+PAT+Keychain 免密 +- 9.3 虚拟机端 git SSH 配置（延续 v3.1 的 8.7） +- 9.4 Claude 自动化开发闭环流程（Mac 改 → push → SSH 虚拟机编译 → 看错误自修 → 循环） +- 9.5 分支策略（main / dev/mac / feature/*） +- 9.6 项目级 CLAUDE.md 机制（新对话零摩擦接手） +- 9.7 本方案全部踩坑：ClashX SSH 劫持、7890 代理端口不转发、APFS 大小写、mihomo 绕不过 Anthropic 风控等 +- 9.8 实测性能数据 + 主要变更（v3.1）: - 4.5 新增 SMB 挂载方式（Mac 端轻量文件访问方案）与 Remote-SSH 对比 - 8.7 首次推送 GitHub 改为 SSH 密钥为主，PAT 降为备选