---
tags: traefik, ssl, https, let's encrypt, acme, ingress, kubernetes, 证书
description: Traefik 配置 Let's Encrypt 自动 SSL 证书的完整指南,解决浏览器显示不安全的问题
title: Traefik SSL 证书配置指南
createdAt: 2025-11-26
---

# Traefik SSL 证书配置指南

## 问题描述

Traefik 默认使用自签名证书,导致浏览器显示"不安全"警告。

## 解决方案

使用 Let's Encrypt 提供的免费 SSL 证书,通过 ACME 协议自动获取和续期。

## 配置步骤

### 1. 更新 Traefik 配置

已在 `traefik-complete.yaml` 中添加:

- **PersistentVolume/PVC**: 存储 ACME 证书数据
- **ACME 配置参数**: 
  - 证书解析器 `letsencrypt`
  - HTTP Challenge 验证
  - 自动 HTTP → HTTPS 重定向

### 2. 关键配置说明

```yaml
# Let's Encrypt 配置
- --certificatesresolvers.letsencrypt.acme.email=your-email@example.com  # 修改为你的邮箱
- --certificatesresolvers.letsencrypt.acme.storage=/acme/acme.json
- --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
```

### 3. 修改邮箱地址

**重要**: 在应用配置前,修改 `traefik-complete.yaml` 中的邮箱:

```bash
# 编辑文件,将 your-email@example.com 改为你的真实邮箱
vi k8s/xiongxiao.me/traefik/traefik-complete.yaml
```

### 4. 应用配置

```bash
# 创建存储目录(在 k8s master 节点上)
sudo mkdir -p /data/traefik-acme
sudo chmod 600 /data/traefik-acme

# 应用配置
kubectl apply -f k8s/xiongxiao.me/traefik/traefik-complete.yaml

# 检查 PV/PVC 状态
kubectl get pv,pvc -n traefik

# 检查 Traefik Pod 状态
kubectl get pods -n traefik
kubectl logs -f deployment/traefik -n traefik
```

### 5. Ingress 使用示例

创建带 SSL 的 Ingress 资源:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: default
  annotations:
    # 指定使用 letsencrypt 证书解析器
    traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt
spec:
  ingressClassName: traefik
  rules:
  - host: example.xiongxiao.me
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80
  tls:
  - hosts:
    - example.xiongxiao.me
    # Let's Encrypt 会自动生成证书,无需手动指定 secretName
```

## 验证 SSL 证书

### 检查证书状态

```bash
# 查看 Traefik 日志中的 ACME 证书获取过程
kubectl logs -f deployment/traefik -n traefik | grep -i acme

# 进入 Pod 检查证书文件
kubectl exec -it deployment/traefik -n traefik -- ls -la /acme/
kubectl exec -it deployment/traefik -n traefik -- cat /acme/acme.json
```

### 浏览器验证

1. 访问你的域名: `https://example.xiongxiao.me`
2. 点击浏览器地址栏的锁图标
3. 查看证书详情,应显示由 "Let's Encrypt" 签发

## 常见问题

### 1. 证书获取失败

**原因**: 
- 域名未正确解析到 Traefik 的公网 IP
- 80 端口未开放(HTTP Challenge 需要)
- 邮箱地址无效

**解决**:
```bash
# 检查域名解析
nslookup example.xiongxiao.me

# 检查 Traefik Service 的 NodePort
kubectl get svc traefik -n traefik

# 确保防火墙开放 80 和 443 端口
```

### 2. 测试环境配置

如果需要测试,使用 Let's Encrypt Staging 环境(避免达到速率限制):

```yaml
# 在 traefik args 中添加:
- --certificatesresolvers.letsencrypt.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory
```

**注意**: Staging 证书不被浏览器信任,仅用于测试。

### 3. 证书续期

Let's Encrypt 证书有效期 90 天,Traefik 会自动在到期前 30 天续期。

### 4. 多域名支持

可以为不同的域名自动获取证书:

```yaml
tls:
- hosts:
  - app1.xiongxiao.me
  - app2.xiongxiao.me
```

## 生产环境检查清单

- [ ] 修改邮箱地址为真实邮箱
- [ ] 确认域名 DNS 解析正确
- [ ] 确认 NodePort 30080 (HTTP) 可访问
- [ ] 确认 NodePort 30443 (HTTPS) 可访问
- [ ] 移除或注释 staging 环境配置
- [ ] 备份 `/data/traefik-acme/acme.json` 文件

## 参考资料

- [Traefik 官方文档 - Let's Encrypt](https://doc.traefik.io/traefik/https/acme/)
- [Let's Encrypt 速率限制](https://letsencrypt.org/docs/rate-limits/)
- [ACME HTTP Challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge)