# cert-manager 部署报告

**部署时间**: 2025-12-20
**状态**: 部分完成 ⚠️

---

## ✅ 已完成项

### 1. cert-manager 基础组件
- ✅ cert-manager Controller 运行正常
- ✅ cert-manager Webhook 运行正常
- ✅ cert-manager CAInjector 运行正常

```bash
NAME                                       READY   STATUS    RESTARTS
cert-manager-776494b6cf-j9fst              1/1     Running   1
cert-manager-cainjector-6cf76fc759-wlhpl   1/1     Running   1
cert-manager-webhook-7bfbfdc97c-mcr4q      1/1     Running   1
```

### 2. ClusterIssuers (HTTP-01 验证方式)
- ✅ `letsencrypt-prod` - 生产环境 (Ready)
- ✅ `letsencrypt-staging` - 测试环境 (Ready)

```bash
NAME                  READY   AGE
letsencrypt-prod      True    4m
letsencrypt-staging   True    4m
```

**ACME 账户**: 已成功注册到 Let's Encrypt
**邮箱**: admin@omniverseai.net

### 3. 配置文件已创建

```
infra/cert-manager/
├── README.md (13KB)                      - 完整技术文档
├── DEPLOY-GUIDE.md (10KB)                - 快速部署指南
├── deploy.sh                             - 一键部署脚本
├── verify.sh                             - 部署验证脚本
├── update-existing-ingress.sh            - Ingress 更新工具
├── clusterissuer-dnspod.yaml             - DNS-01 配置（待部署）
├── clusterissuer-http01.yaml             - HTTP-01 配置（已部署）
├── dnspod-webhook-deployment.yaml        - DNSPod Webhook（镜像拉取失败）
├── dnspod-secret.yaml                    - Token 模板
└── test-certificate.yaml                 - 测试证书示例
```

---

## ⚠️ 遇到的问题

### 问题 1: DNSPod Webhook 镜像拉取失败

**错误信息**:
```
Failed to pull image "qqshfox/cert-manager-webhook-dnspod:v0.2.0":
Error response from daemon: Get "https://registry-1.docker.io/v2/":
context deadline exceeded (Client.Timeout exceeded while awaiting headers)
```

**影响**: 无法使用 DNS-01 验证方式，不支持通配符证书

**临时方案**: 使用 HTTP-01 验证方式（已部署）

### 问题 2: HTTP-01 验证路径冲突

**错误信息**:
```
Waiting for HTTP-01 challenge propagation:
wrong status code '404', expected '200'
```

**原因**: `monitoring-catchall` Ingress 使用 `path: /(.*)` 捕获了所有路径，包括 ACME 挑战路径 `/.well-known/acme-challenge/*`

**影响**: 无法通过 HTTP-01 验证签发证书

---

## 🎯 当前功能状态

| 功能 | 状态 | 说明 |
|------|------|------|
| cert-manager 核心 | ✅ 可用 | 所有核心组件运行正常 |
| ClusterIssuers | ✅ 可用 | HTTP-01 验证方式已就绪 |
| Let's Encrypt 账户 | ✅ 已注册 | 可以签发证书 |
| DNS-01 验证 | ❌ 不可用 | 缺少 DNSPod Webhook |
| HTTP-01 验证 | ⚠️ 受限 | Ingress 路径冲突 |
| 通配符证书 | ❌ 不可用 | 需要 DNS-01 验证 |
| 单域名证书 | ⚠️ 受限 | 需解决 Ingress 冲突 |

---

## 📋 解决方案选择

### 方案 A: DNS-01 验证（推荐）✨

**优势**:
- ✅ 支持通配符证书 (`*.example.com`)
- ✅ 无需暴露 HTTP 端口
- ✅ 适合内网环境
- ✅ 避免 Ingress 路径冲突

**步骤**:

