vpsetup/AGENTS.md

# AGENTS.md

本文件是本仓库的项目指引，**DSH 与 Claude Code 都读它**（`AGENTS.md` 是唯一真源；`CLAUDE.md` 只是指向本文件的短指针）。
This file provides guidance to coding agents working in this repository.

## 主控状态与访问（2026-10 迁移后）

- 项目主控：本机 DSH，workspace `/home/eli/vpsetup`（从「dockerno1 上的 Claude Code」迁入）。
- 旧 Claude 会话原始记录（**含真实凭据，勿入库、勿外传**）：`~/.dsh/archive/vpsetup-claude-2026-09-28/`。
- 部署拓扑、各机差异、ECH 联调结论、未决项：`docs/HANDOFF.md`。

从本机可直连（私钥已在位，不需要复制私钥、也不需要跳板；下表为 2026-10-09 实测）：

| 目标 | 登录用户 | 角色 | 实测状态 |
|---|---|---|---|
| `dockerno1` = 192.168.254.50 | `eli@` | **用户自建的家用服务器（国内）**，非代理节点：仓库与归档在这里，另跑一大堆 docker 服务（nextcloud/firecrawl/open-webui/portainer…）。旧 Claude Code 就跑在这台上。 | 正常 |
| `oraclejp.henhaoji.site` | `ubuntu@` | Oracle 日本 1 号节点，脚本管理 | caddy/xray/hy2 active，Xray 26.3.27 |
| `oraclejp-2.henhaoji.site` | `ubuntu@` | Oracle 日本 2 号节点，脚本管理 | 同上 |
| `gcoregon.henhaoji.site` | `xu_co@` | GCP Oregon：cdn-bypass 透明代理节点 | active + `cdn-bypass-route` active，dokodemo 54443 在听 |
| `alius.henhaoji.site` | `root@` | 阿里云 US：cdn-bypass 的**上游**节点（出口 43.110.45.237） | caddy/xray/hy2 active |
| `git.henhaoji.site` | `ubuntu@` | 私有 git 服务器（本仓库 origin） | 正常 |
| `euserv.henhaoji.site` = `2a02:180:6:1::7ca` | — | EUserv 德国 VPS，**IPv6-only**（IPv4 出口靠 `setup_warp_zerotrust.sh` 走 WARP） | ⚠️ **2026-10-09 实测不可达**：从本机（无 v6 路由）与从 dockerno1（v6 正常，CF DNS 可 ping 通）均 100% 丢包 / SSH 超时，橙云域名 `euserv-cf.henhaoji.site` 也超时 |

- `dockerno1.savorcare.com` 是家用服务器的内网/内网 DNS 名；本机经 WSL NAT（172.25.2.12 → 网关 172.25.0.1）路由到用户内网，所以能直接 ssh 它。
- 家用服务器本身**没有**跑 caddy/xray/hysteria systemd 栈（那是各 VPS 上的），它的 443/8080/8443 监听来自 docker 容器 —— 排查端口占用时别搞混。
- 其余主机（bwg、UK、gpu 等）经跳板：`ssh eli@dockerno1`（`eli@gpu` 本机也直连）。

## Standing constraints（用户下达，务必遵守）

1. **不要碰任何主机的 `rules.v6` / ip6 filter** —— IPv6 规则由另一个 agent 负责，改它等于制造冲突。
2. **凭据纪律**：绝不把 uuid / 分享链接 / token / 私钥打印进对话（会触发凭据拦截）；**绝不 `source .env`**（Northflank JWT 含 shell 特殊字符，会被吃空 → 401），改用 `t=$(grep '^key=' .env | head -1 | cut -d= -f2- | tr -d '\r\n')`，或直接把 token 管道喂给消费方。仓库内一律脱敏；`.env` 已 gitignore、永不提交；真实凭据在各机 `/etc/caddy-xray-hy2/setup.env`（mode 600）。
3. **改动闸门**：提交前 `bash -n` + `shellcheck` + `bash tests/run_tests.sh` 全绿；提交保持小而单一。
4. **nft 不变式**：运行时只 `nft -f` 自己的文件，永不执行整份 `/etc/nftables.conf`（其 `flush ruleset` 会清掉并存的 iptables-persistent / Docker 表）。
5. **CDN 清单只收官方公布的网段**，不要自己发明（上游流量有限，凭空加段只增延迟）。

## What this repo is

Four self-contained bash scripts:

1. `setup_warp_zerotrust.sh` — gives an **IPv6-only Debian/Ubuntu VPS an IPv4 egress** via Cloudflare WARP as a plain WireGuard interface (`wg0`) — no official client. Two modes, selected by environment variables:

