Home Assistant 按需注入远程调试器debugpy.start 动作完全指南【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.ioHome Assistant 的 Remote Python Debugger 集成基于 Microsoftdebugpy允许你用 Visual Studio Code 的 Python 调试工具连接远程实例。而debugpy.start动作是这个方案里最关键的一环它让你在不重启 Home Assistant的情况下按需注入并启动调试器。读完本文你将掌握如何在 UI 与 YAML 两种方式下调用该动作、如何通过start: false配置实现零开销按需调试以及如何与 VS Code 的launch.json配合完成远程断点调试。认识 debugpy.start 动作debugpy.start是 Remote Python Debugger远程 Python 调试器集成提供的一个动作action其官方描述为在运行时注入并启动远程 Python 调试器原文见 debugpy.start 动作文档。它的典型使用场景是你在 Remote Python Debugger 集成 中把start选项设为false此时调试器在 Home Assistant 启动时不会被激活从而完全不占用系统资源当你在排查问题时再通过本动作把调试器热注入到正在运行的进程中无需重启即可开始调试。这套机制带来的直接收益是在生产服务器上调试器带来的性能与内存开销可以一直保持关闭直到你真正需要附加调试器的那一刻才开启。权限要求{% important %}只有拥有管理员administrator权限的用户才能执行该动作。{% endimportant %}这是出于安全考虑——启动调试器意味着允许外部客户端附加进来并执行任意代码因此 Home Assistant 将该动作限制为管理员可执行。前置条件先配置 Remote Python Debugger 集成在调用debugpy.start之前你必须先通过 YAML 配置好 debugpy 集成。在configuration.yaml中添加# Example configuration.yaml entry debugpy:默认情况下该集成监听所有本地接口0.0.0.0的5678端口不等待连接并在 Home Assistant 启动时即注入调试器。集成配置参数参数说明必填默认值host监听的本地接口地址否0.0.0.0所有接口port监听端口否5678start设为true时调试器在 Home Assistant 启动时注入设为false时则通过debugpy.start动作按需注入否truewait设为true时等待调试器连接后才继续启动 Home Assistant当start为false时该选项被忽略否false以上参数说明完整收录于 debugpy 集成文档。关键理解debugpy.start动作本身不携带任何 host/port 参数它启动调试器时使用的监听地址与端口完全来自集成配置。因此如果你希望调试器最终监听在特定地址与端口应在configuration.yaml中指定# Example configuration.yaml entry debugpy: host: localhost port: 6789这在多网卡multi-homed服务器或只想本机访问时非常有用。按需注入的配置方式为了配合debugpy.start动作集成应按如下方式配置# Example configuration.yaml entry debugpy: start: false配置完成后需要重启 Home Assistant 使集成生效。之后调试器保持潜伏状态直到你调用debugpy.start。在 UI 中使用 debugpy.start在可视化编辑器中调用该动作非常简单官方步骤见 UI 使用说明打开设置Settings 自动化与场景Automations scenes。打开一个已有的自动化或脚本或选择创建Create新建一个。如果新建自动化在当When部分添加一个触发器脚本则不需要触发器。在然后执行Then do部分选择添加动作Add action。在搜索框中搜索并选择Remote Python Debugger: Start。选择保存Save。需要注意该动作不支持 targets目标。在 UI 中你不会被提示选择区域area、设备device、实体entity或标签label因为它作用于整个 Home Assistant 进程而非某个具体实体。UI 中的选项该动作在 UI 中没有额外的选项——只需选中启动即可没有任何参数需要填写。在 YAML 中使用 debugpy.start在自动化或脚本的 YAML 中动作名称为debugpy.start字段说明见 YAML 使用说明action: debugpy.start例如一个完整的自动化片段alias: Enable remote debugging on demand trigger: - platform: state entity_id: binary_sensor.debug_switch to: on action: - action: debugpy.start执行该动作后调试器会使用集成配置中的 host 与 port注入并启动——动作本身不接收任何额外参数。YAML 中的选项与 UI 一致该动作在 YAML 中同样没有任何额外选项。你还可以在设置 工具 动作Settings Tools Actions中搜索该动作选择执行动作Perform action进行手动测试无需编写任何 YAML见 Try it yourself。与 VS Code 配合附加调试器调试器启动后需要用 debugpy 兼容的调试客户端连接。Visual Studio Code Python 扩展是最常见的选择。将以下内容放入 VS Code 项目的.vscode/launch.json即可连接到调试器示例源自 debugpy 集成文档{ version: 0.2.0, configurations: [ { name: Python: Attach Local, type: debugpy, request: attach, connect: { port: 5678, host: localhost }, pathMappings: [ { localRoot: ${workspaceFolder}, remoteRoot: . } ] }, { name: Python: Attach Remote, type: debugpy, request: attach, connect: { port: 5678, host: homeassistant.local }, pathMappings: [ { localRoot: ${workspaceFolder}, remoteRoot: /usr/src/homeassistant } ] } ] }Attach Local用于附加到本机调试服务器localhost:5678。Attach Remote用于附加到远程生产服务器示例主机名为homeassistant.local按需替换为你的实际地址并通过pathMappings将本地工作区映射到容器内的/usr/src/homeassistant。调试启动阶段wait 模式如果你需要调试 Home Assistant 的启动序列例如在async_setup中下断点可以在集成配置中启用等待模式# Example configuration.yaml entry debugpy: start: true wait: truedebugpy 集成在启动序列的很早期就会被加载早于其他所有集成因此你能在加载各集成的过程中命中断点逐一定位启动阶段的问题。安全注意事项{% warning %}任何能够访问调试器端口的人都可以在你的 Home Assistant 实例上执行任意代码。只应在你信任的网络上启用调试器并且绝不要将该端口直接暴露到互联网。{% endwarning %}综合 debugpy 集成文档 与动作文档的安全提示你需要遵守两条底线仅在可信网络中启动调试器如果 Home Assistant 位于防火墙之后且只暴露了 HTTP(S) 端口那么调试器对外是安全的。使用debugpy.start按需注入而不是让调试器常驻从源头上缩小暴露窗口。已知限制与注意事项一旦启动就无法停止调试器一旦启动就没有对应的停止动作。要停止它只能重启 Home Assistant。因此在生产环境中使用前请确认你能够接受一次重启作为关闭调试器的手段。常驻调试器有持续开销即使没有客户端附加运行中的调试器也会增加内存占用并降低性能。这正是debugpy.start动作存在的意义通过start: false将这份开销完全推迟到需要时见 debugpy 集成文档 的 Known limitations 部分。历史演进佐证从仓库的发布记录与变更日志可以印证该集成的演进脉络debugpy 集成在Home Assistant 0.1122020 年 7 月中作为新集成引入见 release 0.112 发布说明后续版本中持续升级 debugpy 依赖如 1.0.0、1.2.0、1.6.x、1.8.0 等见 core-2023.10 变更日志2022 年 2 月的版本还修复了debugpy 在启动时阻塞事件循环的问题见 release 2022.2 发布说明进一步提升了该集成在启动阶段的稳定性。移除集成debugpy 集成完全通过 YAML 配置。要移除它只需删除configuration.yaml中的debugpy条目并重启 Home Assistant 即可见 debugpy 集成文档 的 Removing the integration 部分。总结何时使用 debugpy.start开发/测试环境需要经常调试时可让start: true常驻配合wait: true调试启动流程。生产服务器务必设置start: false仅在排查问题时调用debugpy.start临时注入调试器用完通过重启 Home Assistant 关闭。安全基线无论哪种环境只开放可信网络访问调试端口绝不让其暴露到公网。把debugpy.start与start: false组合使用是生产环境零开销、需要时即刻可调的推荐实践。完整动作参考见 debugpy.start 动作文档所有可用动作可按集成分组浏览于 动作列表页。【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考