1. **解决镜像拉取问题**（选择一种方式）:

   **方式 1: 配置 Docker Hub 镜像加速**
   ```bash
   # 使用国内镜像源（如阿里云、腾讯云）
   # 或配置 Harbor 作为 Docker Hub 代理
   ```

   **方式 2: 手动拉取并推送到 Harbor**
   ```bash
   # 在网络条件好的环境拉取镜像
   docker pull qqshfox/cert-manager-webhook-dnspod:v0.2.0

   # 标记并推送到 Harbor
   docker tag qqshfox/cert-manager-webhook-dnspod:v0.2.0 \
     192.168.1.83:8080/library/cert-manager-webhook-dnspod:v0.2.0
   docker push 192.168.1.83:8080/library/cert-manager-webhook-dnspod:v0.2.0

   # 修改 deployment 使用 Harbor 镜像
   ```

   **方式 3: 从源码构建**
   ```bash
   git clone https://github.com/qqshfox/cert-manager-webhook-dnspod
   cd cert-manager-webhook-dnspod
   docker build -t cert-manager-webhook-dnspod:v0.2.0 .
   ```

2. **获取 DNSPod API Token**
   - 访问: https://console.dnspod.cn/account/token/token
   - 创建 API Token（需要 DNS 记录管理权限）
   - 保存格式：`ID,Token`

3. **部署 DNSPod Webhook**
   ```bash
   cd infra/cert-manager

   # 创建 Secret
   kubectl create secret generic dnspod-api-token \
     --from-literal=api-token="YOUR_ID,YOUR_TOKEN" \
     -n cert-manager

   # 部署 Webhook（如果镜像问题已解决）
   kubectl apply -f dnspod-webhook-deployment.yaml

   # 等待 Pod 就绪
   kubectl wait --for=condition=ready pod \
     -l app=cert-manager-webhook-dnspod \
     -n cert-manager --timeout=300s
   ```

4. **更新 ClusterIssuers 为 DNS-01**
   ```bash
   kubectl delete clusterissuer letsencrypt-prod letsencrypt-staging
   kubectl apply -f clusterissuer-dnspod.yaml
   ```

5. **测试证书签发**
   ```bash
   kubectl apply -f test-certificate.yaml
   kubectl get certificate -n cert-manager -w
   ```

### 方案 B: HTTP-01 验证（快速方案）

**优势**:
- ✅ 无需额外组件
- ✅ 快速部署

**限制**:
- ❌ 不支持通配符证书
- ⚠️ 需要修复 Ingress 路径冲突

**步骤**:

1. **修复 Ingress 路径冲突**

   **选项 1: 修改 monitoring-catchall 路径** (推荐)
   ```bash
   kubectl edit ingress monitoring-catchall -n observability
   ```

   将路径从 `/(.*)` 改为更具体的路径，例如：
   ```yaml
   paths:
   - path: /grafana(/|$)(.*)
     pathType: ImplementationSpecific
   ```

   **选项 2: 添加优先级更高的 Ingress**
   ```yaml
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: acme-challenge
     namespace: observability
   spec:
     ingressClassName: nginx
     rules:
     - host: monitor.omniverseai.net
       http:
         paths:
         - path: /.well-known/acme-challenge
           pathType: Prefix
           backend:
             service:
               name: cm-acme-http-solver-*
               port:
                 number: 8089
   ```

2. **创建证书**
   ```yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: monitor-tls
     namespace: observability
   spec:
     secretName: monitor-tls
     issuerRef:
       name: letsencrypt-staging  # 先用 staging 测试
       kind: ClusterIssuer
     dnsNames:
     - monitor.omniverseai.net
   ```

3. **验证签发**
   ```bash
   kubectl get certificate -n observability -w
   kubectl describe certificate monitor-tls -n observability
   ```

### 方案 C: 自签名证书（临时方案）

**用途**: 开发测试环境，快速启用 HTTPS

```bash
# 创建自签名 Issuer
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}
EOF

# 创建证书
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: monitor-tls
  namespace: observability
spec:
  secretName: monitor-tls
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer
  dnsNames:
  - monitor.omniverseai.net
EOF
```

