gao/devops-ai-stack

Fork 0

Files

T

gao 73b14508c6 first commit

2025-11-09 08:31:00 +08:00

13 KiB

Raw Permalink Blame History

DevOps + AI Flow 项目实施计划

📊 项目现状分析

项目概述

本项目是一个DevOps + AI Flow一体化环境，提供完整的开发、CI/CD、AI服务、可观测性和任务编排能力。

技术架构

┌─────────────────────────────────────────────────────────┐
│                    Traefik (80/443)                      │
│                  统一入口与路由网关                       │
└─────────────────────────────────────────────────────────┘
         │              │              │              │
    ┌────┴────┐    ┌────┴────┐   ┌────┴────┐   ┌────┴────┐
    │  Core   │    │   AI    │   │Observ│  │Taskflow │
    │ Services│    │ Services│   │Services │  │Services │
    └─────────┘    └─────────┘   └─────────┘   └─────────┘

核心模块

Core Services (core.yml)
- Traefik: 反向代理与路由
- Gitea: Git仓库 + CI/CD
- Act Runner: Gitea Actions执行器
- Registry: Docker镜像仓库
- Harbor Proxy: Harbor代理缓存
Dev Cache (dev-cache.yml)
- Apt-Cacher-NG: APT包缓存
- Verdaccio: NPM包缓存
- Devpi: PyPI包缓存
Observability (observability.yml)
- Prometheus: 指标收集
- Loki: 日志聚合
- Tempo: 链路追踪
- Grafana: 可视化面板
- Promtail: 日志采集
AI Services (ai.yml)
- LiteLLM: AI网关统一接口
- Ollama: 本地模型服务
- Redis: 缓存服务
- MinIO: 对象存储
AI Visualization (ai-visual.yml)
- Langfuse: AI调用链追踪
- MLflow: 模型实验管理
Task Flow (taskflow.yml)
- Prefect: 任务编排与调度

当前状态评估

✅ 已完成

Docker Compose配置文件完整（6个模块）
Traefik配置与TLS支持
初始化脚本（init-dev.sh, mkcert-init.sh, buildx-setup.sh）
环境变量模板（.env.core.example, .env.ai.example）
Grafana仪表板JSON文件（3个预置面板）
实施指南文档（IMPLEMENTATION_GUIDE.md）
优化蓝皮书（3个版本）
Agent任务清单（agent_tasks.yaml）
Prefect示例任务（example_health_flow.py）

⚠️ 待完成

环境变量实际配置文件（需从.example复制并填写）
证书生成验证
服务健康检查配置
所有compose文件的网络依赖验证
Grafana数据源自动配置验证
LiteLLM路由配置
Prefect部署配置
备份与恢复策略
监控告警规则

❌ 缺失项

secrets目录下实际.env文件
Alertmanager告警配置
SOPS加密配置（生产环境）
服务健康检查脚本
自动化测试脚本
性能基准测试

🎯 实施计划

阶段一：环境准备与配置（优先级：HIGH）

1.1 前置条件检查

目标：确保运行环境满足要求

检查Docker/Docker Compose版本
检查mkcert是否安装
检查系统资源（内存、磁盘）
检查端口占用（80, 443）

执行命令：

docker --version && docker compose version
mkcert -version
df -h && free -h  # Linux
# macOS: Activity Monitor

1.2 域名解析配置

目标：配置本地域名解析

编辑/etc/hosts或配置dnsmasq
添加所有服务域名解析

执行步骤：

sudo vim /etc/hosts
# 添加：
127.0.0.1 traefik.dev.lan git.dev.lan reg.dev.lan grafana.dev.lan \
          ai.dev.lan langfuse.dev.lan mlflow.dev.lan prefect.dev.lan \
          minio.dev.lan

1.3 TLS证书生成

目标：生成本地开发证书

执行mkcert-init.sh
验证证书文件生成
确认证书信任状态

执行命令：

bash infra/scripts/mkcert-init.sh
ls -la infra/traefik/certs/

1.4 环境变量配置

目标：创建并配置所有必需的环境变量

复制.env.example文件
填写Gitea配置
填写LiteLLM配置
填写MinIO凭证
配置API Keys（如需要）

执行步骤：

cp secrets/.env.core.example secrets/.env.core
cp secrets/.env.ai.example secrets/.env.ai
# 编辑并填写实际值
vim secrets/.env.core secrets/.env.ai

必需配置项：

GITEA_RUNNER_TOKEN: Gitea Runner注册令牌（需从Gitea获取）
GITEA__server__ROOT_URL: Gitea根URL
LITELLM_MASTER_KEY: LiteLLM主密钥
MINIO_ROOT_USER/PASSWORD: MinIO管理员凭证

1.5 Docker Buildx初始化

目标：配置多架构构建支持

执行buildx-setup.sh
验证builder创建成功

执行命令：

bash infra/scripts/buildx-setup.sh
docker buildx ls

