# Server Diagnostics（伺服器診斷）

已整合至 Core 側邊欄，順序為 Plugins → Server Diagnostics → Hash & Checksum。它不需要 SSH 工作階段，也不需要下載外掛程式。所有執行階段程式碼、測試與測試資料都位於 `app/` 中；此模組不依賴任何同層的存放庫。存放庫中沒有 `doc.md`，因此由本文件與兩份 README 說明其實作。

## 使用者工作流程

輸入主機名稱、IPv4、IPv6 或 HTTP(S)/WS(S) URL。單獨的主機名稱/IP 預設使用 HTTPS；明確指定的 URL 在要求過程中會保留其路徑、查詢參數與連接埠。URL 中的登入憑據、不支援的通訊協定配置、空白/控制字元，以及類似 shell 的主機名稱都會被拒絕。IPv6 常值會自動加上方括號；URL 剖析器不支援帶有範圍/鏈路本機區域識別碼的位址。

選擇 Auto（優先使用 IPv4，否則使用 IPv6）、IPv4、IPv6 或 Both。使用「解析位址」可選擇特定的目前回應。總覽會顯示所有解析出的回應；探測會測試所選位址，或為每個要求的位址家族各測試一個位址。兩種位址家族會各自獨立量測。僅有 AAAA 記錄存在，絕不代表 IPv6 連線可正常運作。

Run Diagnostics（執行診斷）會執行 DNS、ping、traceroute、HTTP、壓縮、TLS 以及所選的 TCP 連接埠檢測。WebSocket 需手動選擇啟用。每項工具也都有個別的執行/停止控制項。同一時間只能有一次診斷執行處於作用中。一次執行完成僅代表各項工具已結束，並不代表每項探測都成功。不存在籠統的「伺服器離線」判定。

逾時、封包數量、重複次數、最大躍點數、DNS 解析器、通訊協定選擇、預熱連線以及 HTTP/HTTPS 比較皆可設定。變更目標會清除先前選取的 IP。歷史紀錄可重新開啟、比較兩份報告、刪除、匯入 JSON、複製，或透過原生 Core 對話框匯出為 JSON/CSV/TXT。淺色/深色/系統主題適用於診斷區段，並儲存在既有的 UI 設定中。CZ/DE/EN 介面語言會立即跟隨應用程式語言。

## 元件與通訊協定行為

| 元件 | 實作與解讀 |
| --- | --- |
| `common.js` | 驗證目標/選項、限制與列舉值；IDNA 轉換；數值統計會排除未知值。 |
| `dnsDiagnostics.js` | 系統位址解析使用 `dns.lookup`，以遵循作業系統設定與 hosts 檔案。記錄查詢使用受限的 UDP DNS，並在回應被截斷時退回 TCP，查詢對象為 `dns.getServers()` 或明確選擇的自訂/公共解析器。不會在未告知的情況下切換到公共 DNS。 |
| `processTools.js` | 以參數陣列與 `shell: false` 執行作業系統的 ping/traceroute，限制輸出、設定明確的逾時，並負責中止/終止的清理。剖析封包回覆與躍點，而不是將程序執行時間當作 RTT。 |
| `httpDiagnostics.js` | 內建 curl 用於 HTTP/1.1、HTTP/2 和 HTTP/3；嚴格的憑證驗證與固定的 IP 位址家族。每個版本都會個別要求，並記錄實際使用的版本。 |
| `socketDiagnostics.js` | 明確的 TLS 版本探測、受限的 TCP 連線/被動橫幅讀取、使用既有 ssh2 相依套件在驗證前觀察 SSH 主機金鑰，以及選用的 RFC 6455 Upgrade 驗證。 |
| `diagnosticsService.js` | 執行與取消工具、選擇/驗證位址、串流進度、保留部分量測結果，並負責執行的截止時間。 |
| `historyStore.js` | 具版本控制、有容量上限的本機歷史紀錄、資料遮蔽、經結構檢查的匯入，以及量測資料的匯出。 |

### ICMP 與路由

