在 Ubuntu 上配置 Python 远程调试
方案一 VS Code + Remote-SSH + debugpy 推荐
- 本地安装 VS Code 扩展：安装并启用 Remote - SSH 与 Python 扩展。
- 建立 SSH 连接：在 VS Code 左下角选择 Remote Explorer → SSH Targets: Add New SSH Host，填写 user@remote_host，保存到 ~/.ssh/config；随后连接远程 Ubuntu。
- 远程环境准备：在远程主机安装调试器
- Ubuntu 20.04+ 建议：pip install -U debugpy
- 旧项目兼容：pip install ptvsd（旧版 VS Code 远程调试常用）
- 配置调试启动
- 方式 A 附加到已在运行的进程（推荐）
- 在远程代码中加入（放在入口或需要断点的模块顶部）：
import debugpy
debugpy.listen((“0.0.0.0”, 5678)) # 监听所有地址，端口自定义
print(“Waiting for debugger attach…”)
debugpy.wait_for_client() # 阻塞至调试器连接
- VS Code 创建 .vscode/launch.json：
{
“version”: “0.2.0”,
“configurations”: [
{
“name”: “Python: Remote Attach”,
“type”: “python”,
“request”: “attach”,
“connect”: { “host”: “localhost”, “port”: 5678 },
“pathMappings”: [
{ “localRoot”: “${workspaceFolder}”, “remoteRoot”: “.” }
]
}
]
}
- 先在远程运行脚本，再在 VS Code 启动 “Python: Remote Attach”。
- 方式 B 由 VS Code 直接启动并调试
- 远程安装 debugpy 后，VS Code 选择解释器为远程 Python。
- launch.json 使用 “request”: “launch”，指定程序入口与参数，必要时设置 “console”: “integratedTerminal”。
- 网络与权限
- 若 VS Code 与 Ubuntu 跨机，需将远程端口（如 5678）打通到本地（云服务器请在安全组放行；内网可直接连）。
- 生产或多人环境建议用 SSH 密钥登录，避免频繁输入密码。
- 说明
- 旧教程使用 ptvsd 的配置与思路与 debugpy 基本一致，但新项目优先使用 debugpy。
方案二 Docker 中的远程调试
- 启动容器并映射 SSH 与代码目录（示例）：
- docker run --gpus all -it --name tf2 -p 1234:22
-v /home/you/project:/home/project
tensorflow/tensorflow:latest-gpu /bin/bash
- 容器内安装 SSH 服务并允许 root 登录：
- apt-get update && apt-get install -y openssh-server
- 编辑 /etc/ssh/sshd_config：设置 PermitRootLogin yes
- service ssh start
- 设置 root 密码：passwd
- VS Code 配置
- Remote-SSH 配置 Host（示例）：
Host tf2
HostName <服务器IP>
Port 1234
User root
- 连接后选择远程解释器，按方案一创建并启动调试会话（端口映射与路径映射保持一致）。
方案三 终端远程调试工具备选
- pudb（全屏终端可视化调试，支持远程）
- 安装：pip install pudb
- 远程调试：
- 代码内断点：from pudb.remote import set_trace; set_trace(host=“0.0.0.0”, port=5555)
- 另开终端连接：telnet <远程IP> 5555
- rpdb（基于 socket 的远程 pdb）
- 安装：pip install rpdb
- 代码内断点：import rpdb; rpdb.set_trace(addr=“0.0.0.0”, port=4444)
- 连接：nc <远程IP> 4444
- 适用场景：无图形界面、服务器上快速排查；注意开放对应端口与访问控制。
常见问题与排错要点
- 端口连通性
- 云服务器需放行安全组/防火墙；本机与服务器间可用：nc -vz <端口> 测试连通。
- 路径映射
- VS Code 的 pathMappings 必须正确，否则断点无法命中（本地工作区 ↔ 远程项目根目录）。
- 解释器选择
- 使用 Remote-SSH 时，务必在扩展中选择 远程 Python 解释器，否则依赖解析与调试会错位。
- 旧版依赖
- 若项目仍引用 ptvsd，建议迁移到 debugpy；两者在 VS Code 中的附加配置思路一致。
- REPL 与交互
- 通过 debugpy 附加时，本地终端不会成为远程 REPL；需要交互式命令行时，使用 VS Code 的 Remote-SSH 集成终端，或连接 远程 Jupyter 服务器进行交互式执行。