# K3s + GitOps 使用指南

## 📊 当前部署状态总结

### ✅ 1. 幂等性配置已修复

所有配置文件已经修复，支持完全幂等性部署：

- ✅ **inventory/hosts.ini**: 使用正确的组名 `server` 和 `agent`
- ✅ **api_endpoint**: 配置为内网IP `172.23.96.138`
- ✅ **worker节点**: 使用内网IP连接master，配置正确的token
- ✅ **验证**: 最后一次Ansible运行显示 `changed=0`，配置稳定

**可以安全地重复运行部署脚本，不会出错！**

### ✅ 2. 测试项目已创建

已创建完整的测试应用 `test-app`，包含：

- **应用**: 2个nginx副本，带自定义HTML页面
- **Service**: NodePort 30081
- **Ingress**: 域名访问 `test.jpc.net3w.com`
- **Git仓库**: http://8.216.38.248:32158/k3s-apps/test-app
- **ArgoCD应用**: 自动同步部署

## 🌐 访问方式

### 1. NodePort访问（直接可用）
```bash
# 通过任意节点访问
curl http://8.216.38.248:30081
curl http://8.216.41.97:30081
curl http://8.216.33.69:30081
```

### 2. 域名访问（需要DNS配置）

**方式A: 配置本地hosts文件（测试用）**
```bash
# Linux/Mac
sudo echo "8.216.38.248 test.jpc.net3w.com" >> /etc/hosts

# Windows (管理员权限)
# 编辑 C:\Windows\System32\drivers\etc\hosts
# 添加: 8.216.38.248 test.jpc.net3w.com
```

**方式B: 配置DNS解析（生产用）**
在你的域名DNS管理面板添加A记录：
```
test.jpc.net3w.com  →  8.216.38.248
```

配置后访问：
```bash
curl http://test.jpc.net3w.com
# 或在浏览器打开: http://test.jpc.net3w.com
```

## 🔄 更新应用演示

### 方式1: 使用更新脚本（推荐）

在master节点上执行：
```bash
ssh fei@8.216.38.248
cd /home/fei/k3s/test-app

# 更新到v2.0（粉红色背景）
./update-app.sh v2.0

# 更新到v3.0（蓝色背景）
./update-app.sh v3.0

# 更新到v4.0（绿色背景）
./update-app.sh v4.0
```

### 方式2: 手动修改并提交

```bash
ssh fei@8.216.38.248
cd /home/fei/k3s/test-app

# 1. 修改配置
vim manifests/deployment.yaml
# 修改 ConfigMap 中的内容，比如版本号、颜色等

# 2. 提交到Git
git add .
git commit -m "Update to v2.0"
git push

# 3. 等待ArgoCD自动同步（3分钟内）
kubectl get application test-app -n argocd -w
```

### 查看更新状态

```bash
# 查看ArgoCD应用状态
kubectl get application test-app -n argocd

# 查看Pod状态
kubectl get pods -l app=test-app

# 查看实时日志
kubectl logs -f -l app=test-app

# 访问应用验证更新
curl http://8.216.38.248:30081 | grep Version
```

## 📦 将部署配置存入Git

### 1. 初始化Git仓库

```bash
cd /home/fei/opk3s/k3s自动化部署

# 初始化Git
git init -b main

# 添加文件
git add .gitignore
git add README-DEPLOYMENT.md
git add USAGE-GUIDE.md
git add config/cluster-vars.yml.example
git add scripts/
git add k3s-ansible/inventory/hosts.ini

# 提交
git commit -m "Initial commit: K3s deployment configuration"
```

### 2. 推送到远程仓库

**选项A: 推送到Gitea（内部）**
```bash
# 在Gitea创建仓库 k3s-deployment
# 然后推送
git remote add origin http://8.216.38.248:32158/k3s-apps/k3s-deployment.git
git push -u origin main
```

**选项B: 推送到GitHub/GitLab（外部）**
```bash
# 创建GitHub仓库后
git remote add origin https://github.com/YOUR_USERNAME/k3s-deployment.git
git push -u origin main
```

### 3. 下次更新配置

```bash
# 修改配置文 config/cluster-vars.yml

# 重新生成inventory
python3 scripts/generate-inventory.py

# 提交更改
git add k3s-ansible/inventory/hosts.ini
git commit -m "Update cluster configuration"
git push

# 重新部署（幂等操作）
cd k3s-ansible
ansible-playbook site.yml -i inventory/hosts.ini -e "@../config/cluster-vars.yml"
```

## 🚀 创建新的应用

### 1. 在Gitea创建新仓库

