# DevOps 基础设施优化蓝皮书 (v1.0)

## 🧭 一、总体目标
构建稳定、安全、高可观测的 DevOps + AI Flow 一体化环境。
适用于 Mac Studio / Linux 服务器，支持多架构、AI 任务编排、可视化监控。

---

## 🧱 二、六大优化方向
1. 架构层面：Compose 分层、网络隔离、数据持久化、自愈机制。
2. DevOps 自动化：多阶段 CI/CD、镜像扫描、SOPS 加密、GitOps。
3. Observability 完善：Trace、Metrics、Alert、Dashboard 模板化。
4. AI Flow 性能：LiteLLM 路由表、请求缓存、Langfuse + MLflow 联动。
5. Prefect 任务：自动注册、队列分类、日志收集、参数化部署。
6. 系统性能：缓存代理、镜像瘦身、VPN 健康检测、节能策略。

---

## ⚙️ 三、推荐改进配置

### Traefik 健康检查
```yaml
services:
  traefik:
    healthcheck:
      test: ["CMD", "traefik", "healthcheck", "--ping"]
      interval: 30s
      timeout: 5s
      retries: 3
```

### Docker Compose profiles
```yaml
x-profiles:
  dev:
    services: [gitea, registry, traefik]
  prod:
    services: [traefik, observability, ai, taskflow]
```

### SOPS + age 密钥管理
```bash
sops --encrypt --age <YOUR_AGE_KEY> secrets/.env.core > secrets/.env.core.enc
```

---

## 🧩 四、可观测性优化

- 新增 Alertmanager:
```yaml
alertmanager:
  image: prom/alertmanager:latest
  volumes:
    - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml
  networks: [core]
```

- Grafana 模板路径标准化：`infra/observability/grafana-provisioning/dashboards/`  
- OpenTelemetry SDK 集成：Python、Node.js、Spring Boot 全覆盖。

---

## 🧠 五、AI Flow 优化

- LiteLLM 路由配置示例：
```yaml
models:
  gpt-4o-mini: openrouter/gpt-4o-mini
  qwen3-coder: ollama/qwen3-coder:32b
  deepseek-r1: remote/vllm-deepseek-r1
```

- Langfuse + MLflow 联动任务：
```python
from prefect import flow
@flow
def sync_langfuse_mlflow():
    # 从 Langfuse 拉取调用记录写入 MLflow
    ...
```

---

## 🧰 六、Prefect 任务优化

- 自动注册 CI 流程：
```yaml
jobs:
  register_prefect:
    runs-on: docker
    steps:
      - run: prefect deployment build tasks/demo_task.py:health_monitoring_flow -n devops-health
```

- 队列划分：
```
default：普通任务
ai：模型调用类任务
data：数据同步任务
devops：构建/发布任务
```

---

## 📊 七、性能优化

| 模块 | 优化策略 |
|------|-----------|
| Docker 构建 | buildx cache + multi-stage |
| 镜像 | alpine 基础镜像 + distroless |
| VPN | WireGuard KeepAlive + cron 健康检测 |
| 磁盘 | Loki 日志 14 天归档 |
| Mac Studio | CPU 限制 + IO 优先级 |

---

## 🧱 八、团队与知识管理

- Blueprint 目录 `/docs/bluebook/`  
- Prompts + Evals 管理 `/ai/prompts` `/ai/evals`
- DevOps 状态大屏 `/grafana-dashboards/ops-cockpit.json`  
- API 文档 `/docs/openapi.yaml` 自动生成

---

## 🚀 九、路线图

| 阶段 | 目标 | 关键任务 |
|------|------|----------|
| Phase 1 | 稳定化 | Compose 分层，Traefik 域名统一 |
| Phase 2 | 自动化 | CI/CD + Prefect 编排 |
| Phase 3 | 智能化 | AI Flow、Langfuse、MLflow 联动 |
| Phase 4 | 集群化 | k3s + ArgoCD + Harbor Proxy |

---

## 🔚 十、AI Agent 执行模板

```yaml
tasks:
  - name: validate_networks
    action: run
    cmd: docker network ls

  - name: start_stack
    action: run
    cmd: bash infra/scripts/init-dev.sh

  - name: verify_observability
    action: curl
    urls:
      - https://grafana.dev.lan
      - https://prefect.dev.lan
      - https://ai.dev.lan/v1

  - name: report_status
    action: summarize
```

---

> ✅ 建议将本文件放入仓库 `docs/bluebook/` 目录下。  
> 可由 Qwen / Claude 自动解析执行。