# K3s集群迁移指导文档

本文档提供K3s集群完整迁移的详细步骤，包括备份、迁移和恢复全流程。

## 目录

1. [迁移概述](#迁移概述)
2. [迁移前准备](#迁移前准备)
3. [备份现有集群](#备份现有集群)
4. [准备新环境](#准备新环境)
5. [部署新集群](#部署新集群)
6. [恢复数据和应用](#恢复数据和应用)
7. [验证和测试](#验证和测试)
8. [切换流量](#切换流量)
9. [故障回滚](#故障回滚)
10. [清理旧集群](#清理旧集群)

---

## 迁移概述

### 迁移场景

- **云服务商迁移**: 从一个云平台迁移到另一个云平台
- **区域迁移**: 在同一云平台的不同区域间迁移
- **硬件升级**: 迁移到更高配置的服务器
- **架构调整**: 改变集群节点数量或配置
- **灾难恢复**: 从备份恢复整个集群

### 迁移策略

**蓝绿部署（推荐）**:
- 保持旧集群运行
- 部署新集群并验证
- 切换流量到新集群
- 验证后清理旧集群

**优点**: 风险低，可快速回滚
**缺点**: 需要双倍资源

---

## 迁移前准备

### 1. 评估现有集群

```bash
# 记录集群信息
kubectl get nodes -o wide > cluster-info.txt
kubectl version >> cluster-info.txt

# 记录所有命名空间
kubectl get namespaces -o yaml > namespaces-backup.yaml

# 记录所有资源
kubectl get all --all-namespaces -o wide > all-resources.txt

# 记录持久化存储
kubectl get pv,pvc --all-namespaces -o yaml > storage-backup.yaml

# 记录ConfigMaps和Secrets
kubectl get configmaps,secrets --all-namespaces -o yaml > configs-secrets-backup.yaml
```

### 2. 创建迁移清单

创建迁移检查清单，确保不遗漏任何步骤。

### 3. 准备迁移工具

```bash
# 安装必要工具
sudo apt-get update
sudo apt-get install -y rsync tar gzip

# 安装velero（Kubernetes备份工具）
wget https://github.com/vmware-tanzu/velero/releases/download/v1.12.0/velero-v1.12.0-linux-amd64.tar.gz
tar -xvf velero-v1.12.0-linux-amd64.tar.gz
sudo mv velero-v1.12.0-linux-amd64/velero /usr/local/bin/
```

---

## 备份现有集群

### 1. 备份etcd数据

```bash
# 在master节点执行
sudo mkdir -p /backup/etcd

# 备份etcd数据
sudo k3s etcd-snapshot save --name migration-backup

# 查找备份文件
sudo ls -lh /var/lib/rancher/k3s/server/db/snapshots/

# 复制备份到安全位置
sudo cp /var/lib/rancher/k3s/server/db/snapshots/migration-backup* /backup/etcd/

# 下载到本地
scp fei@8.216.38.248:/backup/etcd/migration-backup* ./backups/
```

### 2. 备份Kubernetes资源

```bash
# 创建备份目录
mkdir -p backups/k8s-resources
cd backups/k8s-resources

# 备份所有命名空间的资源
for ns in $(kubectl get ns -o jsonpath='{.items[*].metadata.name}'); do
  echo "Backing up namespace: $ns"
  mkdir -p $ns

  # 备份各类资源
  kubectl get deployments -n $ns -o yaml > $ns/deployments.yaml
  kubectl get services -n $ns -o yaml > $ns/services.yaml
  kubectl get ingress -n $ns -o yaml > $ns/ingress.yaml
  kubectl get configmaps -n $ns -o yaml > $ns/configmaps.yaml
  kubectl get secrets -n $ns -o yaml > $ns/secrets.yaml
  kubectl get pvc -n $ns -o yaml > $ns/pvc.yaml
done

# 备份CRDs和全局资源
kubectl get crd -o yaml > crds.yaml
kubectl get pv -o yaml > persistent-volumes.yaml
kubectl get storageclass -o yaml > storageclasses.yaml

# 打包备份
cd ..
tar -czf k8s-resources-$(date +%Y%m%d-%H%M%S).tar.gz k8s-resources/
```

### 3. 备份Gitea数据

```bash
# 备份Gitea PostgreSQL数据库
kubectl exec -n gitea gitea-postgresql-ha-postgresql-0 -- \
  pg_dump -U postgres gitea > backups/gitea-db-backup.sql

# 备份Gitea数据目录
ssh fei@8.216.38.248 "sudo tar -czf /backup/gitea-data.tar.gz /var/lib/rancher/k3s/storage/gitea-data"
scp fei@8.216.38.248:/backup/gitea-data.tar.gz ./backups/
```

### 4. 备份ArgoCD数据

```bash
# 备份ArgoCD配置
kubectl get configmaps -n argocd -o yaml > backups/argocd-configmaps.yaml
kubectl get secrets -n argocd -o yaml > backups/argocd-secrets.yaml

# 备份ArgoCD Applications
kubectl get applications -n argocd -o yaml > backups/argocd-applications.yaml
```

### 5. 备份配置文件

```bash
# 备份部署脚本和配置
cd /home/fei/opk3s/k3s自动化部署
tar -czf ~/backups/deployment-scripts-$(date +%Y%m%d).tar.gz \
  config/ scripts/ *.md *.sh

# 备份K3s配置
ssh fei@8.216.38.248 "sudo tar -czf /backup/k3s-config.tar.gz \
  /etc/rancher/k3s/ \
  /var/lib/rancher/k3s/server/manifests/"

scp fei@8.216.38.248:/backup/k3s-config.tar.gz ./backups/
```

---

## 准备新环境

### 1. 准备新服务器

**服务器要求**:
- 操作系统: Debian 12 / Ubuntu 22.04
- CPU: 2核以上（推荐4核）
- 内存: 4GB以上（推荐8GB）
- 磁盘: 50GB以上
- 网络: 公网IP，开放必要端口

**端口要求**:
- 6443: Kubernetes API
- 80: HTTP
- 443: HTTPS
- 10250: Kubelet
- 2379-2380: etcd（仅master节点间）

### 2. 配置服务器

```bash
# 在所有新节点上执行

# 更新系统
sudo apt-get update && sudo apt-get upgrade -y

# 设置主机名
sudo hostnamectl set-hostname k3s-master-new-01

# 配置hosts
sudo tee -a /etc/hosts <<EOF
<NEW_MASTER_IP> k3s-master-new-01
<NEW_WORKER1_IP> k3s-worker-new-01
<NEW_WORKER2_IP> k3s-worker-new-02
EOF

# 禁用swap
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

# 配置防火墙
sudo ufw allow 6443/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 10250/tcp
sudo ufw enable
```

### 3. 准备域名和DNS

```bash
# 更新DNS记录（在域名服务商控制台）
# 方式1: 先添加新记录，保留旧记录
new-cluster.jpc.net3w.com  A  <NEW_MASTER_IP>

# 方式2: 准备好，切换时修改
# git.jpc.net3w.com  A  <NEW_MASTER_IP>
# argocd.jpc.net3w.com  A  <NEW_MASTER_IP>
```

---

## 部署新集群

### 1. 上传部署脚本

```bash
# 解压备份的部署脚本
tar -xzf backups/deployment-scripts-*.tar.gz -C /tmp/

# 上传到新master节点
scp -r /tmp/k3s自动化部署 fei@<NEW_MASTER_IP>:/home/fei/

# SSH到新master节点
ssh fei@<NEW_MASTER_IP>
cd /home/fei/k3s自动化部署
```

### 2. 修改配置文件

```bash
# 编辑配置文件
vi config/cluster-vars.yml

# 更新以下内容:
# - master_nodes: 新master节点IP
# - worker_nodes: 新worker节点IP列表
# - 域名配置（如果更改）
```

### 3. 部署K3s集群

```bash
# 使用自动化脚本部署
./scripts/deploy-all.sh

# 或分步部署
# 1. 生成inventory
python3 scripts/generate-inventory.py

# 2. 部署K3s
cd k3s-ansible
ansible-playbook playbooks/site.yml -i inventory.yml

# 3. 配置kubectl
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

# 验证集群
kubectl get nodes -o wide
```

### 4. 部署基础组件

```bash
# 部署Gitea
./scripts/deploy-gitea.sh

# 部署ArgoCD
./scripts/deploy-argocd.sh

# 部署HTTPS支持
./scripts/deploy-https.sh

# 验证所有组件
kubectl get pods --all-namespaces
```

---

## 恢复数据和应用

### 1. 恢复Gitea数据

```bash
# 上传数据库备份
scp backups/gitea-db-backup.sql fei@<NEW_MASTER_IP>:/tmp/

# 恢复数据库
kubectl cp /tmp/gitea-db-backup.sql gitea/gitea-postgresql-ha-postgresql-0:/tmp/
kubectl exec -n gitea gitea-postgresql-ha-postgresql-0 -- \
  psql -U postgres gitea < /tmp/gitea-db-backup.sql

# 重启Gitea
kubectl rollout restart deployment/gitea -n gitea
```

### 2. 恢复ArgoCD配置

```bash
# 恢复ArgoCD Secrets
kubectl apply -f backups/argocd-secrets.yaml

# 恢复ArgoCD Applications
kubectl apply -f backups/argocd-applications.yaml

# 验证
kubectl get applications -n argocd
```

### 3. 恢复应用

**方式1: 通过ArgoCD自动同步**

```bash
# 如果Git仓库已恢复，ArgoCD会自动同步应用
kubectl get applications -n argocd

# 手动触发同步
kubectl patch application <app-name> -n argocd \
  --type merge \
  -p '{"operation":{"initiatedBy":{"username":"admin"},"sync":{"revision":"HEAD"}}}'
```

**方式2: 手动恢复资源**

```bash
# 解压资源备份
tar -xzf backups/k8s-resources-*.tar.gz

# 恢复各命名空间资源
kubectl apply -f k8s-resources/default/
kubectl apply -f k8s-resources/gitea/
kubectl apply -f k8s-resources/argocd/
```

---

## 验证和测试

### 1. 验证集群状态

```bash
# 检查节点状态
kubectl get nodes -o wide

# 检查所有Pod
kubectl get pods --all-namespaces

# 检查资源使用
kubectl top nodes
kubectl top pods --all-namespaces
```

### 2. 验证网络连通性

```bash
# 测试Service访问
kubectl run test-pod --rm -it --image=curlimages/curl -- \
  curl http://<service-name>.<namespace>.svc.cluster.local

# 测试外部访问
curl http://<domain>
curl https://<domain>
```

### 3. 验证应用功能

```bash
# 测试Gitea
curl http://git.jpc.net3w.com

# 测试ArgoCD
curl https://argocd.jpc.net3w.com

# 测试应用
curl http://ng.jpc.net3w.com
curl http://test.jpc.net3w.com
```

### 4. 性能测试

```bash
# 压力测试
kubectl run load-test --rm -it --image=williamyeh/hey -- \
  -z 30s -c 10 http://<app-url>

# 监控资源使用
watch kubectl top pods --all-namespaces
```

---

## 切换流量

### 1. 准备切换

```bash
# 降低DNS TTL（提前24小时）
# 在域名服务商控制台将TTL设置为300秒（5分钟）

# 准备回滚方案
# 记录旧集群IP，准备快速回滚
```

### 2. 灰度切换（推荐）

```bash
# 使用权重DNS或负载均衡器
# 逐步增加新集群流量比例
# 30% -> 50% -> 70% -> 100%

# 监控新集群
watch kubectl top pods --all-namespaces
```

### 3. 完全切换

```bash
# 更新DNS记录
# 在域名服务商控制台修改A记录：
# git.jpc.net3w.com       A  <NEW_MASTER_IP>
# argocd.jpc.net3w.com    A  <NEW_MASTER_IP>
# *.jpc.net3w.com         A  <NEW_MASTER_IP>

# 验证DNS生效
nslookup git.jpc.net3w.com
dig git.jpc.net3w.com

# 等待DNS传播（5-30分钟）
```

### 4. 切换后监控

```bash
# 监控应用状态
watch kubectl get pods --all-namespaces

# 监控日志
kubectl logs -n <namespace> -l app=<app-name> -f

# 检查错误
kubectl get events --all-namespaces --sort-by='.lastTimestamp'
```

---

## 故障回滚

### 1. 快速回滚DNS

```bash
# 如果新集群出现问题，立即回滚DNS
# 在域名服务商控制台修改A记录回旧IP

# 清除本地DNS缓存
sudo systemd-resolve --flush-caches

# 验证回滚
nslookup git.jpc.net3w.com
```

### 2. 回滚应用

```bash
# 在旧集群重新启动应用
kubectl rollout restart deployment/<app-name> -n <namespace>

# 或在新集群回滚到旧版本
kubectl rollout undo deployment/<app-name> -n <namespace>
```

---

## 清理旧集群

### 1. 确认新集群稳定

```bash
# 运行至少7天，确保：
# - 所有功能正常
# - 性能满足要求
# - 没有数据丢失
# - 用户反馈良好
```

### 2. 最后备份旧集群

```bash
# 再次备份旧集群（以防万一）
ssh fei@<OLD_MASTER_IP>
sudo k3s etcd-snapshot save --name final-backup
sudo cp /var/lib/rancher/k3s/server/db/snapshots/final-backup* /backup/
```

### 3. 停止旧集群服务

```bash
# 在旧集群所有节点执行

# 停止K3s服务
sudo systemctl stop k3s
sudo systemctl stop k3s-agent

# 禁用自动启动
sudo systemctl disable k3s
sudo systemctl disable k3s-agent
```

### 4. 清理旧集群数据

```bash
# 在旧集群所有节点执行

# 卸载K3s
/usr/local/bin/k3s-uninstall.sh  # master节点
/usr/local/bin/k3s-agent-uninstall.sh  # worker节点

# 清理残留数据
sudo rm -rf /var/lib/rancher/k3s
sudo rm -rf /etc/rancher/k3s
```

---

## 迁移检查清单

### 迁移前
- [ ] 完整备份已创建
- [ ] 备份已验证可用
- [ ] 新环境已准备
- [ ] 迁移计划已制定
- [ ] 回滚方案已准备

### 迁移中
- [ ] 新集群已部署
- [ ] 基础组件已安装
- [ ] 数据已恢复
- [ ] 应用已部署
- [ ] 功能已验证

### 迁移后
- [ ] DNS已切换
- [ ] 流量已迁移
- [ ] 监控已配置
- [ ] 文档已更新

### 清理阶段
- [ ] 新集群运行稳定（7天+）
- [ ] 旧集群已最终备份
- [ ] 旧集群已停止
- [ ] 旧数据已清理

---

## 最佳实践

### 1. 迁移时机
- 选择业务低峰期
- 避开节假日
- 预留充足时间

### 2. 风险控制
- 保持旧集群运行
- 使用灰度切换
- 准备快速回滚
- 实时监控告警

### 3. 数据安全
- 多重备份
- 异地存储
- 加密传输
- 验证完整性

---

## 常见问题

### Q1: 迁移需要多长时间？

**A**: 取决于集群规模和数据量：
- 小型集群（<10个应用）: 4-8小时
- 中型集群（10-50个应用）: 1-2天
- 大型集群（>50个应用）: 3-7天

### Q2: 迁移期间服务会中断吗？

**A**: 使用蓝绿部署策略，可以实现零停机迁移。DNS切换时可能有短暂的缓存延迟（5-30分钟）。

### Q3: 如何处理有状态应用？

**A**: 有状态应用需要特别注意：
- 提前停止写入，确保数据一致性
- 使用数据库复制或备份恢复
- 验证数据完整性后再切换

### Q4: 如何验证迁移成功？

**A**: 多维度验证：
- 功能测试：所有功能正常工作
- 性能测试：响应时间和吞吐量符合预期
- 数据验证：数据完整且一致
- 监控指标：CPU、内存、网络正常

### Q5: 迁移失败如何回滚？

**A**: 快速回滚步骤：
1. 立即切换DNS回旧集群
2. 清除DNS缓存
3. 验证旧集群服务正常
4. 分析失败原因
5. 修复问题后重新迁移

---

## 相关文档

- [K3s部署指南](./DEPLOYMENT-GUIDE.md)
- [手动部署指南](./MANUAL-DEPLOYMENT-GUIDE.md)
- [故障排查指南](./TROUBLESHOOTING-ACCESS.md)
- [K3s官方文档](https://docs.k3s.io/)

---

**最后更新**: 2026-02-04
**文档版本**: 1.0