安裝與升級疑難排解

升級停在 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， 不碰使用者資料）：

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

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

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

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

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

另一種　從 v1.15.11 ~ v1.16.10 更新時，最後印 Health check failed，Service state 是 RUNNING / active，Windows 還會說找不到日誌。

原因　那幾版的健康檢查本身有錯（少了一行 import）， 不管服務好壞都判成失敗；Windows 與 macOS 也去錯的地方找日誌。

怎麼辦　用瀏覽器打得開就代表更新成功，不需要處理。 v1.16.11 已修，但更新到 v1.16.11 的那一次仍會看到這段訊息 （跑檢查的是更新前那一版的程式），下一次起就正常。 日誌實際的位置：Windows 在 C:\ProgramData\jt-doc-tools\Logs\ （jtdt-svc.err.log 與 jtdt-svc.out.log）、 macOS 在 ~/Library/Logs/（jt-doc-tools.err 與 jt-doc-tools.log）、Linux 用 journalctl -u jt-doc-tools。

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。

「連不上 JTLW」或「連 JTLW 逾時」

症狀　語音服務設定頁按「測試連線」失敗；辨識模式的下拉顯示 「讀不到清單：連不上 JTLW」；或送出錄音時失敗。

原因　送件位址填錯（主機、埠、http / https）、防火牆擋住、 對方的服務沒起來 —— 也可能是憑證驗證失敗：對方用自簽憑證時，連線在 TLS 那一步就被拒， 畫面上一樣只寫「連不上」。

怎麼辦　送件位址照對方給的整串貼（例：https://主機:8790/api/v1）。 在本系統那台機器上試 curl https://主機:8790/api/v1/health： 連不到就是網路或位址的問題；加上 -k 才連得到就是憑證的問題 —— 把對方的憑證（PEM）貼進「對方的憑證」欄位，跟對方公布的 SHA-256 指紋核對過再存。 不要用關閉驗證來繞過：每次送件都會把金鑰交出去，關掉驗證之後任何人都能冒充對方。

「JTLW 不接受這把金鑰（401）」或「沒有這個動作的權限（403）」

症狀　「測試連線」或送件時出現其中一句。

原因　這兩個是不同的狀況。401：金鑰打錯、被對方撤銷，或貼成了整條標頭。 403：金鑰是對的，但這把金鑰沒有這個動作的權限 —— 照「打錯 / 撤銷」去查會查不出問題。 只測對方的健康檢查是看不出來的（那一支不驗金鑰），所以「測試連線」會另外用金鑰問一次。

怎麼辦　401：「API 金鑰」只貼金鑰本身（對方給的那一串； Authorization: Bearer 這條標頭由本系統自己組，貼了前綴也會自動去掉）， 確認無誤就請對方確認這把金鑰是否仍然有效。 403：請對方的管理員幫這把金鑰加上權限 —— 缺哪一個權限，本系統的服務記錄裡有寫 （jtdt logs）。

「對方不接受我們這台的位址 —— 請管理員把『錄音檔對外位址』給對方加進允許清單」

症狀　送出錄音後失敗，訊息結尾附著一個主機名稱。

原因　語音服務只從允許清單上的位址拉錄音檔，而本系統的「錄音檔對外位址」不在清單上。

怎麼辦　把訊息結尾的那個主機名稱交給語音服務的管理員加進允許清單。 換過「錄音檔對外位址」也要請對方一起加 —— 同一套服務可能有內網直連與反向代理兩種到達方式， 填哪一個，對方看到的就是哪一個。

「對方連不到我們的錄音檔位址」或「網址已經過期」

症狀　送出錄音後失敗，訊息是「對方連不到我們的錄音檔位址」、 「對方來拉錄音檔時網址已經過期」，或「對方來拉錄音檔時被我們擋掉了（401 / 403）」。

原因　錄音檔不是本系統推過去的，是對方回頭來拉：本系統交給對方一個短效的簽章網址 （/api/speech/audio/…?exp=…&sig=…，免登入、到期自動失效）。 「錄音檔對外位址」填成只有瀏覽器那台才連得到的名稱（例如 localhost）、 中間的防火牆或反向代理擋住、或反向代理前面加了登入驗證，對方都拉不到。

