Python pdb 与 debugpy：从异常现场到安全远程调试

一个 Python 任务偶尔在数据转换后抛出 KeyError。开发者在异常处理里补了日志，下一次失败却只留下已经清洗过的字段；重新运行同一输入又无法复现。把脚本放进 pdb 后，异常发生时可以停在原始栈帧查看局部变量，团队才发现上游数据中混入了大小写不同的键。真正有用的不是“开了调试器”，而是异常尚未被重试、包装或清理时保存了正确帧。

另一个 Web 服务在父进程断点上正常停住，真正出错的 worker 却直接跑完。远程客户端显示断点未验证，服务端仍监听在所有网卡；排查后发现 debugpy 的子进程配置设置得太晚，本地源码根也映射到了错误的容器目录。这个现场同时包含执行模型、路径身份和安全边界，不能靠反复点击 attach 解决。

Python 本地、事后与远程调试链沿 pdb 当前帧与异常帧、debugpy DAP 会话、PID 注入、子进程、路径映射和回环隧道追踪可验证现场。高清原图

先分清 pdb 与 debugpy 的责任

pdb 属于 Python 标准库，直接在终端中操作当前解释器的栈、帧、断点和变量。它适合本地脚本、可控服务副本、异常后的 post-mortem，以及不依赖图形客户端的快速检查。breakpoint() 默认进入 pdb，pdb.set_trace() 在代码中显式停住，python -m pdb script.py 从启动阶段接管脚本，pdb.post_mortem() 则从异常 traceback 进入失败现场。Python pdb 文档是命令和版本行为的基准。

debugpy 是实现 Debug Adapter Protocol 的调试服务。它可以启动脚本或模块、等待 DAP 客户端、主动连接客户端，也可以注入既有 Python 进程。IDE 中的变量窗口、调用栈和断点通过 DAP 与 debugpy 交换状态；因此“TCP 端口能连接”只证明网络可达，不证明源码映射、进程选择和断点已经正确。

两者都能执行代码，不是只读观察器。pdb 中未识别的输入会作为 Python 表达式或语句在当前帧求值，debugpy 客户端也能修改变量、调用表达式和控制进程。调试权限等价于目标进程代码执行权与内存读取权，必须比普通日志查看更严格。

选择方式可以从现场约束出发：本地单进程与异常栈优先 pdb；需要图形客户端、远程主机、复杂线程或子进程时使用 debugpy；进程已经运行且不能重启时才考虑 PID attach；只剩异常日志而没有 traceback、转储或原进程时，调试器无法凭空恢复已经丢失的局部变量。

先确认解释器，再确认 debugpy 包

pdb 随 Python 提供，不需要单独安装。先确认命令指向项目实际解释器，而不是操作系统别名或另一个虚拟环境：

python --version
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pdb --help

项目使用虚拟环境时，先激活环境，或始终用环境中的解释器绝对入口执行 -m。pip 与 python 可能来自不同环境，因此安装 debugpy 应写成：

python -m pip install --upgrade debugpy
python -m pip show debugpy
python -c "import debugpy; print(debugpy.__version__); print(debugpy.__file__)"

debugpy 的 PyPI 页面给出发行版本与 Python 要求，debugpy 仓库提供 CLI 和故障排查入口。个人环境可通过升级命令取得当前兼容版；团队应把验证过的精确版本写入开发依赖或约束文件，并让虚拟环境、容器和 IDE 扩展核对实际加载的 debugpy。IDE 可能携带自己的版本，不能因为项目环境安装成功就假定两者相同。

版本链至少记录：

python --version
python -m pip show debugpy
python -c "import sys, debugpy; print(sys.executable); print(debugpy.__version__)"

升级后若 python -m debugpy 报模块不存在，先比较 sys.executable、pip show 的 Location 与当前虚拟环境。使用系统 Python 时遇到 externally managed environment，应创建项目虚拟环境或通过发行版支持的包入口安装，不要用强制覆盖破坏系统包。

debugpy 作为开发依赖卸载时使用 python -m pip uninstall debugpy，随后重新执行 import 检查；虚拟环境是一次性对象时，删除整个环境更能避免残留依赖。pdb 属于标准库，不能也无需单独卸载。仓库中还要删除临时 breakpoint()、debugpy 启动参数和日志目录，避免工具包消失而阻塞点仍留在运行路径。

