gao/ljwx-stock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 添加 CICD 实现总结文档

Browse Source 
完整记录了 CICD 系统的：
- 架构和工作流程
- 创建的所有文件清单
- 关键技术解决方案
- 快速启动步骤
- 故障排除速查表
- 后续优化方向

🤖 Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
bruno
2025-11-13 11:59:03 +08:00
co-authored by Claude
parent e135a6396f
commit 8af5fd1385
1 changed files with 482 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CICD_IMPLEMENTATION_SUMMARY.md
+482
View File
@@ -0,0 +1,482 @@
# Claude Stock CICD 完整实现总结
## 📋 项目概述
已成功为 Claude Stock 项目实现完整的 CICD 流程，涵盖以下组件：
- **Gitea** - Git 代码托管和 CI/CD 引擎
- **Gitea Actions Runners** - 两个专用运行器（Docker + Kubernetes）
- **Harbor** - Docker 镜像仓库
- **Kubernetes** - 容器编排平台
- **Ollama** - 本地 LLM 推理引擎
---
## 🏗️ 架构和工作流
```
代码提交 (Gitea)
↓
[Gitea Actions]
↓
┌─────────────────────────────────┐
│ 1. 并行构建镜像 │
│ - Backend (FastAPI) │
│ - Frontend (Vue 3) │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 2. 并行运行测试 │
│ - 单元测试 │
│ - 集成测试 │
│ - 安全扫描 (Trivy) │
│ - 代码覆盖率 │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 3. 推送到 Harbor 镜像仓库 │
│ localhost:8443 │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 4. 部署到 Kubernetes │
│ - claude-stock namespace │
│ - 滚动更新 │
│ - 健康检查 │
│ - Ollama 连接 │
└─────────────────────────────────┘
↓
┌─────────────────────────────────┐
│ 5. 部署后验证 │
│ - Smoke 测试 │
│ - API 可用性验证 │
│ - Ollama 连接验证 │
└─────────────────────────────────┘
↓
部署完成 ✅
```
---
## 📁 创建的文件和目录
### 1. Gitea Actions 工作流
```
.gitea/workflows/
├── cicd.yml # 完整 CICD 工作流（构建、测试、推送、部署）
└── test.yml # 快速测试工作流（适合 PR 验证）
```
**cicd.yml 工作流包含的任务：**
- `build-and-push`: 构建镜像并推送到 Harbor（并行）
- `test`: 运行单元测试和覆盖率分析
- `security-scan`: Trivy 镜像安全扫描
- `deploy`: 部署到 Kubernetes（仅 main 分支）
- `smoke-test`: 部署后验证
- `notify`: 生成部署报告
### 2. Kubernetes 部署清单
```
k8s/
├── namespace.yaml # Namespace 定义
├── configmap.yaml # 应用配置（包括 Ollama 配置）
├── deployment.yaml # 前后端部署（含 Node IP 获取）
├── service.yaml # 服务、RBAC、网络策略
├── ollama-bridge.yaml # Ollama 连接的 4 种方案
└── secrets.sh # 自动创建 K8s Secrets
```
**关键特性：**
- 使用 `status.hostIP` 自动获取宿主 IP
- Pod 通过 Node IP 连接到宿主 Ollama
- 滚动更新策略（零停机部署）
- 水平自动扩展（HPA：2-5 个副本）
- 资源配额和网络策略
- 完整的 RBAC 配置
### 3. 部署脚本和工具
```
项目根目录/
├── deploy-to-k8s.sh # 一键 K8s 部署脚本
├── verify-cicd.sh # 环境验证脚本（10 个检查点）
├── CICD_DEPLOYMENT_GUIDE.md # 详细部署指南（中文）
├── QUICK_START.md # 5 分钟快速启动指南
└── CICD_IMPLEMENTATION_SUMMARY.md # 本文件
```
### 4. Gitea Runner 配置
```
~/work/codes/tools/macos/gitea/
├── docker-compose.yml # 更新：添加两个 runners
├── runner-k8s-config.yaml # K8s runner 专用配置
└── setup-runners.sh # 自动配置脚本
```
---
## 🚀 快速启动步骤
### 第 1 步：验证环境
```bash
cd /Users/brunogao/work/codes/stock/claude-stock
bash verify-cicd.sh
```
**检查项目：**
- Gitea 服务状态
- Gitea Runners 运行状态
- Harbor 镜像仓库访问
- Kubernetes 集群可用性
- Ollama 服务和模型加载
- Docker 可用性
- 文件完整性
- 网络连接
### 第 2 步：启动 Runners
```bash
cd ~/work/codes/tools/macos/gitea
# 启动 Gitea（如果还没启动）
docker-compose up -d gitea
# 启动两个 Runners
docker-compose up -d runner-docker runner-k8s
# 验证状态
docker-compose ps
```
### 第 3 步：创建 Secrets
在 Gitea 中创建以下 Repository Secrets：
```
HARBOR_PASSWORD → Harbor 管理员密码
KUBECONFIG → K8s 配置文件（base64）
OPENROUTER_API_KEY → Claude API Key
TUSHARE_TOKEN → TuShare Token
ALPHA_VANTAGE_API_KEY → Alpha Vantage Key
```
### 第 4 步：部署到 K8s
```bash
cd /Users/brunogao/work/codes/stock/claude-stock
# 自动部署（会自动创建 namespace、secrets、部署应用）
export HARBOR_PASSWORD="Harbor12345"
bash deploy-to-k8s.sh
```
### 第 5 步：触发 CICD
```bash
# 提交代码（会自动触发 CICD）
git add .
git commit -m "feat: 完整 CICD 部署"
git push origin main
# 在 Gitea UI 查看工作流进度
# http://192.168.1.83:33000/<user>/claude-stock/actions
```
---
## 🔑 关键技术解决方案
### 1. K8s 与宿主 Ollama 通信
**问题：** Pod 无法直接访问 `localhost:11434`
**解决方案：** 使用 Kubernetes Node IP
```yaml
# deployment.yaml 中的关键配置
env:
- name: NODE_IP
valueFrom:
fieldRef:
fieldPath: status.hostIP
- name: OLLAMA_BASE_URL
value: "http://$(NODE_IP):11434"
```
**工作原理：**
1. Pod 从 Kubernetes API 自动获取宿主节点 IP
2. 使用 Node IP 代替 localhost 连接到 Ollama
3. 宿主 Ollama 需要监听 `0.0.0.0:11434`
**包含的备选方案：** （见 ollama-bridge.yaml）
- ExternalName Service
- Endpoint + Service
- DaemonSet 代理
- 直接修改 Ollama 监听地址
### 2. Harbor 镜像仓库集成
**认证流程：**
1. CICD 工作流使用 Harbor 凭证登录
2. 构建镜像：`localhost:8443/claude-stock/backend:latest`
3. 推送镜像到 Harbor
4. K8s 使用 Secret 拉取镜像
**关键配置：**
- Docker daemon.json: 配置 insecure registry
- CICD 工作流中的 Harbor 登录步骤
- K8s 中的 `harbor-secret` 镜像拉取凭证
### 3. Gitea Actions Runners
**两个 Runners 的分工：**
| Runner | 用途 | 镜像 | 卷挂载 |
|--------|------|------|--------|
| runner-docker | 构建、测试、推送 | Docker | `/var/run/docker.sock` |
| runner-k8s | K8s 部署、验证 | Docker | `/var/run/docker.sock` + `~/.kube/config` |
**注册流程：**
1. 获取 Runner Token（Gitea Admin 生成）
2. 启动 Runners 容器
3. Runners 自动向 Gitea 注册
4. 查看 Gitea UI 确认注册
### 4. Kubernetes 部署策略
**部署特性：**
- **滚动更新：** 最大化可用副本，实现零停机部署
- **副本数：** 2 个基础副本，自动扩展到 5 个
- **健康检查：** Liveness + Readiness 探针
- **资源限制：** CPU/Memory requests 和 limits
- **Pod 反亲和：** 分散在不同节点上
- **RBAC：** 最小权限原则
- **网络策略：** 限制入站和出站流量
---
## 📊 工作流触发条件
### 自动触发
```
git push origin main → 完整 CICD（包括部署）
git push origin develop → 仅运行测试和扫描
创建 Pull Request → 仅运行测试和扫描
```
### 忽略条件
```
- *.md 文件变更
- docs/ 目录变更
- .gitignore 更新
```
### 仅在 main 分支执行
```
- 部署到 Kubernetes
- 部署后验证（Smoke Test）
```
---
## 🔐 Secrets 管理
### Gitea Repository Secrets
| Secret | 用途 | 示例 |
|--------|------|------|
| HARBOR_PASSWORD | Harbor 登录 | `Harbor12345` |
| KUBECONFIG | K8s 访问 | `$(cat ~/.kube/config \| base64)` |
| OPENROUTER_API_KEY | Claude API | `sk-or-v1-xxxxx` |
| TUSHARE_TOKEN | TuShare 数据 | `xxxxxxxxxxxxxxxx` |
| ALPHA_VANTAGE_API_KEY | 股票数据 | `FFJVQK6LCQ5RSPNH` |
### Kubernetes Secrets
由 `k8s/secrets.sh` 自动创建：
```bash
- harbor-secret # 镜像拉取
- claude-stock-secrets # 应用凭证
- db-credentials # 数据库凭证
- redis-credentials # Redis 凭证
```
---
## 🐛 故障排除速查表
| 问题 | 症状 | 解决方案 |
|------|------|--------|
| Runners 无法注册 | 容器不断重启 | 检查 Gitea 健康、Token 有效性、网络 |
| Ollama 连接失败 | Backend Pod 启动失败 | 确保宿主 Ollama 监听 0.0.0.0:11434 |
| Harbor 推送失败 | `x509: certificate signed by unknown authority` | 配置 Docker insecure registry |
| K8s 部署超时 | kubectl rollout status 超时 | 检查镜像拉取、Pod 日志、资源不足 |
| 测试失败 | CICD 工作流停止 | 查看测试日志、检查依赖、数据库连接 |
详见：[CICD_DEPLOYMENT_GUIDE.md](CICD_DEPLOYMENT_GUIDE.md) 的故障排除部分
---
## 📈 后续优化方向
### 短期（1-2 周）
1. **监控和告警**
- 集成 Prometheus 监控
- 设置告警规则
- Grafana 仪表板
2. **日志管理**
- 集中化日志收集（ELK Stack）
- 结构化日志输出
- 日志搜索和分析
3. **性能优化**
- 镜像缓存优化
- 构建并行度提升
- 测试执行时间优化
### 中期（1-3 个月）
1. **GitOps**
- 集成 ArgoCD 或 Flux
- 配置驱动部署
- 自动同步
2. **高可用性**
- 跨节点部署
- PVC 持久化存储
- 备份和恢复策略
3. **安全加强**
- 镜像签名验证
- OPA Policy as Code
- RBAC 精细化控制
### 长期（3-6 个月）
1. **多环境部署**
- Staging 环境
- Production 环境
- 金丝雀部署
2. **成本优化**
- 资源自动优化
- 闲置资源回收
- 成本预算告警
3. **开发者体验**
- 本地开发环境快速启动
- 一键式调试
- IDE 集成
---
## 📚 文档导航
| 文件 | 内容 | 适用场景 |
|------|------|---------|
| **QUICK_START.md** | 5 分钟快速启动 | 首次部署 |
| **CICD_DEPLOYMENT_GUIDE.md** | 详细部署指南 | 深入学习和故障排除 |
| **.gitea/workflows/cicd.yml** | 完整 CICD 定义 | 自定义工作流 |
| **k8s/deployment.yaml** | K8s 部署清单 | 理解部署配置 |
---
## 🎯 验证检查清单
在启动 CICD 之前，确保完成以下检查：
- [ ] Gitea 正常运行（http://192.168.1.83:33000）
- [ ] Harbor 正常运行（https://localhost:8443）
- [ ] Kubernetes 集群可用（`kubectl cluster-info`）
- [ ] Ollama 服务运行（`curl http://localhost:11434/api/tags`）
- [ ] Docker 可访问（`docker ps`）
- [ ] Runners 已启动（`docker-compose ps`）
- [ ] Gitea Secrets 已配置（5 个 secrets）
- [ ] K8s namespace 已创建
- [ ] 代码已提交到 Gitea
- [ ] `.gitea/workflows/` 目录存在
- [ ] `k8s/` 目录存在
---
## 🔗 相关资源链接
### 本项目资源
- **Gitea**: http://192.168.1.83:33000
- **Harbor**: https://localhost:8443
- **Ollama**: http://localhost:11434
### 官方文档
- [Gitea Actions](https://docs.gitea.io/en-us/actions/)
- [Kubernetes 官方文档](https://kubernetes.io/docs/)
- [Harbor 官方文档](https://goharbor.io/docs/)
- [Ollama 官方文档](https://github.com/ollama/ollama)
### 相关技术
- FastAPI: https://fastapi.tiangolo.com/
- Vue 3: https://vuejs.org/
- Docker: https://www.docker.com/
- Kubernetes: https://kubernetes.io/
---
## 📝 版本历史
| 日期 | 版本 | 变更 |
|------|------|------|
| 2025-11-13 | v1.0.0 | 初始完整 CICD 实现 |
---
## 💡 关键概念总结
### CICD 流程的三个核心要素
1. **CI（持续集成）**
- 代码提交自动触发
- 自动化构建和测试
- 快速反馈开发者
2. **CD（持续部署）**
- 自动推送镜像到仓库
- 自动部署到生产环境
- 无需手动干预
3. **自动化验证**
- 部署后自动测试
- 健康检查
- 告警和回滚
### Kubernetes 部署的三个关键特性
1. **声明式配置**
- YAML 文件定义期望状态
- K8s 自动调和实际状态
- 版本控制和可重现性
2. **自动扩展和恢复**
- HPA 自动调整副本数
- Pod 失败自动重启
- 节点故障自动迁移
3. **零停机更新**
- 滚动更新策略
- 健康检查确保可用性
- 快速回滚能力
---
**现在你拥有一个完整的、生产级的 CICD 系统！** 🎉
有任何问题，请查看 [CICD_DEPLOYMENT_GUIDE.md](CICD_DEPLOYMENT_GUIDE.md)。