kozea/wdb

wdb - Web调试器

镜像概述

wdb是基于客户端-服务器架构的全功能Python Web调试器。服务器端通过Tornado框架管理调试实例与浏览器WebSocket连接，客户端支持断点设置、单步调试、代码执行、代码编辑（基于CodeMirror）等功能。兼容Python 2（2.6、2.7）、Python 3（3.2-3.5）及PyPy，支持多线程/多进程场景，可跨机器远程调试，甚至通过gdb注入代码暂停运行中的Python进程。

核心功能

• 多环境兼容：支持Python 2/3、PyPy及多线程/多进程调试。
• 远程调试：跨机器调试（如A机器运行程序、B机器调试、C机器部署服务器）。
• 浏览器操作：断点管理、单步调试（步入/步过/步出）、实时代码执行、变量查看与编辑。
• Web框架集成：支持Flask、Django、Tornado、CherryPy等框架的中间件集成。
• 代码注入：通过gdb/ptrace注入代码，暂停运行中的Python进程。
• 代码补全：基于Jedi实现动态代码补全。

使用场景

1. 本地脚本调试：插入wdb.set_trace()快速断点调试Python脚本。
2. Web应用调试：集成到Web框架，捕获请求异常并调试。
3. 远程调试：跨机器调试分布式应用或容器内程序。
4. Docker环境调试：通过Docker Compose部署wdb服务器与应用容器，调试容器内代码。

配置说明

安装

全局安装服务器：

bash
pip install wdb.server

虚拟环境安装：

bash
pip install wdb

启动服务器

直接启动：

bash
wdb.server.py &

systemd socket激活：

bash
cd /etc/systemd/system
curl -O https://raw.githubusercontent.com/Kozea/wdb/master/server/wdb.server.service
curl -O https://raw.githubusercontent.com/Kozea/wdb/master/server/wdb.server.socket
systemctl enable wdb.server.socket
systemctl start wdb.server.socket

基础使用

调试脚本：

bash
python -m wdb your_file.py

设置断点：

python
import wdb
wdb.set_trace()

捕获异常：

python
from wdb import trace
with trace():
    your_code()

Web框架集成

Flask

python
from flask import Flask
from wdb.ext import WdbMiddleware
app = Flask(__name__)
app.debug = True
app.wsgi_app = WdbMiddleware(app.wsgi_app)
app.run(use_debugger=False)

Django

修改wsgi.py：

python
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()
from wdb.ext import WdbMiddleware
application = WdbMiddleware(application)

修改settings.py：

python
DEBUG = True
DEBUG_PROPAGATE_EXCEPTIONS = True

Docker配置

Docker Compose示例：

yaml
db:
  image: postgres
web:
  build: .
  command: python manage.py runserver 0.0.0.0:8000
  volumes:
    - .:/code
  ports:
    - "8000:8000"
  links:
    - db
    - wdb
  environment:
    WDB_SOCKET_SERVER: wdb
    WDB_NO_BROWSER_AUTO_OPEN: True
wdb:
  image: kozea/wdb
  ports:
    - "1984:1984"

访问http://<Docker主机IP>:1984查看调试会话。

远程调试

指定服务器地址：

bash
WDB_NO_BROWSER_AUTO_OPEN=True WDB_SOCKET_SERVER=server_ip WDB_SOCKET_PORT=19840 python -m wdb your_file.py

在浏览器访问服务器地址的调试会话（如http://server_ip/debug/session/[uuid]）。

浏览器内命令

常用命令：

• .s/Ctrl+↓/F11：步入
• .n/Ctrl+→/F10：步过
• .r/Ctrl+↑/F9：步出
• .c/Ctrl+←/F8：继续
• .b：设置断点（语法：[文件][:行号][#函数][,条件]）
• .h：查看帮助

许可证

本镜像基于GPLv3许可证开源。