Ping 預設會逐一傳送四個 ICMP echo 要求。結果包含每個封包實測的 RTT、已收到/已傳送數量、封包遺失、最小值/平均值/最大值、母體標準差、相鄰兩次實測 RTT 差值的平均絕對值（抖動）、輸出中有提供時的 TTL/Hop Limit，以及時間戳記。`<1 ms` 的回覆會計為已收到並記錄其上限，而不會編造具體的 RTT 數值。未知的 RTT 不計入延遲統計。統計使用保留範圍內最多 500 個封包；傳送/接收/遺失計數則涵蓋整次執行。圖表顯示最近 200 次觀測，並以不同符號區分回覆、低於解析度的回覆、遺失的回覆，以及明確的要求/程序逾時。

遺失的回覆可能反映 ICMP 過濾、封包遺失或逾時；這些觀測無法確切斷定存在防火牆。缺少執行檔、本機權限失敗與無效的工具呼叫屬於個別的工具錯誤，而非封包遺失或伺服器無法使用。不會要求提升權限。

Traceroute 會串流顯示躍點、位址、個別探測、平均值，以及觀測到的未回應探測百分比。反向 DNS 會在路由完成後使用所選解析器進行解析。重複執行會比較觀測到的躍點位址序列；差異可能反映負載平衡。中間躍點未回應並不能證明路由中斷。原始探測中繼資料與方法會顯示在可展開的詳細資料中。macOS 要求 traceroute 的等待時間為整數秒；實際生效的四捨五入逾時值會被記錄下來。

### DNS

十二種記錄類型為 A、AAAA、CNAME、MX、NS、TXT、SOA、SRV、CAA、PTR、DS 和 DNSKEY。DNS 封包剖析會檢查交易/問題的一致性、記錄大小、壓縮指標迴圈以及訊息限制。回應會保留記錄的 TTL、查詢時間、解析器，以及 NXDOMAIN/NODATA/SERVFAIL/refused/timeout 狀態。作業系統的位址查詢無法提供 TTL；另行執行的記錄查詢則可以。

跟隨 CNAME 最多八次，並具備迴圈偵測。一致性檢查會從所選解析器重複取得 A/AAAA 回應，並對 IP 常值的 DNS 測試執行正向確認的 PTR 查詢。回應有所變化僅是一種觀測，並不能證明 DNS 發生故障。SRV 查詢會依原樣使用目標名稱；必要時請輸入服務名稱，例如 `_service._tcp.example.org`。DNSSEC 一律**未經驗證**。DS/DNSKEY 的存在，甚至解析器的 AD 旗標，都絕不會被視為獨立的驗證。

### HTTP、效能與壓縮

只有在伺服器實際傳回 HTTP/1.1 時，才會認定該版本受到支援。HTTPS 上的 HTTP/2 需要協商出 h2；任何退回都不會被重新標示。明文 HTTP/2 使用事先知識（prior knowledge），而非 HTTP/1.1 Upgrade 探測。對於每個 HTTP/WebSocket 要求，TLS 驗證一律保持嚴格。

手動重新導向最多八次；迴圈、無效的目的地與過多的重新導向都會明確回報失敗。完整的重新導向鏈會記錄跨網域變化與 HTTPS 降級；通訊協定配置與 www 的變化可從來源/目的地 URL 看出。登入憑據與非 HTTP(S) 的重新導向配置會被拒絕。每次跨主機的重新導向都會透過所選解析器與要求的 IP 位址家族獨立解析。

量測項目包括 DNS（若有執行）、TCP、TLS、最終回應的 TTFB、包含 DNS/重新導向的整體 TTFB、下載、重新導向與總經過時間、實際的實體位元組數、傳輸速度、狀態、回應標頭、實際的伺服器位址/連接埠、ALPN，以及經驗證的連線重複使用。在固定或重複使用的連線上未執行的 DNS/TCP/TLS 階段會顯示為 `N/A`，而不是虛假的零值。QUIC 沒有 TCP 階段；其交握會另行記錄。標頭傳輸或完整的線路額外負荷不會被當作實體位元組的量測結果。這些是伺服器/網路的時間資料，而非網頁轉譯時間或 Lighthouse 分數。