用 pdb 看当前帧，也看异常帧

在隔离目录创建一个稳定失败的脚本：

def normalize(record):
    user_id = record["user_id"]
    return user_id.strip().lower()

def main():
    payload = {"User_ID": " Demo "}
    print(normalize(payload))

if __name__ == "__main__":
    main()

从启动阶段进入调试器：

python -m pdb app.py

在 (Pdb) 提示符中执行：

break app.py:2
continue
p record
where
up
p payload
continue

断点会在取键前停住，record 应显示只有 User_ID，where 应展示从 main() 到 normalize() 的调用链。继续后程序抛出 KeyError，python -m pdb 会自动进入 post-mortem；此时再次 where、p record，能证明当前检查的是异常 traceback 中保存的帧，而不是重跑后的新状态。

python -m pdb 在 post-mortem 结束或程序正常退出后会重新启动脚本并保留断点。看到入口再次执行不是业务自动恢复。实验结束用 quit 真正退出，再确认没有 Python 子进程残留。

代码内也可以只在捕获异常后进入现场：

import pdb

try:
    main()
except Exception:
    pdb.post_mortem()
    raise

这种写法只适合本地或一次性诊断分支。共享服务若进入交互提示符而没有终端，会挂住 worker；提交前应删除或用默认关闭、显式授权的诊断开关保护。不要把真实请求体打印到工单来替代调试，变量查看同样要遵守数据分级。

breakpoint() 可由 PYTHONBREAKPOINT 控制。默认值调用 pdb.set_trace()，设为 0 会禁用断点，也可以改成其他可导入的调试入口；环境中断点“完全没反应”时，应检查该变量和 sys.breakpointhook。团队测试脚本可以临时设置 PYTHONBREAKPOINT=0 防止误停，但普通启动环境不应悄悄覆盖它后让开发者误判代码未执行。

pdb -p 有明确的 Python 版本边界

Python 3.14 才新增 python -m pdb -p <pid>。在更早的解释器中照抄这条命令不会得到等价 attach，应先执行 python --version，再从对应版本的pdb 文档确认能力。

python -m pdb -p <pid>

attach 需要平台允许调试该进程。目标若阻塞在系统调用或 I/O 中，调试会等到下一条 Python 字节码执行，或在目标收到信号后才生效；“命令暂时没有提示符”不一定是网络问题。先确认 PID、用户、启动时间和解释器路径，再判断目标是否仍在 Python 执行阶段。

进入后先用 where、up、down 和只读表达式观察，不急于赋值。Python 3.13 起，pdb 在活动作用域中的名称赋值会立即影响运行代码；Python 3.14 还增加了异步停点和 backend 选择等行为。调试器中的实验性赋值可能修复一次请求，也可能破坏后续状态，所有共享环境操作都应记录动作并在隔离副本验证。

PID attach 不是网络服务，不提供 TLS、用户认证或远程租户隔离。跨主机时仍需先进入目标主机的受控 Shell，再由当地 Python 对 PID 附加；不能把 pdb -p 当作 debugpy 端口的替代写法。

debugpy 的启动、等待与连接方向

最小本地入口让 debugpy 监听回环，并在客户端连接前暂停目标启动：

python -m debugpy \
  --listen 127.0.0.1:5678 \
  --wait-for-client \
  app.py

没有 --wait-for-client 时程序会立即运行，不会自动停在第一行。目标是模块时使用 -m，参数放在模块名后：

python -m debugpy --listen 127.0.0.1:5678 -m your_package.worker --queue demo

--listen 表示目标进程打开服务端口等待客户端；--connect host:port 表示目标主动连接一个正在等待的客户端。网络策略只允许目标出站、无法让工作站进入目标网络时，后者可能更合适，但客户端监听地址、访问控制和审计仍要受控。二者是连接方向，不是安全等级。

为了让 CLI 实验留下可诊断证据，可以先创建专用目录并启用日志：

mkdir -p .debug/debugpy-logs
python -m debugpy \
  --listen 127.0.0.1:5678 \
  --wait-for-client \
  --log-to .debug/debugpy-logs \
  app.py