- **Consumer mode** (default): anonymous free-WARP registration.
- **Team mode** (`CF_TEAM` + `CF_ACCESS_CLIENT_ID`/`CF_ACCESS_CLIENT_SECRET`, or `WARP_JWT`): enrolls as a Cloudflare One (Zero Trust) organization device via service-token → JWT exchange at `https://<team>.cloudflareaccess.com/warp`, then registers with header `CF-Access-Jwt-Assertion`.

2. `setup_caddy_xray_hysteria.sh` — deploys **Caddy + Xray (VLESS+REALITY/WS/XHTTP) + Hysteria2 + nftables port-hopping** on a Debian/Ubuntu VPS. Xray:443 takes REALITY traffic and falls back to Caddy on `127.0.0.1:8003` (PROXY protocol); Caddy serves the camouflage reverse-proxy and routes `WS_PATH` (default `/scilad`; WS:54442 — parameterized so migrations can keep an old path like `/vlessws`) and a random path (XHTTP:8080). Hysteria2:8443/UDP gets its cert via `HY2_CERT_MODE` (default `http`): built-in certmagic ACME HTTP-01 listening only on `127.0.0.1:9180` (altPort), with Caddy's port-80 block reverse-proxying `/.well-known/acme-challenge/` to it — no public port opened, no DNS token needed, non-wildcard `DOMAIN` cert, auto-renewed and hot-applied (TLS-ALPN is unusable: the CA only connects to TCP 443, which Xray owns). Fallback `dns`: Cloudflare DNS-01 for a `*.BASE_DOMAIN` wildcard (needs `CF_API_TOKEN`). nftables redirects UDP 20000-30000 → 8443 (runtime only `nft -f`s its own `hysteria.nft` — never executes the full `/etc/nftables.conf`, whose `flush ruleset` would wipe coexisting iptables-persistent/Docker tables; boot-time ordering nftables@sysinit → netfilter-persistent@multi-user makes the flush harmless there). Config templates are embedded as quoted heredocs with `__VAR__` placeholders (rendered via bash parameter expansion, never sed); credentials auto-generate and persist to `/etc/caddy-xray-hy2/setup.env` (mode 600) which is sourced on re-run. The rendered Caddyfile ends with `import $CADDY_SITES_DIR/*.caddy` (default `/etc/caddy/sites`) — an **upgrade-safe extension point** for user site blocks: the script only creates the dir and, when it is completely empty, a comment-only `00-example.caddy`; it never overwrites or deletes user `*.caddy` files (`uninstall` leaves them alone too). Glob import, so an empty/missing dir is a warning, not an error. Blocks placed there MUST carry `bind 127.0.0.1 [::1]` (otherwise they land on an unwrapped `:8003` listener that Xray's PROXY-protocol fallback can never reach — the script warns but does not block), and a wildcard host needs a supplied cert file because the stock binary ships no DNS plugin. `DRY_RUN=1` renders everything to `./dry-run-output/` without system changes — this is how `tests/run_tests.sh` validates the script on a dev machine. The apt step is tolerant in exactly one narrow case (`apt_update_tolerant()`): when `apt-get update` fails **only** for the Caddy/Cloudsmith repo *and* `caddy` is already installed, it warns and continues (configs still re-rendered, validated and reloaded); any other repo in the errors, or a missing caddy, still hard-fails. Reason: from 2026-10-09 Cloudsmith served 402 for the whole `/deb/debian/` path (quota exhausted by CI abuse — caddyserver/dist#142), which otherwise aborted `ACTION=upgrade` at its first apt call on every host. Actions: `ACTION=install` (default) / `upgrade` (same idempotent pipeline — apt/script installs already pull latest — but requires an existing setup.env and never prompts) / `uninstall`. Legacy setup.env files without `HY2_CERT_MODE` infer `dns` when `CF_API_TOKEN` is present, so upgrades don't silently switch wildcard certs to single-domain. Unlike the WARP script, this one intentionally uses the official cloudsmith apt repo (Caddy) and the official Xray/Hysteria2 install scripts; original hand-written templates are archived in `docs/templates-original/`.

3. `setup_cdn_bypass_tproxy.sh` — for VPSs whose egress to Cloudflare/Fastly/Akamai is blocked or metered (e.g. Google Cloud): transparently proxies **CDN-destined local outbound** through an upstream xray node. Requires an already-installed xray/v2ray service; takes a pasted `VLESS_LINK` share link and (a) injects inbound/outbound/routing via a systemd drop-in adding `-confdir /etc/xray-cdn-bypass/` — the user's own config.json is never modified (drop-in MUST be named `20-cdn-bypass-confdir.conf`: the official xray install script ships `10-donot_touch_single_conf.conf` which re-sets ExecStart to the plain single-config form and sorts after any `10-*` name, silently dropping the confdir); (b) writes `/etc/nftables/cdn-bypass.nft` (mark table `cdn_bypass_mark` + tproxy table `cdn_bypass_tproxy`, embedded 188-CIDR official-source-only list — CF ips-v4 + Fastly public-ip-list + Akamai/Linode WHOIS, audited 2026-09 — since blocked hosts can't fetch lists online) with the same never-run-the-full-nftables.conf convention; all filtering lives in nft (CIDR set + TCP/UDP ports 53/80/443 via `th dport`), the xray fragment is a catch-all dokodemo→proxy with zero filtering; (c) installs oneshot `cdn-bypass-route.service` persisting `ip rule fwmark 1 lookup 100` + `ip route local default dev lo table 100` (ip commands are pure runtime kernel state — nothing else persists them); (d) the injected outbound carries `sockopt.mark=255` and nft exempts mark 255, so an upstream IP inside the CDN ranges can't loop; the main config's direct outbound must NOT carry mark 255 — if it does, client-proxied CDN traffic gets exempted and egresses raw (the classic "local curl works, clients don't" symptom on GCP). IPv4 only. Same conventions: `DRY_RUN=1`, `ACTION=uninstall`, idempotent.