```bash
ssh fei@8.216.38.248
cd /home/fei/k3s

# 创建新应用目录
mkdir -p my-new-app/manifests

# 创建Kubernetes清单
cat > my-new-app/manifests/deployment.yaml << 'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-new-app
  namespace: default
spec:
  replicas: 2
  selector:
    matchLabels:
    app: my-new-app
  template:
    metadata:
      labels:
        app: my-new-app
    spec:
      containers:
      - name: app
        image: nginx:alpine
        ports:
        - containerPort: 80
EOF

# 创建Service
cat > my-new-app/manifests/service.yaml << 'EOF'
apiVersion: v1
kind: Service
metadata:
  name: my-new-app
  namespace: default
spec:
  type: NodePort
  selector:
    app: my-new-app
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30082
EOF

# 初始化Git并推送
cd my-new-app
git init -b main
git add .
git commit -m "Initial commit"

# 推送到Gitea（需要先在Gitea创建仓库）
git remote add origin http://argocd:ArgoCD%402026@localhost:32158/k3s-apps/my-new-app.git
git push -u origin main
```

### 2. 创建ArgoCD应用

```bash
kubectl apply -f - << 'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-new-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/my-new-app.git
    targetRevision: main
    path: manifests
  destination:
    server: https://kubernetes.default.svc
    namespace: default
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
EOF
```

## 📊 监控和管理

### ArgoCD Web UI
- **URL**: https://8.216.38.248:31875
- **用户名**: admin
- **密码**: ArgoAdmin@2026

功能：
- 查看所有应用的同步状态
- 手动触发同步
- 查看部署历史
- 回滚到之前的版本

### Gitea Web UI
- **URL**: http://8.216.38.248:32158
- **管理员**: gitea_admin / GitAdmin@2026
- **ArgoCD用户**: argocd / ArgoCD@2026

功能：
- 管理Git仓库
- 查看提交历史
- 创建新仓库
- 管理用户和权限

### 命令行管理

```bash
# 查看所有ArgoCD应用
kubectl get application -n argocd

# 查看应用详情
kubectl describe application test-app -n argocd

# 手动触发同步
kubectl patch application test-app -n --type merge -p '{"metadotations":{"argocd.argoproj.io/refresh":"hard"}}}'

# 查看所有Pod
kubectl get pods -A

# 查看特定应用的Pod
kubectl get pods -l app=test-app

# 查看Ingress
kubectl get ingress -A
```

## 🔧 故障排查

### 应用无法访问

1. **检查Pod状态**
```bash
kubectl get pods -l app=test-app
kubectl describe pod <pod-name>
kubectl logs <pod-name>
```

2. **检查Service**
```bash
kubectl get svc test-app
kubectl describe svc test-app
```

3. **检查Ingress**
```bash
kubectl get ingress test-app
kubectl describe ingress test-app
```

### ArgoCD同步失败

1. **查看应用状态**
```bash
kubectl get application test-app -n argocd
kubectl describe application test-app -n argocd
```

2. **查看ArgoCD日志**
```bash
kubectl logs -n argocd deployment/argocd-application-controller
kubectl logs -n argocd deployment/argocd-repo-server
```

3. **检查Git仓库连接**
```bash
# 在master节点测试
curl http://gitea-http.gitea.svc.cluster.local:3000/k3s-apps/test-app.git
```

### 域名无法访问

1. **检查DNS解析**
```bash
nslookup test.jpc.net3w.com
# 或
dig test.jpc.net3w.com
```

2. **检查Traefik Ingress Controller**
```bash
kubectl get pods -n kube-system -l app.kubernetes.io/name=traefik
kubectl logs -n kube-system -l app.kubernetes.io/name=traefik
```

3. **临时使用hosts文件**
```bash
# 添加到 /etc/hosts
8.216.38.248 test.jpc.net3w.com
```

## 📝 最佳实践

1. **使用Git管理所有配置**
   - 所有Kubernetes清单文件都应该在Git中
   - 使用分支管理不同环境（dev/staging/prod）

2. **定期备份**
   - 备份Gitea数据：`kubectl exec -n gitea <pod> -- tar czf /tmp/backup.tar.gz /data`
   - 备份ArgoCD配置：`kubectl get application -n argocd -o yaml > argocd-apps-backup.yaml`

3. **监控资源使用**
   ```bash
   kubectl top nodes
   kubectl top pods -A
   ```

4. **使用命名空间隔离应用**
   ```bash
   kubectl create namespace production
   kubectl create namespace staging
   ```

5. **配置资源限制**
   在Deployment中添加：
   ```yaml
   resources:
     requests:
       memory: "64Mi"
       cpu: "100m"
     limits:
       memory: "128Mi"
       cpu: "200m"
   ```

## 🎯 下一步

1. **配置HTTPS**
   - 安装cert-manager
   - 配置Let's Encrypt自动证书

2. **添加监控**
   - 部署Prometheus + Grafana
   - 配置告警规则

3. **配置CI/CD**
   - 集成Gitea Actions或Jenkins
   - 自动构建Docker镜像

4. **多环境管理**
   - 使用ArgoCD ApplicationSet
   - 管理dev/staging/prod环境

## 📞 获取帮助

- **ArgoCD文档**: https://argo-cd.readthedocs.io/
- **K3s文档**: https://docs.k3s.io/
- **Gitea文档**: https://docs.gitea.io/
- **Kubernetes文档**: https://kubernetes.io/docs/