Windows 部署挑戰與解決方案 - AI NotebookLM Runtime Lab

1 設定檔 macOS 硬編碼路徑衝突

已修復

🔍 問題現象 (Symptom)

啟動環境檢查腳本 environment_check.py 時直接崩潰，拋出 PermissionError [WinError 5] Access is denied: 'C:\Users\force'。

💡 原因分析 (Root Cause)

原始部署包內的 v2/config/config.json 設定檔中，寫入了原作者在 macOS 上的絕對路徑（如 /Users/force/...）。Windows 執行時嘗試在不存在且無權限的 C:\Users\force 目錄下建立資料夾而發生崩潰。

✅ 解決方案 (Solution)

自動跨平台路徑防呆 (v3.01)：在 app_config.py 當中新增了跨平台路徑校正，若是在 Windows 上執行卻讀取到 Unix 格式的絕對路徑，程式會自動忽略並使用本機實體路徑重新生成乾淨的相對路徑設定檔。

2 伺服器重啟時 Port 衝突無法關閉舊行程

已修復

🔍 問題現象 (Symptom)

每次重啟地端伺服器時，啟動器 falo_launcher.py 都會判定 Port 8765 被佔用，進而無法將其關閉，被迫使用備用埠口導致設定混亂。

💡 原因分析 (Root Cause)

啟動器藉由 GET 請求 /api/status 回傳的 JSON 判定是否為本專案行程。但由於該 API 預設需要登入驗證（HTTP 401），未登入時會拋出異常中斷，導致啟動器誤判。

✅ 解決方案 (Solution)

修改 v2/runtime_server.py 中的 do_GET 方法，放行對 /api/status 的免驗證 GET 請求。現在啟動器能正常獲取 PID 並在重啟時自動關閉舊進程。

3 Windows 控制台字型編碼異常導致提問崩潰

已修復

🔍 問題現象 (Symptom)

在 Portal 前端進行 AI 對話提問時，系統彈出紅字錯誤：
UnicodeEncodeError: 'charmap' codec can't encode characters: character maps to <undefined>。

💡 原因分析 (Root Cause)

ask_helper.py 與 gemini_helper.py 輸出結果時使用原生中文字元。但在 Windows 系統中，終端機預設編碼（如 cp950）無法對映中文字元，導致 print 拋出編碼異常而直接崩潰。

✅ 解決方案 (Solution)

1. 在 ask_helper.py 與 gemini_helper.py 開頭強制將 sys.stdout 的輸出流重新配置為 utf-8。
2. 修改 runtime_server.py，在呼叫 subprocess.run 時明確指定 encoding="utf-8" 進行解碼。

4 Gemini 提問遺失 orjson 依賴庫

已修復

🔍 問題現象 (Symptom)

點擊「Gemini Advanced」向 Gemini 提問時，系統提示錯誤 ModuleNotFoundError: No module named 'orjson'。

💡 原因分析 (Root Cause)

gemini_helper.py 調用的 gemini_webapi 模組依賴高效能 JSON 解析庫 orjson，但在原始部署包提供的 requirements.txt 中遺漏了這個套件。

✅ 解決方案 (Solution)

已將 orjson 依賴套件正式加入 v2/requirements.txt。在新環境執行 pip install -r requirements.txt 時會一併自動安裝。

5 CLI 登入程式無聲閃退

已修復

🔍 問題現象 (Symptom)

執行 notebooklm login --fresh 以嘗試重新登入 CLI 時，程式瞬間閃退，且背景沒有任何反應。

💡 原因分析 (Root Cause)

在新的虛擬環境中，尚未下載 Playwright 對應的 Chromium 瀏覽器二進位實體檔。當登入程式調用 Playwright 準備彈出瀏覽器時便會直接拋出異常。

✅ 解決方案 (Solution)

在 Windows 指南中增加手動下載與安裝指令的說明：

.venv\Scripts\playwright install chromium

6 ngrok 穿透 Port 對接錯誤 (ERR_NGROK_8012)

已修復

🔍 問題現象 (Symptom)

外部 GAS 點擊測試時失敗，訪問 ngrok 連結會彈出紅字錯誤 ERR_NGROK_8012。

💡 原因分析 (Root Cause)

本機已經有一個正在連通的 ngrok 隧道進程，但該隧道被配置為將外部流量轉發到本地的 8888 Port，而我們剛剛啟動的地端 Python 伺服器卻是運行在預設的 8765 Port。

✅ 解決方案 (Solution)

在 falo_launcher.py 內新增 get_any_process_on_port 的邏輯，如果發現 8765 埠口被任何不明行程佔用，會自動使用系統 `netstat -aon` 獲取其 PID 並調用 taskkill 將其強制釋放，確保服務埠口完全對齊。

Windows 環境部署挑戰與排除指南

🎯 部署背景與任務目標

🎉 v3.01 版本自動修復公告

⚡ 備份與一鍵啟動說明