gao/devops-ai-stack

Fork 0

Files

T

gao dc37415d0c Add all project files for DevOps+AI Stack

2025-11-10 13:52:09 +08:00

14 KiB

Raw Permalink Blame History

DevOps AI Stack 部署检查清单

📋 文档版本

版本: 1.0.0
更新时间: 2024 年 11 月
适用范围: 本地开发/小规模团队部署
质量等级: Production-Ready (开发环境)

🎯 部署目标

目标	预期值	状态
系统可用性	>= 99.5%	⚠️ 仅开发环境
服务启动时间	< 5 分钟	🎯
关键服务响应时间	< 1 秒	🎯
错误率	< 0.1%	🎯
备份完整性	100%	🎯
安全合规	OWASP Top 10 防护	⚠️ 开发环境

📝 部署前检查清单 (Pre-Deployment)

系统要求验证

操作系统: macOS 12.0+
- 验证命令: sw_vers
- 预期: macOS Monterey 或更新版本
CPU 和内存
- 最低要求: 4 核 CPU, 8GB 内存
- 推荐配置: 8 核 CPU, 16GB+ 内存
- 验证命令: system_profiler SPHardwareDataType | grep -E "Cores:|Memory:"
可用磁盘空间: >= 100GB
- 验证命令: df -h | grep -E '/$'

软件依赖检查

Docker Desktop (最新版本)

docker --version
# 预期: Docker version 24.0+

Docker Compose

docker compose version
# 预期: Docker Compose version 2.20+

Homebrew
```
brew --version
# 预期: Homebrew 4.0+
```

必要工具

# 验证所有工具已安装
which mkcert curl git

可选工具 (建议安装)
```
brew install kubectl helm
```

网络配置检查

本地 DNS 解析

配置 /etc/hosts:

127.0.0.1 localhost
127.0.0.1 dev.lan
127.0.0.1 traefik.dev.lan
127.0.0.1 git.dev.lan
127.0.0.1 grafana.dev.lan
127.0.0.1 ai.dev.lan

验证命令: ping traefik.dev.lan

防火墙配置
- 允许 Docker 使用网络
- 允许端口: 80, 443 (Traefik)

网络连通性

# 测试互联网访问 (用于拉取镜像)
curl https://www.google.com

Git 仓库检查

仓库状态

git status
# 预期: 工作目录干净或仅有 .gitignore 中的文件

分支检查

git branch
# 预期: 在 main 或 develop 分支

🚀 部署步骤 (Deployment)

第一阶段: 环境初始化

1.1 验证环境配置

# 步骤 1: 验证环境变量
cd /Users/brunogao/work/codes/tools/macos/ai/devops-ai-stack-finalized

# 验证必要的文件存在
[ -f secrets/.env.core ] && echo "✅ .env.core 存在" || echo "❌ .env.core 缺失"
[ -f secrets/.env.ai ] && echo "✅ .env.ai 存在" || echo "❌ .env.ai 缺失"

# 运行环境验证脚本
bash infra/scripts/validate-env.sh

# 结果检查清单
- [ ] 所有必需的环境变量已配置
- [ ] 没有使用默认/占位符值
- [ ] URL 格式正确
- [ ] 密码强度满足要求

验证完成时间: ______ | 验证者: ______ | 状态: [ ] 通过

1.2 生成 TLS 证书

# 步骤 2: 生成本地开发证书
bash infra/scripts/mkcert-init.sh

# 检查证书生成
ls -la infra/traefik/certs/

# 结果检查清单
- [ ] cert.pem 已生成
- [ ] key.pem 已生成
- [ ] 证书有效期 >= 365 天

证书生成时间: ______ | 过期日期: ______ | 状态: [ ] 通过

第二阶段: 服务启动

2.1 一键启动所有服务

# 步骤 3: 启动完整堆栈
bash infra/scripts/init-dev.sh

# 输出示例:
# ========================================
# 🚀 DevOps AI Stack 启动开始
# ========================================
# ...
# ✅ SUCCESS: DevOps AI Stack 启动完成！

# 结果检查清单
- [ ] 无关键错误 (WARNING 可以接受)
- [ ] 所有 6 个服务启动成功
  - [ ] core (Traefik + Gitea + Registry)
  - [ ] dev-cache (缓存)
  - [ ] observability (监控)
  - [ ] ai (AI 网关)
  - [ ] ai-visual (AI 可视化)
  - [ ] taskflow (任务编排)
- [ ] 关键服务健康检查通过

启动开始时间: ______ | 启动完成时间: ______ | 耗时: ______ | 状态: [ ] 通过

2.2 验证服务状态

# 步骤 4: 检查容器运行状态
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# 预期输出:
# NAMES                    STATUS              PORTS
# traefik                  Up 2 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
# gitea                    Up 2 minutes        0.0.0.0:222->22/tcp, 0.0.0.0:3000->3000/tcp
# registry                 Up 2 minutes        0.0.0.0:5000->5000/tcp
# ...

# 结果检查清单
- [ ] 所有主要容器状态为 "Up"
  - [ ] traefik
  - [ ] gitea
  - [ ] registry
  - [ ] prometheus
  - [ ] grafana
  - [ ] litellm
  - [ ] ollama
  - [ ] redis
  - [ ] minio
  - [ ] postgres
  - [ ] prefect-server

容器检查时间: ______ | 正常容器数: ____ / 12 | 状态: [ ] 通过

第三阶段: 服务验证

3.1 访问各服务仪表板

在浏览器中访问以下 URL，验证服务可用性:

服务	URL	预期响应	检查状态
Traefik	https://traefik.dev.lan/	仪表板加载	[ ]
Gitea	https://git.dev.lan/	登录页面	[ ]
Grafana	https://grafana.dev.lan/	Grafana 界面	[ ]
MinIO	https://minio.dev.lan/	MinIO 控制台	[ ]
Registry	https://reg.dev.lan/v2/	JSON 响应	[ ]
LiteLLM	https://ai.dev.lan/v1/models	模型列表	[ ]
Langfuse	https://langfuse.dev.lan/	Langfuse 界面	[ ]
Prefect	https://prefect.dev.lan/	Prefect 仪表板	[ ]

服务验证时间: ______ | 成功访问数: ____ / 8 | 状态: [ ] 通过

3.2 API 健康检查

# 验证 API 端点
echo "检查 Traefik..."
curl -sk https://traefik.dev.lan/ping
# 预期: ok

echo "检查 Gitea..."
curl -sk https://git.dev.lan/api/healthz
# 预期: 200 OK

echo "检查 Grafana..."
curl -sk https://grafana.dev.lan/api/health
# 预期: 200 OK

echo "检查 LiteLLM..."
curl -sk https://ai.dev.lan/v1/models
# 预期: 模型列表 JSON

# 结果检查清单
- [ ] Traefik 健康检查通过
- [ ] Gitea 健康检查通过
- [ ] Grafana 健康检查通过
- [ ] LiteLLM 健康检查通过

API 检查时间: ______ | 通过数: ____ / 4 | 状态: [ ] 通过

3.3 日志验证

# 检查启动日志
tail -50 logs/init-dev-*.log

# 结果检查清单
- [ ] 没有 ERROR 级别日志
- [ ] 所有关键服务初始化完成
- [ ] 没有数据库连接错误
- [ ] 没有证书相关错误

日志检查时间: ______ | 错误数: ____ | 状态: [ ] 通过

第四阶段: 功能验证

4.1 Gitea 仓库初始化

# 步骤 5: 配置 Gitea
# 通过 Web 界面 (https://git.dev.lan/) 完成初始化:
# 1. 设置管理员账户
# 2. 配置服务器设置
# 3. 测试 Git 克隆

# 结果检查清单
- [ ] Gitea 管理员账户已创建
- [ ] 可以通过 Web UI 访问
- [ ] 可以创建新仓库
- [ ] Git SSH 可以连接: ssh -p 222 git@localhost

Gitea 配置时间: ______ | 状态: [ ] 通过

4.2 Grafana 仪表板配置

