修正 Ansible 基础环境#

实际 inventory 位于 ~/.config/ansible/inventory.yml。远端解释器应使用通用路径：

1
[defaults]
2
interpreter_python = /usr/bin/python3
3
inventory = /home/hyperbola/.config/ansible/inventory.yml

部分主机的 sudo PATH 没有 /usr/sbin，所以：

• play 显式设置标准 root PATH；
• Nginx 校验使用 /usr/sbin/nginx -t；
• 部署前用 setup 模块确认远端 Python。

安装 Nginx，但禁止 postinst 抢占 80#

1
- name: Install Nginx
2
  ansible.builtin.apt:
3
    name: nginx
4
    state: present
5
    update_cache: true
6
    cache_valid_time: 3600
7
    policy_rc_d: 101
8
  notify: Restart nginx

policy_rc_d: 101 会阻止新安装的 Nginx 使用默认配置立即启动。完整顺序是：

1. 安装软件包；
2. 渲染 30080 虚拟主机；
3. 删除默认 80 站点；
4. 执行 /usr/sbin/nginx -t；
5. 校验通过后 restart。

把旧 TLS 站点降为纯 HTTP 后端#

1
server {
2
    listen 30080;
3
    listen [::]:30080;
4
    server_name gitea.hyperbola.cc;
5

6
    location / {
7
        proxy_pass http://[::1]:30000;
8
        proxy_set_header Host $host;
9
        proxy_set_header X-Real-IP $remote_addr;
10
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
11
        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
12
    }
13
}

需要删除：

• listen 80 和 listen 443 ssl；
• 证书、TLS cipher/session/protocol；
• Nginx 内部 80→443 重定向；
• /etc/nginx/sites-enabled/default。

Traefik 会保留 Host，Nginx 的 name-based virtual host 仍然有效。

审计遗漏的 Nginx 配置#

最终检查发现 txy 还有 Twikoo/Umami 占用 80/443。定位命令：

1
/usr/sbin/nginx -T 2>&1 | awk '
2
  /^# configuration file / { file=$4; sub(/:$/, "", file) }
3
  /^[[:space:]]*listen[[:space:]]/ { print file ": " $0 }
4
'

额外站点需要按主机过滤：

• Twikoo：仅部署到 txy，回源 10.0.0.10:28080；
• Umami：仅部署到 txy，回源 10.0.0.10:23000。

恢复 k3s 默认 Traefik#

k3s 原配置包含：

1
disable:
2
  - traefik

只删除 - traefik，不能重写整个 config.yaml，否则可能破坏 token、节点地址、Flannel、TLS SAN 和 etcd 设置。之后：

1. 重启 k3s；
2. 等待 /readyz；
3. apply k3s 生成的 packaged traefik.yaml；
4. 等待 deployment/traefik rollout。

在 EntryPoint 层全局跳转 HTTPS#

1
apiVersion: helm.cattle.io/v1
2
kind: HelmChartConfig
3
metadata:
4
  name: traefik
5
  namespace: kube-system
6
spec:
7
  valuesContent: |-
8
    additionalArguments:
9
      - --entryPoints.web.http.redirections.entryPoint.to=:443
10
      - --entryPoints.web.http.redirections.entryPoint.scheme=https
11
      - --entryPoints.web.http.redirections.entryPoint.permanent=true

必须使用 to=:443。本次故障中，线上参数是 to=websecure，而 websecure EntryPoint 在 Traefik 容器内监听 :8443，因此 Traefik 实际返回了 Location: https://hyperbola.cc:8443/。改成显式外部端口 :443 后，跳转恢复为 https://hyperbola.cc/。自动化还应等待 Deployment 参数出现 --entryPoints.web.http.redirections.entryPoint.to=:443，不能只确认 HelmChartConfig 已写入。

安装 cert-manager#

公网入口统一由 Traefik 终止 TLS，证书管理也属于入口基础设施。使用 k3s HelmChart 安装 cert-manager，并等待 controller、cainjector、webhook 全部 Ready：

1
apiVersion: helm.cattle.io/v1
2
kind: HelmChart
3
metadata:
4
  name: cert-manager
5
  namespace: kube-system
6
spec:
7
  chart: cert-manager
8
  repo: https://charts.jetstack.io
9
  version: v1.21.1
