From 86b3797c55aca6ac1253a3fb6cc8e08a20473ab4 Mon Sep 17 00:00:00 2001 From: heweidong-ecco <290444878+heweidong-ecco@users.noreply.github.com> Date: Mon, 21 Sep 2026 21:54:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20origin=20=E6=94=B9=E8=B5=B0=20SSH-over-?= =?UTF-8?q?443=20+=20=E4=B8=A4=E6=9D=A1=E6=93=8D=E4=BD=9C=E5=88=A4?= =?UTF-8?q?=E6=8D=AE=EF=BC=88CLAUDE.md=20=C2=A78=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 诊断到层:github.com:443 的 **HTTPS 被掐** —— DNS 正常、TCP 能连(nc 通), 但 curl 12s 超时、git 报 "Failure when receiving data from the peer" / "expected flush after ref listing";同一时刻 api.github.com 是 HTTP 200(0.11s)。 - origin 改走 ssh://git@ssh.github.com:443/heweidong-ecco/memory-system.git (只改本地 remote,不动仓库设置;实测 git fetch 一次成功) ⛔ 不要改回 https。选"换通道"而不是"降标准"(关 TLS 校验明确禁止) - CLAUDE.md §8 补两节: ① 本仓 origin 走 SSH-over-443 + 判据表(含"gh 通 ≠ git 通"、SSH 认证被拒怎么办) ② 判断命令成败别经过管道 —— `git fetch … | tail -1` 的退出码是 tail 的、恒为 0, 本次真实踩到两次:打出假 ✅("fetch 成功"而 origin/main 根本没动),差点据此以为已同步 - 顺带清掉两处遗留:6 个过期本地远端引用(remote prune)· 1 个远端孤儿分支 ci/blocking-embedding-job(PR #4 已合并但分支没删) ⚠️ 删前核对方法:squash 造新 SHA ⇒ merge-base --is-ancestor 必为假, 要用 git diff --stat <旧分支> 是否为空来判断(本次为空 ⇒ 删除无损) 提交前两问 ① 本次有决策事项 ⇒ 新建 DEC-008-推送走哪条通道-20260921.md (四选一:继续重试 https / 改走 SSH-over-443 / 用 gh API 造提交 / 关 TLS 校验 → 选定第二种,理由"换通道而不是降标准";含反悔成本) ② CHANGELOG 已写(第 3 轮 Ops 小节) 测试:61 passed --- CHANGELOG.md | 19 +++++++ CLAUDE.md | 38 +++++++++++++ ...5\241\351\200\232\351\201\223-20260921.md" | 55 +++++++++++++++++++ 3 files changed, 112 insertions(+) create mode 100644 "docs/decisions\345\206\263\347\255\226/DEC-008-\346\216\250\351\200\201\350\265\260\345\223\252\346\235\241\351\200\232\351\201\223-20260921.md" diff --git a/CHANGELOG.md b/CHANGELOG.md index 365bb6e..6329c0f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,25 @@ --- +## [第 3 轮] · 2026-09-21 · A1/E/D4/C1 + 推送通道 · ✅ 已完成 + +> 本轮 4 个 PR 已合并(#4 #5 #6 #7);详见各小节与 `docs/decisions决策/DEC-004~008`。 + +### 操作(Ops)· 推送通道与仓库卫生 + +- **`origin` 改走 SSH-over-443**(`ssh://git@ssh.github.com:443/...`)—— + `github.com` 的 **HTTPS 被掐**(TCP 通、`curl` 12s 超时、git 报"收不到数据"),而 `api.github.com` 一直 200。 + ⛔ **不要改回 https**;判据表见 `CLAUDE.md §8`,裁决见 **`DEC-008`** +- **清理两处遗留**:6 个过期本地远端引用(`remote prune`)· 1 个远端孤儿分支 `ci/blocking-embedding-job`(PR #4 已合并但分支没删) + - ⚠️ 删前核对内容的方法:squash 会造新 SHA ⇒ `merge-base --is-ancestor` **必为假**, + 要用 `git diff --stat <旧分支> ` **是否为空**来判断 +- **`CLAUDE.md §8` 补两节**: + 1. **本仓 origin 走 SSH-over-443**(含"gh 通≠git 通"的判据表,与"⛔ 不许关 TLS 校验") + 2. **判断命令成败别经过管道** —— 用 `git fetch … | tail -1` 判成败 ⇒ 退出码恒为 0 ⇒ **假 ✅** + (本次真实踩到两次,差点据此以为已同步) + +--- + ## [第 2 轮] · 2026-09-21 · 挂 CI + RAG 条件性判据 · 🚧 进行中 ### 修复(Fixed)· ⭐ 本轮起改用 **TDD(先写会失败的测试)** diff --git a/CLAUDE.md b/CLAUDE.md index cdae712..5777a43 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -256,6 +256,44 @@ git log --oneline origin/main..HEAD # 核对:应只剩你自己 > `git fetch` 失败时 `git merge --ff-only origin/main` 会说 **「Already up to date」—— 那是假的**。 > **判据:`git ls-remote origin refs/heads/main` 读实际值,别信提示。** +### 🔀 本仓 `origin` 走的是 **SSH-over-443**(不是 https) + +**本机实测(2026-09-21)**:`github.com:443` 的 **HTTPS 被掐** —— +DNS 正常(`20.205.243.166`)、**TCP 也能连**(`nc github.com 443` 通), +但 `curl https://github.com` **12 秒超时**、git 报 `Failure when receiving data from the peer` / +`expected flush after ref listing`;同一时刻 **`api.github.com` 是 HTTP 200(0.11s)**,`gh` 全程可用。 + +⇒ 本仓 `origin` 已改为: +``` +ssh://git@ssh.github.com:443/heweidong-ecco/memory-system.git +``` +(GitHub 官方的 **SSH-over-443** 通道;`~/.ssh/id_ed25519` 已在 GitHub 登记,实测 `ssh -T -p 443 git@ssh.github.com` 直接通过) + +⛔ **`git remote -v` 看到这个 SSH URL 是正常的,别改回 https。** + +| 现象 | 判据 / 做法 | +|---|---| +| git 报 `Couldn't connect` / `Failure when receiving data` | 走的是 HTTPS 的话**重试 1–3 次**(实测第 1–3 次会通);或直接用 `gh`(API 通道独立可用) | +| `gh` 可用、`git` 不可用 | 两者走**不同主机**(`api.github.com` vs `github.com`)—— ⛔ **别把 "`gh` 通" 当成 "git 通"** | +| SSH 认证被拒 | 先 `ssh -T -p 443 git@ssh.github.com` 单独验;必要时 `-i ~/.ssh/id_ed25519 -o IdentitiesOnly=yes` | + +> ⛔ **不要**为绕过而关 TLS 校验(`GIT_SSL_NO_VERIFY`、改 CA)—— 那是拿安全换连通。 + +### ⛔ 判断命令成败,**别经过管道** + +**本次真实踩到两次**:用 `git fetch … | tail -1` 判成败 ⇒ +**管道的退出码是 `tail` 的,恒为 0** ⇒ 打出假的 ✅("fetch 成功"而 `origin/main` 根本没动), +差点据此以为已经同步。 + +**正确写法**: +```bash +if git fetch origin >/tmp/f.log 2>&1; then echo 成功; else echo "失败: $(tail -1 /tmp/f.log)"; fi +# 或让 $? 紧挨着被测命令:git fetch origin; echo $? +``` + +> 📌 与「别信 `Already up to date`」同族:**别让工具的输出格式替你做判断** —— +> 要用**能失败的东西**(退出码、实际 ref 值)来判,并且**报"已验证"前先确认判据本身没坏**。 + ### ⚠️ `gh` 通、`git` 不通 —— 判断真实远端状态要用 `gh` / `ls-remote` **本机实测(2026-09-21)**:`git fetch/push` 连续 6 次 16 秒超时(`Failed to connect to github.com port 443`), diff --git "a/docs/decisions\345\206\263\347\255\226/DEC-008-\346\216\250\351\200\201\350\265\260\345\223\252\346\235\241\351\200\232\351\201\223-20260921.md" "b/docs/decisions\345\206\263\347\255\226/DEC-008-\346\216\250\351\200\201\350\265\260\345\223\252\346\235\241\351\200\232\351\201\223-20260921.md" new file mode 100644 index 0000000..9a66b8d --- /dev/null +++ "b/docs/decisions\345\206\263\347\255\226/DEC-008-\346\216\250\351\200\201\350\265\260\345\223\252\346\235\241\351\200\232\351\201\223-20260921.md" @@ -0,0 +1,55 @@ +# DEC-008 · 推送走哪条通道(`github.com` 的 HTTPS 被掐) + +| 项 | 值 | +|---|---| +| **日期** | 2026-09-21 | +| **状态** | ✅ 已裁决:`origin` 改走 **SSH-over-443** | +| **触发** | 合并 PR #6 后 `git fetch/push` **连续多次失败**,而 `gh` 一直可用 | +| **相关** | `CLAUDE.md §8` · 用户全局规约的「推送节奏」条 | + +--- + +## 一 · 诊断(先定位到层,再选路) + +| 检查 | 结果 | 结论 | +|---|---|---| +| DNS `dig github.com` | `20.205.243.166` | ✅ 解析正常 | +| TCP `nc github.com 443` | **通** | ✅ 端口可达 | +| HTTPS `curl https://github.com` | **12s 超时**,HTTP `000` | ❌ **应用层被掐** | +| git 报错 | `Failure when receiving data from the peer` / `expected flush after ref listing` | ❌ 与上面一致:连上后**收不到数据** | +| `curl https://api.github.com` | **HTTP 200 / 0.11s** | ✅ 另一台主机,不受影响 | +| `ssh -T -p 443 git@ssh.github.com` | `Hi heweidong-ecco! You've successfully authenticated` | ✅ 可用 | + +⇒ **不是"GitHub 挂了",也不是"权限/证书问题",是 `github.com` 这一跳的 HTTPS 被干扰。** +**判据**:TCP 通 + HTTPS 不通 ⇒ 问题在应用层,**不在网络可达性**,换通道即可绕过。 + +## 二 · 备选方案 + +| 方案 | 优 | 劣 | +|---|---|---| +| A. 继续重试 https | 零配置 | 成功率低(实测要试 1–8 次才中一次),且**每次失败要等 15–75 秒** | +| **B. `origin` 改走 `ssh://git@ssh.github.com:443/...`** ✅**选定** | 一次实测即通;**不用改远端配置、不改 SSH config**(key 已登记) | 若哪天 SSH 也断,需换回/另想 | +| C. 用 `gh` API 造提交(blob→tree→commit→ref) | API 通道可靠 | **绕开 git**,本地与服务端会产生**不同 SHA 的同内容提交** ⇒ 分叉,后续要人工清 | +| D. 关 TLS 校验(`GIT_SSL_NO_VERIFY`)/ 改 CA | 可能"连上" | ⛔ **拿安全换连通** —— 明确禁止(用户全局规约亦禁止调 CA) | + +**选 B 的核心理由**:**换通道,而不是降标准**。B 与 A 花的是同类代价(多一条配置), +但把"碰运气"换成了"确定的路径";D 则是用安全性换连通性,不接受。 + +## 三 · 决定 + +1. `git remote set-url origin ssh://git@ssh.github.com:443/heweidong-ecco/memory-system.git` + (**只改本地 remote,不动仓库设置**;实测 `git fetch` 一次成功) +2. 该 URL **不要改回 https**;原因与判据表写进 `CLAUDE.md §8`。 +3. `gh` 仍照常用(API 通道独立),**但不得把"`gh` 通"当成"git 通"**。 + +## 四 · 遗留(本次顺带清掉的两处) + +- **6 个过期的本地远端分支引用** ⇒ `git remote prune origin` +- **1 个远端孤儿分支** `ci/blocking-embedding-job`(PR #4 已合并但分支没被删)⇒ 远端删除。 + ⚠️ 删前**先核对内容已在 main**:squash 会造新 SHA,`merge-base --is-ancestor` **必然为假**, + 所以判据要用 **`git diff --stat <旧分支>
` 是否为空**(本次为空 ⇒ 删除无损)。 + +## 五 · 反悔成本 + +低。`git remote set-url origin https://github.com/...` 一行即可改回。 +若将来 HTTPS 通道恢复且更稳,改回也无需改任何文件。