@clize/clize 0.10.1 → 0.11.0

package/skills/clize-site-debug/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: clize-site-debug
+description: >-
+  当用户说某个用 clize 部署的站点 / 域名「打不开、访问不了、部署了但没生效、还是占位页」时,用这个 skill 系统排查。
+  clize 站点托管 = 共享 worker clize-handle-site + KV clize-sites,按 hostname serve;域名经 CF Workers custom domain 绑到 worker。
+  按「先排代理 → 内容层(KV) → 绑定层(workers/domains) → DNS 层(zone/NS)」四步定位,Vercel 注册域名要切 NS→CF。
+  触发:"我的站打不开"、"X 域名访问不了"、"deploy 了没生效"、"还是占位页"、"freevideocompressor 这种站不能用"。
+---
+
+# clize 托管站点打不开 —— 系统排查
+
+clize 站点托管 = 共享 worker **`clize-handle-site`** + KV **`clize-sites`**,worker 按 hostname 从 KV 取 `${host}${path}`(无内容→占位页)。域名通过 **CF Workers custom domain** 绑到这个 worker,要求域名 zone 在 CF 且 **active**(NS 指向 CF)。
+
+「打不开」基本是这条链某一环断了。**按顺序查,别跳步。**
+
+## 0. 先排除本机代理(最容易误判,务必第一步)
+
+用户本机若跑 Clash/Surge(TUN / fake-ip 模式),`dig` 会把域名解析到 **`198.18.x.x`**(fake-ip 段)或**连不上公共 DNS**。这种情况本机 `dig` / `curl` / 浏览器结果**全部不可信** —— 站点可能完全正常,只是被本机代理拦了。
+
+- 判据:`dig +short A <域名>` 返回 `198.18.*` / `198.19.*`,或 `dig @1.1.1.1 <域名>` 超时。
+- 对策:**从云端验证,别信本机**:
+  - `WebFetch https://<域名>` —— 从云端抓真实内容 / 看能否访问。
+  - `WebFetch "https://dns.google/resolve?name=<域名>&type=NS"` —— 查权威 NS。
+- 先让用户**关代理 / 换手机流量**再访问一次,很多「打不开」到此就解决。
+
+## 1. 内容层:站点真写进 KV 了吗
+
+```bash
+NSID=$(curl -s ".../accounts/<ACCT>/storage/kv/namespaces?per_page=100" "${A[@]}" | jq -r '.result[]|select(.title=="clize-sites").id')
+curl -s ".../accounts/<ACCT>/storage/kv/namespaces/$NSID/keys?limit=1000" "${A[@]}" | jq -r '.result[].name' | grep -i "<域名>"
+```
+有 `<域名>/index.html` 等 key → deploy 的「写 KV」成功了,进第 2 步。没有 → 站点根本没部署,重新 `clize deploy ./site --domain <域名>`。
+
+## 2. 绑定层:域名绑到 handle-site 了吗
+
+```bash
+curl -s ".../accounts/<ACCT>/workers/domains" "${A[@]}" | jq -r '.result[]|select(.service=="clize-handle-site").hostname' | grep -i "<域名>"
+```
+有 → 绑定 OK(若仍打不开,回第 0 步查代理 / 等 SSL)。**没有 → 域名没接到 worker(最常见的打不开原因)**,进第 3 步。
+
+## 3. DNS 层:CF zone active 吗 / NS 指 CF 吗
+
+```bash
+curl -s ".../zones?name=<域名>" "${A[@]}" | jq -r '.result[0]|{id, status, name_servers}'
+```
+- `status=active` → NS 已指 CF,直接跳第 5 步绑定。
+- `status=pending` → **NS 没委派给 CF**,这是断点。CF 注册的域名 NS 本应在 CF(异常,查 NS 记录);**Vercel 注册的域名**默认 `vercel-dns.com`,要切 → 第 4 步。
+
+## 4. ⚠️ Vercel 注册域名的 NS 坑
+
+Vercel 注册(`boughtAt` 有值、`serviceType:"zeit.world"`)的域名默认用 Vercel DNS。切到 CF:
+```bash
+# CF 的两个 NS = 第 3 步查到的 name_servers
+curl -s -X PATCH ".../v1/registrar/domains/<域名>/nameservers?teamId=<TEAM>" \
+  -H "Authorization: Bearer <VERCEL_TOKEN>" -H "Content-Type: application/json" \
+  -d '{"nameservers":["xxx.ns.cloudflare.com","yyy.ns.cloudflare.com"]}'
+```
+**关键坑**:切完后 Vercel 自己的 `nameservers` / `intendedNameservers` 字段**会显示滞后**(还写着 vercel-dns),只有 `customNameservers` 是你设的值。**别信 Vercel 的字段** —— 用 `WebFetch "https://dns.google/resolve?name=<域名>&type=NS"` 查**注册局权威 NS**,看到 `cloudflare.com` 就是切成功了。(经验:Vercel 注册域名的 NS **是能切到 CF 的**,之前「NS 锁死」是被这个滞后字段误导。)
+
+## 5. 修复:激活 zone + 绑 custom domain
+
+```bash
+# 催 CF 立即重查 NS(pending→active)
+curl -s -X PUT ".../zones/<ZID>/activation_check" "${A[@]}"
+# zone active 后,绑 custom domain 到 handle-site
+curl -s -X PUT ".../accounts/<ACCT>/workers/domains" "${A[@]}" \
+  -H "Content-Type: application/json" \
+  -d '{"hostname":"<域名>","service":"clize-handle-site","environment":"production","zone_id":"<ZID>"}'
+```
+绑成功 + KV 有内容 → 站点立刻上线(SSL 自动签,首访可能等几十秒)。
+
+## 认证速记 / 占位
+
+- CF API base:`https://api.cloudflare.com/client/v4`;认证 `A=(-H "X-Auth-Email: <email>" -H "X-Auth-Key: <CF global key>")`。
+- Vercel base:`https://api.vercel.com`;认证 `-H "Authorization: Bearer <VERCEL_TOKEN>"` + `?teamId=<TEAM>`。
+- `<ACCT>` / `<ZID>` / `<NSID>` 都用上面的 list 接口现查,别硬编码。
+
+---
+
+> **此排查流程已固化进部署**:[`src/core/sites.ts`](../../src/core/sites.ts) 的 `ensureZoneActiveForHandle` 会在 `clize deploy` 时自动建 zone / 切 NS(Vercel 域名)/ 激活 / 绑定,且绑定失败会**报错**(不再 `.catch(()=>{})` 假成功)。所以新部署一般不会再出这问题;这个 skill 主要用于**排查历史遗留**(那次 bug 期间「假成功」但没真接上的站)和**事后核验**已上线域名。建站流程见 `clize-site-build` skill。