每個選取的通訊協定都使用相同的目標與重複次數。IPv4/IPv6 與 HTTP/HTTPS 是明確的比較選項。另一種通訊協定配置會使用其預設連接埠。每個通訊協定在每次取樣時都會啟動一個獨立的內建用戶端程序。不會宣稱連線有被重複使用。總時間統計包括最小值/平均值/中位數/最大值/最近排名 P95，以及獨立的傳輸/通訊協定錯誤率；即使伺服器成功傳回 4xx/5xx 回應，HTTP 狀態碼也會保持可見。

壓縮檢測會分別以 identity、gzip、deflate、br 以及（在執行環境支援時）zstd 作為 Accept-Encoding 傳送要求。Content-Encoding 必須相符，且受限的解壓縮必須成功。只有在解碼後的內容雜湊、最終 URL 與狀態都與 identity 基準一致時，才會計算壓縮率。被忽略的編碼視為不支援；內容會變動/動態的回應不計算壓縮率。這只是針對該 URL/狀態的觀測結果，並不代表伺服器的普遍支援情況。

安全性標頭檢查會顯示 HSTS、CSP、X-Content-Type-Options、Referrer-Policy、Permissions-Policy 與 X-Frame-Options 是否存在及其值。CSP 的 frame-ancestors 指示詞可以取代後者。標頭存在並不能證明原則設定正確，也不能證明網站是安全的。

### HTTP/3 的需求與證明


HTTP/1.1、HTTP/2 和 HTTP/3 使用同一個內建的 curl 用戶端。macOS arm64 與 Linux x64 使用 curl 8.22.0、OpenSSL 3.5.9、nghttp2 1.70.0、ngtcp2 1.25.0 和 nghttp3 1.18.0。Windows x64 使用 curl.se 官方的 curl-for-win 8.22.0_3 靜態組建，搭配 LibreSSL 4.3.3 及相同的 HTTP 程式庫。不需要退回使用系統 curl、不需要在執行時下載，也不需要管理員權限。Windows 上游的可重現建置方法位於 https://github.com/curl/curl-for-win/tree/9d77e31e 。

封裝前請使用 `python3 scripts/native/build.py` 建置（Windows：`python scripts/native/build.py`）。macOS/Linux 需要 C/C++ 工具、CMake、Ninja、Perl、make 和 pkg-config。原始碼依版本與上游 SHA-256 固定於 `scripts/native/dependencies.lock.json` 中。指令碼會驗證每一次下載、以靜態方式連結第三方傳輸程式庫，並在缺少 HTTP2/HTTP3/SSL 功能時失敗。只有作業系統程式庫維持動態連結。Windows 使用固定的官方二進位壓縮檔，而非在本機編譯的 Windows 傳輸堆疊。內建的 CA 檔案有其獨立固定的雜湊；元件授權與上游建置來源資訊會隨執行環境一併提供。

用戶端與信任存放區安裝在 app.asar 之外的 `resources/native-runtime/<platform>-<arch>/` 中。每次診斷前都會驗證元件雜湊、架構與執行檔的功能。設定檔、Proxy、TLS 信任環境覆寫以及程式庫注入變數都會被排除。curl 以絕對路徑執行、停用 shell、使用經過驗證的 CA 信任、明確解析的 IP 位址家族、不使用 Cookie、不自動跟隨重新導向，並限制輸出與時間。重新導向由應用程式驗證並重新解析。支援 443 以外連接埠上的 HTTPS。

HTTP/3 使用 `--http3-only`，只有在完成一次回報 HTTP 版本 3 且憑證驗證成功的傳輸後才會確認。404 之類的 HTTP 錯誤回應也可以確認該通訊協定。Alt-Svc 只是一種通告，而非證明。QUIC 逾時、憑證失敗、DNS 失敗、連線遭拒、通訊協定不相容以及元件故障會分別區分。UDP 逾時代表伺服器是否支援仍未經驗證。QUIC 交握時間不會被回報為 TCP 時間。

