hoelee-blog/src/content/posts/zh/traefik-yaegi-plugin-package-name-trap.md at b2fdccf284a6f25b680367c17be7e6954a95b310

hoelee/hoelee-blog

0 Fork 0

Files

T

hoelee b2fdccf284 feat(posts): draft batch-06 (5 bilingual posts) and package consultant review pack

2026-10-27 20:34:54 +08:00

7.0 KiB

Raw Blame History

title, description, pubDate, category, blueprint, blueprintLayer, tags, draft, summary, dynamicCta

title

description

pubDate

本地测试全绿，上云启动暴雷的 Go 插件

在为私有化部署的公网服务构建边缘安全防护时，使用 Go 语言为 Traefik 编写自定义中间件插件是最轻量、性能最好的方案之一。它无需引入 Redis 或外部校验服务，所有扫描拦截与轻量级客户端评分逻辑均在反向代理进程内部原生运行。

近期我编写了 traefik-botfilter 插件，用于检测异常的 HTTP 请求头、阻断常见的黑客扫描路径（如 .env、wp-login.php），并在内存中对高危 IP 进行平滑扣分与限时封禁。

在本地开发环境中，测试用例表现非常完美：

go test -v ./...
# PASS: TestBotFilter (0.04s)
# PASS: TestCacheExpiration (0.12s)
# ok  github.com/hoelee/traefik-botfilter 0.182s

然而，当我将代码挂载到 Traefik 的 plugins-local 目录并启动生产容器时，Traefik 却直接崩溃退出了：

2026-10-23T04:47:12Z ERR Failed to create middleware error="failed to load plugin botfilter: CreateConfig failed with Yaegi: symbol not found" entryPointName=web routerName=app@file

Yaegi 动态解释器的包名推断规则

Traefik 加载中间件插件的方式并不是像常见 Nginx 模块那样加载预先编译好的 .so 动态链接库。相反，Traefik 内部嵌入了 Yaegi——一个轻量级的 Go 语言动态解释器。在 Traefik 启动时，Yaegi 会在内存中直接对 Go 源码进行语法分析、符号解析与动态编译。

在 Traefik 的静态配置文件中声明插件时：

experimental:
  localPlugins:
    botfilter:
      moduleName: github.com/hoelee/traefik-botfilter

Traefik 会要求 Yaegi 在插件包中寻找并导出符合中间件契约的两个标准函数入口：

CreateConfig() *Config
New(ctx context.Context, next http.Handler, config *Config, name string) (http.Handler, error)

然而，这里隐藏了一个极其隐蔽的契约断层。

在标准的 Go 语言开发中，如果一个仓库的名字带有连字符（如 traefik-botfilter），开发者通常会在源码文件首行采用惯用的简短包名（例如 package botfilter）。官方的 Go 编译器（go build）与测试框架（go test）完全允许这种写法，只要同目录下所有文件的 package 声明保持一致即可。

但是，Yaegi 并不会读取 go.mod 来推断你声明的包名。

Traefik 的插件加载器会硬编码地从 moduleName 的最后一个路径段 计算期望的包标识符，并且自动将所有的连字符（-）强制替换为下划线（_）：

\text{模块路径}: \texttt{github.com/hoelee/traefik-botfilter} \longrightarrow \text{预期包名}: \texttt{traefik\_botfilter}

而我当时的 Go 源码首行写的是：

// botfilter.go
package botfilter // <-- YAEGI 在这个命名空间下找不到导出的符号！

结果就是：Yaegi 去 AST 抽象语法树中检索 traefik_botfilter.CreateConfig 时，内存中只有 botfilter.CreateConfig。由于命名空间无法对齐，Yaegi 直接判定入口符号缺失，导致 Traefik 在启动阶段抛出致命异常并拒绝挂载网关端口。

修复步骤与目录树对齐

要让 Yaegi 正常识别插件入口，需要完成两步对齐：

1. 将所有 Go 源文件的 package 声明重命名

把项目下所有的 .go 文件（包括单元测试）首行的包名统一改为连字符转下划线后的名称：

// Package traefik_botfilter is a Traefik middleware plugin...
package traefik_botfilter

2. 严格对齐物理目录层级

对于 Traefik 的本地插件（localPlugins），源码所在的物理路径必须严格复刻完整的 Go 模块导入路径，挂载于 plugins-local/src/ 下：

plugins-local/
└── src/
    └── github.com/
        └── hoelee/
            └── traefik-botfilter/
                ├── .traefik.yml
                ├── go.mod
                ├── botfilter.go
                ├── config.go
                └── ...

点击查看修正后的动态 Traefik 中间件配置示例

http:
  middlewares:
    botfilter:
      plugin:
        botfilter:
          statusCode: 403
          requireUserAgent: true
          requireAccept: true
          browserValidation: true
          temporaryBanMinutes: 15
          scoreThreshold: 100
          blockedPaths:
            - /.env
            - /.git
            - /wp-login.php
          blockedUserAgents:
            - sqlmap
            - nikto
            - masscan
          logBlockedRequests: true

  routers:
    protected-app:
      rule: Host(`service.internal`)
      entryPoints:
        - websecure
      middlewares:
        - botfilter
      service: backend-service

交付结果

将源码包名从 botfilter 修正为 traefik_botfilter 后重新启动 Traefik，容器在 0.42 秒 内平稳拉起并成功装载插件：

2026-10-23T04:48:43Z INF Loading local plugin: botfilter
2026-10-23T04:48:44Z INF Plugin loaded successfully module=github.com/hoelee/traefik-botfilter

对于开发 Traefik 动态插件的工程师而言：Go 官方编译器的通过并不代表动态运行时的认可。 必须确保包名与模块路径最后一段的下划线转换规则完全一致，才能避免网关在生产启动时发生静默瘫痪。

7.0 KiB Raw Blame History Unescape Escape