4. `migrate_existing_stack.sh` — one-shot migration bringing a **manually-deployed** caddy/xray/hysteria2 stack under script 2's management. Read-only parses the three old configs (python3 brace-matching for Caddyfile blocks, comment-stripping + json for xray, awk for hysteria YAML), interactively confirms DOMAIN/EMAIL/WS_PATH (defaults from parsed values; DOMAIN ≠ old REALITY serverName warns loudly), then: writes `setup.env` (same `%q` format as save_env) preserving old credentials so same-protocol clients survive, backs up old configs to `/etc/caddy-xray-hy2/migration-backup-<ts>/`, extracts non-main-domain Caddy site blocks verbatim **and installs them into the extra-sites dir** (`CADDY_SITES_DIR`, default `/etc/caddy/sites`, as `migrated-extra-sites.caddy`) so the new Caddyfile's `import` picks them up and upgrades stop clobbering them — no manual merge. It deliberately falls back to reference-file-only (with a loud warning) in two cases: blocks using custom `dns <provider>` plugin directives (the stock apt caddy can't parse them, and installing them would make `caddy validate` fail and thereby block upgrades), or a failed `caddy adapt` pre-check when caddy is present; it also warns about blocks lacking `bind 127.0.0.1`, and backs up an existing target file before overwriting; and only *inspects* nft — a dirty/customized `hysteria_nat` table yields a reference file, never an include insertion. Refuses to run if setup.env already exists. `DRY_RUN=1` reads real configs but writes only to `./dry-run-output/`; config paths overridable via `CADDYFILE_PATH`/`XRAY_CONFIG_PATH`/`HYSTERIA_CONFIG_PATH`/`NFT_RULESET_FILE` (this is how the fixtures tests work).

There is no build system or package manifest; tests are `tests/run_tests.sh` (DRY_RUN + grep/json.tool assertions) covering the caddy/xray/hysteria script and the migration script (fixtures under `tests/fixtures/migrate/`).

## Commands

- Syntax check: `bash -n setup_warp_zerotrust.sh setup_caddy_xray_hysteria.sh setup_cdn_bypass_tproxy.sh migrate_existing_stack.sh`
- Lint: `shellcheck setup_warp_zerotrust.sh setup_caddy_xray_hysteria.sh setup_cdn_bypass_tproxy.sh migrate_existing_stack.sh`
- Test (all scripts, DRY_RUN only): `bash tests/run_tests.sh`
- Run (only on a disposable target VPS, never on a dev machine): `sudo bash setup_warp_zerotrust.sh`
  - With no env vars it interactively prompts for team name + service token (reads from `/dev/tty`, so `wget|bash` piping still works); empty team name or incomplete credentials silently fall back to consumer mode. Env vars fully set → no prompts. No controlling tty → prompts skipped, env-only.
  - Team mode: `sudo CF_TEAM=<team> CF_ACCESS_CLIENT_ID=<id> CF_ACCESS_CLIENT_SECRET=<secret> bash setup_warp_zerotrust.sh`
  - Uninstall + free the device seat: `sudo ACTION=delete bash setup_warp_zerotrust.sh`
  - Optional overrides: `ALLOWED_IPS` (default `0.0.0.0/0`), `MTU` (default `1280`)
- It requires root, `apt`-installs packages, overwrites `/etc/resolv.conf`, writes `/etc/wireguard/wg0.conf` + `/etc/wireguard/warp-account.json`, and enables the `wg-quick@wg0` systemd unit.
- Verification is built into the script's final output: IPv4 exit IP, unchanged IPv6 exit, and `warp=` from cloudflare.com/cdn-cgi/trace.

## Architecture and invariants

The script is a one-shot bootstrap sequence; its correctness depends on a few deliberate constraints:

1. **Temporary DNS64 for bootstrap only, with two takeover modes chosen by resolv.conf's actual disposition.** If `/etc/resolv.conf` resolves (via `readlink -f`) into `/run/systemd/resolve/*` and systemd-resolved is active, the script never touches resolv.conf — it injects global DNS64 via an `/etc/systemd/resolved.conf.d/zz-warp-dns64.conf` drop-in (`DNS=` + `Domains=~.`) and restarts resolved; restore just deletes the drop-in (writing through the Ubuntu-default stub symlink would clobber a resolved-managed file in /run that resolved never reads, silently breaking the bootstrap). Otherwise it backs up the file's *content* and overwrites resolv.conf; restore writes the backup back **in place** (`cat > file`, never whole-file `cp`) so the inode and any symlink survive and systemd-resolved's inotify watch keeps working (a `cp`-style inode replacement leaves resolved blind to the file while its contents look correct). A `trap cleanup EXIT INT TERM` guarantees restoration even on failure — any new early-exit path must preserve this guarantee, or the VPS is left with broken/wrong DNS.
2. **IPv6 transport, IPv4 payload.** Registration uses `curl -6` (the API has native AAAA) and the WireGuard endpoint is Cloudflare's IPv6 anycast (`[2606:4700:d0::a29f:c001]:2408`), but `AllowedIPs = 0.0.0.0/0` by default — IPv6 traffic must stay on the native connection. Dashboard split-tunnel settings do NOT apply to a plain WireGuard client; `ALLOWED_IPS` is the only routing control.
3. **The reg API returns a FLAT JSON object** (`.id`, `.token`, `.config.interface.addresses.{v4,v6}`, `.config.peers[0]`) — there is no `.result` wrapper (that's the v4 dashboard API convention, not this one). A `CF-Client-Version` header is mandatory or registration is rejected; known-good pairings (as of 2026-08): `v0a4471`+`a-6.35-4471` (Aether) and `v0a1922`+`a-6.3-1922` (wgcf v2.2.32). The script tries both. Registration curls pin `--tlsv1.2 --tls-max 1.2 --http1.1` because Cloudflare rejects non-app TLS fingerprints with 403 error 1020. HTTP 403 otherwise means the VPS IP is flagged; 429 means rate-limited.
4. **Idempotency via `/etc/wireguard/warp-account.json`.** Re-runs PATCH the existing device's key (`PATCH /reg/<id>` with its Bearer token) instead of registering anew — Zero Trust free plans cap at 50 devices, so repeated fresh registrations would burn seats. The PATCH path is only taken when the saved team matches the current `CF_TEAM` (switching free ↔ team always re-registers). Fall back to fresh registration on 401/404/410.
5. **MTU 1280** survives the double overhead of NAT64/DNS64 plus the WireGuard tunnel; don't raise it without testing on the target network.
6. **Kernel-module probe with wireguard-go fallback.** The script probes `ip link add wgprobe type wireguard` (after `modprobe wireguard`); on failure it installs `wireguard-go` (noble universe, ~1MB) and relies on wg-quick's built-in userspace fallback (`add_if()` falls back to `wireguard-go` when the kernel module is absent — covers LXC containers and custom old kernels, works for boot autostart too). Requires `/dev/net/tun`; if absent (some LXC), the script errors out with a hint.
7. **Supply-chain constraint (user requirement).** Install only via the distro's signed apt repos; never add third-party apt sources, download binaries, or pipe remote code. Outbound calls go to Cloudflare-owned domains only (registration API, team Access endpoint, cdn-cgi/trace for the connectivity check — ip.sb kept only as fallback). The bootstrap DNS64 resolvers are overridable via `DNS64_SERVERS`. Keys/credentials stay local under `/etc/wireguard/` (mode 600); only the WireGuard public key leaves the machine.

## Conventions

- Script comments are written in Chinese; match that when editing.
- `README.md` (Chinese) documents the 2026 dashboard paths for Zero Trust service-token enrollment — keep its UI paths in sync with the script header comment when Cloudflare reorganizes navigation.
- The repo has no CI; commits are small single-file updates. Remote is the private git server `git.henhaoji.site/eli/vpsetup` (credentials live in the local git remote config — never paste the remote URL with its token anywhere).
- 改动脚本行为时，同步更新三处文档：本文件、`README.md`、`docs/HANDOFF.md`（部署事实变了也要更新 HANDOFF）。