higress插件调试环境搭建：使用Docker Compose本地开发
项目地址: https://gitcode.com/GitHub_Trending/hi/higress 你是否还在为云原生网关插件开发时的环境配置而烦恼？本地调试困难、依赖复杂、迭代周期长？本文将带你使用Docker Compose快速搭建Higress插件的本地开发调试环境，让你专注于插件逻辑实现，提升开发效率。读完本文后，你将能够：搭建完整的Higress插件本地开发环境、使用Docker Compose管理服务依赖、进行插件的实时调试与测试。
环境准备
在开始搭建Higress插件调试环境之前，需要确保本地环境已安装以下工具：
- Docker Engine (20.10.0+)
- Docker Compose (v2+)
- Git
- Go (1.24+，用于Golang插件开发)
克隆Higress项目代码库：
git clone https://gitcode.com/GitHub_Trending/hi/higress.git
cd higress
插件开发框架选择
Higress支持多种语言开发插件，目前主要有两种框架可供选择：
Golang HTTP Filter
Golang HTTP Filter允许开发者使用Go语言编写自定义的Envoy Filter，支持在请求和响应流程中执行Golang代码。该框架的优势在于插件可以独立于Envoy进行编译，极大提高了开发和部署的灵活性。
注意 Golang Filter需要Higress 2.1.0或更高版本才能使用。详细开发指南可参考Golang HTTP Filter文档。
Wasm-go SDK
Wasm-go SDK用于使用Go语言开发Higress的Wasm插件，采用WebAssembly技术栈，具有更好的跨平台兼容性。使用以下命令可以快速构建wasm-go插件：
# 构建request-block插件示例
PLUGIN_NAME=request-block make build
构建产物将输出到extensions/request-block/plugin.wasm，可直接用于本地调试。详细构建流程可参考Wasm-go SDK文档。
Docker Compose环境配置
Higress提供了基于Docker Compose的本地开发环境配置，通过hgctl工具实现一键启动。核心实现逻辑位于hgctl/pkg/docker/compose.go，该模块负责Docker Compose服务的创建、启动和管理。
服务架构
本地开发环境主要包含以下服务组件：
- Higress Gateway：基于Envoy的核心网关服务
- Controller：Higress控制平面组件
- etcd：配置存储服务
- 插件开发调试容器：包含插件编译和调试工具链
服务架构如下图所示： 
启动开发环境
使用hgctl工具启动Docker Compose开发环境：
# 进入hgctl目录
cd hgctl
# 启动本地开发环境
go run cmd/hgctl/main.go dashboard
该命令会自动生成Docker Compose配置并启动所有依赖服务。首次启动时会拉取相关镜像，可能需要几分钟时间，请耐心等待。
插件开发调试流程
1. 创建插件项目
以Golang Filter插件为例，创建插件项目结构：
# 创建插件目录
mkdir -p plugins/golang-filter/my-plugin
# 创建主程序文件
touch plugins/golang-filter/my-plugin/main.go
在main.go中编写基础插件框架代码：
package main
import (
"github.com/alibaba/higress/plugins/golang-filter/pkg/http"
"github.com/envoyproxy/envoy/contrib/golang/filters/http/sdk/go/pkg/api"
)
func init() {
http.RegisterHttpFilterFactoryAndConfigParser(
"my-plugin",
NewFilterFactory,
&ConfigParser{},
)
}
type FilterFactory struct{}
func NewFilterFactory() api.StreamFilterFactory {
return func(cb api.FilterCallbackHandler) api.StreamFilter {
return &MyFilter{cb: cb}
}
}
type MyFilter struct {
cb api.FilterCallbackHandler
}
// 实现HTTP请求处理逻辑
func (f *MyFilter) DecodeHeaders(header api.RequestHeaderMap, endStream bool) api.StatusType {
// 添加自定义处理逻辑
header.Add("X-My-Plugin", "active")
return api.Continue
}
// 其他必要接口实现...
2. 配置插件调试
修改Docker Compose配置，将本地插件目录挂载到容器中：
services:
higress-gateway:
volumes:
- ./plugins/golang-filter:/etc/higress/plugins
environment:
- ENVOY_GOOGLE_FILTER_CONFIG_PATH=/etc/higress/plugins/my-plugin
3. 实时调试
启动插件调试模式：
# 构建插件
cd plugins/golang-filter/my-plugin
GOOS=linux GOARCH=amd64 go build -buildmode=plugin -o my-plugin.so .
# 重启Higress网关使插件生效
docker compose restart higress-gateway
查看插件日志：
docker compose logs -f higress-gateway
测试验证
使用curl命令发送测试请求：
curl -v http://localhost:8080/test -H "Host: example.com"
若在响应头中看到X-My-Plugin: active，说明插件已成功加载并运行。
插件工作流程验证
Higress网关的请求处理流程如下： 
可通过修改插件逻辑并重复构建-重启-测试流程，验证不同场景下的插件行为。
常见问题解决
插件加载失败
若遇到插件加载失败，可检查以下几点：
- 插件编译是否成功生成
.so文件 - Docker Compose挂载路径是否正确
- 插件日志输出，可通过以下命令查看：
docker compose exec higress-gateway cat /var/log/higress/filter.log
调试断点无法命中
Golang插件调试需要确保：
- 编译时添加了调试符号（不使用
-s -w编译选项） - IDE调试配置正确映射了容器内路径
总结与展望
通过本文介绍的方法，我们使用Docker Compose快速搭建了Higress插件的本地开发调试环境，实现了插件的实时开发与测试。这种方式极大简化了环境配置复杂度，缩短了插件开发迭代周期。
未来，Higress团队将进一步优化插件开发体验，计划支持：
- 插件热重载，无需重启网关
- 更完善的调试工具链集成
- 可视化插件开发控制台
如果你在使用过程中遇到问题或有功能建议，欢迎通过Higress项目提交issue或PR参与贡献。
提示：更多插件开发示例可参考Higress插件示例，包含各类常见场景的实现代码。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
