surfe/traefik-correlation-id

# Traefik Correlation ID 一个 [Traefik](https://traefik.io) 中间件插件，可确保每个传入的 HTTP 请求都携带唯一的 Correlation ID 标头。如果该标头已存在，则原样传递；如果不存在，中间件会自动生成一个 UUID v4。这使得单个请求可以跨服务进行端到端追踪，从而简化了调试和可观测性。 ## 功能 - 当标头不存在时，生成加密安全的随机 UUID v4 - 原样传递现有标头，保留上游调用者设置的 ID - 可配置的标头名称（默认：`correlation-id`） - 零外部依赖 ## 安装 ### Traefik Pilot / 插件目录 将此插件添加到您的 Traefik 静态配置中： ``` # traefik.yml experimental: plugins: correlation: moduleName: github.com/surfe/traefik-correlation-id version: v0.1.0 ``` ### 本地开发 挂载插件源代码并将其注册为本地插件： ``` # traefik.yml experimental: localPlugins: correlation: moduleName: github.com/surfe/traefik-correlation-id ``` 包含的 `docker-compose.yml` 会自动完成此设置。 ## 配置 | 字段 | 类型 | 默认值 | 描述 | |---|---|---|---| | `headerName` | `string` | `correlation-id` | 要读取和注入的标头名称 | ### 静态配置 (traefik.yml) ``` experimental: plugins: correlation: moduleName: github.com/surfe/traefik-correlation-id version: v0.1.0 ``` ### 动态配置 **File provider:** ``` http: middlewares: correlation: plugin: correlation: headerName: correlation-id routers: my-router: middlewares: - correlation ``` **Docker labels (per service):** ``` labels: - "traefik.http.middlewares.correlation.plugin.correlation.headerName=correlation-id" - "traefik.http.routers.my-service.middlewares=correlation@docker" ``` **全局中间件（入口点上的所有路由）：** ``` # traefik.yml entryPoints: web: address: ":80" http: middlewares: - correlation@docker ``` ## 使用 Docker 进行本地开发 `docker-compose.yml` 会启动 Traefik，加载来自本地源码树的插件，并提供一个 `whoami` 服务用于测试。 ``` docker compose up ``` 然后验证标头是否已注入： ``` curl -H "Host: whoami.localhost" http://localhost # Response 将包含：correlation-id: # 现有 header 将被保留： curl -H "Host: whoami.localhost" -H "correlation-id: my-trace-id" http://localhost # Response 将包含：correlation-id: my-trace-id ``` Traefik 仪表板可在 [http://localhost:8080](http://localhost:8080) 访问。 ## 运行测试 ``` go test -v -cover ./... ``` ## 许可证 [MIT](LICENSE)

标签：API集成, EVTX分析, Go, Ruby工具, Traefik, 中间件, 可观测性, 日志审计, 请求拦截, 链路追踪