启动后，目标应保持等待，回环地址出现监听；DAP 客户端连接并设置断点后，断点应变为已验证，继续执行才进入业务代码。日志目录应出现 debugpy*.log，但具体文件名和数量随组件、版本与子进程变化，不能写死。客户端断开、目标结束后，端口应消失。

反向实验去掉 --wait-for-client 再启动短脚本。预期脚本可能在客户端完成连接前就结束，断点不会命中；这证明“监听已创建”与“业务会等待调试”是两件事。恢复等待参数后重新验证，不要靠把脚本改成长睡眠掩盖连接时序。

attach 到既有进程时，权限与副作用一起进入

debugpy 可把调试服务注入现有 Python 进程：

python -m debugpy --listen 127.0.0.1:5678 --pid <pid>

先用平台工具核对 PID、用户、启动时间、命令行和解释器。Linux 的 ptrace_scope、容器 capability 与 PID namespace，macOS 的调试授权，Windows 的完整性级别都可能阻止注入。收到 permission denied 时应申请对目标进程的短时最小权限，或在同安全域的隔离副本复现；全局降低主机安全策略、给普通容器永久增加 SYS_PTRACE 或直接使用特权容器，都会把一次调试扩大成持续攻击面。

注入不是零影响操作。它会向活进程加载代码、建立线程与套接字，并允许客户端暂停线程和执行表达式。长时间持锁、心跳与请求超时可能在断点期间继续累积。共享环境应先摘流或选择隔离副本，设置暂停预算与退出条件，再执行 attach。

正向验收应同时看到四项：注入命令成功，目标回环端口监听，DAP 会话关联到正确 PID，授权断点在该进程中命中。反向验收使用无权限身份附加同一类测试进程，预期被平台拒绝；若越权身份也能成功，先修权限边界，再推广工具。

退出时先让目标继续并断开客户端，但不要假设 DAP disconnect 会卸载已经注入的 debugpy 或关闭监听。对 --pid 注入的长寿命进程，若 5678 仍由目标持有，公开 API 没有一个可以从外部保证安全卸载全部注入组件的通用“detach 后复原”动作；需要彻底移除入口时，应在既定维护窗口重启隔离副本。退出证明要同时检查端口 owner、目标健康状态和日志结尾，不能只看 UI 已关闭。

子进程调试的关键是配置时点

Python Web server、任务队列和 multiprocessing 经常由父进程创建真正执行代码的 child。只在父进程设置断点，可能观察到启动器而错过 worker。debugpy 支持子进程调试，但策略必须在子进程创建前生效。

用下面的程序验证父子边界：

import multiprocessing as mp
import os
import time

def child(value):
    result = value * 2
    print("child", os.getpid(), result, flush=True)

if __name__ == "__main__":
    print("parent", os.getpid(), flush=True)
    process = mp.Process(target=child, args=(21,))
    process.start()
    process.join()
    time.sleep(30)

通过 launch 启动时，DAP 客户端可在配置中决定 subProcess；完整 IDE 配置应由团队编辑器模板维护。对于已经 attach 的服务端，若要关闭自动子进程注入，必须在客户端连接前传入：

python -m debugpy \
  --listen 127.0.0.1:5678 \
  --configure-subProcess False \
  --pid <parent-pid>

代码嵌入模式也要在 listen() 或客户端连接前调用 debugpy.configure(subProcess=False)。客户端连上后再改，可能已经错过早期 child 的注入时机。

正向实验启用子进程调试，在 child() 内设置断点；客户端应出现与 child PID 对应的会话。断点停在赋值完成后才能同时读到 value == 21 和 result == 42；若停在 result = value * 2 这一行执行前，result 尚未绑定，不能把 NameError 误判为子进程调试失败。反向实验在连接前设置 --configure-subProcess False，父进程仍可调试，但 child 不应建立调试会话，也不应产生该 child 的 debugpy adapter 日志。普通业务输出中的 child PID 仍会出现，它不能作为“已注入”证据。若两个实验结果相同，检查进程是 fork、spawn 还是外部 exec，核对配置是否在首个客户端连接之前生效，并为每个 PID 分开读日志。

启用自动子进程调试会增加连接、日志和暂停面。高并发 worker 池可能一次创建大量会话，影响启动和客户端可用性。项目模板应默认覆盖最小进程集合，并提供明确开关；排查结束恢复默认策略，删除每个子进程产生的 debugpy 日志。

