跳轉到

歷史記錄 · 2026-07-22

月份索引｜歷史記錄

重大重構里程碑

2026-07-22 ─ signaling canon 對齊輪：repo 規格全面對齊已交付實作、CF Workers 降「規劃中方向」、/match 配對藍圖除名（部署資訊/open-4wd-signaling.md 整檔改寫、程式架構/signaling-service.md §3–§5 改寫、程式流程圖重繪）

決策檔：D-20260722-01

open-4wd-signaling 實作（07-19～20 交付、07-22 TURN 增補）落地後，canon 仍是實作前的舊 provider 藍圖——根源＝signaling 設計 doc §13「spec 待更新 10 項」除 /turn-token 外九項未回寫。本輪盤點（必改 20／判斷 7／不動 15）→ 裁決 → 全數執行：

CF Workers 降「規劃中方向」（J1 裁 (b)）：原 07-05 D1 部署模型定案「open-4wd-signaling＝Cloudflare Worker、官方 day-one 部署（Workers 免費額度、無機器）」——實作交付形狀＝平台無關協定核心（core 純 reducer）＋Node 適配器單一實作，無任何 CF 產物。裁決＝方向不翻案、時序標明：官方部署現況＝Node 路徑（use-template 部署 repo＋docker compose；all-in-one 可與 coturn 同機）、CF Workers 適配器＝規劃中方向（時機待裁決＝工作區內部文件（未入 repo）伺服器元件依賴分析 §10.8、待辦掛 §10.9-15）；wrangler／Durable Object／KV／worker/index.js 機制細節自 canon 全數移除、CF 僅存「規劃中」一句。散佈點同語義對齊：部署資訊.md §4.2（Provider 表改「client 端分級命名＝同質 wss 端點清單、伺服器端同一實作」——「級＝變體」對映拆除〔J3〕）、使用技術.md §4.1/§9、流程/配對.md §6、程式架構.md 索引列、工作區內部文件 伺服器元件依賴分析（§1.1/§2/§3.2/§4/§10 決策記錄殘影同步；「signaling + redis」操作指引修正）。

/match 配對藍圖除名（J4）：原 canon 把 POST /match KV 佇列／match-request 轉發／match-found 寫成活功能——實作零配對（/match 端點不存在、match-request 經 WS 靜默丟棄、match-found 不產生；配對主路徑＝GossipSub）。canon 全除：wire 表兩列改標「型別存在、無生產使用」、程式流程「自動配對流程」KV 時序圖整圖刪除（gossip 版專圖已在 程式流程/matchmaking.md）；「中央 /match＝已知韌性缺口」記錄（含未簽章評分 POST 弱點）不留 repo 規格正文、住工作區內部文件（未入 repo）伺服器元件依賴分析 §10.6-②。redis 字樣（含「無 redis」否定句）全 corpus 清零。

§13 懸置九項一次清償：①repo 目錄樹改實檔集（core/＋adapters/node/＋deploy/docker 兩 compose＋scripts；vendored MANIFEST hash 雙層漂移檢查補記）②伺服器義務補記（64 上限伺服器強制＝防全房快照被 client parser 丟棄；liveness＝WS ping/pong、間隔派生＝PEER_TIMEOUT_MS/3）②b 三條安全規則（未 register 不得送訊息／sender 須等於綁定 PeerId／register 期限逾時關閉）③peers 保留註冊順序＝安全相依明文化（首項即房主、client 防冒充依據）④join-as-spectator＝伺服器只回答路由（recommendedSource＝房主、password 忽略、空房 room-closed）、許可裁決在房主撥號層——觀戰.md 步驟 3 歸屬語同步（J7）⑤/match（上段）⑦伺服器常數進 程式參數表 §9 伺服器段（RATE_LIMIT_PER_MIN 60／PEER_TIMEOUT_MS 90_000＝唯一時窗旋鈕／REGISTER_DEADLINE_MS 10_000／MESSAGE_RATE_LIMIT_PER_MIN 1_200／maxPayload 256 KiB）＝單一權威、repo 規格檔 env 表引用（J5）⑧Vercel 標受阻（client 零 SSE）／Deno Deploy 標存疑（無 per-key 路由原語）⑨peerId 唯一＝自我取代語意（同連線重送＝違規關閉；新連線合法 proof＝原位換鍵保序、舊連線 close code superseded）。§5 Rate Limit 同步實況（in-memory 固定窗、TRUST_PROXY 預設關、訊息級限流、/turn-token 獨立窗）；leave 補「以 left 關閉連線」步。

turn canon「不併入原因」句重寫（J2）：原「因需 raw UDP、不可跑 Cloudflare Workers——這是它不併入 signaling repo 的原因（部署目標不同：Cloudflare vs k8s）」對比框架失真（signaling 現況非 CF、且 all-in-one 已讓兩者同一份 compose 部署）→ 改「一 repo＝一部署單元＝一條 CI；coturn＝無自寫程式碼的第三方軟體設定模板 vs signaling＝TS 服務」（raw UDP 保留為 coturn 特性；部署資訊/open-4wd-turn.md :5＋部署資訊.md §4.3＋工作區內部文件 伺服器元件依賴分析 §3.2 三處同步）。

程式流程圖重繪：整體架構圖（CF Edge／DO／KV 拓撲→Node 單行程拓撲）、多 Provider Fallback（webrtc-star 誤植修＝中央 signaling server 語義、CF 字樣除）、部署選項對照（四平台平列→Template→部署 repo→兩 compose 形狀）——改動圖套 流程.md §3 樣板（init＋五色 classDef）；連線建立時序圖與訊息流圖（「純訊息轉發、不存長期狀態」）與交付一致、原樣保留。

附帶：pinning「Go」殘影兩處修（程式架構.md 索引列、使用技術.md §9→TypeScript app 三容器現況——07-20 pinning A′ 改寫的索引鏡像漏網）。

2026-07-22 ─ open-4wd-turn 公版模板落地＋signaling /turn-token 憑證端點＋all-in-one compose：TURN 認證鏈端到端完整（部署資訊/open-4wd-turn.md 逐節對齊實檔、程式架構/signaling-service.md 新 §6.1）

turn repo 建成（零自寫程式碼＝conf 模板＋部署 manifests＋驗證 CI；coturn 上游官方 image 釘版 coturn/coturn:4.14.0、compose／k8s／CI／all-in-one 全引用處同值）：config/turnserver.conf.tmpl（8 佔位鍵；denied-peer-ip 內網／保留段全段防跳板）／deploy/docker-compose.yml＋.env.example（單機路徑；envsubst 渲染前須 set -a; . ./.env; set +a 匯入）／deploy/k8s/ 四件（hostNetwork＋Recreate＋replicas 1；TLS 掛載側移 /etc/coturn-tls、不巢於 configMap 唯讀掛載）／⭐deploy/examples/deploy.yml＝部署 repo 用 workflow 樣板附檔模式（放 examples/ 下公版不執行、use-template 後複製啟用：必填三鍵 :? 硬檢、configmap 由渲染檔生成、secret 真值 --from-literal 注入〔repo 內 secret.yaml＝形狀樣板不 apply〕、apply 後顯式 rollout restart〔conf 變更不自動觸發滾動、中繼會話會斷〕、concurrency 序列化、部署後 smoke）／.github/workflows/ci.yml＝公版唯一 workflow 純驗證（樣本值渲染＋模板佔位集↔樣本鍵集集合比對〔envsubst 對未設值靜默代空、grep 降級後盾〕＋compose config＋k8s YAML parse＋真 coturn 冒煙 turnutils_stunclient／turnutils_uclient -W、logs-before-assert）。

signaling repo 增補（tests 67＋e2e 2 全綠、零新依賴）：⭐POST /turn-token REST 憑證端點——重用 register proof 驗身（{ peerId, proof: { nonce, timestamp, signatureHex } }、purpose 哨兵 '/turn-token' 佔 room 位）、回 coturn REST auth 短期憑證（username＝到期秒:peerId、credential＝base64(HMAC-SHA1(secret, username))、ttlSec: 300）、錯誤面 404（未組態）/413/400/403 invalid-proof/403 nonce-replayed/429、獨立 nonce 表＋限流窗＋tick 剪枝（剪枝窗＝時戳容忍窗、無重放縫）；'/' 前綴房名整段保留（WS 註冊房名等於哨兵或以 '/' 開頭一律拒）；http／升級兩路 request-target URL 解析加固（畸形 target 單請求可崩整行程→安全解析、失敗回 400）；all-in-one compose（deploy/docker/docker-compose.all-in-one.yml＝signaling＋coturn 一台全包；signaling in-memory、無 redis；必填四鍵 :? 硬檢拒起）。

