Jason Tools
文件工具箱

安裝與升級疑難排解

下面每一則都是真實發生過的狀況 —— 症狀、原因、怎麼辦。 安裝腳本與 jtdt update 失敗時也會把這一頁的網址印出來。

升級停在 git fetch failed Health check timed out CERTIFICATE_VERIFY_FAILED 沒有 git 的安裝無法更新 Windows 找不到 git / 沒有 winget uv venv failed 磁碟空間不足 readonly database 缺 Office 引擎 / 中文變方框 遠端使用者一上傳就 CSRF 失敗

升級停在 git fetch failed（would clobber existing tag）

症狀　jtdt update 印出 git fetch failed 就中止，服務被還原成原本的版本，看不出原因。

原因　本專案在 2026-09-13 改寫過 git 歷史（移除一筆誤入版控的資料）， 所有標籤都指向新的 commit。本地標籤還指著舊的時候， git fetch --tags（沒有 --force）會逐個回報 would clobber existing tag 並以離開碼 1 結束。

怎麼辦　跑一次下面這行就永久解決（只動 .git 裡的 ref， 不碰使用者資料）：

Linux / macOS
sudo git -C /opt/jt-doc-tools fetch --tags --force origin
Windows（以系統管理員身分執行 PowerShell）
git -C "C:\Program Files\jt-doc-tools" fetch --tags --force origin

不受影響：tarball 安裝（沒有 .git）、Windows 安裝程式、 或 2026-09-13 之後才安裝的。v1.15.41 起已修正。

Health check timed out（但服務其實是好的）

症狀　更新流程最後一步逾時，可是用瀏覽器打得開。

原因　改過監聽位址或連接埠（jtdt bind）之後， 舊版的健康檢查從執行更新那個 shell 的環境變數讀位址 —— 那裡根本沒有設定， 於是永遠去探 127.0.0.1:8765。企業環境的 http_proxy 也會讓「連自己」被送去代理伺服器。

怎麼辦　v1.15.15 起已修（改讀服務管理員自己的設定、直連不走代理， 並會印出探過哪些位址與日誌最後 20 行）。先升到該版以上； 還是逾時的話看 jtdt logs 的最後幾行。

CERTIFICATE_VERIFY_FAILED（企業 TLS 檢查環境）

症狀　更新、下載 OCR 語言檔、或連 LLM / SSO 時憑證驗證失敗。

原因　公司的 TLS 檢查代理把外部憑證換成自家 CA，而 Python / uv 預設不認那張 CA。

怎麼辦　程式會自動接上作業系統的信任庫（truststore）， 多數環境不必設定。仍然失敗時把企業 CA 匯入作業系統信任庫； 臨時繞過用 JTDT_TLS_INSECURE=1（只在確認過的內網用）。

沒有 git 的安裝無法更新

症狀　jtdt update 說找不到 git，或說這裡不是 git 儲存庫。

原因　機器上沒有 git 時，一行安裝會改走下載壓縮檔那條路， 裝出來的目錄沒有 .git。

怎麼辦　裝上 git 之後重跑一次一行安裝指令 —— 它會原地收編成 git 儲存庫（既有的 .venv 與資料都保留），之後就能正常更新。

Windows 找不到 git，或說要用 winget 安裝

症狀　剛裝完 git 還是找不到；或 Windows Server 上沒有 winget。

原因　剛安裝的程式只更新登錄檔裡的 PATH，已經開著的終端機（含新開分頁） 看到的仍是舊的；而 Windows Server 2019 / 2022 內建沒有 winget。

怎麼辦　直接再跑一次即可，不必重開機 —— 程式會依 「PATH → 登錄檔 → 標準安裝位置」三層去找。Server 版請到 git 官網下載安裝檔。

[X] uv venv failed（Windows 升級時）

症狀　用安裝程式裝到既有安裝上時失敗；無介面安裝還會像卡住不動。

原因　服務還跑著，python.exe 佔住了虛擬環境的檔案， 刪不掉。舊版的失敗對話框沒有無介面預設值，所以會等一個沒有人能按的按鈕。

怎麼辦　v1.15.37 起已修（安裝前先停服務並等行程真的放掉檔案， 所有對話框都有無介面預設）。卡住時先手動停服務再裝； 安裝程式自己的記錄在 C:\ProgramData\jt-doc-tools\Logs\installer.log。

升級時磁碟空間不足

症狀　備份階段失敗，而且服務已經停掉了。

原因　升級前會完整備份資料目錄並保留三份。

怎麼辦　v1.15.17 起在停服務之前就先檢查空間，並會說差多少； 備份也跳過會自己長回來的東西（統編資料庫、暫存、作業結果）， 實測每份 1.93 → 0.56 GB。清出空間後重跑即可。

attempt to write a readonly database

症狀　用 sudo 跑過某個 CLI 指令之後，服務就寫不進資料庫了。

原因　以 root 執行時新建出來的檔案屬於 root，而服務是用自己的帳號跑的。 最容易中的是 jtdt reset-password —— 救援做完反而登不進去。

怎麼辦　v1.15.16 起所有 CLI 指令結束時都會把資料目錄的擁有者改回服務帳號。 舊版遇到時手動修正擁有者即可（Linux： sudo chown -R jtdt:jtdt <資料目錄>）。

轉檔回 503，或產出的中文變成方框

症狀　辦公文件相關的工具回「服務暫時無法使用」； 或產出的 PDF 中文是空心方框。

原因　這台機器缺 LibreOffice / OxOffice，或缺中日韓字型。

怎麼辦　錯誤訊息會說要裝什麼。Linux 裝 libreoffice（或 OxOffice）與 fonts-noto-cjk； 管理區的「系統相依」頁會逐項列出缺什麼。

遠端使用者一上傳就「CSRF token 遺失或不正確」

症狀　在伺服器本機怎麼測都正常，只有從別台電腦連進來會失敗； 登入也可能一直被踢回登入頁。

原因　反向代理把 X-Forwarded-Proto 寫死成 https，但站台其實是 http —— 後端因此在 cookie 加上 Secure，而瀏覽器在明文連線下會直接丟掉那個 cookie。 http://localhost 是瀏覽器的安全來源例外，所以本機測不出來。

怎麼辦　讓反向代理照實傳協定（IIS 用 rewriteMap 把 {HTTPS} 翻成 https/http）， 或直接把站台改成 HTTPS。範例見 OPS.md。

還是沒解決？

把下面這些一起附上，會快很多：

回報問題