Odoo远程调试Gevent断点失效解决方法

本文深入探讨Odoo与VSCode远程调试环境中，当启用Gevent支持时，断点无法正常触发的问题。核心解决方案是利用自定义Python入口脚本，在调试器加载Odoo之前，以编程方式重新设置GEVENT_SUPPORT环境变量，从而规避debugpy与Gevent之间的兼容性冲突。此方法适用于Python 3.12以下版本，确保调试功能正常运作，并消除冗余警告信息。

Odoo远程调试断点失效问题概述

在使用VSCode对运行在Docker容器中的Odoo进行远程调试时，开发者常遇到一个棘手的问题：尽管所有配置（如launch.json中的pathMappings、debugpy的安装和端口映射）看似正确，且VSCode能够识别远程文件中的断点（显示为红色），但程序执行到断点处时却未能停止。尤其当Odoo环境启用了Gevent进行异步操作时，这一问题更为突出。

典型的调试设置包括：

1. Docker Compose配置：暴露调试端口（如5678）并启动debugpy监听。

   ports:
     - "8069:8069"
     - "5678:5678"
   expose:
     - 8069
     - 5678    
   command: "python3 -m debugpy --listen 0.0.0.0:5678 --wait-for-client /path_to_odoo/odoo-bin args"

2. VSCode launch.json配置：类型为python，请求为attach，并设置pathMappings。

   {
       "version": "0.2.0",
       "env": {
           "GEVENT_SUPPORT": "True" // 问题根源之一
       },
       "configurations": [
           {
               "name": "Debug",
               "type": "python",
               "request": "attach",
               "connect": {
                   "host": "127.0.0.1",
                   "port": 5678
               },
               "pathMappings": [
                   {
                       "localRoot": "/local_folder/odoo",
                       "remoteRoot": "/remote_folder/odoo"
                   }
               ],
               "justMyCode": true
           }
       ]
   } 

   尽管debugpy在容器中正常监听，且VSCode连接成功，断点依然无法触发。

问题根源：Gevent与Debugpy的兼容性冲突

经过深入调查，发现此问题与debugpy（特别是其1.8及以下版本）在处理Gevent支持时的一个已知Bug有关。当VSCode的launch.json中明确设置"GEVENT_SUPPORT": "True"，或者Gevent在Odoo环境中被激活时，debugpy的Gevent支持机制会与断点功能发生冲突，导致断点失效。

如果简单地从launch.json中移除或将GEVENT_SUPPORT设置为False，断点可能会恢复正常，但Odoo通常会输出大量警告信息，提示Gevent猴子补丁已启用，并建议设置GEVENT_SUPPORT=True以启用调试器对Gevent的支持，这又回到了原点。

解决方案：自定义Odoo启动入口脚本

为了解决这一矛盾，我们需要一种方法，既能让debugpy在启动时避免Gevent冲突，又能确保Odoo运行时Gevent支持被正确启用，且不产生警告。核心思路是创建一个自定义的Python入口脚本，由debugpy执行，该脚本负责在加载Odoo主程序之前，以编程方式设置GEVENT_SUPPORT环境变量。

步骤一：调整VSCode launch.json配置

首先，从VSCode的launch.json配置中移除或将GEVENT_SUPPORT环境变量的设置。这样，debugpy在启动时就不会直接被GEVENT_SUPPORT=True影响。

{
    "version": "0.2.0",
    // 移除或注释掉 "env": { "GEVENT_SUPPORT": "True" }
    "configurations": [
        {
            "name": "Debug",
            "type": "python",
            "request": "attach",
            "connect": {
                "host": "127.0.0.1",
                "port": 5678
            },
            "pathMappings": [
                {
                    "localRoot": "/local_folder/odoo",
                    "remoteRoot": "/remote_folder/odoo"
                }
            ],
            "justMyCode": true
        }
    ]
} 

步骤二：创建自定义Odoo启动脚本

在Odoo项目文件夹中（例如，与odoo-bin同级或在项目根目录），创建一个名为odoo_custom.py的新Python文件。这个脚本将作为Odoo的实际入口点。

#!/usr/bin/env python3

import sys
import os

# 将Odoo框架路径添加到sys.path，确保能正确导入Odoo模块
# 请根据您的实际项目结构调整此路径
sys.path.append('/path/to/project_folder/framework') 

# 在导入Odoo主程序之前，以编程方式设置GEVENT_SUPPORT环境变量
# 这样可以避免debugpy启动时的冲突，同时满足Odoo对Gevent支持的需求
os.environ['GEVENT_SUPPORT'] = 'true'

# 可选：设置服务器时区为UTC，在time模块被导入之前设置
os.environ['TZ'] = 'UTC'

# 导入并执行Odoo主程序 (odoo-bin)
if __name__ == "__main__":
    # 使用with open读取odoo-bin文件内容并执行
    # 这样可以模拟直接运行odoo-bin的行为
    with open("/path/to/project_folder/framework/odoo-bin") as f:
        code = compile(f.read(), "odoo-bin", 'exec')
        exec(code)

请务必根据您的实际项目路径修改sys.path.append和with open中的/path/to/project_folder/framework。 通常，/path/to/project_folder/framework指的是包含odoo-bin文件及其依赖模块的Odoo核心代码目录。

步骤三：更新Docker Compose配置

最后，修改docker-compose.yml中的command指令，使其不再直接执行odoo-bin，而是执行我们刚刚创建的odoo_custom.py脚本。

ports:
  - "8069:8069"
  - "5678:5678"
expose:
  - 8069
  - 5678    
command: "python3 -m debugpy --listen 0.0.0.0:5678 --wait-for-client /path/to/project_folder/odoo_custom.py args"

同样，这里的/path/to/project_folder/odoo_custom.py应替换为odoo_custom.py文件在容器内的实际路径。

注意事项与总结

1. 路径映射（pathMappings）：确保VSCode launch.json中的localRoot和remoteRoot路径映射正确无误，这是远程调试的基础。
2. 端口暴露与监听：确认Docker Compose中已正确暴露5678端口，且debugpy在容器内监听0.0.0.0:5678。
3. debugpy安装：确保您的Odoo Docker镜像中已安装debugpy（通常通过pip3 install debugpy）。
4. Python版本兼容性：此解决方案主要针对debugpy在Python 3.12以下版本中与Gevent的兼容性问题。debugpy团队已在2024年1月3日关闭相关Issue，并计划在Python 3.12+版本中修复此问题。因此，如果您的Odoo环境运行在Python 3.12或更高版本上，未来可能无需此复杂的工作流。但对于当前和较旧的Python版本，此自定义入口脚本是有效的解决方案。
5. sys.path.append的重要性：自定义脚本需要能够找到并执行Odoo的核心程序odoo-bin。sys.path.append确保Python解释器能正确导入Odoo框架中的模块。

通过上述步骤，您将能够成功在Odoo与VSCode之间建立稳定的远程调试会话，并确保断点在Gevent环境下正常触发，同时避免不必要的警告信息。这个自定义入口脚本提供了一个灵活且强大的方式来处理特定环境下的调试挑战。