# K3s GitOps 自动部署指南

## 🎯 GitOps 工作流概述

本项目已配置完整的 GitOps 自动部署流程：**Git 提交 → 自动同步 → 集群部署**

## ✅ 已满足的实现条件

### 1. 基础设施 ✅
- **k3s 集群**: v1.34.3+k3s1 (单节点)
- **存储系统**: Longhorn 分布式存储
- **证书管理**: cert-manager + Let's Encrypt
- **Ingress**: Traefik

### 2. GitOps 工具链 ✅
- **ArgoCD**: 已部署并运行
  - 访问地址: https://argocd.u9.net3w.com
  - 用户名: `admin`
  - 初始密码: `R5ALO8NIRi4KoN8Q`

- **Gitea**: 已部署并运行
  - 访问地址: https://git.u9.net3w.com
  - 用于托管 k3s 配置文件

### 3. Git 仓库 ✅
- 本地仓库已初始化
- 所有 k3s 配置文件已提交

## 🚀 GitOps 自动部署流程

### 方式一：使用 Gitea（推荐）

#### 步骤 1: 在 Gitea 创建仓库
```bash
# 1. 访问 https://git.u9.net3w.com
# 2. 注册/登录账号
# 3. 创建新仓库: k3s-configs
# 4. 获取仓库 URL
```

#### 步骤 2: 推送代码到 Gitea
```bash
# 添加远程仓库
git remote add origin https://git.u9.net3w.com/你的用户名/k3s-configs.git

# 推送代码
git push -u origin master
```

#### 步骤 3: 配置 ArgoCD 连接 Gitea
```bash
# 1. 访问 https://argocd.u9.net3w.com
# 2. 登录 (admin / R5ALO8NIRi4KoN8Q)
# 3. Settings → Repositories → Connect Repo
#    - Repository URL: https://git.u9.net3w.com/你的用户名/k3s-configs.git
#    - Username: 你的 Gitea 用户名
#    - Password: 你的 Gitea 密码
```

#### 步骤 4: 创建 ArgoCD Application
```bash
# 修改 k3s/argocd-app.yaml 中的 repoURL
# 然后应用配置
kubectl apply -f k3s/argocd-app.yaml
```

### 方式二：使用 GitHub/GitLab

如果你想使用 GitHub 或 GitLab：

```bash
# 推送到 GitHub
git remote add origin https://github.com/你的用户名/k3s-configs.git
git push -u origin master

# 在 ArgoCD 中配置对应的仓库地址
```

## 📝 日常使用流程

### 1. 修改配置文件
```bash
# 例如：修改 WordPress 副本数
vim k3s/my-blog/02-wordpress.yaml
# 将 replicas: 2 改为 replicas: 3
```

### 2. 提交并推送
```bash
git add k3s/my-blog/02-wordpress.yaml
git commit -m "Scale WordPress to 3 replicas"
git push
```

### 3. 自动部署 🎉
- ArgoCD 会在 **3 分钟内**自动检测到变更
- 自动同步到 k3s 集群
- 可在 ArgoCD UI 查看部署状态

## 🔧 ArgoCD 配置说明

### 自动同步策略
```yaml
syncPolicy:
  automated:
    prune: true      # 自动删除 Git 中不存在的资源
    selfHeal: true   # 自动修复被手动修改的资源
```

### 手动同步
如果需要立即同步，可以：
1. 在 ArgoCD UI 点击 "Sync" 按钮
2. 或使用命令行：
```bash
# 安装 argocd CLI
curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
chmod +x /usr/local/bin/argocd

# 登录
argocd login argocd.u9.net3w.com --username admin --password R5ALO8NIRi4KoN8Q

# 手动同步
argocd app sync k3s-apps
```

## 📊 已部署的服务

| 服务 | 域名 | 配置文件路径 |
|------|------|-------------|
| WordPress | https://blog.u9.net3w.com | k3s/my-blog/ |
| Docker Registry | https://registry.u9.net3w.com | k3s/registry/ |
| n8n | https://n8n.u9.net3w.com | k3s/n8n/ |
| Gitea | https://git.u9.net3w.com | k3s/ztg_自托管/ |
| Uptime Kuma | https://status.u9.net3w.com | k3s/kuma-stack.yaml |
| 导航页 | https://nav.u9.net3w.com | k3s/nav/ |
| ArgoCD | https://argocd.u9.net3w.com | - |

## 🎯 最佳实践

### 1. 分支策略
```bash
# 创建开发分支
git checkout -b dev

# 在 dev 分支测试
git add .
git commit -m "Test new feature"
git push origin dev

# 测试通过后合并到 master
git checkout master
git merge dev
git push
```

### 2. 配置文件组织
```
k3s/
├── my-blog/          # WordPress 博客
├── registry/         # Docker 仓库
├── n8n/             # 工作流自动化
├── nav/             # 导航页
└── argocd-app.yaml  # ArgoCD 应用配置
```

### 3. 回滚操作
```bash
# 查看历史提交
git log --oneline

# 回滚到指定版本
git revert <commit-hash>
git push

# ArgoCD 会自动同步回滚
```

## 🔍 监控和调试

### 查看 ArgoCD 应用状态
```bash
kubectl get applications -n argocd
kubectl describe application k3s-apps -n argocd
```

### 查看同步日志
```bash
# 在 ArgoCD UI 中查看
# 或使用 CLI
argocd app logs k3s-apps
```

### 常见问题

#### 1. 同步失败
- 检查 Git 仓库是否可访问
- 检查 YAML 文件语法是否正确
- 查看 ArgoCD 日志

#### 2. 证书问题
```bash
# 如果 Gitea 使用自签名证书
kubectl patch configmap argocd-cm -n argocd --type merge -p '{"data":{"repositories":"- url: https://git.u9.net3w.com/user/repo\n  insecure: true"}}'
```

## 📚 下一步

1. **配置 Webhook**: 在 Gitea 中配置 Webhook，实现即时同步
2. **多环境部署**: 创建 dev/staging/prod 分支
3. **密钥管理**: 使用 Sealed Secrets 管理敏感信息
4. **监控告警**: 集成 Prometheus + Grafana

## 🎉 总结

现在你已经拥有完整的 GitOps 工作流：

```
修改 YAML → Git Commit → Git Push → ArgoCD 自动同步 → k3s 集群更新
```

所有配置变更都通过 Git 管理，实现了：
- ✅ 版本控制
- ✅ 自动部署
- ✅ 快速回滚
- ✅ 审计追踪