17 KiB
17 KiB
K3s集群自动化部署与GitOps方案（含Gitea私有Git服务）
概述
本项目提供完整的K3s集群自动化部署方案，集成Gitea私有Git服务器和ArgoCD实现完整的GitOps工作流。所有配置参数化，完全支持幂等部署，可在重装系统后无需手动调试即可自动化部署。
🎯 核心特性
- ✅ 完全幂等: 所有脚本可重复执行，不会破坏现有配置
- ✅ 一键部署: 使用
deploy-all.sh统一编排所有步骤 - ✅ 断点续传: 部署失败后可从中断处继续
- ✅ 自动重试: 网络失败自动重试，提高可靠性
- ✅ 工具检查: 自动检查和安装所有依赖工具
- ✅ 状态管理: 记录已完成步骤，避免重复执行
- ✅ 详细日志: 完整的部署日志便于问题排查
- ✅ 验证脚本: 自动验证部署状态和服务健康
实际环境信息
- 集群规模: 1 master + 2 worker节点
- 主节点: 8.216.38.248 (内网: 172.23.96.138) - *.jpc.net3w.com
- 从节点1: 8.216.41.97 (内网: 172.23.96.139) - *.jpc2.net3w.com
- 从节点2: 8.216.33.69 (内网: 172.23.96.140) - *.jpc3.net3w.com
- SSH用户: fei / 密码: 1
- 目标目录: /home/fei/k3s
特性
部署特性
- ✅ 基于k3s-ansible的幂等部署
- ✅ 统一部署脚本
deploy-all.sh编排所有步骤 - ✅ 自动检查和安装依赖工具（yq, htpasswd, helm等）
- ✅ 网络下载自动重试机制
- ✅ 部署状态持久化，支持断点续传
- ✅ 详细的日志记录和错误处理
功能特性
- ✅ 所有敏感信息变量化配置
- ✅ 一键部署K3s集群
- ✅ 自动部署Gitea私有Git服务器
- ✅ 自动创建Gitea组织、仓库和用户
- ✅ 自动安装和配置ArgoCD
- ✅ ArgoCD连接Gitea实现GitOps自动同步部署
- ✅ 自动配置HTTPS证书（cert-manager + Let's Encrypt）
- ✅ 部署验证脚本自动检查所有服务
认证方式
- ✅ 支持密码认证和SSH密钥认证
- ✅ 支持Ansible Vault加密
目录结构
.
├── config/
│ ├── cluster-vars.yml.example # 配置模板
│ └── cluster-vars.yml # 实际配置（已创建）
├── scripts/
│ ├── lib/
│ │ └── common.sh # 通用函数库（新增）
│ ├── deploy-all.sh # 统一部署脚本（新增）
│ ├── verify-deployment.sh # 部署验证脚本（新增）
│ ├── generate-inventory.py # 生成Ansible inventory（支持密码认证）
│ ├── deploy.sh # K3s部署脚本
│ ├── deploy-gitea.sh # Gitea部署脚本
│ ├── setup-gitea.sh # Gitea初始化脚本
│ ├── deploy-argocd.sh # ArgoCD部署脚本（已改进）
│ ├── deploy-https.sh # HTTPS证书配置脚本（新增）
│ ├── create-argocd-app.sh # 创建ArgoCD应用
│ └── push-demo-app.sh # 推送示例应用
├── templates/ # 模板文件
├── k3s-ansible/ # k3s-ansible项目（需克隆）
├── .deployment-state # 部署状态文件（自动生成）
└── deployment.log # 部署日志（自动生成）
快速开始
方式一：一键部署（推荐）
使用统一部署脚本自动完成所有步骤：
cd /home/fei/opk3s/k3s自动化部署
# 克隆k3s-ansible（首次需要）
git clone https://github.com/k3s-io/k3s-ansible.git
# 设置脚本执行权限
chmod +x scripts/*.sh scripts/*.py
# 一键部署所有组件
./scripts/deploy-all.sh
特性:
- ✅ 自动检查所有前置条件
- ✅ 自动安装缺失的工具
- ✅ 按正确顺序执行所有步骤
- ✅ 失败后可断点续传
- ✅ 详细的进度显示和日志
断点续传: 如果部署中途失败，修复问题后直接重新运行即可从中断处继续：
./scripts/deploy-all.sh
重置状态: 如果需要从头开始部署：
./scripts/deploy-all.sh --reset
方式二：分步部署
如果需要更细粒度的控制，可以手动执行各个步骤：
1. 克隆k3s-ansible项目
cd /home/fei/opk3s/k3s自动化部署
git clone https://github.com/k3s-io/k3s-ansible.git
2. 设置脚本执行权限
chmod +x scripts/*.sh scripts/*.py
3. 部署K3s集群
./scripts/deploy.sh
4. 部署Gitea私有Git服务器
./scripts/deploy-gitea.sh
5. 初始化Gitea
./scripts/setup-gitea.sh
6. 部署ArgoCD
./scripts/deploy-argocd.sh
7. 配置HTTPS证书
./scripts/deploy-https.sh
8. 创建ArgoCD应用
./scripts/create-argocd-app.sh
9. 推送示例应用
./scripts/push-demo-app.sh
验证部署
部署完成后，运行验证脚本检查所有服务：
./scripts/verify-deployment.sh
验证脚本会检查：
- K3s集群状态
- Gitea服务
- ArgoCD服务
- HTTPS证书
- GitOps工作流
- 存储卷状态
配置说明
节点配置（实际配置）
master_nodes:
- hostname: k3s-master-01
public_ip: "8.216.38.248"
private_ip: "172.23.96.138"
ssh_user: "fei"
ssh_password: "1" # 使用密码认证
worker_nodes:
- hostname: k3s-worker-01
public_ip: "8.216.41.97"
private_ip: "172.23.96.139"
ssh_user: "fei"
ssh_password: "1"
- hostname: k3s-worker-02
public_ip: "8.216.33.69"
private_ip: "172.23.96.140"
ssh_user: "fei"
ssh_password: "1"
K3s配置
k3s_version: "v1.28.5+k3s1"
k3s_token: "" # 留空自动生成
flannel_iface: "eth0"
target_dir: "/home/fei/k3s"
域名配置
domain_name: "jpc.net3w.com"
master_domain: "jpc1.net3w.com"
worker1_domain: "jpc2.net3w.com"
worker2_domain: "jpc3.net3w.com"
gitea_domain: "git.jpc.net3w.com"
argocd_domain: "argocd.jpc.net3w.com"
Gitea配置（私有Git服务器）
gitea_enabled: true
gitea_admin_user: "gitea_admin"
gitea_admin_password: "GitAdmin@2026"
gitea_org_name: "k3s-apps"
gitea_repo_name: "demo-app"
gitea_user_name: "argocd" # ArgoCD使用的用户
gitea_user_password: "ArgoCD@2026"
ArgoCD配置
argocd_admin_password: "ArgoAdmin@2026"
git_repo_url: "http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/demo-app.git"
验证部署
自动验证（推荐）
使用验证脚本自动检查所有服务：
./scripts/verify-deployment.sh
验证脚本会检查：
- ✅ K3s集群状态（节点、系统Pod）
- ✅ Gitea服务（部署、Pod、访问地址）
- ✅ ArgoCD服务（Server、Controller、Repo Server）
- ✅ HTTPS证书（cert-manager、ClusterIssuer、Certificate）
- ✅ GitOps工作流（ArgoCD Application状态）
- ✅ 存储卷状态（PV、PVC）
手动验证
验证K3s集群
# 查看节点状态
kubectl get nodes
# 查看所有Pod
kubectl get pods -A
# 创建测试Pod
kubectl run test --image=nginx
验证Gitea
# 查看Gitea Pod状态
kubectl get pods -n gitea
# 查看Gitea服务
kubectl get svc -n gitea
# 获取Gitea访问地址
GITEA_NODEPORT=$(kubectl get svc gitea-http -n gitea -o jsonpath='{.spec.ports[0].nodePort}')
echo "Gitea访问地址: http://8.216.38.248:$GITEA_NODEPORT"
验证ArgoCD
# 查看ArgoCD Pod状态
kubectl get pods -n argocd
# 查看ArgoCD服务
kubectl get svc -n argocd
# 获取ArgoCD访问地址
ARGOCD_NODEPORT=$(kubectl get svc argocd-server -n argocd -o jsonpath='{.spec.ports[0].nodePort}')
echo "ArgoCD访问地址: https://8.216.38.248:$ARGOCD_NODEPORT"
echo "用户名: admin"
echo "密码: ArgoAdmin@2026"
# 查看Application状态
kubectl get application -n argocd
验证GitOps
# 查看应用同步状态
kubectl describe application demo-app -n argocd
# 查看示例应用
kubectl get pods -n default
kubectl get svc demo-nginx -n default
# 访问示例应用
curl http://8.216.38.248:30080
# 测试自动同步：修改Gitea仓库内容，等待3分钟观察自动部署
安全建议
1. 使用Ansible Vault加密配置
# 加密配置文件
ansible-vault encrypt config/cluster-vars.yml
# 编辑加密文件
ansible-vault edit config/cluster-vars.yml
# 部署时使用加密文件
cd k3s-ansible
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml" --ask-vault-pass
2. 限制文件权限
chmod 600 config/cluster-vars.yml
3. 不要提交敏感信息到Git
.gitignore已配置忽略敏感文件：
config/cluster-vars.ymlconfig/*-vars.yml*.vault
故障排查
K3s部署失败
# 测试SSH连接
ansible all -i k3s-ansible/inventory/hosts.ini -m ping
# 查看详细日志
cd k3s-ansible
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml" -vvv
Gitea无法访问
# 检查Pod状态
kubectl get pods -n gitea
# 查看日志
kubectl logs -n gitea -l app.kubernetes.io/name=gitea
# 检查Service
kubectl get svc -n gitea
# 检查持久化存储
kubectl get pvc -n gitea
ArgoCD无法访问
# 检查Pod状态
kubectl get pods -n argocd
# 查看日志
kubectl logs -n argocd deployment/argocd-server
# 检查Service
kubectl get svc -n argocd
GitOps同步失败
# 查看Application详情
kubectl describe application demo-app -n argocd
# 查看ArgoCD控制器日志
kubectl logs -n argocd deployment/argocd-application-controller
# 测试ArgoCD到Gitea的连接
kubectl exec -n argocd deployment/argocd-server -- curl -v http://gitea-http.gitea.svc.cluster.local:3000
# 检查Gitea仓库凭证
kubectl get secret gitea-creds -n argocd -o yaml
幂等性保证
什么是幂等性？
幂等性意味着脚本可以重复执行多次，每次都会产生相同的结果，不会破坏现有配置或产生错误。
本项目的幂等性实现
1. 统一部署脚本 (deploy-all.sh)
- ✅ 状态持久化: 记录已完成的步骤到
.deployment-state文件 - ✅ 断点续传: 失败后重新运行会跳过已完成的步骤
- ✅ 重复执行安全: 已完成的步骤会被自动跳过
2. 工具依赖检查
- ✅ 自动检测: 检查工具是否已安装
- ✅ 自动安装: 缺失的工具自动安装
- ✅ 重试机制: 网络下载失败自动重试（最多3次）
3. K3s部署 (deploy.sh)
- ✅ 使用Ansible的幂等特性
- ✅ 重复执行不会重新安装已存在的组件
- ✅ kubectl配置自动检测和更新
4. Gitea部署 (deploy-gitea.sh)
- ✅ 使用Helm的幂等特性
- ✅ 命名空间已存在时自动跳过创建
- ✅ 重复执行会更新配置而不是重新安装
5. ArgoCD部署 (deploy-argocd.sh)
- ✅ 使用
kubectl apply声明式部署 - ✅ 自动检测htpasswd和yq工具
- ✅ 密码更新使用patch操作，安全幂等
6. HTTPS配置 (deploy-https.sh)
- ✅ cert-manager CRDs和组件使用
kubectl apply - ✅ ClusterIssuer和Ingress可重复应用
- ✅ 证书自动续期，无需手动干预
测试幂等性
重复执行部署脚本验证幂等性：
# 第一次部署
./scripts/deploy-all.sh
# 验证部署
./scripts/verify-deployment.sh
# 重复执行（应该跳过所有已完成步骤）
./scripts/deploy-all.sh
# 再次验证（状态应该不变）
./scripts/verify-deployment.sh
重装系统后的部署流程
-
准备环境:
# 创建fei用户（如果不存在） sudo useradd -m -s /bin/bash fei sudo passwd fei # 配置sudo权限 echo "fei ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/fei -
复制配置文件:
# 备份配置文件 cp config/cluster-vars.yml ~/cluster-vars.yml.backup # 重装系统后恢复 cp ~/cluster-vars.yml.backup config/cluster-vars.yml -
一键部署:
./scripts/deploy-all.sh -
验证部署:
./scripts/verify-deployment.sh
常见问题
Q: 部署失败后如何继续？
A: 直接重新运行 ./scripts/deploy-all.sh，脚本会自动跳过已完成的步骤。
Q: 如何从头开始部署？
A: 运行 ./scripts/deploy-all.sh --reset 清除状态后重新部署。
Q: 网络下载失败怎么办？ A: 脚本会自动重试3次，如果仍然失败，检查网络连接后重新运行。
Q: 如何查看部署日志？
A: 查看 deployment.log 文件获取详细日志。
部署架构
┌─────────────────────────────────────────────────────────────┐
│ K3s Cluster (3 nodes) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Master │ │ Worker 1 │ │ Worker 2 │ │
│ │ 8.216.38.248 │ │ 8.216.41.97 │ │ 8.216.33.69 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Gitea (Private Git Server) │ │
│ │ git.jpc.net3w.com (NodePort) │ │
│ │ - Organization: k3s-apps │ │
│ │ - Repository: demo-app │ │
│ │ - User: argocd (for ArgoCD access) │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ │
│ (Git Sync) │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ArgoCD (GitOps Engine) │ │
│ │ argocd.jpc.net3w.com (NodePort) │ │
│ │ - Monitors Gitea repository │ │
│ │ - Auto-sync on Git push │ │
│ │ - Deploys to K3s cluster │ │
│ └─────────────────────────────────────────────────────┘ │
│ ↓ │
│ (Auto Deploy) │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Application Workloads │ │
│ │ - demo-nginx (example app) │ │
│ │ - Managed by ArgoCD from Gitea │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Developer Workflow:
1. Developer pushes code to Gitea (git.jpc.net3w.com)
2. ArgoCD detects changes (polling every 3 minutes)
3. ArgoCD syncs and deploys to K3s cluster
4. Application updates automatically
后续优化
- 配置Ingress: 使用Traefik Ingress暴露服务
- ArgoCD: argocd.jpc.net3w.com
- Gitea: git.jpc.net3w.com
- HTTPS证书: 集成cert-manager + Let's Encrypt自动管理证书
- RBAC配置: 为不同团队配置Gitea和ArgoCD权限
- 多环境管理: 使用ArgoCD ApplicationSet管理dev/staging/prod
- 监控告警: 集成Prometheus和Grafana
- 备份方案:
- K3s etcd自动备份
- Gitea数据持久化和备份
- CI/CD集成: 集成Gitea Actions或Jenkins
- 镜像仓库: 部署Harbor私有镜像仓库
- SSH密钥认证: 替换密码认证提高安全性
参考资源
许可证
本项目使用MIT许可证。