路径映射错了，断点会成为空心证据

远程主机或容器中的源码路径与工作站通常不同。DAP 客户端用 pathMappings 把 localRoot 映射到目标的 remoteRoot；映射方向、路径大小写、符号链接或容器挂载点错误时，典型现象是断点空心或未验证，客户端停在不存在的远端路径，日志出现路径翻译失败。

最低限度的诊断信息是：本地源码根、远端源码根、两端提交、目标解释器实际导入文件。目标侧可以执行：

python -c "import your_package; print(your_package.__file__)"

客户端侧核对同一模块来自当前工作区，并比较提交。localRoot 必须指向工作站源码，remoteRoot 必须指向目标进程看到的源码；pathMappings 是 DAP 客户端配置，不是 debugpy --listen 的 CLI 参数。VS Code Python 调试文档提供了远程 attach 与映射示例，完整 launch.json 应留在编辑器家族和团队模板中维护。

例如工作站打开 ${workspaceFolder}，容器把同一提交挂载到 /workspace/app，attach 配置中的关键部分应是：

{
  "request": "attach",
  "connect": {
    "host": "127.0.0.1",
    "port": 5678
  },
  "pathMappings": [
    {
      "localRoot": "${workspaceFolder}",
      "remoteRoot": "/workspace/app"
    }
  ]
}

remoteRoot 取自目标解释器实际导入路径，不取 Dockerfile 的 WORKDIR 猜测值，也不取宿主机 bind mount 的源路径。镜像中若安装的是 wheel，module.__file__ 可能落在 site-packages；此时映射工作区源码并不能证明两者内容相同，应先比对 wheel 版本、制品摘要或源码提交，再决定是调试已安装副本还是改用同身份的可编辑构建。

正向实验把本地根映射到目标实际工作目录，在 child() 设置断点；验收证据是断点变为已验证，并停在与目标同一提交的函数。反例把 remoteRoot 临时改成不存在的目录，保留未验证断点和 debugpy 日志中的路径证据；随后恢复正确映射并重新命中。不要通过在远端复制另一份源码“修复”断点，那会让显示内容与进程实际导入文件继续分叉。

若路径正确但断点仍不命中，检查模块是否已在 attach 前执行完、是否由另一 worker 导入、是否加载了打包后的副本、代码是否被生成或覆盖。先用 module.__file__ 和 PID 证明执行对象，再调整断点；反复改行号只会掩盖身份问题。

容器场景还要把“能连端口”和“能附加进程”拆开验证。由 debugpy 启动目标时，优先让容器内服务监听 127.0.0.1:5678，再使用能够进入该网络命名空间并访问其回环地址的受控 exec、平台端口转发或 SSH 隧道；普通宿主端口发布通常转发到容器接口，未必能抵达只监听容器回环的进程，不能把发布规则存在当成链路成立。不要为了省一步把 5678 直接暴露到宿主所有接口。使用 --pid 注入时，调试进程还必须看见目标 PID，并拥有平台允许的跟踪权限；端口转发成功却报 No such process，优先检查 PID namespace，报 permission denied 则检查目标用户与 ptrace/capability，不能把两类失败都归因于防火墙。

远程调试端口只绑定回环

debugpy 只给端口时默认绑定 127.0.0.1；显式使用 0.0.0.0 会监听所有接口。官方文档警告，任何能连接 debugpy 端口的人都可能在被调试进程中执行任意代码。因此远程目标应只监听回环：

python -m debugpy \
  --listen 127.0.0.1:5678 \
  --wait-for-client \
  your_app.py

工作站建立 SSH 本地转发：

ssh -N -o ExitOnForwardFailure=yes \
  -L 5678:127.0.0.1:5678 user@debug-host

-N 只建立转发，ExitOnForwardFailure=yes 会让本地端口占用或转发建立失败以非零状态结束；若 SSH 没有保持运行，不能继续把本地 5678 当成本次受控入口。DAP 客户端连接工作站的 127.0.0.1:5678。debugpy 本身不是带 TLS、认证和多租户隔离的远程管理服务；SSH 身份、主机密钥、访问审批和会话审计承担安全边界。需要经过跳板机时，用组织支持的 ProxyJump 或访问代理，仍然不要把调试端口直接暴露到业务网段。