阶段二：核心服务部署（优先级：HIGH）

2.1 启动Core服务栈

目标：部署Traefik、Gitea、Registry等核心服务

启动core.yml
验证Traefik Dashboard可访问
验证Gitea初始化完成
验证Registry可访问
获取Gitea Runner Token

执行命令：

docker compose -f infra/compose/core.yml up -d
docker compose -f infra/compose/core.yml ps
curl -k https://traefik.dev.lan/dashboard/
curl -k https://git.dev.lan

验证清单：

Traefik: https://traefik.dev.lan → 200 OK
Gitea: https://git.dev.lan → 登录页面
Registry: https://reg.dev.lan/v2/ → 200 OK
更新.env.core中的GITEA_RUNNER_TOKEN

2.2 启动依赖缓存服务

目标：部署APT/NPM/PyPI缓存代理

启动dev-cache.yml
验证各缓存服务运行状态

执行命令：

docker compose -f infra/compose/dev-cache.yml up -d
docker compose -f infra/compose/dev-cache.yml ps

阶段三：可观测性部署（优先级：MEDIUM）

3.1 启动Observability服务栈

目标：部署监控、日志、追踪服务

启动observability.yml
验证Prometheus抓取目标
验证Grafana数据源配置
导入预置仪表板

执行命令：

docker compose -f infra/compose/observability.yml up -d
curl -s http://localhost:9090/api/v1/targets | jq
curl -k https://grafana.dev.lan/api/health

验证清单：

Prometheus: http://localhost:9090 → 可访问
Grafana: https://grafana.dev.lan → 登录页面
Loki: 日志查询正常
Tempo: 追踪数据正常
仪表板导入成功（3个JSON文件）

3.2 配置Grafana数据源

目标：确保Grafana自动发现数据源

检查grafana-provisioning配置
验证数据源连接状态

验证命令：

curl -k https://grafana.dev.lan/api/datasources

阶段四：AI服务部署（优先级：HIGH）

4.1 启动AI服务栈

目标：部署LiteLLM、Ollama、Redis、MinIO

启动ai.yml
验证Ollama服务
验证Redis连接
验证MinIO控制台
配置LiteLLM路由

执行命令：

docker compose -f infra/compose/ai.yml up -d
docker compose -f infra/compose/ai.yml ps
curl -k https://minio.dev.lan

验证清单：

LiteLLM: https://ai.dev.lan/v1/models → 返回模型列表
Ollama: 容器运行正常
Redis: 连接测试通过
MinIO: https://minio.dev.lan → 控制台可访问

4.2 配置LiteLLM路由

目标：配置模型路由规则

创建LiteLLM配置文件
配置Ollama模型路由
配置外部API路由（如需要）
测试模型调用

配置示例：

# 创建 infra/compose/ai/litellm-config.yaml
model_list:
  - model_name: qwen3-coder
    litellm_params:
      model: ollama/qwen3-coder:32b
      api_base: http://ollama:11434

测试命令：

curl -k -X POST https://ai.dev.lan/v1/chat/completions \
  -H "Authorization: Bearer dev_local_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3-coder","messages":[{"role":"user","content":"hello"}]}'

4.3 启动AI可视化服务

目标：部署Langfuse和MLflow

启动ai-visual.yml
验证Langfuse UI
验证MLflow UI
配置LiteLLM与Langfuse集成

执行命令：

docker compose -f infra/compose/ai-visual.yml up -d
curl -k https://langfuse.dev.lan
curl -k https://mlflow.dev.lan

验证清单：

Langfuse: https://langfuse.dev.lan → UI可访问
MLflow: https://mlflow.dev.lan → UI可访问
LiteLLM调用记录出现在Langfuse

阶段五：任务编排部署（优先级：MEDIUM）

5.1 启动Prefect服务

目标：部署Prefect Server和Agent

启动taskflow.yml
验证Prefect UI
配置Prefect API连接

执行命令：

docker compose -f infra/compose/taskflow.yml up -d
curl -k https://prefect.dev.lan

验证清单：

Prefect: https://prefect.dev.lan → UI可访问
Prefect Agent: 运行中

5.2 注册示例任务

目标：测试Prefect任务执行

运行example_health_flow.py
在Prefect UI中查看执行结果
验证任务日志

执行命令：

# 配置Prefect API URL
export PREFECT_API_URL=https://prefect.dev.lan/api
python tasks/example_health_flow.py

阶段六：集成测试与验证（优先级：HIGH）

6.1 端到端服务验证

目标：验证所有服务正常运行

执行agent_tasks.yaml中的验证任务
检查所有服务健康状态
验证服务间通信

验证脚本：

