k3s_auto_deploy/README.md

# 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                # 部署日志（自动生成）
```

## 快速开始

### 方式一：一键部署（推荐）

使用统一部署脚本自动完成所有步骤：

```bash
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
```

**特性**:
- ✅ 自动检查所有前置条件
- ✅ 自动安装缺失的工具
- ✅ 按正确顺序执行所有步骤
- ✅ 失败后可断点续传
- ✅ 详细的进度显示和日志

**断点续传**:
如果部署中途失败，修复问题后直接重新运行即可从中断处继续：
```bash
./scripts/deploy-all.sh
```

**重置状态**:
如果需要从头开始部署：
```bash
./scripts/deploy-all.sh --reset
```

### 方式二：分步部署

如果需要更细粒度的控制，可以手动执行各个步骤：

#### 1. 克隆k3s-ansible项目
```bash
cd /home/fei/opk3s/k3s自动化部署
git clone https://github.com/k3s-io/k3s-ansible.git
```

#### 2. 设置脚本执行权限
```bash
chmod +x scripts/*.sh scripts/*.py
```

#### 3. 部署K3s集群
```bash
./scripts/deploy.sh
```

#### 4. 部署Gitea私有Git服务器
```bash
./scripts/deploy-gitea.sh
```

#### 5. 初始化Gitea
```bash
./scripts/setup-gitea.sh
```

#### 6. 部署ArgoCD
```bash
./scripts/deploy-argocd.sh
```

#### 7. 配置HTTPS证书
```bash
./scripts/deploy-https.sh
```

#### 8. 创建ArgoCD应用
```bash
./scripts/create-argocd-app.sh
```

#### 9. 推送示例应用
```bash
./scripts/push-demo-app.sh
```

### 验证部署

部署完成后，运行验证脚本检查所有服务：

```bash
./scripts/verify-deployment.sh
```

验证脚本会检查：
- K3s集群状态
- Gitea服务
- ArgoCD服务
- HTTPS证书
- GitOps工作流
- 存储卷状态

## 配置说明

### 节点配置（实际配置）

```yaml
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配置

```yaml
k3s_version: "v1.28.5+k3s1"
k3s_token: ""                      # 留空自动生成
flannel_iface: "eth0"
target_dir: "/home/fei/k3s"
```

### 域名配置

```yaml
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服务器）

```yaml
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配置

```yaml
argocd_admin_password: "ArgoAdmin@2026"
git_repo_url: "http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/demo-app.git"
```

## 验证部署

### 自动验证（推荐）

使用验证脚本自动检查所有服务：

```bash
./scripts/verify-deployment.sh
```

验证脚本会检查：
- ✅ K3s集群状态（节点、系统Pod）
- ✅ Gitea服务（部署、Pod、访问地址）
- ✅ ArgoCD服务（Server、Controller、Repo Server）
- ✅ HTTPS证书（cert-manager、ClusterIssuer、Certificate）
- ✅ GitOps工作流（ArgoCD Application状态）
- ✅ 存储卷状态（PV、PVC）

### 手动验证

#### 验证K3s集群

```bash
# 查看节点状态
kubectl get nodes

# 查看所有Pod
kubectl get pods -A

# 创建测试Pod
kubectl run test --image=nginx
```

### 验证Gitea

```bash
# 查看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

```bash
# 查看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

```bash
# 查看应用同步状态
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加密配置

```bash
# 加密配置文件
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. 限制文件权限

```bash
chmod 600 config/cluster-vars.yml
```

### 3. 不要提交敏感信息到Git

`.gitignore`已配置忽略敏感文件：
- `config/cluster-vars.yml`
- `config/*-vars.yml`
- `*.vault`

## 故障排查

### K3s部署失败

```bash
# 测试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无法访问

```bash
# 检查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无法访问

```bash
# 检查Pod状态
kubectl get pods -n argocd

# 查看日志
kubectl logs -n argocd deployment/argocd-server

# 检查Service
kubectl get svc -n argocd
```

### GitOps同步失败

```bash
# 查看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可重复应用
- ✅ 证书自动续期，无需手动干预

### 测试幂等性

重复执行部署脚本验证幂等性：

```bash
# 第一次部署
./scripts/deploy-all.sh

# 验证部署
./scripts/verify-deployment.sh

# 重复执行（应该跳过所有已完成步骤）
./scripts/deploy-all.sh

# 再次验证（状态应该不变）
./scripts/verify-deployment.sh
```

### 重装系统后的部署流程

1. **准备环境**:
   ```bash
   # 创建fei用户（如果不存在）
   sudo useradd -m -s /bin/bash fei
   sudo passwd fei

   # 配置sudo权限
   echo "fei ALL=(ALL) NOPASSWD:ALL" | sudo tee /etc/sudoers.d/fei
   ```

2. **复制配置文件**:
   ```bash
   # 备份配置文件
   cp config/cluster-vars.yml ~/cluster-vars.yml.backup

   # 重装系统后恢复
   cp ~/cluster-vars.yml.backup config/cluster-vars.yml
   ```

3. **一键部署**:
   ```bash
   ./scripts/deploy-all.sh
   ```

4. **验证部署**:
   ```bash
   ./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
```

## 后续优化

1. **配置Ingress**: 使用Traefik Ingress暴露服务
   - ArgoCD: argocd.jpc.net3w.com
   - Gitea: git.jpc.net3w.com
2. **HTTPS证书**: 集成cert-manager + Let's Encrypt自动管理证书
3. **RBAC配置**: 为不同团队配置Gitea和ArgoCD权限
4. **多环境管理**: 使用ArgoCD ApplicationSet管理dev/staging/prod
5. **监控告警**: 集成Prometheus和Grafana
6. **备份方案**:
   - K3s etcd自动备份
   - Gitea数据持久化和备份
7. **CI/CD集成**: 集成Gitea Actions或Jenkins
8. **镜像仓库**: 部署Harbor私有镜像仓库
9. **SSH密钥认证**: 替换密码认证提高安全性

## 参考资源

- [k3s-ansible项目](https://github.com/k3s-io/k3s-ansible)
- [ArgoCD文档](https://argo-cd.readthedocs.io/)
- [Gitea文档](https://docs.gitea.com/)
- [K3s官方文档](https://docs.k3s.io/)

## 许可证

本项目使用MIT许可证。