安全反例应在隔离网络验证：目标保持回环监听，在另一台无 SSH 隧道的主机设置目标的管理地址后执行：

TARGET_ADDR="${TARGET_ADDR:?set TARGET_ADDR to the target management address}"
if nc -vz -w 3 "$TARGET_ADDR" 5678; then
  echo "unexpected: debugpy is directly reachable" >&2
  exit 1
else
  echo "expected: direct connection was refused or timed out"
fi

运行前由实验者把 TARGET_ADDR 设置为目标的管理地址。这里外层 Shell 预期返回 0，但只有因为 nc 连接失败才算通过；若 nc 成功，脚本显式返回 1。nc 的超时参数在不同实现中可能不同，执行前先看本机 nc -h；Windows 可用 Test-NetConnection $env:TARGET_ADDR -Port 5678 并要求 TcpTestSucceeded 为 False。随后只有持有 SSH 权限并成功建立隧道的工作站，才应通过本地端口完成 DAP initialize 与 attach。若远端直接可达，检查进程是否误绑 0.0.0.0、容器端口是否发布到宿主、Service 或防火墙是否扩大了范围；修复后重复越权连接，直到直连失败而隧道内 DAP 握手成功。

--wait-for-client 会阻塞业务启动。它只属于人工触发的诊断入口，必须设置时限和回滚，不得长期写进普通服务命令、健康检查或自动扩容模板。会话结束后关闭 SSH 隧道，并检查 ss -ltnp、Get-NetTCPConnection 或平台等价命令，确认工作站转发已消失；目标由 CLI 启动且随诊断任务结束时，目标监听也应消失。若是 --pid 注入的长寿命进程，监听可能继续存在，应按前述退出策略重启隔离副本，不能把客户端断开冒充端口回收。

把项目接入做成默认关闭的诊断能力

本地开发可在依赖组中锁定 debugpy，并提供独立启动脚本；生产依赖若不需要远程调试，就不要为了“以后可能用”默认安装。一个较窄的代码嵌入入口应由显式环境开关触发、只绑定回环，并保持默认不等待客户端：

import os

def enable_debugpy_if_requested() -> None:
    if os.getenv("ENABLE_DEBUGPY") != "1":
        return

    import debugpy

    debugpy.configure(subProcess=False)
    debugpy.listen(("127.0.0.1", 5678))

enable_debugpy_if_requested()

这段代码刻意不调用 wait_for_client()，避免普通启动无限阻塞。若某次诊断必须等待，应由外层启动脚本设置明确超时和失败语义，而不是在应用线程中永久等待。ENABLE_DEBUGPY 只能由受控部署参数打开，不能接受用户请求或未认证管理接口动态设置。

项目脚本应同时记录解释器、debugpy 版本、提交、PID 和脱敏启动模式；禁止输出完整环境变量、命令行 secret 或变量快照。日志写入 .debug/debugpy-logs 这类已忽略目录，容量受限，任务结束即清理。虚拟环境、容器和远端主机使用同一依赖锁，但仍需分别验证平台 attach 权限。

本地 pdb 断点也要有退出门禁。提交前扫描 breakpoint()、pdb.set_trace()、pdb.post_mortem() 和 debugpy.listen()；允许保留的诊断钩子必须默认关闭、有 owner、有测试覆盖，普通请求无法触发。测试与日志规范由各自工具链负责，这里只保证运行时调试入口不会意外进入常规路径。

从失败现象回到进程、源码和协议

pdb 看不到预期变量时，先用 where 确认当前帧，再用 up 或 down 移动。异常已被 except 转换、traceback 已释放或任务已重试时，原始帧可能不存在；修复是更靠近异常点进入 post-mortem 或保留受控 traceback，而不是在新请求中猜旧变量。

debugpy 端口存在但客户端立即断开时，查看 debugpy*.log 中的 DAP 握手与版本信息，核对连接方向、端口和客户端是否真使用 DAP。把普通 TCP 探针成功当成调试成功，会漏掉 initialize 与 attach 失败。修复后至少要看到断点验证和目标 PID 匹配。

attach 注入失败时，按目标用户、PID namespace、平台保护策略、解释器架构和 debugpy 所在环境逐层排查。不要先修改全局安全参数。若隔离副本能在同用户下 attach，而生产副本被策略拒绝，说明工具本身可用，剩下的是权限决策，不是安装问题。

