temp
This commit is contained in:
289
k8s/xiongxiao.me/docs/07-nginx-migration.md
Normal file
289
k8s/xiongxiao.me/docs/07-nginx-migration.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# Nginx 配置迁移到 K3s + Traefik 指南
|
||||
|
||||
---
|
||||
tags: kubernetes, k3s, traefik, nginx-migration, ingress, services
|
||||
description: 将 Nginx 反向代理配置迁移到 K3s Kubernetes 集群，使用 Traefik 作为 Ingress Controller
|
||||
title: Nginx 到 K3s Traefik 迁移指南
|
||||
createdAt: 2025-11-26
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本指南说明如何将原有的 Nginx 反向代理配置迁移到 K3s Kubernetes 集群，使用 Traefik 作为 Ingress Controller。
|
||||
|
||||
## 架构说明
|
||||
|
||||
### 原架构（Nginx）
|
||||
- Nginx 直接反向代理到各个应用服务
|
||||
- 使用 Let's Encrypt 证书
|
||||
- 手动配置每个域名的 SSL
|
||||
|
||||
### 新架构（K3s + Traefik）
|
||||
- Traefik 作为统一的 Ingress Controller
|
||||
- 自动申请和续期 Let's Encrypt 证书
|
||||
- 使用 Kubernetes Service 和 Endpoints 映射外部服务
|
||||
- 使用 IngressRoute CRD 配置路由规则
|
||||
|
||||
## 配置文件说明
|
||||
|
||||
### 1. 外部服务配置 (`services/external-services.yaml`)
|
||||
|
||||
为每个外部运行的应用创建 Kubernetes Service 和 Endpoints：
|
||||
|
||||
```yaml
|
||||
# Service 定义服务接口
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: blinko-external
|
||||
namespace: default
|
||||
spec:
|
||||
type: ClusterIP
|
||||
ports:
|
||||
- port: 3111
|
||||
targetPort: 3111
|
||||
protocol: TCP
|
||||
name: http
|
||||
|
||||
# Endpoints 指向实际的 IP 地址
|
||||
apiVersion: v1
|
||||
kind: Endpoints
|
||||
metadata:
|
||||
name: blinko-external
|
||||
namespace: default
|
||||
subsets:
|
||||
- addresses:
|
||||
- ip: 10.0.32.6 # 实际服务运行的 IP
|
||||
ports:
|
||||
- port: 3111
|
||||
name: http
|
||||
```
|
||||
|
||||
### 2. Traefik IngressRoute 配置 (`ingress/apps-ingressroute.yaml`)
|
||||
|
||||
为每个服务配置域名路由和 HTTPS：
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: IngressRoute
|
||||
metadata:
|
||||
name: blinko-https
|
||||
namespace: default
|
||||
spec:
|
||||
entryPoints:
|
||||
- websecure # HTTPS 入口
|
||||
routes:
|
||||
- match: Host(`blinko.xiongxiao.me`)
|
||||
kind: Rule
|
||||
services:
|
||||
- name: blinko-external
|
||||
port: 3111
|
||||
tls:
|
||||
certResolver: letsencrypt # 自动申请 SSL 证书
|
||||
```
|
||||
|
||||
## 服务列表
|
||||
|
||||
已迁移的服务包括：
|
||||
|
||||
| 域名 | 服务名称 | 端口 | IP 地址 | 说明 |
|
||||
|------|---------|------|---------|------|
|
||||
| blinko.xiongxiao.me | blinko-external | 3111 | 10.0.32.6 | Blinko 笔记 |
|
||||
| chat.xiongxiao.me | chat-external | 3000 | 127.0.0.1 | 聊天服务 |
|
||||
| kevisual.xiongxiao.me | kevisual-external | 3005 | 127.0.0.1 | Kevisual |
|
||||
| www.xiongxiao.me | www-external | 3005 | 127.0.0.1 | 主网站 |
|
||||
| immich.xiongxiao.me | immich-external | 2283 | 127.0.0.1 | 图片管理 |
|
||||
| cloud.xiongxiao.me | cloud-external | 5212 | 127.0.0.1 | 云盘 |
|
||||
| docmost.xiongxiao.me | docmost-external | 3011 | 127.0.0.1 | 文档协作 |
|
||||
| drawio.xiongxiao.me | drawio-external | 13000 | 127.0.0.1 | 绘图工具 |
|
||||
| minio.xiongxiao.me | minio-external | 9000 | 127.0.0.1 | 对象存储 |
|
||||
| npm.xiongxiao.me | npm-external | 30001 | 10.0.32.6 | NPM 私有仓库 |
|
||||
| gist.xiongxiao.me | gist-external | 6157 | 127.0.0.1 | 代码片段 |
|
||||
| webdav.xiongxiao.me | webdav-external | 6060 | 127.0.0.1 | WebDAV |
|
||||
| esm.xiongxiao.me | esm-external | 12000 | 127.0.0.1 | ESM CDN |
|
||||
| umami.xiongxiao.me | umami-external | 4004 | 127.0.0.1 | 网站分析 |
|
||||
| pwd.xiongxiao.me | pwd-external | 8180 | 127.0.0.1 | 密码管理 |
|
||||
| meilisearch.xiongxiao.me | meilisearch-external | 7700 | 127.0.0.1 | 搜索引擎 |
|
||||
| memos.xiongxiao.me | memos-external | 8181 | 10.0.32.6 | Memos |
|
||||
| git.xiongxiao.me | gitea-external | 3000 | 10.0.32.6 | Gitea |
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 1. 确保 Traefik 已部署
|
||||
|
||||
```bash
|
||||
# 检查 Traefik 是否运行
|
||||
kubectl get pods -n traefik
|
||||
|
||||
# 如果未部署，先部署 Traefik
|
||||
kubectl apply -f k8s/xiongxiao.me/traefik/traefik-complete.yaml
|
||||
```
|
||||
|
||||
### 2. 部署外部服务配置
|
||||
|
||||
```bash
|
||||
# 应用外部服务配置
|
||||
kubectl apply -f k8s/xiongxiao.me/services/external-services.yaml
|
||||
|
||||
# 验证服务创建成功
|
||||
kubectl get svc -n default | grep external
|
||||
kubectl get endpoints -n default | grep external
|
||||
```
|
||||
|
||||
### 3. 部署 IngressRoute
|
||||
|
||||
```bash
|
||||
# 应用 IngressRoute 配置
|
||||
kubectl apply -f k8s/xiongxiao.me/ingress/apps-ingressroute.yaml
|
||||
|
||||
# 验证 IngressRoute 创建成功
|
||||
kubectl get ingressroute -n default
|
||||
```
|
||||
|
||||
### 4. 验证路由配置
|
||||
|
||||
```bash
|
||||
# 检查 Traefik Dashboard
|
||||
kubectl port-forward svc/traefik 8080:8080 -n traefik
|
||||
# 访问 http://localhost:8080/dashboard/
|
||||
|
||||
# 测试域名解析
|
||||
curl -k https://blinko.xiongxiao.me
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
### IP 地址说明
|
||||
|
||||
- `127.0.0.1` - 指向 Kubernetes 主节点本地运行的服务
|
||||
- `10.0.32.6` - 指向局域网中其他机器运行的服务
|
||||
|
||||
**重要**: 如果服务是在 Pod 外部运行的：
|
||||
- 本地服务需要确保端口可以从 Pod 内访问
|
||||
- 远程服务需要确保网络互通
|
||||
|
||||
### WebSocket 支持
|
||||
|
||||
Traefik 默认支持 WebSocket，以下服务需要 WebSocket：
|
||||
- chat.xiongxiao.me
|
||||
- kevisual.xiongxiao.me
|
||||
- www.xiongxiao.me
|
||||
- immich.xiongxiao.me
|
||||
- docmost.xiongxiao.me
|
||||
- drawio.xiongxiao.me
|
||||
- minio.xiongxiao.me
|
||||
- gist.xiongxiao.me
|
||||
- webdav.xiongxiao.me
|
||||
- esm.xiongxiao.me
|
||||
- umami.xiongxiao.me
|
||||
|
||||
### SSL 证书
|
||||
|
||||
- Traefik 自动使用 Let's Encrypt 申请证书
|
||||
- 证书存储在 `/data/traefik-acme/acme.json`
|
||||
- 自动续期，无需手动操作
|
||||
|
||||
### 大文件上传
|
||||
|
||||
部分服务配置了大文件上传支持（原 Nginx 的 `client_max_body_size`）：
|
||||
- blinko: 1024m
|
||||
- chat: 200m
|
||||
- kevisual: 200m
|
||||
- immich: 1024m
|
||||
- cloud: 1024m
|
||||
- docmost: 1024m
|
||||
- drawio: 1024m
|
||||
- minio: 200m
|
||||
- npm: 24m
|
||||
- gist: 1024m
|
||||
- webdav: 2024m
|
||||
- esm: 2048m
|
||||
- umami: 1024m
|
||||
- git: 2048m
|
||||
|
||||
如需在 Traefik 中配置，可添加 Middleware：
|
||||
|
||||
```yaml
|
||||
apiVersion: traefik.io/v1alpha1
|
||||
kind: Middleware
|
||||
metadata:
|
||||
name: large-upload
|
||||
namespace: default
|
||||
spec:
|
||||
buffering:
|
||||
maxRequestBodyBytes: 2147483648 # 2GB
|
||||
```
|
||||
|
||||
## 特殊配置
|
||||
|
||||
### look-good.xiongxiao.me (静态网站)
|
||||
|
||||
这是一个静态网站服务，需要单独处理：
|
||||
|
||||
**方案 1**: 将静态文件打包到 Pod 中运行 Nginx
|
||||
```bash
|
||||
# 创建 ConfigMap 或使用 PV 挂载静态文件
|
||||
# 运行 Nginx Pod
|
||||
```
|
||||
|
||||
**方案 2**: 继续使用原 Nginx 服务器，通过 Service 映射
|
||||
|
||||
### home.mz.xiongxiao.me
|
||||
|
||||
这个服务指向外部域名 `xionmi.mz.zxj.im:8123`，需要特殊处理。
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 服务无法访问
|
||||
|
||||
1. 检查 Service 和 Endpoints
|
||||
```bash
|
||||
kubectl get svc,endpoints -n default | grep <service-name>
|
||||
```
|
||||
|
||||
2. 检查 IngressRoute
|
||||
```bash
|
||||
kubectl describe ingressroute <name> -n default
|
||||
```
|
||||
|
||||
3. 检查 Traefik 日志
|
||||
```bash
|
||||
kubectl logs -n traefik -l app=traefik
|
||||
```
|
||||
|
||||
### SSL 证书问题
|
||||
|
||||
1. 检查证书文件
|
||||
```bash
|
||||
kubectl exec -n traefik <traefik-pod> -- cat /acme/acme.json
|
||||
```
|
||||
|
||||
2. 确认 Let's Encrypt 配置
|
||||
```bash
|
||||
kubectl describe deployment traefik -n traefik | grep acme
|
||||
```
|
||||
|
||||
## 回滚到 Nginx
|
||||
|
||||
如果需要回滚：
|
||||
|
||||
1. 在 DNS 中将域名指回原 Nginx 服务器
|
||||
2. 删除 K3s 配置：
|
||||
```bash
|
||||
kubectl delete -f k8s/xiongxiao.me/ingress/apps-ingressroute.yaml
|
||||
kubectl delete -f k8s/xiongxiao.me/services/external-services.yaml
|
||||
```
|
||||
|
||||
## 后续优化
|
||||
|
||||
1. **容器化服务**: 逐步将外部服务容器化并部署到 K3s
|
||||
2. **服务网格**: 考虑使用 Istio 或 Linkerd
|
||||
3. **监控告警**: 集成 Prometheus + Grafana
|
||||
4. **自动扩展**: 配置 HPA (Horizontal Pod Autoscaler)
|
||||
5. **日志聚合**: 使用 ELK 或 Loki 收集日志
|
||||
|
||||
## 参考资料
|
||||
|
||||
- [Traefik 官方文档](https://doc.traefik.io/traefik/)
|
||||
- [K3s 官方文档](https://docs.k3s.io/)
|
||||
- [Kubernetes Services 文档](https://kubernetes.io/docs/concepts/services-networking/service/)
|
||||
Reference in New Issue
Block a user