---

## 🚀 推荐实施路径

### 阶段 1: 立即可用（5 分钟）
```bash
# 使用自签名证书快速启用 HTTPS
cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager

# 创建自签名证书
kubectl apply -f - <<EOF
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: selfsigned
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: monitor-tls
  namespace: observability
spec:
  secretName: monitor-tls
  issuerRef:
    name: selfsigned
    kind: ClusterIssuer
  dnsNames:
  - monitor.omniverseai.net
EOF
```

### 阶段 2: 配置镜像代理（1 小时）
```bash
# 配置 Harbor 作为 Docker Hub 代理
# 参考: /Users/brunogao/work/codes/tools/macos/harbor/
cd /Users/brunogao/work/codes/tools/macos/harbor
./configure-containerd-mirrors.sh

# 或手动配置镜像加速
```

### 阶段 3: 部署 DNS-01（10 分钟）
```bash
# 1. 获取 DNSPod API Token
#    https://console.dnspod.cn/account/token/token

# 2. 运行部署脚本
cd /Users/brunogao/work/codes/tools/macos/k8s/infra/cert-manager
./deploy.sh

# 3. 验证部署
./verify.sh
```

### 阶段 4: 生产环境证书（5 分钟）
```bash
# 更新现有 Ingress
./update-existing-ingress.sh

# 监控证书签发
kubectl get certificates --all-namespaces -w
```

---

## 📊 验证检查清单

### 基础组件
- [x] cert-manager Controller 运行
- [x] cert-manager Webhook 运行
- [x] cert-manager CAInjector 运行

### ClusterIssuers
- [x] letsencrypt-prod (HTTP-01)
- [x] letsencrypt-staging (HTTP-01)
- [ ] dnspod-letsencrypt (DNS-01) - 待部署

### DNSPod 集成
- [ ] DNSPod API Token Secret
- [ ] DNSPod Webhook Deployment
- [ ] DNSPod Webhook Pod 运行
- [ ] ValidatingWebhookConfiguration

### 证书签发
- [ ] 测试证书签发成功
- [ ] 生产证书签发成功
- [ ] 证书自动续期配置

---

## 📞 后续支持

### 故障排查
```bash
# 查看 cert-manager 日志
kubectl logs -n cert-manager -l app=cert-manager -f

# 查看证书状态
kubectl get certificates --all-namespaces
kubectl describe certificate <name> -n <namespace>

# 查看验证挑战
kubectl get challenges -n <namespace>
kubectl describe challenge <name> -n <namespace>
```

### 相关文档
- [完整技术文档](infra/cert-manager/README.md)
- [快速部署指南](infra/cert-manager/DEPLOY-GUIDE.md)
- [方案总览](CERT-MANAGER-SOLUTION.md)

### 官方资源
- [cert-manager 文档](https://cert-manager.io/docs/)
- [Let's Encrypt 文档](https://letsencrypt.org/docs/)
- [DNSPod API 文档](https://docs.dnspod.cn/api/)

---

## 💡 关键提示

1. **首次部署建议**:
   - 先使用 `letsencrypt-staging` 测试
   - 避免触发 Let's Encrypt 生产环境速率限制
   - 验证成功后再切换到生产环境

2. **Let's Encrypt 速率限制**:
   - 每个域名: 50 个证书/周
   - 每个账户: 300 个新订单/3 小时
   - 失败验证: 5 次失败/账户/小时

3. **DNS-01 vs HTTP-01**:
   - **DNS-01**: 支持通配符，无需暴露端口，适合内网
   - **HTTP-01**: 简单快速，但不支持通配符，需要 80 端口

4. **证书续期**:
   - Let's Encrypt 证书有效期：90 天
   - cert-manager 自动续期时间：到期前 30 天
   - 完全自动化，无需人工干预

---

**生成时间**: 2025-12-20
**下次更新**: 完成 DNSPod Webhook 部署后