每次量測都會啟動個別的程序/連線。warm 選項不會宣稱內建用戶端重複使用了連線。如此可確保通訊協定比較的一致性。報告包含執行環境版本、功能、TLS 驗證與 QUIC 計時，而歷史紀錄/匯出會移除內容、URL 查詢參數與驗證標頭。

更新傳輸堆疊或 CA 信任存放區時，請更新這些固定值，並為每個支援的平台重新建置。已發布的成品與原始碼快照不可變更。

## Core IPC

Preload 只公開 `window.chjCore.diagnostics`；所有處理常式都保留既有的主視窗傳送者檢查，網路作業一律在主要程序中進行。結果使用 `{ ok: true, value }` 或 `{ ok: false, error: { code, message } }`。

| 通道 / preload 方法 | 承載資料 / 結果 |
| --- | --- |
| `diagnostics:resolve` / `resolve(options)` | 經驗證的目標/設定 → 目標與解析出的位址。最多同時進行兩個解析要求。 |
| `diagnostics:start` / `start(options)` | 經驗證的目標/設定/工具選擇 → 不透明的工作 ID 與初始報告。 |
| `diagnostics:cancel` / `cancel(id, tool?)` | 取消一個作用中/佇列中的工具或整次執行。 |
| `diagnostics:get` / `get(id)` | 已知執行或已儲存報告的快照。 |
| `diagnostics:history` / `history()` | 本機歷史紀錄摘要。 |
| `diagnostics:removeHistory` / `removeHistory(id)` | 移除所選的歷史紀錄項目。 |
| `diagnostics:copy` / `copy(id, format)` | 主要程序將一份經過遮蔽的已知報告寫入剪貼簿。 |
| `diagnostics:export` / `export(id, format)` | 透過原生儲存對話框匯出 JSON/CSV/TXT；轉譯器無法提供檔案系統路徑。 |
| `diagnostics:import` / `import()` | 原生檔案選擇器，儲存前會進行大小/結構/深度驗證與資料遮蔽。 |
| `diagnostics:progress` / `onProgress(callback)` | 解析出的位址、工具的開始/完成、封包、躍點、HTTP 取樣與完成狀態；傳回一個取消訂閱的回呼。 |

不公開任何通用的 shell、檔案系統或網路 API。內容隔離、沙箱、停用的 Node 整合以及既有的轉譯器 CSP 都保持啟用。既有的外掛程式合約與更新程式的驗證/例外均未變更。

## 資源預算與本機資料

- 一次執行、兩個作用中的工具，每個工具最多探測兩種 IP 位址家族；TCP 另外將每個位址限制為四個連線。
- 每項作業的逾時為 250–30000 ms；1–100 個封包、1–20 次重複、1–40 個躍點、1–16 個連接埠。一般執行會在五分鐘後停止；持續 ping 會在三十分鐘後停止。traceroute 子程序另有 180 秒的上限。
- 程序輸出通常為 256 KiB；HTTP 實體內容 2 MiB；解壓縮後的內容 8 MiB；HTTP 標頭有大小限制；回應內容不會進入歷史紀錄。
- 最多保留 500 個封包/進度事件、記憶體中的五次執行、三十份歷史報告以及 10 MiB 的歷史紀錄。歷史紀錄使用既有的私有不可分割寫入器，路徑為 `<userData>/diagnostics/history.json`（模式 0600）。
- 匯入的檔案最大 2 MiB、結構版本 1，巢狀層級受限且結果集合經過驗證。CSV 儲存格會被跳脫，公式前置字元會被中和。URL 查詢參數/片段、登入憑據、Cookie、驗證標頭與原始內容都會從儲存/複製/匯出的報告中排除。原始詳細資料顯示的是量測到的結構化資料，而不是封包擷取或保留的回應內容。
- 沒有雲端同步、自動登入、伺服器設定變更或激進/不受限制的掃描。目標/連接埠/解析器由使用者明確選擇。

## 平台需求與驗證

