Files

T

brunoandClaude 8af5fd1385 docs: 添加 CICD 实现总结文档

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

🤖 Generated with Claude Code

Co-Authored-By: Claude <[email protected]>

2025-11-13 11:59:03 +08:00

13 KiB

Raw Permalink Blame History

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 步：验证环境

cd /Users/brunogao/work/codes/stock/claude-stock
bash verify-cicd.sh

检查项目：

Gitea 服务状态
Gitea Runners 运行状态
Harbor 镜像仓库访问
Kubernetes 集群可用性
Ollama 服务和模型加载
Docker 可用性
文件完整性
网络连接

第 2 步：启动 Runners

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

cd /Users/brunogao/work/codes/stock/claude-stock

# 自动部署（会自动创建 namespace、secrets、部署应用）
export HARBOR_PASSWORD="Harbor12345"
bash deploy-to-k8s.sh

第 5 步：触发 CICD

# 提交代码（会自动触发 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

# deployment.yaml 中的关键配置
env:
  - name: NODE_IP
    valueFrom:
      fieldRef:
        fieldPath: status.hostIP

  - name: OLLAMA_BASE_URL
    value: "http://$(NODE_IP):11434"

工作原理：

Pod 从 Kubernetes API 自动获取宿主节点 IP
使用 Node IP 代替 localhost 连接到 Ollama
宿主 Ollama 需要监听 0.0.0.0:11434

包含的备选方案： （见 ollama-bridge.yaml）

ExternalName Service
Endpoint + Service
DaemonSet 代理
直接修改 Ollama 监听地址

2. Harbor 镜像仓库集成

认证流程：

CICD 工作流使用 Harbor 凭证登录
构建镜像：localhost:8443/claude-stock/backend:latest
推送镜像到 Harbor
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`

注册流程：

获取 Runner Token（Gitea Admin 生成）
启动 Runners 容器
Runners 自动向 Gitea 注册
查看 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 自动创建：

- 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 的故障排除部分

📈 后续优化方向

短期（1-2 周）

监控和告警
- 集成 Prometheus 监控
- 设置告警规则
- Grafana 仪表板
日志管理
- 集中化日志收集（ELK Stack）
- 结构化日志输出
- 日志搜索和分析
性能优化
- 镜像缓存优化
- 构建并行度提升
- 测试执行时间优化

中期（1-3 个月）

GitOps
- 集成 ArgoCD 或 Flux
- 配置驱动部署
- 自动同步
高可用性
- 跨节点部署
- PVC 持久化存储
- 备份和恢复策略
安全加强
- 镜像签名验证
- OPA Policy as Code
- RBAC 精细化控制

长期（3-6 个月）

多环境部署
- Staging 环境
- Production 环境
- 金丝雀部署
成本优化
- 资源自动优化
- 闲置资源回收
- 成本预算告警
开发者体验
- 本地开发环境快速启动
- 一键式调试
- 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/ 目录存在

🔗 相关资源链接

本项目资源

官方文档

📝 版本历史

日期	版本	变更
2025-11-13	v1.0.0	初始完整 CICD 实现

💡 关键概念总结

CICD 流程的三个核心要素

CI（持续集成）
- 代码提交自动触发
- 自动化构建和测试
- 快速反馈开发者
CD（持续部署）
- 自动推送镜像到仓库
- 自动部署到生产环境
- 无需手动干预
自动化验证
- 部署后自动测试
- 健康检查
- 告警和回滚

Kubernetes 部署的三个关键特性

声明式配置
- YAML 文件定义期望状态
- K8s 自动调和实际状态
- 版本控制和可重现性
自动扩展和恢复
- HPA 自动调整副本数
- Pod 失败自动重启
- 节点故障自动迁移
零停机更新
- 滚动更新策略
- 健康检查确保可用性
- 快速回滚能力

现在你拥有一个完整的、生产级的 CICD 系统！ 🎉

有任何问题，请查看 CICD_DEPLOYMENT_GUIDE.md。

13 KiB Raw Permalink Blame History Unescape Escape