Debian 上 Python 远程调试实操指南
一 常用方案与适用场景
- IDE 远程解释器 + 调试器：使用 VS Code Remote-SSH 或 PyCharm 专业版 On SSH，在远端 Debian 上运行代码，本地断点、变量、栈帧可视化，适合日常开发与持续调试。
- 远程 stdin/stdout 调试：在远端插入 pdb / ipdb 断点，通过 SSH 端口转发把本地终端接入调试会话，轻量、无需额外服务。
- 远程网络调试器：使用 remote-pdb / pyrpdb 在远端监听端口，本地 telnet/nc 连接进入调试，适合无图形环境或容器场景。
二 方案一 VS Code Remote-SSH 调试
- 前置准备
- 远端 Debian 安装 Python3、pip 与 openssh-server，并确保 SSH 可达（建议配置免密登录）。
- 本地安装 VS Code 及扩展：Remote - SSH、Python。
- 连接与解释器
- VS Code 打开命令面板（F1）→ Remote-SSH: Connect to Host → 添加远端 user@host，首次连接会自动在远端部署 vscode-server。
- 打开项目后，按 Ctrl+Shift+P → Python: Select Interpreter → Enter interpreter path，选择远端解释器（如 /usr/bin/python3）。
- 配置调试
- 创建或打开 .vscode/launch.json，使用 Python Debugger 配置，示例：
- 方式 A（推荐，直接附加到远端已运行进程）：
- 类型：python
- 请求：attach
- 连接方式：SSH
- 主机/端口：填写远端 host/22
- 路径映射：localRoot ↔ remoteRoot
- 可选：设置 “justMyCode”: false 以进入第三方库源码
- 方式 B（运行并调试当前文件）：
- 类型：python
- 请求：launch
- 程序：${file}
- 控制台：integratedTerminal
- 环境变量：按需设置（如 PYTHONPATH）
- 运行与排错
- 先在远端运行程序（或按 F5 启动），命中断点后可在 VARIABLES/WATCH/STACK 面板查看与单步。
- 若端口或路径映射异常，检查 Remote-SSH 输出面板与 launch.json 的 pathMappings。
三 方案二 PyCharm 专业版远程解释器调试
- 新建远端解释器
- File → Settings → Project → Python Interpreter → Add → On SSH，填写远端 IP/端口/用户名，选择远端 Python 路径（如 /usr/bin/python3）。
- 部署与路径映射
- Tools → Deployment → Configuration 新增 SFTP，配置远端 Root path 与本地/远端路径映射；需要时开启自动上传或手动上传。
- 运行与调试
- 新建运行配置，解释器选择刚创建的 SSH Interpreter，保存后直接 Debug；可在断点处查看变量、栈与线程。
- 适用于 Debian 设备（如 RK3566/RK3588） 等嵌入式板卡的远程开发与 UI 程序调试。
四 方案三 远程 stdin/stdout 调试 pdb ipdb
- 在远端代码中插入断点
- 使用内置调试器：
- import pdb; pdb.set_trace()
- 使用增强调试器：
- 安装：pip install ipdb
- 断点：import ipdb; ipdb.set_trace()
- 建立 SSH 本地端口转发并连接
- 转发本地端口到远端调试端口（默认 22 转发到远端 pdb 会话的 stdio 不适用，需改用远程网络调试器或运行于前台终端）：
- 示例：ssh -L 4444:localhost:4444 user@remote
- 适用场景与提示
- 适合快速定位问题，无需改动复杂部署；注意生产环境慎用 set_trace，避免阻塞服务。
- 若需图形界面与更丰富交互，优先选择 IDE 远程调试。
五 方案四 远程网络调试器 remote-pdb pyrpdb
- 安装与断点
- 安装：pip install remote-pdb（或 pyrpdb）
- 在代码中插入：
- from remote_pdb import RemotePdb
- RemotePdb(‘0.0.0.0’, 4444).set_trace()
- 防火墙与转发
- 开放远端端口（示例）：sudo iptables -A INPUT -p tcp --dport 4444 -j ACCEPT
- 本地连接：
- telnet remote_ip 4444
- 或使用 nc remote_ip 4444
- 调试命令
- 常用：n（下一行）、s（进入函数）、c（继续）、l（列出代码）、p var（打印变量）、q（退出）
- 适用场景
- 容器或无图形环境、需要多人或跨机接入同一调试会话时更灵活。