码思特创意坊

标签： Traefik

  • cert-manager 自动签发 HTTPS 证书：配置与三个常见失败

    手动申请证书、手动配置、到期前手动续期——这件事在只有一两个域名时还能忍，一旦有 beta 和 prod 两套环境就很容易忘。cert-manager 把整个流程变成了一段声明式配置。

    集群里跑的是 cert-manager v1.21.2。

    ClusterIssuer 与两个环境

    Issuer 是命名空间级的，ClusterIssuer 是集群级的。因为 beta 和 prod 都要用，建了 ClusterIssuer。

    关键是建两个：staging 和 prod。它们的区别不在安全性，而在速率限制：

    • staging：Let’s Encrypt 的测试环境，签发频率限制很宽松，但证书不被浏览器信任（会报红色警告）。用来验证流程通不通。
    • prod：正式环境，证书被信任，但对”同一域名在一段时间内的签发次数”有严格限制（目前是每周 50 张）。

    正确顺序是：先用 staging 把流程跑通，确认 HTTP-01 校验能通过，再切到 prod。反过来做的话，很容易因为配置错误反复重试，几小时内就把一周的额度用光，然后只能干等。

    HTTP-01 校验为什么失败

    cert-manager 会在你的站点上临时放一个校验文件，然后让 Let’s Encrypt 从公网访问 http://<你的域名>/.well-known/acme-challenge/<token> 来确认这个域名确实归你。

    失败通常就三个原因：

    • 80 端口不通：云厂商安全组、服务器防火墙没放行。HTTP-01 只能用 80 端口，没有例外。
    • 被强制跳转 HTTPS：如果 Ingress 配了”所有 HTTP 请求 301 到 HTTPS”，校验请求会被跳走，Let’s Encrypt 拿不到文件内容。需要给 challenge 路径单独放行。
    • DNS 还没生效：域名解析没指向这台服务器，或者刚改过解析还在传播中。

    排查命令固定三板斧：

    kubectl get certificate -A
kubectl describe certificate &lt;name&gt; -n &lt;ns&gt;
kubectl get challenge -A      # 看 challenge 的状态和原因

    describe certificate 输出的 Events 基本会直接告诉你卡在哪一步。

    证书复用

    同一台主机下的所有 Ingress 共用一张证书。我的 WordPress、/qrcode、/tools 都在 www.mazter.cn 下，所以只有一张 wp-tls。

    新增子路径应用时不需要动证书配置，这一点在 Traefik 那篇里也提过——共用域名的隐性收益。

    续期

    Let’s Encrypt 证书有效期 90 天。cert-manager 会在到期前自动续期，默认是到期前 30 天开始尝试。你什么都不用做。

    值得做的一件事是加个监控：证书状态不是 Ready 时能收到通知。它平时不出问题，但一旦出问题（比如 DNS 改了、80 端口被封），表现是”整站突然打不开”，而且往往在你最不想处理事情的时候发生。

  • Traefik 子路径路由：一个域名挂多个应用

    这个域名下挂着三套完全独立的东西：根路径是 WordPress，/qrcode 是一个 Nuxt 应用（二维码与文件分享），/tools 是另一个 Nuxt 应用（在线图片工具）。它们没有共用任何代码，只是恰好共用一个域名。

    让这件事成立的是 Traefik 的 Ingress 路径匹配。

    路径规则

    Ingress 里按前缀分流，一个 host 下三条规则：

    rules:
  - host: www.mazter.cn
    http:
      paths:
        - path: /qrcode
          pathType: Prefix
          backend:
            service:
              name: svc-qrcode-app
              port:
                number: 80
        - path: /tools
          pathType: Prefix
          backend:
            service:
              name: svc-tools-app
              port:
                number: 80
        - path: /
          pathType: Prefix
          backend:
            service:
              name: svc-wordpress
              port:
                number: 80

    匹配规则是最长前缀优先：/tools/compress 先匹配 /tools 而不是 /。所以顺序写在前面后面其实不影响结果，但把具体的写在前面更符合直觉。

    要不要 stripPrefix

    这是最容易踩的一个决策点。所谓 stripPrefix，是指 Ingress 把 /qrcode 这段前缀剥掉再转给后端，后端收到的就是 /。

    我没有用它，理由是：现代前端框架（Nuxt、Next、Vite）都要求在构建期就知道自己的 base 路径。如果让 Ingress 偷偷把前缀剥掉，前端生成的资源链接和实际访问路径就会对不上，出现”页面能打开但 JS/CSS 全 404″。

    做法是让应用自己知道前缀，构建时注入：

    # Nuxt 构建期指定 baseURL
nuxt.config.ts 中：
  app: {
    baseURL: '/qrcode/'
  }

    于是后端收到的请求路径仍然是 /qrcode/xxx，应用自己也按 /qrcode 生成链接，两边对得上。

    Middleware 的 API 组陷阱

    Traefik v2 和 v3 的 CRD 分属不同的 API 组，写错的话资源能创建但完全不生效，而且不报错：

    # v2（当前集群是 v2.11.18）