10
  targetNamespace: cert-manager
11
  createNamespace: true
12
  valuesContent: |-
13
    crds:
14
      enabled: true
15
    prometheus:
16
      enabled: false

配置 Cloudflare DNS-01#

角色从 /home/hyperbola/.acme.sh/account.conf 读取已有 Cloudflare API Token，以 no_log: true 写入 cert-manager namespace 的 Secret，再由 ClusterIssuer 引用。Token 不进入 Git，也不能出现在 Ansible 输出中。

这里踩过的坑是错误是root下~/导致文件读取 /root/.acme.sh/account.conf。自动化应先用 stat 确认真实路径，并对读取、解析和写 Secret 的全部任务启用 no_log。

签发 ECDSA 通配符证书并全局使用#

证书覆盖根域名和一级子域名，私钥算法使用 ECDSA：

1
apiVersion: cert-manager.io/v1
2
kind: Certificate
3
metadata:
4
  name: hyperbola-cc-wildcard
5
  namespace: kube-system
6
spec:
7
  secretName: hyperbola-cc-wildcard-tls
8
  privateKey:
9
    algorithm: ECDSA
10
    size: 256
11
  issuerRef:
12
    name: letsencrypt-prod-cloudflare
13
    kind: ClusterIssuer
14
  dnsNames:
15
    - hyperbola.cc
16
    - "*.hyperbola.cc"

Kubernetes Secret 不能跨 namespace 直接引用，所以这里的“全局共享”发生在 Traefik TLS 终止层，而不是 Secret 层。在 kube-system 创建 Traefik 默认 TLSStore：

1
apiVersion: traefik.io/v1alpha1
2
kind: TLSStore
3
metadata:
4
  name: default
5
  namespace: kube-system
6
spec:
7
  defaultCertificate:
8
    secretName: hyperbola-cc-wildcard-tls

工作链路为：cert-manager 签发 Certificate → 写入同 namespace 的 hyperbola-cc-wildcard-tls Secret → TLSStore/default 引用 Secret → Traefik 的 websecure EntryPoint 向各 namespace 的 HTTPS 路由提供默认证书。业务 Ingress 不声明 tls.secretName，因此 default 中的旧 Nginx 路由和 zabbix 中的 Web 路由都使用同一张证书，也不会产生多份 Secret 的续期状态漂移。

*.hyperbola.cc 只覆盖一级子域名，例如 zabbix.hyperbola.cc；它不覆盖 a.b.hyperbola.cc。

配置 Docker Hub mirror#

Traefik Helm Job、CoreDNS 和 metrics-server 曾因无法拉取 pause 镜像卡在 ContainerCreating。四个节点统一配置：

1
---
2
mirrors:
3
  docker.io:
4
    endpoint:
5
      - "https://docker.m.daocloud.io"

文件路径是 /etc/rancher/k3s/registries.yaml，使用 serial: 1 逐台重启 k3s/k3s-agent。

把集群外 Nginx 注册为 Kubernetes 后端#

Nginx 没有 Pod label，所以使用无 selector Service + EndpointSlice。此类过渡资源属于入口迁移层，应放在 default，不能塞进 zabbix 业务 namespace：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: host-nginx-server
5
  namespace: default
6
spec:
7
  ports:
8
    - name: http
9
      port: 30080
10
      targetPort: 30080
11
---
12
apiVersion: discovery.k8s.io/v1
13
kind: EndpointSlice
14
metadata:
15
  name: host-nginx-server
16
  namespace: default
17
  labels:
18
    kubernetes.io/service-name: host-nginx-server
19
addressType: IPv4
20
ports:
21
  - name: http
22
    protocol: TCP
23
    port: 30080
24
endpoints:
25
  - addresses:
26
      - 10.0.0.10

addressType/ports/endpoints 位于 EndpointSlice 顶层，不在 spec 下。不同主机必须使用独立 EndpointSlice：Twikoo/Umami 指向 10.0.0.30，不能复用 server 的后端。host-nginx-aly 当前仅预留无 selector Service，不设置地址和域名，因此不会接收流量；以后补齐 address 与 hosts 即可启用。以后迁入 k3s 的站点应删除对应外部 EndpointSlice；节点特有页面则保留独立后端，避免把节点本地文件错误地复制成共享内容。