如何在容器化环境构建APISIX Debug环境

源码仓库：github.com/cj2a7t/apis...

1.为什么要在容器化环境调试？

由于Mac M1 make run error、每个开发环境(windows、ubantu、mac、mac m1等等)本地源码安装方式的差异、没有单步调试的直接方式等问题。我们想搭建一套可以单步调试的Apisix开发环境，需要查阅很多资料，而且资料特别分散。所以想在Apisix Dokcer仓库基于debian-dev提供一种快速的搭建本地开发环境的方式。下面以VS code为例来搭建一套Apisix的开发环境。

2.开发环境全景图

3.扩展构建步骤说明

3.1 构建镜像

debian-emmy中的docker-compose.yaml中配置的镜像是已经构建好的镜像(可以直接使用)，如果有其他需求可以采用下面的步骤，本地重新构建apisix-emmy镜像，用于本地调试使用。

dockerfile 复制代码

services:
  apisix:
    # [Debian Emmy]: This is a built emmy debug image that includes /usr/local/emmy.so. 
    # [Debian Emmy]: If there is no special version available, you can use this version directly.
    # [Debian Emmy]: If there is a need for customization.
    # [Debian Emmy]: Build an image version based on the ./image/Dockerfile
    image: "coderjia/apisix-emmy:0.0.2"

在Debian-Emmy文件夹image目录下的Dockerfile，相对于官方的debian-dev新增如下内容，主要目的是将emmy_core.so文件直接生成到容器内的/usr/local/emmy/目录下，如果后续想升级emmy的debug版本，可以自行调整。然后构建出新的镜像。

3.2 准备调试的源码

将自己的定制化版本的apisix源码，放置到这个目录中，如果你需要官方版本的代码学习，那可以直接拉取官方的源码目录代码。切记：是源码目录，不包含构建文件的目录。将./emmy/emmy-debugger.lua插件拷贝到./apisix/plugins目录下，这个就是全景图中绿色的插件，用于容器内加载emmy debug。

3.3 配置调整

a. 调整./apisix_conf/config.yaml中的fix_path，调整为你本地的源码绝对路径目录。

yaml 复制代码

# [Debian Emmy]: It is only recommended to start one worker in the debug environment.
nginx_config:
  worker_processes: 1
# [Debian Emmy]: Loading emmy debugger.lua during the startup of Apisix is the key to emmy dbg listening and hooking(fix path).
plugins:
  - emmy-debugger                        # priority: 50000
# [Debian Emmy]: The fixPath function retrieves the path of the file and "fixes" it to the path expected by VS Code.
plugin_attr:
  emmy-debugger:
    fix_path: ${prefix}/apisix
    port: 9966

b. 如果有需要挂载新的目录，调整docker-compose.yaml中的挂载目录。

yaml 复制代码

    volumes:
      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
      # [Debian Emmy]: Customized version of Apisix source code
      - ./apisix:/usr/local/apisix/apisix:ro
      # [Debian Emmy]: When customizing code, you can volume it in more directories.

3.4 启动debug环境

a. 先启动Apisix相关的容器

docker 复制代码

# Version needs to be adjusted independently
APISIX_DOCKER_TAG=0.0.2 docker-compose up -d

查看日志，看emmy dbg是否已经开启监听 b. 在VS Code中安装Emmy Lua插件 c. 配置 EmmyLua插件选择EmmyLua New Debugger 添加一行preLaunchTask 在.vscode创建个task.json，主要是为了debug之前重启下容器，避免代码缓存导致debug没有到新增的代码，还有一种方式是关闭lua code cache。另外task的command是以unix的系统为例，在windows系统里，可以调整为powershell。

json 复制代码

// unix
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "restartAndDelay",
            "type": "shell",
            "command": "sh",
            "args": [
                "-c",
                "docker restart debian-emmy_apisix_1 && sleep 3"
            ]
        }
    ]
}
// windows
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "restartAndDelay",
            "type": "shell",
            "command": "powershell",
            "args": [
                "-NoProfile",
                "-ExecutionPolicy", "Bypass",
                "-Command", "docker restart debian-emmy_apisix_1 ; Start-Sleep -Seconds 3"
            ]
        }
    ]
}

d. 开始debug验证，在init.lua的access阶段加个断点 VS Code启动监听创建个测试路由，并调用路由

sh 复制代码

# create a new route
curl --location --request PUT 'http://localhost:9180/apisix/admin/routes/1' \
--header 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
--header 'Content-Type: application/json' \
--data '{
    "uri": "/anything",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "httpbin.org": 1
        }
    }
}'
# call route
curl --location 'http://localhost:9080/anything'

当调用路由后，可以看到已经debug成功