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 配置中定义
  • 对于自定义页面，使用配置中的确切页面名称

延伸阅读

有关实现细节，请参阅源代码文档。