wangjia
53caaf54f0
- CLAUDE.md 重写:去掉 EC2/marzban 部署、架构、cutover/rollback 命令、自动部署 CD; 改为自有 VPS 自建方向(RackNerd Debian 12、ssh racknerd 免密、512MB→SQLite)、 补 server/ Go 后端与多数据库(DB_DRIVER)说明;保留设计 token 单源段 - 删 docs/回滚手册.md(EC2 edge 切换/回滚,脚本已删) - 删 docs/备份与灾备.md(EC2 MySQL/marzban xtrabackup→S3,backup 栈已删) - app/kernel/poc/README.md:REALITY 参数来源由 EC2 改为自建节点(single-node) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Pangolin 桌面端 PoC M1 — 接线指南
任务: tsk_SLCsjNgtmng3 · M1 首发打通（macOS TUN + REALITY）
前置条件
1. 下载 sing-box 二进制
# macOS Apple Silicon
cd app/kernel
./fetch-desktop-bin.sh darwin arm64
# macOS Intel
./fetch-desktop-bin.sh darwin amd64
产物: app/kernel/dist/desktop/darwin-arm64/sing-box
2. 配置 TUN 提权（macOS PoC）
sing-box TUN 模式需要创建 utun 接口，必须有 root 权限。PoC 阶段使用 sudo：
# 方式 A: sudoers 免密白名单（推荐，避免每次输密码）
SINGBOX_PATH="$(pwd)/app/kernel/dist/desktop/darwin-arm64/sing-box"
echo "$(whoami) ALL=(root) NOPASSWD: ${SINGBOX_PATH}" | sudo tee /etc/sudoers.d/pangolin-singbox
sudo chmod 440 /etc/sudoers.d/pangolin-singbox
# 方式 B: 用 setuid（不推荐用于正式版）
sudo chown root "${SINGBOX_PATH}"
sudo chmod u+s "${SINGBOX_PATH}"
正式版说明: macOS 正式版应使用 SMJobBless 注册特权 Helper Daemon， 并完成 Apple 公证 (notarization)。此 PoC 路径记录在 BACKLOG-11D-HELPER。
3. 获取 REALITY 服务端参数
从自建节点(deploy/single-node)拿 REALITY 公钥/short_id 和节点 UUID：
# 节点上由 single-node/deploy.sh 生成的 REALITY 参数:
ssh <node> "grep -E 'REALITY_PBK|REALITY_SHORT_ID' /etc/pangolin/reality.env"
# 节点 UUID:见 single-node 的 seed,或控制面 nodes 表
4. 渲染 PoC 配置
export SERVER_HOST="<节点公网IP>" # 自建节点公网 IP
export SERVER_PORT="11443" # REALITY 端口
export REALITY_UUID="your-uuid-here"
export REALITY_PUBLIC_KEY="your-x25519-public-key"
export REALITY_SHORT_ID="your-short-id"
export REALITY_SNI="www.apple.com"
./app/kernel/poc/gen-poc-config.sh --out /tmp/pangolin-poc-config.json
验收测试
M1 验收步骤
# 1. 设置二进制路径
export PANGOLIN_SINGBOX_BIN="$(pwd)/app/kernel/dist/desktop/darwin-arm64/sing-box"
# 2. 用渲染后的 config 启动（PoC 会自动 sudo）
sudo "${PANGOLIN_SINGBOX_BIN}" run -c /tmp/pangolin-poc-config.json &
KERNEL_PID=$!
# 3. 等待就绪（Clash API）
sleep 3
# 4. 验证出口 IP
curl -s https://ifconfig.me # 应显示节点 IP（18.136.60.128 或接近）
# 5. DNS 泄露检测
dig @8.8.8.8 google.com # 通过 VPN 解析
dig google.com # 应走 sing-box DNS（不泄露本地 ISP）
# 6. 流量统计（Clash API）
CLASH_PORT="$(cat /tmp/pangolin-poc-config.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['experimental']['clash_api']['external_controller'].split(':')[1])")"
CLASH_SECRET="$(cat /tmp/pangolin-poc-config.json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['experimental']['clash_api']['secret'])")"
curl -s -H "Authorization: Bearer ${CLASH_SECRET}" "http://127.0.0.1:${CLASH_PORT}/connections"
# 7. 停止（还原路由/DNS）
kill "${KERNEL_PID}"
sleep 2
# 8. 验证还原
netstat -rn | grep utun # 不应出现 pangolin TUN 条目
scutil --dns | head -20 # DNS 应回到系统默认
Dart 集成测试
cd client
flutter test test/bridge/kernel_process_test.dart -v
架构说明
DesktopVpnBridge.start(configJson)
│
├─ _injectClashApi() 注入随机端口+secret 到 experimental.clash_api
├─ _writeConfig() 写 ~/Library/Application Support/com.pangolin.vpn/kernel/
│
└─ DesktopKernelProcess.spawn(configPath)
│
├─ _resolveBinaryPath() PANGOLIN_SINGBOX_BIN / 开发目录 / /usr/local/bin
├─ Process.start(['sudo', binPath, 'run', '-c', configPath])
├─ _waitForClashApi() 轮询 GET /connections 直到就绪（20s 超时）
├─ _startStatsPoll() 每秒轮询 /connections → VpnStatsEvent
└─ emit VpnStatus.on
已知限制（PoC 阶段）
| 限制 | 原因 | 正式版方案 |
|---|---|---|
| sudo 提权 | TUN 需 root | SMJobBless Helper + 公证 (BACKLOG-11D-HELPER) |
| 单 REALITY outbound | 节点选优未实现 | URLTest 多节点 (11G) |
| 统计用 /connections 轮询 | SSE 流实现更复杂 | /traffic SSE 订阅 |
| Windows Wintun 未测 | 主验收平台 macOS | M1 验收后补 |
| 无 kill-switch | strict_route 做基础保护 | 11G |
| Android/iOS | 归 11E/11F | NEPacket/VpnService |