| 平台 | ICMP | 路由 | 其他通訊協定 |
| --- | --- | --- | --- |
| Windows 10/11 | `ping.exe -4/-6` | `tracert.exe -4/-6`，ICMP | 內建的 curl.exe，支援 HTTP/2 和 HTTP/3。在地化的 RTT 欄位不依賴「time」這個字。 |
| macOS | `/sbin/ping`、`/sbin/ping6` | `/usr/sbin/traceroute`、`/usr/sbin/traceroute6`，UDP；整數秒等待 | 內建 curl，支援 HTTP/2 和 HTTP/3。 |
| Ubuntu/Linux | iputils `ping -4/-6` | 標準的 `traceroute -4/-6`，UDP | 內建 curl，支援 HTTP/2 和 HTTP/3；缺少 ICMP/路由工具時會另行回報。 |

沒有新增任何 npm 相依套件。實作使用 Node 內建模組與應用程式既有的 ssh2。它不會安裝系統工具，也不會要求管理員權限。防火牆與 UDP 限制可能讓測試無法確認支援情況；僅憑一次逾時無法推斷出這些限制。

自動化測試涵蓋範圍位於 `diagnosticsCore.test.js`、`diagnosticsNetwork.test.js`、`diagnosticsHttp.test.js` 與 `diagnosticsIpc.test.js`：驗證/IPv6 常值、原生/本機 DNS UDP+TCP 測試資料、遺失/雙位址家族回應與解析器錯誤、CNAME/一致性、作業系統參數/剖析測試資料、受限的實際子程序、遭封鎖的 ICMP 觀測、實際的本機 HTTP/1.1 與 TLS h2、重新導向/內容限制/逾時/重複使用、啟用/被忽略的壓縮、HTTP3 功能/成功結果剖析/拒絕退回、本機 CA 信任/不符/過期以及實際的 IPv6 HTTP/HTTPS、TCP 連線/遭拒/模擬逾時、實際的 WebSocket 與 SSH 驗證前交握、取消/清理/部分結果、離線狀態、私有歷史紀錄往返/匯入拒絕/匯出、受信任的 IPC 與 preload 訂閱。

`npm test` 會執行確定性的測試，不依賴公共測試伺服器。`npm run test:diagnostics:ui` 會在圖形化的 Electron 桌面中執行 `scripts/smokeDiagnostics.js`，使用正式環境的 UI/preload/IPC，以及實際的本機 HTTP/壓縮探測。只有在此測試工具中，無關的服務才會被替換為虛設/離線狀態。它會檢查導覽順序、通訊協定結果、持續保存、CZ/DE/EN、兩種主題、窄視窗溢位以及沙箱偏好設定。若 shell 設定了 ELECTRON_RUN_AS_NODE，請在執行此指令時取消設定。

目前的執行環境驗證涵蓋受控的 QUIC 傳輸、IPv4/IPv6、非預設連接埠上的 HTTPS、404 回應、TLS 失敗，以及一個通告 Alt-Svc 的純 TCP 服務。每個組建的結果會隨各版本一併提供。

明確的選用限制：不進行獨立的 DNSSEC 驗證（需要完整的驗證型解析器/信任錨點生命週期）、不進行 Lighthouse 稽核（僅限伺服器/網路計時）、不進行已淘汰 TLS 稽核或撤銷/CT 服務檢查、不宣稱 HTTP3 預熱重複使用，也不量測 HTTP/3 預熱重複使用。不支援的功能會如實顯示，而不是加以模擬。

## 此變更中的檔案

新建：`src/main/diagnostics/` 中的七個服務檔案；`src/renderer/diagnostics.js`、`diagnosticsI18n.js`、`diagnostics.css`；四個 `test/diagnostics*.test.js` 檔案；`test/fixtures/diagnostics/` 下的五個檔案；`scripts/smokeDiagnostics.js`；本文件。

整合/更新：`src/main/index.js`、`src/main/ipc/registerCoreIpc.js`、`src/preload/corePreload.js`、`src/renderer/index.html`、`app.js`、`i18n.js`、`package.json`、`app/README.md`、根目錄的 `README.md`、`.gitignore`（四個公開測試資料例外），以及根目錄的 gitleaks 允許清單——其中僅精確列出那個刻意公開的 TLS 測試金鑰資料。簽署 CA 的私密金鑰已被捨棄；該測試資料絕不會被應用程式執行環境使用。