自定义中间件

Traefik 中间件允许你在请求到达应用程序之前对其进行调整——例如添加标头、速率限制、IP 白名单等。

在 Coolify 中应用自定义中间件的方式取决于你的部署类型：

标准应用程序 — 直接编辑容器标签。
Docker Compose — 使用 Coolify 简写标签，或在 docker-compose.yml 中定义标签。

这两种方法都可以引用内联定义（在 Docker 标签中）或外部定义（在 Traefik 的动态配置中）的中间件。

标准应用程序

对于标准（非 Docker Compose）应用程序，你可以通过在 Coolify 界面中编辑容器标签来配置中间件。

操作步骤

在 Coolify 中打开你的应用程序，并滚动到容器标签部分。
取消勾选只读标签，使标签文本框变为可编辑状态。

添加你的中间件定义标签。例如，要添加速率限制：

traefik.http.middlewares.my-ratelimit.ratelimit.average=100
traefik.http.middlewares.my-ratelimit.ratelimit.period=1m

找到现有的 traefik.http.routers.https-0-<uuid>.middlewares=... 行，并将你的中间件名称追加到其中：
```
traefik.http.routers.https-0-<uuid>.middlewares=gzip,my-ratelimit
```
保存并重新部署。

重要提示

取消勾选只读标签后，Coolify 将停止在部署时自动生成标签。你需要负责确保所有路由标签的正确性。如果标签配置错误，你的应用程序可能会无法访问。

如需恢复自动生成的标签，请使用重置标签为默认值按钮。

完整示例

假设 Coolify 生成的标签如下：

traefik.enable=true
traefik.http.middlewares.gzip.compress=true
traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https
traefik.http.routers.http-0-abc123.entryPoints=http
traefik.http.routers.http-0-abc123.middlewares=redirect-to-https
traefik.http.routers.http-0-abc123.rule=Host(`app.example.com`) && PathPrefix(`/`)
traefik.http.routers.http-0-abc123.service=http-0-abc123
traefik.http.routers.https-0-abc123.entryPoints=https
traefik.http.routers.https-0-abc123.middlewares=gzip
traefik.http.routers.https-0-abc123.rule=Host(`app.example.com`) && PathPrefix(`/`)
traefik.http.routers.https-0-abc123.service=https-0-abc123
traefik.http.routers.https-0-abc123.tls.certresolver=letsencrypt
traefik.http.routers.https-0-abc123.tls=true
traefik.http.services.http-0-abc123.loadbalancer.server.port=3000
traefik.http.services.https-0-abc123.loadbalancer.server.port=3000

要添加自定义标头中间件，请添加定义并更新路由器：

traefik.http.middlewares.security-headers.headers.browserXssFilter=true
traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true
traefik.http.middlewares.security-headers.headers.frameDeny=true
traefik.http.routers.https-0-abc123.middlewares=gzip,security-headers

Docker Compose 服务

对于 Docker Compose 部署，Coolify 提供了一个简写标签，可自动将你的中间件注入到路由器链中——无需手动编辑路由器标签。

使用 Coolify 简写标签

将 coolify.traefik.middlewares 添加到你的服务标签中：

services:
  myapp:
    image: nginx:alpine
    labels:
      - "traefik.http.middlewares.my-ratelimit.ratelimit.average=100"
      - "traefik.http.middlewares.my-ratelimit.ratelimit.period=1m"
      - "coolify.traefik.middlewares=my-ratelimit"

在部署期间，Coolify 会读取此标签，提取中间件名称，并将其与 gzip 等内置中间件一起追加到路由器的中间件链中。

对于多个中间件，请使用逗号分隔：

labels:
  - "coolify.traefik.middlewares=my-ratelimit,security-headers"

coolify.traefik.middlewares 标签在标签生成过程中被 Coolify 消费，不会出现在运行中的容器上。它是一个部署时指令，而非 Docker 标签。

使用外部中间件（`@file`）

如果你在 Traefik 的动态配置中定义了中间件，可以通过在其名称后附加 @file 来引用它。这样可以避免在多个应用程序中重复定义中间件。

1. 在动态配置中定义中间件

前往 服务器（Server） → 代理（Proxy） → 动态配置（Dynamic Configurations），并创建一个新的配置文件：

http:
  middlewares:
    my-ipallowlist:
      ipAllowList:
        sourceRange:
          - "192.168.1.0/24"
          - "10.0.0.0/8"

2. 在应用程序中引用它

标准应用程序 — 更新路由器中间件行：

traefik.http.routers.https-0-abc123.middlewares=gzip,my-ipallowlist@file

Docker Compose — 使用简写标签：

labels:
  - "coolify.traefik.middlewares=my-ipallowlist@file"

@file 后缀指示 Traefik 在其基于文件的动态配置中查找中间件，而不是在 Docker 标签中查找。这是标准的 Traefik 提供程序命名空间语法。

常用中间件示例

速率限制

有关所有可用选项，请参阅 Traefik RateLimit 参考。

traefik.http.middlewares.my-ratelimit.ratelimit.average=100
traefik.http.middlewares.my-ratelimit.ratelimit.period=1m
traefik.http.middlewares.my-ratelimit.ratelimit.burst=50

自定义标头

有关所有可用选项，请参阅 Traefik Headers 参考。

traefik.http.middlewares.security-headers.headers.browserXssFilter=true
traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true
traefik.http.middlewares.security-headers.headers.frameDeny=true
traefik.http.middlewares.security-headers.headers.stsSeconds=31536000
traefik.http.middlewares.security-headers.headers.stsIncludeSubdomains=true

IP 白名单

有关所有可用选项，请参阅 Traefik IPAllowList 参考。

traefik.http.middlewares.my-ipwhitelist.ipallowlist.sourcerange=192.168.1.0/24,10.0.0.0/8

重定向

关于 www/non-www 重定向和域名转发，请参阅专门的重定向指南，该指南还涵盖了 Coolify 内置的 Direction 设置。

更多中间件示例请参阅官方 Traefik 文档。

标签转义

当你的中间件标签包含 $ 等特殊字符（常见于 basic auth 哈希值）时，Coolify 在容器标签部分提供了一个转义标签中的特殊字符复选框。

启用后，$ 字符将被转义为 $$，以防止 Docker 将其解释为环境变量引用。

如果你在标签值中使用了美元符号（$）（例如 bcrypt 哈希值）且未启用转义，Docker 将尝试将其作为变量进行扩展，从而导致配置损坏。

故障排除

中间件未生效

标准应用：确认你已将中间件名称添加到 traefik.http.routers.*.middlewares 标签中。仅定义中间件是不够的——必须在路由器中进行引用。
Docker Compose：确认存在 coolify.traefik.middlewares 标签，且中间件名称完全匹配。
检查 Traefik 仪表板（如果已启用），查看中间件是否已注册到你的路由器下。

编辑标签后应用程序无法访问

如果你编辑了标准应用程序的标签并导致路由损坏，请使用重置标签为默认值按钮，重新启用只读标签，然后重新部署。
如果使用 Docker Compose，请检查 docker-compose.yml 的语法是否存在引号问题。

找不到 `@file` 中间件

确保动态配置文件已保存在正确的位置，且 Traefik 已重新加载。
验证配置中的中间件名称与你引用的名称是否匹配（区分大小写）。
检查动态配置中是否存在 YAML 语法错误。

On this page