# 创建验证脚本
cat > verify-services.sh << 'EOF'
#!/bin/bash
services=(
  "https://traefik.dev.lan"
  "https://git.dev.lan"
  "https://grafana.dev.lan"
  "https://ai.dev.lan/v1/models"
  "https://langfuse.dev.lan"
  "https://mlflow.dev.lan"
  "https://prefect.dev.lan"
)
for url in "${services[@]}"; do
  if curl -k -s -o /dev/null -w "%{http_code}" "$url" | grep -q "200\|302"; then
    echo "✅ $url"
  else
    echo "❌ $url"
  fi
done
EOF
chmod +x verify-services.sh
./verify-services.sh

6.2 功能测试

目标：测试核心功能

Gitea: 创建仓库、推送代码
Registry: 推送/拉取镜像
LiteLLM: 模型调用测试
Langfuse: 调用链追踪验证
Prefect: 任务执行测试
Grafana: 仪表板数据展示

6.3 性能测试

目标：验证系统性能

服务启动时间
API响应时间
资源使用情况
并发请求处理

阶段七：优化与加固（优先级：LOW）

7.1 安全加固

添加服务健康检查
配置服务重启策略
实施SOPS加密（生产环境）
配置防火墙规则
更新默认密码

7.2 监控告警

部署Alertmanager
配置告警规则
设置通知渠道（Slack/Webhook）
测试告警触发

7.3 备份策略

配置数据卷备份
设置自动备份计划
测试恢复流程
文档化备份步骤

7.4 性能优化

实施蓝皮书中的HIGH优先级优化项
优化Docker镜像大小
配置资源限制
优化网络配置

📋 快速启动检查清单

首次部署前

Docker/Docker Compose已安装
mkcert已安装（brew install mkcert nss）
域名解析已配置（/etc/hosts）
环境变量文件已创建并填写
证书已生成

部署顺序

bash infra/scripts/mkcert-init.sh
bash infra/scripts/buildx-setup.sh
docker compose -f infra/compose/core.yml up -d
获取Gitea Runner Token并更新.env.core
docker compose -f infra/compose/dev-cache.yml up -d
docker compose -f infra/compose/observability.yml up -d
docker compose -f infra/compose/ai.yml up -d
docker compose -f infra/compose/ai-visual.yml up -d
docker compose -f infra/compose/taskflow.yml up -d
验证所有服务可访问

一键启动（推荐）

bash infra/scripts/init-dev.sh

🚨 常见问题与解决方案

问题1: 证书不受信任

解决：执行mkcert -install安装CA证书

问题2: Gitea Runner无法注册

解决：从Gitea UI获取Runner Token并更新.env.core

问题3: 服务无法通过域名访问

解决：检查/etc/hosts配置和Traefik路由标签

问题4: LiteLLM无法连接Ollama

解决：检查网络配置，确保litellm和ollama在同一网络

问题5: Grafana数据源未自动配置

解决：检查grafana-provisioning目录配置

📈 后续优化方向

集群化部署：迁移到k3s + ArgoCD
高可用：多节点部署与负载均衡
安全加固：TLS证书管理、RBAC、审计日志
性能调优：缓存策略、资源配额、网络优化
扩展功能：集成更多AI模型、CI/CD模板、监控告警

📝 更新日志

2024-XX-XX: 初始版本实施计划创建

注意：本计划基于当前项目结构分析生成，实际执行时请根据环境情况调整。
建议按阶段逐步实施，每完成一个阶段进行验证后再继续下一阶段。

13 KiB Raw Permalink Blame History Unescape Escape

DevOps + AI Flow 项目实施计划

📊 项目现状分析

项目概述

技术架构

核心模块

当前状态评估

✅ 已完成

⚠️ 待完成

❌ 缺失项

🎯 实施计划

阶段一：环境准备与配置（优先级：HIGH）

1.1 前置条件检查

1.2 域名解析配置

1.3 TLS证书生成

1.4 环境变量配置

1.5 Docker Buildx初始化

阶段二：核心服务部署（优先级：HIGH）

2.1 启动Core服务栈

2.2 启动依赖缓存服务

阶段三：可观测性部署（优先级：MEDIUM）

3.1 启动Observability服务栈

3.2 配置Grafana数据源

阶段四：AI服务部署（优先级：HIGH）

4.1 启动AI服务栈

4.2 配置LiteLLM路由

4.3 启动AI可视化服务

阶段五：任务编排部署（优先级：MEDIUM）

5.1 启动Prefect服务

5.2 注册示例任务

阶段六：集成测试与验证（优先级：HIGH）

6.1 端到端服务验证

6.2 功能测试

6.3 性能测试

阶段七：优化与加固（优先级：LOW）

7.1 安全加固

7.2 监控告警

7.3 备份策略

7.4 性能优化

📋 快速启动检查清单

首次部署前

部署顺序

一键启动（推荐）

🚨 常见问题与解决方案

问题1: 证书不受信任

问题2: Gitea Runner无法注册

问题3: 服务无法通过域名访问

问题4: LiteLLM无法连接Ollama

问题5: Grafana数据源未自动配置

📈 后续优化方向

📝 更新日志

13 KiB

Raw Permalink Blame History