Skip to content

除錯指南

標註項目的除錯標誌、日誌選項和故障排除技巧。

Potato 提供了多個命令列標誌和配置選項，幫助除錯和測試標註項目。這些在開發和故障排除過程中非常有用。

伺服器配置

你可以在 YAML 配置檔案中直接配置伺服器設定：

yaml
server:
  port: 8000        # Port to run on (default: 8000)
  host: "0.0.0.0"   # Host to bind to (default: 0.0.0.0)
  debug: false      # Enable Flask debug mode (default: false)

注意： CLI 標誌優先於配置檔案中的值。例如，-p 9000 將覆蓋 server.port: 8000。

除錯標誌

--debug

以除錯模式啟動 Potato，用於在你自己的機器上測試配置。

bash
potato start config.yaml --debug

效果：

  • 啟用詳細日誌
  • 關閉會話空閒超時
  • 對來自本機的請求，無需金鑰即可開啟管理頁面
  • 允許使用 --debug-phase，它會讓每個訪問者都以 debug_user 身份登入

單獨使用 --debug 時登入頁面仍會保留，--debug-phase（見下文）會跳過它。

除錯模式可以在任何地址上啟動，包括預設的 0.0.0.0，所以其他機器也能訪問伺服器，在你自己的機器上則開啟 http://localhost:<port>。有兩樣東西只留給本機。管理頁面和管理 API 只對來自本機的請求免金鑰開放，不對其他機器開放，也不對經過代理的請求開放；在其他情況下，它們照常需要管理員 API 金鑰。Werkzeug 的互動式偵錯程式會在每個錯誤頁面上提供一個 Python 控制台，它只在伺服器繫結到 127.0.0.1 時提供。除錯階段對任何能連線的人都生效，因為使用 --debug-phase 時每個訪問者都會以同一個 debug_user 身份登入，所以不要在陌生人能訪問的伺服器上開啟除錯模式。Potato 2.8.2 到 2.11.0 在預設的 0.0.0.0 地址上拒絕以除錯模式啟動，所以在這些版本上請加上 --host 127.0.0.1。

--debug-log

控制系統不同部分的除錯日誌輸出。

bash
potato start config.yaml --debug --debug-log=all

選項：

值描述
all同時啟用 UI（前端）和伺服器（後端）的日誌
ui僅啟用前端 JavaScript 控制台日誌
server僅啟用後端 Python 日誌
none停用所有除錯日誌

示例：

bash
# Debug frontend issues (JavaScript errors, UI state)
potato start config.yaml --debug --debug-log=ui
 
# Debug backend issues (API calls, data processing)
potato start config.yaml --debug --debug-log=server
 
# Full debugging (both frontend and backend)
potato start config.yaml --debug --debug-log=all
 
# Quiet mode - minimal output
potato start config.yaml --debug --debug-log=none

--debug-phase

跳過早期階段，直接進入特定階段或頁面。這對於測試標註工作流的特定部分非常有用。

bash
potato start config.yaml --debug --debug-phase=annotation

要求： 必須同時設定 --debug 標誌。

有效階段名稱：

  • login - 登入頁面
  • consent - 知情同意表單
  • prestudy - 研究前調查
  • instructions - 說明頁面
  • training - 培訓階段
  • annotation - 主要標註階段
  • poststudy - 研究後調查
  • done - 完成頁面

示例：

bash
# Jump directly to annotation (most common use case)
potato start config.yaml --debug --debug-phase=annotation
 
# Test post-study survey
potato start config.yaml --debug --debug-phase=poststudy
 
# Test a specific named page
potato start config.yaml --debug --debug-phase=my_custom_survey

工作原理：

  • 讓每個訪問者都以一個名為 debug_user 的共享使用者身份登入
  • 跳過指定階段之前的所有階段
  • 使用者狀態設定為已完成所有先前階段

組合除錯標誌

可以組合標誌用於不同的除錯場景：

bash
# Quick annotation testing with minimal noise
potato start config.yaml --debug --debug-phase=annotation --debug-log=none
 
# Full debugging of annotation phase
potato start config.yaml --debug --debug-phase=annotation --debug-log=all
 
# Debug only backend while testing post-study
potato start config.yaml --debug --debug-phase=poststudy --debug-log=server

其他有用標誌

--verbose / -v

啟用詳細輸出用於常規操作日誌。

bash
potato start config.yaml -v

--veryVerbose

啟用非常詳細的輸出，包含詳細的內部狀態資訊。

bash
potato start config.yaml --veryVerbose

--port / -p

在指定埠執行（在執行多個實例時很有用）。

bash
potato start config.yaml -p 8080

瀏覽器開發者工具

除了命令列標誌，還可以使用瀏覽器開發者工具進行除錯：

  1. 控制台：檢視 JavaScript 日誌和錯誤（F12 或 Cmd+Option+I）
  2. 網路：監控前後端之間的 API 呼叫
  3. 元素：檢查 DOM 和 CSS 樣式
  4. 應用程式：檢查會話儲存和 cookie

重新啟用控制台日誌

如果通過 --debug-log=server 或 --debug-log=none 停用了 UI 日誌，可以在瀏覽器控制台中重新啟用：

javascript
enableUIDebug();

常見除錯場景

測試新的標註模式

bash
# Skip to annotation with full logging
potato start config.yaml --debug --debug-phase=annotation --debug-log=all

除錯 API 問題

bash
# Server-only logging to focus on backend
potato start config.yaml --debug --debug-log=server

然後使用瀏覽器網路標籤頁檢查請求/響應資料。

測試使用者流程

bash
# Start from the beginning with UI logging
potato start config.yaml --debug --debug-log=ui

效能測試

bash
# Minimal logging overhead
potato start config.yaml --debug --debug-phase=annotation --debug-log=none

故障排除

"debug-phase requires --debug flag"

--debug-phase 選項僅在同時指定 --debug 時有效：

bash
# Wrong
potato start config.yaml --debug-phase=annotation
 
# Correct
potato start config.yaml --debug --debug-phase=annotation

階段未找到

如果指定的階段在配置中不存在，請檢查：

  • 階段名稱拼寫正確
  • 階段已在 YAML 配置中定義
  • 對於自定義頁面，使用配置中的確切頁面名稱

延伸閱讀

有關實現細節，請參閱原始碼文件。