177 lines
4.9 KiB
Markdown
177 lines
4.9 KiB
Markdown
|
||
# 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 指令自动执行构建。
|
||
> 人工阅读则按章节顺序操作即可。
|