父进程能停、worker 不能停时，比较父子 PID、启动方式、subProcess 配置时点和每个 debugpy 日志。若 worker 已在客户端连接前创建，晚到的配置无法追回早期执行；在隔离环境重启并提前设置策略，是比在线反复注入更可解释的验证。

断点显示未验证时，先比较 module.__file__、两端提交和 pathMappings。路径映射恢复后仍失败，再检查代码是否已经执行、进程是否正确、模块是否来自 wheel 或挂载副本。只有断点变为已验证且在目标 PID 命中，路径修复才算完成。

内存、日志和变量都按敏感数据处理

变量窗口可能直接展示 token、Cookie、数据库密码、请求正文和个人数据；求值表达式还可能调用具有副作用的函数。共享现场先检查结构、长度、类型和脱敏字段，避免展开整个对象；禁止把变量窗口截图、完整 traceback locals 或调试日志直接贴进公开工单。

debugpy 日志可能包含本机与远端路径、环境、命令行、PID、模块清单和协议消息。启用子进程调试时，每个 child 都可能产生独立日志，容量和敏感面都会扩张。日志目录使用最小权限与短保留期，传输前脱敏，到期删除并复查；需要长期保存的结论应提炼为构建身份、栈位置和修复验证，不保存整份内存上下文。

pdb 与 debugpy 都允许修改活动变量。现场若为了验证假设临时赋值，记录变量名、旧值类别、动作和恢复方式，不记录 secret 明文；随后在隔离副本用代码修复重放。一次调试会话中的手工修正不构成正式修复，也不能替代可评审变更。

清理必须覆盖进程、端口、代码和权限

本地实验结束先在 pdb 中 quit，或让 DAP 客户端继续目标后断开；再停止测试进程和 SSH 隧道。检查 5678 没有监听，删除 .debug/debugpy-logs，移除测试脚本和临时虚拟环境。Windows 清理前用 Get-NetTCPConnection -LocalPort 5678 -ErrorAction SilentlyContinue 确认 owner，Linux 使用 ss -ltnp 定位，不按端口盲杀不相关进程。

共享环境还要撤销临时 attach 权限、容器 capability、网络策略和跳板会话，恢复被摘流实例或按计划重建。若代码临时加入 ENABLE_DEBUGPY 或诊断依赖，合并前确认默认关闭、部署参数已删除、制品不再发布端口。只有 UI 断开而端口、权限或日志仍在，调试并没有结束。

清理后的再验证是：普通启动不等待客户端，越权身份不能 attach，其他主机不能直连调试端口，目标健康状态恢复，日志和临时文件数量回到基线。把这些结果和变更记录关联，而不是保存敏感变量内容。

团队治理从版本矩阵走到退出证明

团队应维护 Python 发行线、debugpy、IDE 客户端和目标平台的兼容矩阵。升级先在隔离环境重跑四组不变量：pdb 能在异常帧读取局部状态；debugpy 本地等待与非等待行为可区分；授权 PID attach 成功而越权失败；子进程与错误路径映射反例能稳定暴露问题。版本号变了但这些证据没有重新建立，不能视为升级完成。

权限按风险分层。本机 pdb 属于开发者权限；共享环境远程调试需要服务 owner 和短时网络入口；PID 注入需要平台调试权限；查看含真实数据的变量和日志还需要数据授权。工具链 owner 维护版本与模板，服务 owner 决定目标和暂停预算，安全 owner 管理临时入口与审计，数据 owner 决定转储和日志保留。

团队模板只提供默认关闭的调试入口、回环监听、日志目录、版本采集和清理动作，不把 0.0.0.0、永久 SYS_PTRACE、无限 wait_for_client 或全量环境输出包装成“开箱即用”。审计记录关联操作者、目标 PID、构建或提交、时限、批准人、端口和清理结果；变量值、密钥和用户数据不进入审计正文。

一次会话最终要能证明五件事：调试的是正确解释器与进程，源码与目标一致，暂停和表达式副作用在预算内，端口与权限已经撤销，日志和敏感现场已按策略保留或销毁。到这个程度，pdb 与 debugpy 才从个人排错技巧变成团队可重复、可审计、可退出的 Python 运行时调试能力。