# 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. 解析域名
```bash
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
bash infra/scripts/mkcert-init.sh
```

### Step 3. 初始化多架构 Builder
```bash
bash infra/scripts/buildx-setup.sh
```

### Step 4. 填写环境变量
```bash
cp secrets/.env.core.example secrets/.env.core
cp secrets/.env.ai.example secrets/.env.ai
# 编辑 secrets/.env.*
```

### Step 5. 一键启动全部栈
```bash
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 调试指令

### 调用统一接口
```bash
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 集成指令

```yaml
# .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 指令风格）

```yaml
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 指令自动执行构建。  
> 人工阅读则按章节顺序操作即可。