From c1a52d4fc2d35bb305a6e14e6362359fc654278d Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Fri, 19 Jun 2026 19:24:59 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E8=8A=82=E7=82=B9=E9=87=8D?=
 =?UTF-8?q?=E5=BB=BA=20+=20=E9=81=BF=E9=A3=8E=E6=8E=A7=20checklist?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

固化首个 VPS 被支付风控暂停的教训(非流量检测,是新号+信用卡+地理画像+
未及时处理验证)+ 脚本化重建步骤(bootstrap→single-node→自编 v2ray_api
sing-box→ufw→enroll→客户端 dart-define)+ 重建后备份 DB + 接 P1 实测。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/node-rebuild-checklist.md | 87 ++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 docs/node-rebuild-checklist.md

diff --git a/docs/node-rebuild-checklist.md b/docs/node-rebuild-checklist.md
new file mode 100644
index 0000000..a74bbbb
--- /dev/null
+++ b/docs/node-rebuild-checklist.md
@@ -0,0 +1,87 @@
+# 新节点重建 + 避风控 Checklist
+
+> 背景:首个 RackNerd VPS(107.172.55.251)在下单 3 天后被**支付风控部门**暂停
+> (要求 Stripe Identity 实名验证,因没及时回应被自动 suspend)。**不是流量被检测**
+> ——栽的是「新号 + 信用卡 + 中美地理不一致」的反欺诈画像 + 没处理验证请求。
+> 本文档固化:① 开局避风控的注意事项 ② 脚本化重建步骤 ③ 重建后必做(备份/测试)。
+
+相关:合规决策见 todo #10(Apple/VPS 实名暴露)。
+
+---
+
+## 一、选商 + 开局避风控(下单前/当天)
+
+- **选 VPN 宽容的商家**:RackNerd 风控偏严。优先选明确允许 VPN/proxy、或对此宽松的商家。
+- **付款画像别太冲**:
+  - 新号 + 信用卡 + 中国 IP 买美国机 = 高危组合,极易触发反欺诈。
+  - 想匿名 → **加密货币**(伪匿名、不可退);想省事 → 信用卡/支付宝(实名,可能风控)。权衡见 todo #10。
+- **下单后立刻看邮件/客户区工单**:若有「Additional Order Verification」之类的验证请求,
+  **当天就处理**(验证 or 当天退款换地方),**别拖**——拖几天会被自动 suspend。
+- **养号**:别新机当天就大流量/纯翻墙特征;先低调用两天。
+- **主体/身份隔离**:别用核心身份/主体撑 VPN 基础设施(同 todo #10)。
+- **多节点**:别把鸡蛋放一个篮子,一台被停不至于全断。
+
+## 二、脚本化重建(新 VPS 到手后,约 30 分钟)
+
+前提:新机 Debian 12,root SSH(配 `~/.ssh/config` 别名,如 `node2`)。
+
+### 1. 加固(幂等)
+```bash
+scp -r deploy/bootstrap node2:/root/ && ssh node2 'cd /root/bootstrap && bash init.sh'
+```
+装:ufw + fail2ban + BBR + swap + pangolin 用户 + Telegram 监控。
+
+### 2. 整套自建栈(控制面 + agent + sing-box)
+```bash
+ssh node2 'cd /path/to/repo && sudo VPS_IP=<新机公网IP> bash deploy/single-node/deploy.sh'
+```
+起:SQLite(512MB 约束,不用 MySQL)+ Redis + pangolin-server(`:8080` HTTP / `:9443` gRPC mTLS)
++ pangolin-agent + sing-box(reality-in TCP443 + hy2-in UDP443)。
+
+### 3. ⚠️ 替换 sing-box 为带 v2ray_api 的自编版(per-user 流量统计必需)
+single-node 装的是官方 sing-box(**无 v2ray_api**),per-user 统计跑不了。需替换:
+```bash
+# 本机编(sing-box v1.13.13 源码;与官方对齐,绕 badtls linkname 坑)
+TAGS="$(cat release/DEFAULT_BUILD_TAGS_OTHERS),with_v2ray_api"
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build \
+  -ldflags "-s -w -checklinkname=0 -X github.com/sagernet/sing-box/constant.Version=1.13.13" \
+  -tags "$TAGS" -o sing-box-v2ray ./cmd/sing-box
+# 传到节点替换 + 重启 agent(agent 会重渲染带 v2ray_api 的配置)
+scp sing-box-v2ray node2:/tmp/
+ssh node2 'systemctl stop pangolin-agent sing-box; install -m755 /tmp/sing-box-v2ray /usr/bin/sing-box; systemctl start pangolin-agent'
+```
+> agent 用 `UseV2RayUsage()`(cmd/agent/main.go),配置自动带 `experimental.v2ray_api`
+> + `stats.users`=全 dp_uuid;hy2 自签证书由 agent 自动生成(`/etc/sing-box/hy2.{crt,key}`)。
+
+### 4. 防火墙放行(ufw)
+```bash
+ssh node2 'ufw allow 22/tcp; ufw allow 8080/tcp; ufw allow 443/tcp; ufw allow 443/udp'
+```
+- `22` SSH、`8080` 控制面 HTTP(客户端访问)、`443/tcp` REALITY、`443/udp` Hy2。
+- `9443` gRPC 仅 agent↔控制面本机,**不对外**。
+
+### 5. enroll 节点 + 建账号 + 配置
+- agent 自 enroll(deploy 流程内);确认 `nodes` 表里新节点 endpoint = `<新IP>:443`、reality_sni 等。
+- hy2 如需启用:`sqlite3 /var/lib/pangolin/pangolin.db "UPDATE nodes SET hy2_port=443; UPDATE directory_version SET version=version+1 WHERE id=1;"`。
+- 建/迁用户账号(测试用 wang880812@gmail.com 等)。
+- **客户端指向新控制面**:`flutter run -d macos --dart-define=PANGOLIN_API_URL=http://<新IP>:8080`
+  (或 `scripts/local_test.sh` 的 `API_URL` 改新 IP)。
+
+## 三、重建后必做
+
+- [ ] **立刻备份控制面 DB**(避免再被停时丢数据):
+  ```bash
+  scp node2:/var/lib/pangolin/pangolin.db ./backups/pangolin-$(date +%F).db
+  ```
+  > ⚠️ 注意:**禁止 Bash 用 `$()`**(全局规则),实际执行时拆步或用固定文件名。
+- [ ] 定期备份 DB(cron / 手动),关键密钥(`/etc/pangolin*`)另存(不入 git)。
+- [ ] 关掉本地 Shadowrocket 等占 TUN 的代理 → 测客户端连真节点(出口 IP = 新节点)。
+
+## 四、上线测原生隧道(macOS,接 P1)
+
+新节点通后,接着 P1 最后一步实测(代码全就绪):
+1. 关 Shadowrocket(避免 TUN 冲突)
+2. `flutter run -d macos --dart-define=PANGOLIN_API_URL=http://<新IP>:8080`
+3. app 加载节点 → 点连接 → sysext 加载(系统设置允许一次)→ 真隧道
+4. Console.app 搜 `PacketTunnel` 看扩展日志(startTunnel / openTun / 报错),逐个调运行时问题
+5. 验证出口 IP = 新节点;速率/延迟/Kill Switch/退出拆隧道全过 → `kUseNativeVpnMacOS` 已 true