# Nginx 到 K3s Traefik 迁移总结

---
tags: kubernetes, k3s, traefik, nginx, migration, summary
description: Nginx 配置迁移到 K3s + Traefik 的完整总结和快速参考
title: 迁移总结和快速参考
createdAt: 2025-11-26
---

## 快速开始

### 一键部署
```bash
cd /Users/xion/kevisual/k8s-docs/k8s/xiongxiao.me
./deploy-apps.sh
```

### 测试服务
```bash
./test-services.sh
```

### 卸载
```bash
./undeploy-apps.sh
```

## 文件结构

```
k8s/xiongxiao.me/
├── services/
│   └── external-services.yaml        # 外部服务定义 (18个服务)
├── ingress/
│   └── apps-ingressroute.yaml        # Traefik 路由配置 (18个域名)
├── docs/
│   └── 07-nginx-migration.md         # 详细迁移文档
├── deploy-apps.sh                    # 自动部署脚本
├── undeploy-apps.sh                  # 自动卸载脚本
└── test-services.sh                  # 服务测试脚本
```

## 迁移的服务 (18个)

| # | 域名 | 服务 | 端口 | 位置 |
|---|------|------|------|------|
| 1 | blinko.xiongxiao.me | 笔记 | 3111 | 10.0.32.6 |
| 2 | chat.xiongxiao.me | 聊天 | 3000 | 本地 |
| 3 | kevisual.xiongxiao.me | Kevisual | 3005 | 本地 |
| 4 | www.xiongxiao.me | 主站 | 3005 | 本地 |
| 5 | immich.xiongxiao.me | 图片 | 2283 | 本地 |
| 6 | cloud.xiongxiao.me | 云盘 | 5212 | 本地 |
| 7 | docmost.xiongxiao.me | 文档 | 3011 | 本地 |
| 8 | drawio.xiongxiao.me | 绘图 | 13000 | 本地 |
| 9 | minio.xiongxiao.me | 存储 | 9000 | 本地 |
| 10 | npm.xiongxiao.me | NPM | 30001 | 10.0.32.6 |
| 11 | gist.xiongxiao.me | 代码 | 6157 | 本地 |
| 12 | webdav.xiongxiao.me | WebDAV | 6060 | 本地 |
| 13 | esm.xiongxiao.me | CDN | 12000 | 本地 |
| 14 | umami.xiongxiao.me | 分析 | 4004 | 本地 |
| 15 | pwd.xiongxiao.me | 密码 | 8180 | 本地 |
| 16 | meilisearch.xiongxiao.me | 搜索 | 7700 | 本地 |
| 17 | memos.xiongxiao.me | Memos | 8181 | 10.0.32.6 |
| 18 | git.xiongxiao.me | Gitea | 3000 | 10.0.32.6 |

## 关键特性

### ✅ 自动 HTTPS
- 使用 Let's Encrypt 自动申请证书
- 自动续期，无需手动干预
- HTTP 自动重定向到 HTTPS

### ✅ WebSocket 支持
- 原生支持 WebSocket 连接
- 无需额外配置

### ✅ 灵活扩展
- 轻松添加新服务
- 支持多种后端类型
- 可配置中间件

## 常用命令

### 查看服务状态
```bash
# 查看所有外部服务
kubectl get svc -n default | grep external

# 查看 Endpoints
kubectl get endpoints -n default | grep external

# 查看 IngressRoute
kubectl get ingressroute -n default
```

### 查看日志
```bash
# Traefik 日志
kubectl logs -n traefik -l app=traefik -f

# 查看特定服务的 Endpoints
kubectl describe endpoints blinko-external -n default
```

### Traefik Dashboard
```bash
# 端口转发
kubectl port-forward svc/traefik 8080:8080 -n traefik

# 访问 http://localhost:8080/dashboard/
```

### 调试服务
```bash
# 测试单个服务
curl -k -v https://blinko.xiongxiao.me

# 查看 DNS 解析
nslookup blinko.xiongxiao.me

# 查看证书
openssl s_client -connect blinko.xiongxiao.me:443 -servername blinko.xiongxiao.me
```

## 添加新服务

### 1. 添加 Service 和 Endpoint

在 `services/external-services.yaml` 中添加：

```yaml
---
# 新服务
apiVersion: v1
kind: Service
metadata:
  name: newapp-external
  namespace: default
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
---
apiVersion: v1
kind: Endpoints
metadata:
  name: newapp-external
  namespace: default
subsets:
- addresses:
  - ip: 127.0.0.1  # 或实际 IP
  ports:
  - port: 8080
    name: http
```

### 2. 添加 IngressRoute

在 `ingress/apps-ingressroute.yaml` 中添加：

```yaml
---
# 新应用 - newapp.xiongxiao.me
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: newapp-https
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`newapp.xiongxiao.me`)
      kind: Rule
      services:
        - name: newapp-external
          port: 8080
  tls:
    certResolver: letsencrypt
```

### 3. 应用配置

```bash
kubectl apply -f services/external-services.yaml
kubectl apply -f ingress/apps-ingressroute.yaml
```

## 故障排查清单

### 服务无法访问

- [ ] DNS 是否指向正确的 IP (Traefik NodePort 30443)
- [ ] Service 是否存在: `kubectl get svc -n default`
- [ ] Endpoints 是否有地址: `kubectl get endpoints -n default`
- [ ] IngressRoute 是否正确: `kubectl get ingressroute -n default`
- [ ] 后端服务是否运行
- [ ] 网络是否互通: `ping 10.0.32.6`
- [ ] Traefik 是否正常: `kubectl get pods -n traefik`

### SSL 证书问题

- [ ] 域名是否可以公网访问 (Let's Encrypt 验证)
- [ ] 端口 80 是否开放 (HTTP Challenge)
- [ ] ACME 存储是否正常: `kubectl get pvc -n traefik`
- [ ] 查看证书申请日志: `kubectl logs -n traefik -l app=traefik | grep acme`

### WebSocket 连接失败

- [ ] 检查后端服务是否支持 WebSocket
- [ ] 查看 Traefik 日志是否有错误
- [ ] 测试直接连接后端服务

## 性能优化

### 启用压缩

```yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: compress
  namespace: default
spec:
  compress: {}
```

### 限流

```yaml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: rate-limit
  namespace: default
spec:
  rateLimit:
    average: 100
    burst: 50
```

### 添加到 IngressRoute

```yaml
spec:
  routes:
    - match: Host(`example.xiongxiao.me`)
      kind: Rule
      middlewares:
        - name: compress
        - name: rate-limit
      services:
        - name: example-external
          port: 8080
```

## 安全建议

1. **限制访问源**: 使用 IP 白名单中间件
2. **启用认证**: BasicAuth 或 OAuth 中间件
3. **定期更新**: 保持 Traefik 和 K3s 最新版本
4. **监控告警**: 集成 Prometheus 监控
5. **日志审计**: 保留访问日志

## 下一步

- [ ] 将服务逐步迁移到容器化部署
- [ ] 配置自动扩展 (HPA)
- [ ] 集成监控和告警
- [ ] 配置备份策略
- [ ] 文档化运维流程