# 步骤 6: 导入 Grafana 仪表板
# 通过 Web UI (https://grafana.dev.lan/) 完成配置:
# 1. 添加 Prometheus 数据源 (http://prometheus:9090)
# 2. 导入预置仪表板

# 结果检查清单
- [ ] Prometheus 数据源已添加
- [ ] 可以查询指标
- [ ] 预置仪表板已导入:
  - [ ] 01-observability.json
  - [ ] 02-ai-flow.json
  - [ ] 03-taskflow.json
- [ ] 仪表板显示数据正常

Grafana 配置时间: ______ | 仪表板数: ____ / 3 | 状态: [ ] 通过

4.3 AI 功能测试

# 步骤 7: 测试 LiteLLM API
# 获取可用模型
curl -sk https://ai.dev.lan/v1/models \
  -H "Authorization: Bearer dev_local_key"

# 结果检查清单
- [ ] 可以列出模型
- [ ] Ollama 模型可用
- [ ] 外部 API 密钥已配置

AI 功能测试时间: ______ | 状态: [ ] 通过

4.4 备份功能测试

# 步骤 8: 测试备份机制
bash infra/scripts/backup-manager.sh backup

# 验证备份
ls -la backups/
find backups/ -name "*.tar.gz" | head -5

# 结果检查清单
- [ ] 备份脚本执行成功
- [ ] 所有数据卷已备份
- [ ] 配置文件已备份
- [ ] 备份清单已生成
- [ ] 备份大小合理

备份测试时间: ______ | 备份大小: ______ | 状态: [ ] 通过

✅ 部署后检查清单 (Post-Deployment)

监控和告警验证

Prometheus 指标收集

# 验证指标数量
curl -sk https://grafana.dev.lan/api/datasources

告警规则已加载

# 查看告警规则数
curl -sk 'https://ai.dev.lan:9090/api/v1/rules' | jq '.data.groups | length'
# 预期: > 10

Loki 日志收集
- 验证日志可在 Grafana 中查询
分布式追踪 (可选)
- 验证 Tempo 配置完成

性能基准测试

# 响应时间测试
echo "测试 Traefik 响应时间..."
time curl -sk https://traefik.dev.lan/ping

echo "测试 Gitea 响应时间..."
time curl -sk https://git.dev.lan/api/healthz

echo "测试 LiteLLM API..."
time curl -sk https://ai.dev.lan/v1/models

# 结果检查清单
- [ ] 平均响应时间 < 200ms
- [ ] 最大响应时间 < 1s
- [ ] 所有端点都有一致的性能

安全性检查

TLS 证书有效

openssl s_client -connect traefik.dev.lan:443 -showcerts < /dev/null
# 验证证书有效期

环境变量未泄露

# 验证敏感信息
grep -r "REPLACE_ME" secrets/
# 预期: 无输出

Docker 网络隔离

docker network ls
# 验证核心网络隔离

容器镜像安全

# 扫描已知漏洞
docker images --format "table {{.Repository}}\t{{.Tag}}"

备份和恢复验证

定时备份配置

# 计划每日备份任务 (crontab 或 launchd)
# 备份脚本路径: ./infra/scripts/backup-manager.sh

恢复流程测试

# 在测试环境中验证恢复流程
# 不在生产环境运行此测试!

文档完整性检查

README.md 已更新
IMPLEMENTATION_GUIDE.md 已审查
DEPLOYMENT_CHECKLIST.md 已填写
故障排查文档 已准备
环保版本 ENV_VALIDATION_REPORT.md 已生成

📊 部署统计

时间统计

阶段	计划耗时	实际耗时	偏差	状态
前置检查	15 分钟	______	______	[ ]
环境初始化	10 分钟	______	______	[ ]
服务启动	5 分钟	______	______	[ ]
服务验证	10 分钟	______	______	[ ]
功能验证	20 分钟	______	______	[ ]
总计	60 分钟	______	______	[ ]

问题记录

遇到的问题

