devops-ai-stack/IMPLEMENTATION_GUIDE.md

DevOps + AI Flow Implementation Guide

本文档既供工程师人工操作，也可供 Qwen / Claude-Code 等 AI Agent 直接解析执行。

---

1️⃣ 目标与原则

目标： 统一开发服务器的 DevOps、CI/CD、AI Flow、可观测性与任务编排，形成可复用的一键环境。

核心原则：

1. 仅 Traefik 占用 80/443；
2. 所有服务走域名路由，防止端口冲突；
3. 统一 .dev.lan 内网域；
4. 统一 AI 接口入口：https://ai.dev.lan/v1；
5. 模型路由、任务编排、日志指标、实验追踪全部可视化。

---

2️⃣ 目录说明

目录	内容	Qwen 指令关键词
infra/compose/	各模块 compose 文件	docker-compose up
infra/scripts/	初始化脚本	bash infra/scripts/init-dev.sh
infra/traefik/	Traefik 主配置与 TLS	mkcert
infra/registry/	Docker Registry 配置	docker registry
infra/observability/	Prometheus / Grafana / Loki 等配置	observability
grafana-dashboards/	预置 Grafana 面板 JSON	grafana import
secrets/	环境变量模板（需复制填写）	env setup
ai/prompts/	Prompt 模板库	prompt register
ai/evals/	评测与指标	mlflow run

---

3️⃣ 环境准备步骤

Step 1. 解析域名

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

Step 2. 生成证书

bash infra/scripts/mkcert-init.sh

Step 3. 初始化多架构 Builder

bash infra/scripts/buildx-setup.sh

Step 4. 填写环境变量

cp secrets/.env.core.example secrets/.env.core
cp secrets/.env.ai.example secrets/.env.ai
# 编辑 secrets/.env.*

Step 5. 一键启动全部栈

bash infra/scripts/init-dev.sh

---

4️⃣ 各栈职责

模块	内容	访问地址
core.yml	Traefik + Gitea + Runner + Registry	https://git.dev.lan
dev-cache.yml	APT / NPM / PyPI 缓存	内网
observability.yml	Prometheus + Grafana + Loki + Tempo	https://grafana.dev.lan
ai.yml	LiteLLM + Ollama + Redis + MinIO	https://ai.dev.lan/v1
ai-visual.yml	Langfuse + MLflow	https://langfuse.dev.lan
taskflow.yml	Prefect Server + Agent	https://prefect.dev.lan

---

5️⃣ 验证任务（可由 Qwen 执行）

验证项	命令	期望结果
Traefik 路由	curl -k https://traefik.dev.lan/dashboard/	返回 HTML
Registry 存取	docker login reg.dev.lan	登录成功
Grafana 面板	curl -I https://grafana.dev.lan	200 OK
LiteLLM	curl -k https://ai.dev.lan/v1/models	返回模型列表
Prefect	curl -I https://prefect.dev.lan	200 OK
Langfuse	curl -I https://langfuse.dev.lan	200 OK

---

6️⃣ AI Flow 调试指令

调用统一接口

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

在 Langfuse 可视化调用链

访问 https://langfuse.dev.lan
可看到每次 Prompt、模型路由、延迟、Token 成本。

---

7️⃣ CI/CD 集成指令

# .gitea/workflows/build.yml
name: build-push
on: [push]
jobs:
  build:
    runs-on: docker
    steps:
      - uses: actions/checkout@v4
      - run: ./infra/scripts/buildx-setup.sh
      - run: docker login reg.dev.lan -u $REG_USER -p $REG_PASS
      - run: docker buildx bake --file infra/buildx/docker-bake.hcl

---

8️⃣ 观测面板

Grafana 预置 3 个仪表盘：

• 01-observability.json：系统与容器指标
• 02-ai-flow.json：LiteLLM / Langfuse / MLflow 调用分析
• 03-taskflow.json：Prefect 任务成功率与执行时间

---

9️⃣ 高级选项

场景	扩展方式
集群化部署	替换 Compose 为 k3s + ArgoCD
持续监控告警	Prometheus Alertmanager / Grafana Alert
远程节点互通	WireGuard / Tailscale
模型混合部署	LiteLLM 多后端（Ollama / vLLM / OpenRouter）
安全	全栈 HTTPS、TLS、账号密码在 secrets/.env 内定义

---

🔟 Qwen 实施提示（Agent 指令风格）

instructions:
  - name: setup_devops_env
    action: run
    cmd: bash infra/scripts/init-dev.sh
  - name: check_services
    action: curl
    urls:
      - https://grafana.dev.lan
      - https://ai.dev.lan/v1
      - https://prefect.dev.lan
  - name: report_status
    action: summarize
    outputs: [logs, success, warnings]

---

📎 本文档可直接放入仓库根目录。
Qwen-Code / Claude-Code 可识别标题、命令块、YAML 指令自动执行构建。
人工阅读则按章节顺序操作即可。