apiVersion: traefik.containo.us/v1alpha1

# v3
apiVersion: traefik.io/v1alpha1

    判断方法很简单，看集群里实际装了哪些 CRD：

    kubectl get crd | grep traefik

    哪个组存在就用哪个。这个坑的表现是”我明明配了跳转 HTTPS，为什么不生效”，而 YAML 看起来毫无问题。

    证书：一个 host 只有一张

    三个应用共用一个 host，所以也只能有一张 TLS 证书。它们复用同一个 Secret（这里是 wp-tls），不需要为每个应用单独签发。cert-manager 按 host 签发，不是按路径。

    这意味着新增子路径应用时，证书部分什么都不用做——这是共用域名的另一个便利。

    什么时候该换子域名

    子路径方案的前提是所有应用”彼此信任、共用一套 Cookie 域”。我的两个应用确实需要共享登录态（同一个 mazter_token Cookie 挂在根路径上），所以子路径是加分项。

    如果某个应用需要完全独立的 Cookie、独立的安全策略，或者要交给别人维护，那就该拆成子域名。判断标准不是技术难度，是信任边界。

  • 一个 HTTP 请求头引发的 72 小时崩溃循环

    有一阵子 beta.mazter.cn 一直打不开，返回 404。当时没太在意，以为是 WordPress 初始化慢。三天后去看 Pod，才发现它已经重启了 5 次，一直卡在崩溃循环里。

    这篇文章记录完整的排查链条和根因——它有个挺有意思的特点：每一个组件都在按设计工作，组合起来却产生了死循环。

    现象

    $ kubectl get pods -n beta
NAME                         READY   STATUS    RESTARTS   AGE
wordpress-5c79d8dc94-xxxxx   0/1     Running   5          3d22h

    同一套配置在 prod 命名空间一切正常（0 次重启），所以第一反应不是配置错，而是”beta 环境有什么特殊的”。这个判断后来被证明是错的——prod 只是运气好。

    看 Events

    kubectl describe pod 是这类问题唯一的正确答案来源：

    Events:
  Warning  Unhealthy  liveness probe failed: HTTP probe failed with statuscode: 503
  Warning  Unhealthy  Readiness probe failed: HTTP probe failed with statuscode: 503
  Normal   Killing    Container failed liveness probe, will be restarted

    还有一条很关键的：Probe terminated redirects。探针跟随重定向，然后被终止了。

    还原死循环

    把整条链路串起来是这样：

    • 探针按配置去请求 http://<PodIP>:80/wp-login.php。
    • WordPress 收到的是明文 HTTP，而站点地址配置的是 HTTPS，于是它回一个 302，让客户端跳到 https://beta.mazter.cn/wp-login.php。
    • 这个 HTTPS 请求出去之后，经过 Traefik Ingress 又被路由回来——目标是同一个 WordPress Service。
    • 而此刻这个 Pod 还没通过 readiness 检查，后端池里没有可用端点，Traefik 返回 503。
    • 探针拿到 503，判定存活失败，kubelet 杀掉容器重启。
    • 重启后一切重演。

    为什么 WordPress 坚持要跳 HTTPS？因为官方镜像的 wp-config.php 里有一段条件判断，只有在检测到代理头 X-Forwarded-Proto: https 时，才会把 $_SERVER['HTTPS'] 置为 on。探针直连 Pod，不带这个头，于是 WordPress 认为”你现在是 HTTP，不安全”，坚持把你推向 HTTPS。

    修复

    给探针补上这个头即可，readiness 和 liveness 都要改：

    readinessProbe:
  httpGet:
    path: /wp-login.php
    port: 80
    httpHeaders:
      - name: X-Forwarded-Proto
        value: https
  initialDelaySeconds: 30
  periodSeconds: 10
livenessProbe:
  httpGet:
    path: /wp-login.php
    port: 80
    httpHeaders:
      - name: X-Forwarded-Proto
        value: https
  initialDelaySeconds: 60
  periodSeconds: 15

    改完 apply 之后 Pod 一次就 Ready 了，beta.mazter.cn 和 /wp-login.php 恢复 200。

    为什么 prod 没炸

    这是最值得警惕的部分。prod 之所以正常，是因为它的 Pod 已经跑了很久、早就处于 Ready 状态，重定向绕回来时能命中一个健康的后端，拿到 200 而不是 503。

    换句话说：prod 不是没有问题，只是还没被触发。任何一次重启（节点重启、镜像更新、资源不足被驱逐）都可能让 prod 走进同一个循环。所以修复同时打到了两个环境。

    更根本的解法

    补请求头是把 WordPress 的行为”哄”对了。更稳妥的做法是让探针打一个不会重定向的端点，比如在站点根放一个空的 healthz.html，探它即可。这样探针不依赖应用层的 HTTPS 判断逻辑，也不受代理头约定变化的影响。

    两种方案都行，重要的是别让健康检查去请求一个”可能会重定向”的地址——重定向会让探针的失败原因变得极难解释。