后端【免费下载链接】zoraxyA general purpose HTTP reverse proxy and forwarding tool. Now written in Go!项目地址https://gitcode.com/gh_mirrors/zo/zoraxy点击查看免费下载Zoraxy 插件本质上就是一个带 HTTP Server / Listener 的普通 Go 程序因此它的构建流程与编译一个普通 Go 程序完全一致先go mod tidy整理依赖再go build产出平台相关二进制最后用-introspect标志校验产物是否符合 Zoraxy 的插件加载协议。本文以 6. Compile a Plugin.md 为骨架结合仓库中的zoraxy_plugin库源码与 example 插件工程完整讲解从目录结构、依赖引入、构建命令、内省验证到部署安装与热重载的全过程读完即可动手编译并验证自己的第一个 Zoraxy 插件。一、编译前的准备插件就是会说话的 Go 程序官方文档给出了最核心的定性插件基本上就是一个带有 HTTP Server / Listener 的 Go 程序构建插件的步骤与构建普通 Go 程序完全一样。这意味着你不需要掌握任何特殊工具链、插件 SDK 编译器或专有构建系统只要本机具备标准的 Go 工具链go命令即可。需要额外准备的是zoraxy_plugin库。该库是 Zoraxy 与插件之间通信协议的 Go 实现同时被 Zoraxy 主程序和插件共同使用。它并非通过go get从公共仓库拉取而是以源码目录形式直接复制进你的插件工程例如仓库中每个示例插件的mod/zoraxy_plugin/目录example/plugins/helloworld/ ├── mod/ │ └── zoraxy_plugin/ # 从 src/mod/plugins/zoraxy_plugin 复制而来 │ ├── zoraxy_plugin.go # -introspect 与 -configure 的解析实现 │ ├── embed_webserver.go # 基于 embed.FS 的插件 UI 路由 │ ├── dev_webserver.go # 基于文件系统的开发模式 UI 路由 │ ├── static_router.go # 静态捕获路径路由 │ ├── dynamic_router.go # 动态捕获 sniff/ingress 路由 │ └── events/ # 事件订阅相关实现 ├── www/index.html ├── go.mod └── main.goexample/plugins/helloworld/mod/zoraxy_plugin/README.txt对此做了说明复制整个zoraxy_plugin模块到插件的 mod 目录保持目录结构与文件组织即可获得处理-introspect、-configure启动流程以及内嵌 Web UI 路由的全部能力。由于该库向后兼容其文件头注释明确 Usually this file are backward compatible旧版本插件复制的旧库也能被新版 Zoraxy 正常加载。示例插件的go.mod非常简单只声明 module 名与 Go 版本依赖的zoraxy_plugin库通过目录内的包路径如example.com/zoraxy/helloworld/mod/zoraxy_plugin直接解析因此只要mod/zoraxy_plugin目录存在离线也能完成go mod tidy与go buildmodule example.com/zoraxy/helloworld go 1.23.6注意如果插件引入了mod/zoraxy_plugin之外的第三方依赖如仓库中 upnp 示例插件 就依赖 miniupnpcgo mod tidy时会需要联网拉取依赖并生成go.sum。二、标准构建流程go mod tidygo build原文档给出的构建命令只有三行但在实际工程中建议配合前置检查与产物命名一起执行# 假设你当前位于插件工程的根目录包含 main.go 与 go.mod go mod tidy go build # 用 -introspect 标志验证插件是否正确构建 ./{{your_plugin_name}} -introspect # 此时插件的元信息会以 JSON 字符串打印到 STDOUT1.go mod tidy整理插件工程的依赖。对于只依赖mod/zoraxy_plugin库的插件该命令不会产生任何额外下载对于有第三方依赖的插件它会解析并写入go.sum。2.go build在当前目录产出二进制。go build的默认输出名取自插件根目录名filepath.Base这与 Zoraxy 插件管理器的自动重建逻辑一致在 hotrebuild.go 的RebuildPlugin中Zoraxy 使用go build -o 目录名Windows 下追加.exe来产出与插件目录同名的二进制// src/mod/plugins/hotrebuild.go outputBinary : filepath.Base(plugin.RootDir) if runtime.GOOS windows { outputBinary .exe } cmd exec.Command(goPath, build, -o, outputBinary, .)3. 跨平台交叉编译与分发命名Zoraxy 插件以平台相关二进制分发命名约定为操作系统_CPU架构_插件名例如linux_amd64_foobar、windows_amd64_foobar.exe、linux_arm64_foobar见 1. What is Zoraxy Plugin.md。编译分发版本时可用 Go 标准的交叉编译参数GOOSlinux GOARCHamd64 go build -o linux_amd64_foobar GOOSwindows GOARCHamd64 go build -o windows_amd64_foobar.exe GOOSlinux GOARCHarm64 go build -o linux_arm64_foobar这一设计正是插件架构选择普通 Go 程序 HTTP 通信而非 Unix Socket / gRPC 的原因跨平台、跨 CPU 架构编译几乎没有额外成本也不存在协议转换的复杂性问题见 1. Plugin Architecture.md。三、-introspect验证编译产物能否被 Zoraxy 识别构建完成后必须用-introspect标志运行产物。这是 Zoraxy 插件三步流程Introspect → Configure → Forwarding中的第一步也是编译验证环节的核心。1. 插件侧ServeIntroSpect做了什么zoraxy_plugin库提供了ServeIntroSpect函数实现于 zoraxy_plugin.go。它检查命令行参数当第一个参数是-introspect时将插件声明的IntroSpect结构体以带缩进的 JSON 打印到 STDOUT 并退出os.Exit(0)func ServeIntroSpect(pluginSpect *IntroSpect) { if len(os.Args) 1 os.Args[1] -introspect { //Print the intro spect and exit jsonData, _ : json.MarshalIndent(pluginSpect, , ) fmt.Println(string(jsonData)) os.Exit(0) } }在插件main()中这一调用位于最前面。以 helloworld 示例插件 为例func main() { // 打印 introspect 并在传入 -introspect 标志时退出 runtimeCfg, err : plugin.ServeAndRecvSpec(plugin.IntroSpect{ ID: com.example.helloworld, Name: Hello World Plugin, Author: foobar, AuthorContact: adminexample.com, Description: A simple hello world plugin, URL: https://example.com, Type: plugin.PluginType_Utilities, VersionMajor: 1, VersionMinor: 0, VersionPatch: 0, UIPath: /, // 工具类插件只提供 UI不捕获流量 }) ... }ServeAndRecvSpec等价于先执行ServeIntroSpect内省并退出再执行RecvConfigureSpec读取-configure配置进入运行模式是官方推荐的入口封装。2. 手动触发确认返回的 JSON 正确-introspect支持手动触发用于在发布前确认返回内容正确。文档给出的 debugger 示例插件 的验证输出如下$ ./debugger -introspect { id: org.aroz.zoraxy.debugger, name: Plugin Debugger, author: aroz.org, author_contact: https://aroz.org, description: A debugger for Zoraxy \u003c-\u003e plugin communication pipeline, url: https://zoraxy.aroz.org, type: 0, version_major: 1, version_minor: 0, version_patch: 0, static_capture_paths: [ { capture_path: /test_a }, { capture_path: /test_b } ], static_capture_ingress: /s_capture, dynamic_capture_sniff: /d_sniff, dynamic_capture_ingress: /d_capture, ui_path: /debug, subscription_path: , subscriptions_events: null }3. Zoraxy 侧内省是如何被消费的Zoraxy 在加载插件时会调用插件二进制并解析其 STDOUT 输出introspect.gocmd : exec.CommandContext(ctx, entryPoint, -introspect) output, err : cmd.Output() if ctx.Err() context.DeadlineExceeded { return nil, fmt.Errorf(plugin introspect timed out) } ... err json.Unmarshal(output, pluginSpec)两个关键约束由此而来超时Zoraxy 给内省调用设置了 10 秒超时context.WithTimeout(..., 10*time.Second)。如果插件在-introspect模式下启动缓慢例如初始化时访问网络会被判定为内省超时编译成功但加载失败。输出纯净STDOUT 必须只包含 JSON 内省结果。fmt.Println之类的调试输出如果出现在内省模式下会导致json.Unmarshal失败。示例插件中调试打印都放在内省之后如 debugger 的pathRouter.SetDebugPrintMode(true)这是值得沿用的习惯。另外intrspect.go 中的checkSupportHotRebuild会检查插件目录是否存在Makefile或main.go据此决定该插件是否支持热重建这直接影响后续的编译工作流见第五节。四、IntroSpect结构内省 JSON 的字段契约内省返回的结构体定义在zoraxy_plugin库中Zoraxy 与插件共同使用。以当前仓库 zoraxy_plugin.go 的实现为准完整字段如下字段JSON 键说明IDid插件唯一 ID建议使用反写域名如com.yourdomain.pluginnameNamename插件名称Authorauthor作者名AuthorContactauthor_contact作者联系方式如邮箱Descriptiondescription插件描述URLurl插件主页 URLTypetype插件类型0Router路由插件或1Utilities工具插件VersionMajor/Minor/Patchversion_major/minor/patch主/次/修订版本号StaticCapturePathsstatic_capture_paths静态捕获路径列表capture_path插件启用后这些规则恒定作用于 HTTP 代理规则速度快但灵活性低StaticCaptureIngressstatic_capture_ingress静态捕获入口路径如/s_handlerDynamicCaptureSniffdynamic_capture_sniff动态捕获嗅探路径如/d_sniffZoraxy 把请求转发到这里插件返回 280 才捕获流量DynamicCaptureIngressdynamic_capture_ingress动态捕获入口路径如/d_handlerUIPathui_path插件 UI 路径如/uiZoraxy Web UI 会把该子路径整棵代理到插件SubscriptionPathsubscription_path订阅事件路径如/notifyme事件触发时 Zoraxy 以SubscriptionEvent为 body 发送 POSTSubscriptionsEventssubscriptions_events订阅事件映射键为事件名、值为事件说明PermittedAPIEndpointspermitted_api_endpoints插件允许访问的 Zoraxy API 端点列表方法、端点、原因用于插件向 Zoraxy 发起 API 调用其中PluginType与ControlStatusCode的取值定义同样来自该库type PluginType int const ( PluginType_Router PluginType 0 // 路由插件处理/路由/转发流量 PluginType_Utilities PluginType 1 // 工具插件不拦截 dpcore 流量如 Zerotier、静态 Web 服务器 ) const ( ControlStatusCode_CAPTURED ControlStatusCode 280 // 流量被插件捕获 ControlStatusCode_UNHANDLED ControlStatusCode 284 // 插件未处理交由下一个插件 ControlStatusCode_ERROR ControlStatusCode 580 // 处理出错交给 Zoraxy 处理并记录日志 )想深入理解静态捕获与动态捕获的语义差异可继续阅读 4. Capture Modes.md对应路由实现见 static_router.go 与 dynamic_router.go。五、编译产物的部署与热重建1. 手动安装测试编译并验证通过后将二进制放入 Zoraxy 安装目录下的/plugins/{plugin_name}/文件夹即可手动安装见 1. What is Zoraxy Plugin.md。注意文件夹内的二进制名称必须与插件文件夹名完全一致——放在/plugins/foobar/中的二进制应命名为foobarWindows 为foobar.exe不能叫foobar_plugin.exe之类的名字否则插件无法被正确识别。2. Zoraxy 自动重建Hot Rebuild对于开发中的插件Zoraxy 提供自动重建能力。hotrebuild.go 的RebuildPlugin逻辑为插件目录含Makefile时执行make构建否则要求目录含main.go且系统安装有 Go 编译器执行go build -o 目录名重建前若插件正在运行则先停止重建成功后若之前处于启用状态则自动重启并刷新标签映射。与此配套的是 development.go 中的热重载Hot Reload机制Zoraxy 周期性默认HotReloadInterval秒对插件入口二进制计算 SHA-256 哈希一旦发现文件变更就自动调用HotReloadPlugin完成停止 → 从磁盘重载最新版本的闭环间隔通过 API 可调且最小为 1 秒。这意味着编译脚本如go build覆盖二进制与 Zoraxy 热重载配合可以实现改代码后自动生效的开发循环无需手工重启。3. 批量构建示例工程仓库 build_all.sh 展示了多插件工程的批量构建流程先将src/mod/plugins/zoraxy_plugin最新版复制到每个插件的mod/目录再逐个执行go mod tidy与go build任一失败则整体返回非零退出码。单插件开发时保持mod/zoraxy_plugin与主仓库同步是避免协议不匹配的关键。六、构建验证清单与常见问题结合本文所有要点给出编译与验证插件的最终检查清单目录结构完整插件根目录含main.go、go.mod且mod/zoraxy_plugin/目录完整含zoraxy_plugin.go等文件go mod tidy无报错有第三方依赖时确认网络可达、go.sum生成go build成功二进制默认以插件目录名命名-introspect输出为纯 JSON直接运行./你的插件名 -introspect确认输出能被json.Unmarshal解析且id唯一、type取值正确内省耗时在 10 秒内Zoraxy 侧内省调用有 10 秒超时introspect.go避免在启动路径中做阻塞性网络操作部署命名匹配放入/plugins/{name}/的二进制文件名与文件夹名一致运行模式自测插件进入运行模式后监听127.0.0.1:port端口由 Zoraxy 通过-configure注入的ConfigureSpec提供见 3. Configure.md确认 UI 路径与捕获路径可访问。七、延伸阅读编译与内省协议定义zoraxy_plugin.go内省调用与热重建检测introspect.go、hotrebuild.go完整可编译示例helloworld、debugger、restful-example、api-call-example插件内省机制详解2. Introspect.md配置注入机制详解3. Configure.md插件架构总览1. Plugin Architecture.md赞分享后端【免费下载链接】zoraxyA general purpose HTTP reverse proxy and forwarding tool. Now written in Go!项目地址https://gitcode.com/gh_mirrors/zo/zoraxy点击查看免费下载相关推荐Termux编译构建从源码编译应用和插件Termux编译构建从源码编译应用和插件 引言告别无法安装的困境 你是否曾因Google Play版本限制而无法使用Termux的完整功能是否在调试插移动开发CLI操作系统Zoraxy 插件信息面板完全指南从 IntroSpect 元数据到运行时洞察Zoraxy 插件信息面板完全指南从 IntroSpect 元数据到运行时洞察 导读 本篇指南聚焦 Zoraxy 反向代理中插件信息查看功能的完整使用与底层实后端NVD3 Node.js/CommonJS 构建与验证指南从源码编译到浏览器测试NVD3 Node.js/CommonJS 构建与验证指南从源码编译到浏览器测试 NVD3 是一款基于 d3.js 的可复用图表库其核心构建产物 build数据可视化前端上一篇Iris Admin一个功能丰富的Go语言Web管理框架下一篇CEF源码编译完全指南从下载到构建的详细步骤创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