怎麼辦　「錄音檔對外位址」要填從語音服務那台連得到的位址（設定頁不會從瀏覽器的網址推算， 那樣推錯的話會「有些人可以、有些人不行」）。反向代理前面有 SSO / Kerberos 之類的登入驗證時， /api/speech/audio/ 這一段要放行 —— 它本身已經用簽章把關。 「網址已經過期」不是排隊造成的：對方收到送件就會立刻拉檔，之後排多久都不會再拉這個網址 —— 所以多半是送出之前重試或等了太久，重新送一次即可。

一直停在「排隊中（前面還有 N 件）」，或「等了 N 分鐘，對方還沒有回報結果 —— 已經請對方取消」

症狀　轉逐字稿送出後一直顯示排隊中；或輪到之後處理很久，最後失敗並顯示上面那句話。 也可能直接看到「對方的佇列滿了，請稍後再送一次」。

原因　語音服務的 GPU 一次只處理一件、其餘排隊，前面的件數包含別人的作業。 排隊時畫面會寫出前面還有幾件，這段時間不算進等待上限；輪到之後，辨識與校正的進度會往前。 本系統只在輪到之後計時（15 分鐘與錄音長度的一半兩者取大），超過就請對方取消這一件； 排隊本身最長等 4 小時。

怎麼辦　排隊中就等它輪到；很長的錄音避開別人正在送長會議的時段。 輪到之後逾時、或排隊超過 4 小時，請語音服務那側確認 GPU 伺服器的狀態。

「JTLW 回報成功，但一段逐字稿都沒有」

症狀　轉逐字稿失敗，訊息是這一句；錄音裡明明有人講話。

原因　語音服務在把辨識結果傳回來的途中重啟過（更新或當機），傳到一半的結果被當成完整的， 最常見的是一段都沒有。本系統拿到 0 段一律判失敗，不會當成功交出一份空的逐字稿。

怎麼辦　重新送一次通常就好。一直發生的話，請語音服務那側確認伺服器是否在更新或重啟。

錄音最後很長一段沒有字　錄音最後超過一分鐘沒有任何文字時，結果頁會寫出空白有多長。 語音服務 2026-09-23 起已修掉「只傳回前面一段」的問題，所以這個提示多半代表錄音忘了停、或結尾是掌聲音樂； 如果那段時間確實有人在講話，請重新送一次。

「語音服務不接受這個語言設定」

症狀　選了某個語言，一送出就失敗。

原因　語音服務只收目前辨識模式支援的語言。v1.16.8 以前頁面把「中文」送成 zh， 對方要的是 zh-Hant，所以選中文的每一件都會被退回（v1.16.9 修正）； 之後仍然出現的話，多半是管理員選的辨識模式不支援這個語言（例如台語那一組只收台語與中文）。

怎麼辦　改選「自動判斷」再送一次。一直發生的話，請管理員到「語音服務（JTLW）」看目前的辨識模式支援哪些語言 （選好辨識模式後，下方會列出）。

中文會議卻整場辨識成英文（或反過來）

症狀　逐字稿大部分是錯字，或整場變成另一種語言；語言選的是「自動判斷」。

原因　「自動判斷」只看錄音開頭約 30 秒的講話來決定整場用哪一種語言。開頭若有人先講另一種語言 （例如先用英文開場，20 秒就夠），整場都會用錯的語言辨識 —— 語音服務實測：中文為主但開頭是英文的會議， 中文句的錯誤率從 15% 變成 88%。開頭的靜音、雜音不影響，不需要剪掉。

怎麼辦　在「語言」選整場使用的語言，再送一次。中英句子交錯的會議請選佔多數的語言： 另一種語言的整句大多無法正確辨識（中文句子裡夾英文術語沒有問題）。

「會議錄音轉逐字稿」是反灰的，或顯示「還沒設定語音服務（JTLW）」

症狀　側欄與首頁的那支工具點不下去；打開工具頁只看到一句設定提示。

原因　這支工具依賴外部的語音服務，管理區沒有啟用、或送件位址與金鑰沒填完整時一律反灰 —— 刻意的，免得出現一個看起來正常、按下去才失敗的上傳區。

怎麼辦　到管理區「語音服務（JTLW）」勾選啟用，填好送件位址、API 金鑰與錄音檔對外位址， 按「測試連線」確認之後儲存。其他 49 支工具不受影響。

還是沒解決？

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

• 作業系統與版本、jtdt status 的輸出
• jtdt logs 的最後 20 行
• 失敗指令的完整輸出（不要只貼最後一行 —— 真正的原因常在上面幾行）

回報問題