canon 同步：⭐「純 STUN 自架＝零設定（不填 secret）」句安全語義修正（部署資訊/open-4wd-turn.md §7）——空值／週知 secret＝任何人可自算 HMAC 憑證＝開放中繼；正確＝secret 仍填高熵隨機值且不提供給任何 signaling（TURN 面實質停用）、徹底關閉＝conf 加 stun-only、嚴禁留空或沿用樣本值。另：all-in-one 組成「signaling＋redis＋coturn」→「signaling＋coturn」（redis 殘影清除，含 部署資訊/open-4wd-signaling.md 兩處）；部署 repo 跟版首次 merge 補 --allow-unrelated-histories；§4 變數表對齊 deploy.yml 實態（REALM／EXTERNAL_IP＝GitHub vars 渲染入 configmap、TLS 憑證＝營運者手動入叢集 Secret、必填三鍵缺值紅燈）；§2 樹改列 ci.yml＋deploy/examples/deploy.yml（原 deploy.yml 在公版樹＝已非現況）。client 呼 /turn-token 餵 iceServers＝主 repo 待辦（官方 TURN 上線時 iceServers 首位加回；記工作區內部文件（未入 repo）伺服器元件依賴分析 §10.9-14）。

2026-07-22 ─ 流程/ 12 檔 ASCII 流程圖全面 Mermaid 化＋圖表風格規範定案（流程.md §3 改版、26 圖、零語意變更）

使用者裁決風格樣張（house-style flowchart＋sequenceDiagram 對照）方向可行後執行。①流程.md §3「圖表工具」改版為「圖表工具與風格規範」：全 corpus 圖表一律 mermaid（ASCII ↓ 箭頭表示法退場）；圖型對應（線性管線→flowchart TD／多方訊息→sequenceDiagram／狀態機→stateDiagram-v2）；統一 init 樣板＋classDef 五色語意（local 綠＝本地單端／consensus 黃＝多方協調／chain 藍＝帳本全網／fail 紅＝中止拒絕／ui 紫＝呈現）＋形狀語意（([…]) 觸發／{…} 決策／[(…)] 帳本寫入）；sequence box 三色板；轉換紀律＝圖是骨架、文字是權威（規範細節不入節點標籤、下沉圖下「步驟細目」清單，嚴禁圖文兩份規範文字）；GitHub 相容紅線（禁 fa: 圖示／不用 ELK／顏色 classDef 明示）。②流程/ 12 檔批量轉換：約 120 個 ↓ 的 ASCII 區塊全數改寫為 26 張 mermaid（治理事件流程 §1 採 sequenceDiagram；衍生流程 §2 fork 樹＋§4 分潤扇出一併圖化；比賽進行流程 7 塊全轉）；原區塊內規範細節（公式引用、參數、門檻）逐字下沉為「步驟細目」編號清單——零刪減、語意零變更。③總覽.md 的 流程.md 行描述同步。grep 驗證：流程/ 內 ↓ 歸零、26 張 mermaid 分佈 12 檔。

2026-07-22 ─ 檔名維持中文與 URL slug 預留

決策檔：D-20260722-02

  • 規劃靜態文檔站時重新評估「檔名是否該拉丁化」：中文檔名在 GitHub 與未來站點都會產生 percent-encoded URL，分享出去不美觀。裁決＝維持中文檔名——拉丁化要重寫 1,600 筆以上入站連結，且社群與貢獻者以中文為主、中文檔名本身就是導覽線索。
  • 退路以 frontmatter slug 欄位預留（值為 null 或 ASCII slug）：日後若「分享連結美觀」成為真實需求，加一層轉址即可，不改檔名、不動任何入站連結。該欄位隨兩日後的 corpus frontmatter 上線一併落地，現階段全 corpus 一律 null。
  • 連帶紀律：檔名是入站連結與錨點的穩定載體，啟用轉址層時同樣不改檔名。