k8s-docs/k8s/xiongxiao.me/README.md

Nginx 到 K3s Traefik 迁移总结

---

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

快速开始

一键部署

cd /Users/xion/kevisual/k8s-docs/k8s/xiongxiao.me
./deploy-apps.sh

测试服务

./test-services.sh

卸载

./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 连接
• 无需额外配置

✅ 灵活扩展

• 轻松添加新服务
• 支持多种后端类型
• 可配置中间件

常用命令

查看服务状态

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

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

# 查看 IngressRoute
kubectl get ingressroute -n default

查看日志

# Traefik 日志
kubectl logs -n traefik -l app=traefik -f

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

Traefik Dashboard

# 端口转发
kubectl port-forward svc/traefik 8080:8080 -n traefik

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

调试服务

# 测试单个服务
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 中添加：

---
# 新服务
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 中添加：

---
# 新应用 - 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. 应用配置

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 日志是否有错误
• 测试直接连接后端服务

性能优化

启用压缩

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

限流

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

添加到 IngressRoute

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)
• 集成监控和告警
• 配置备份策略
• 文档化运维流程