在 Ubuntu 上配置 Python 远程调试

当你的代码跑在远程服务器上，本地却想逐行“透视”它的执行过程时，远程调试就成了刚需。别担心，这事儿没想象中那么复杂。下面咱们就来聊聊几种主流方案，帮你打通本地与远程的调试通道。

方案一：VS Code + Remote-SSH + debugpy（推荐组合）

这套组合堪称当前最流畅的远程调试体验之一，核心思路是利用 VS Code 强大的远程开发能力。

• 本地安装 VS Code 扩展：首先，确保你的 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：附加到已在运行的进程（推荐）
    1. 在远程的 Python 代码中（通常是入口文件或你需要打断点的模块顶部）插入以下代码：

       import debugpy
       debugpy.listen((“0.0.0.0”, 5678)) # 监听所有网络接口，端口号可自定义
       print(“Waiting for debugger attach…”)
       debugpy.wait_for_client() # 程序将在此阻塞，直到调试器连接

    2. 在本地 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”: “.” }]
           }]
       }

    3. 操作顺序：先在远程终端运行你的 Python 脚本，看到 “Waiting for debugger attach…” 提示后，再在 VS Code 中启动名为 “Python: Remote Attach” 的调试配置。
  • 方式 B：由 VS Code 直接启动并调试
    1. 在远程安装好 debugpy 后，在 VS Code 的 Python 解释器选择器中，切换到远程的 Python 环境。
    2. 在 launch.json 中，使用 “request”: “launch” 的配置，指定程序入口文件和参数，必要时可以设置 “console”: “integratedTerminal”。
• 网络与权限
  • 如果 VS Code 和 Ubuntu 服务器不在同一台机器上，需要确保远程监听的端口（例如 5678）能够被本地访问到。对于云服务器，记得在安全组规则中放行该端口；内网环境则可以直接连接。
  • 在生产或多人协作环境下，强烈建议配置 SSH 密钥登录，避免反复输入密码，既安全又便捷。
• 说明
  • 网上一些旧教程使用的 ptvsd，其配置思路和 debugpy 基本一致。但对于新项目，优先推荐使用 debugpy，它能获得更好的支持和性能。

方案二：Docker 容器中的远程调试

如果你的应用运行在 Docker 容器内，调试同样可以安排。思路是将容器视为一个微型远程主机。

• 启动容器并映射端口与目录：运行容器时，需要映射 SSH 端口（例如 22）和你的代码目录。

  docker run --gpus all -it --name tf2 -p 1234:22 -v /home/you/project:/home/project tensorflow/tensorflow:latest-gpu /bin/bash

• 容器内配置 SSH 服务：进入容器后，需要安装并启动 SSH 服务。
  • 更新包列表并安装：apt-get update && apt-get install -y openssh-server
  • 编辑 SSH 配置以允许 root 登录：vim /etc/ssh/sshd_config，设置 PermitRootLogin yes。
  • 启动服务：service ssh start
  • 为 root 用户设置一个密码：passwd
• VS Code 配置
  • 在 VS Code 的 SSH 配置文件中添加容器主机信息（示例）：

    Host tf2
        HostName <服务器IP>
        Port 1234
        User root

  • 使用 Remote-SSH 连接这个名为 “tf2” 的主机，之后的选择远程解释器、创建调试会话等步骤，就完全和方案一一样了。只需确保端口映射和代码路径映射正确无误。

方案三：终端远程调试工具备选

对于没有图形界面的纯终端环境，或者需要快速排查的生产服务器，这些基于命令行的调试工具非常实用。

• 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)
    • 使用 netcat 连接：nc <远程IP> 4444
• 适用场景：这类工具特别适合在无图形界面的服务器上进行快速问题定位。当然，使用前务必记得在防火墙或安全组中开放对应的调试端口，并做好访问控制。

常见问题与排错要点

调试之路难免遇到小坎坷，以下几个关键点帮你快速排雷：

• 端口连通性
  • 云服务器用户，请首先检查安全组规则是否放行了调试端口。一个简单的测试命令是：nc -vz <端口>。
• 路径映射
  • 在 VS Code 的 launch.json 中，pathMappings 配置至关重要。它建立了本地工作区与远程项目根目录的对应关系，如果配错，断点将无法命中。
• 解释器选择
  • 使用 Remote-SSH 连接后，务必在 VS Code 的 Python 扩展中选择远程的 Python 解释器，否则依赖解析和调试环境会发生错位。
• 旧版依赖
  • 如果项目仍在使用 ptvsd，建议逐步迁移到 debugpy。两者的附加（Attach）配置思路是相通的，迁移成本不高。
• REPL 与交互
  • 通过 debugpy 附加调试时，本地的调试控制台并不会直接变成远程的 REPL。如果需要交互式命令行，可以打开 VS Code 的 Remote-SSH 集成终端，或者连接远程的 Jupyter 服务器来执行交互式代码。