问题描述	严重程度	解决方案	解决时间	解决人
______	[ ] P0 / [ ] P1 / [ ] P2	______	______	______
______	[ ] P0 / [ ] P1 / [ ] P2	______	______	______

改进建议

建议 1: ______
建议 2: ______
建议 3: ______

🔍 故障排查快速指南

常见问题

Q1: 无法访问服务 (HTTPS 证书警告)

原因: mkcert 证书未安装到系统信任库

解决方案:

# 重新运行证书初始化
bash infra/scripts/mkcert-init.sh

# 在 macOS 中手动信任证书
security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain \
  infra/traefik/certs/cert.pem

Q2: Docker Compose 端口冲突

原因: 端口已被其他服务占用

解决方案:

# 查找占用端口的进程
lsof -i :80
lsof -i :443

# 停止冲突的服务或修改 Compose 配置

Q3: 服务启动失败

原因: 资源不足或依赖未就绪

解决方案:

# 查看日志
tail -50 logs/init-dev-*.log

# 检查容器日志
docker compose -f infra/compose/core.yml logs traefik

# 检查资源使用
docker stats

Q4: 数据库连接错误

原因: PostgreSQL 初始化失败

解决方案:

# 清理并重新启动
docker volume rm postgres
bash infra/scripts/init-dev.sh

完整故障排查指南

详见 TROUBLESHOOTING.md

📚 后续步骤

立即执行

完成所有检查清单项目
记录部署统计信息
设置定期备份任务
配置 Prometheus 告警
设置监控仪表板

本周内完成

配置 Gitea Actions CI/CD
创建示例项目和 Pipeline
测试备份和恢复流程
编制团队培训文档
设置访问权限和认证

本月内完成

性能优化和基准测试
安全加固和合规检查
高可用性架构评估
Kubernetes 迁移规划
文档完善和知识库建设

📞 获取帮助

常用命令

# 查看启动日志
tail -f logs/init-dev-*.log

# 停止所有服务
bash infra/scripts/cleanup-dev.sh

# 验证环境配置
bash infra/scripts/validate-env.sh

# 创建备份
bash infra/scripts/backup-manager.sh backup

# 查看服务状态
docker ps
docker compose -f infra/compose/core.yml logs

支持资源

文档: 查看项目中的 docs/ 和 IMPLEMENTATION_GUIDE.md
日志: 检查 logs/ 目录
备份: 查看 backups/ 目录结构

✍️ 签字确认

部署完成后，请相关人员确认:

角色	姓名	签名	日期	备注
部署工程师	______	______	______	______
质量负责人	______	______	______	______
技术主管	______	______	______	______

文档生成时间: 2024 年 11 月版本: 1.0.0 状态: ✅ 生效中

14 KiB Raw Permalink Blame History

DevOps AI Stack 部署检查清单

📋 文档版本

🎯 部署目标

📝 部署前检查清单 (Pre-Deployment)

系统要求验证

软件依赖检查

网络配置检查

Git 仓库检查

🚀 部署步骤 (Deployment)

第一阶段: 环境初始化

1.1 验证环境配置

1.2 生成 TLS 证书

第二阶段: 服务启动

2.1 一键启动所有服务

2.2 验证服务状态

第三阶段: 服务验证

3.1 访问各服务仪表板

3.2 API 健康检查

3.3 日志验证

第四阶段: 功能验证

4.1 Gitea 仓库初始化

4.2 Grafana 仪表板配置

4.3 AI 功能测试

4.4 备份功能测试

✅ 部署后检查清单 (Post-Deployment)

监控和告警验证

性能基准测试

安全性检查

备份和恢复验证

文档完整性检查

📊 部署统计

时间统计

问题记录

遇到的问题

改进建议

🔍 故障排查快速指南

常见问题

Q1: 无法访问服务 (HTTPS 证书警告)

Q2: Docker Compose 端口冲突

Q3: 服务启动失败

Q4: 数据库连接错误

完整故障排查指南

📚 后续步骤

立即执行

本周内完成

本月内完成

📞 获取帮助

常用命令

支持资源

✍️ 签字确认

14 KiB

Raw Permalink Blame History