Skip to content
BranchesTags

Repository files navigation

aiflow-micro-parent

AI 感知的微服务可观测性 + 治理脚手架 SkyWalking(链路) · Prometheus + Loki + Grafana(指标/日志) · Langfuse(AI 观测) · Spring Cloud Alibaba(治理)

一套脚手架:微服务引入一个 Starter 依赖即自动获得指标 / 日志 / 链路能力,AI 调用可被观测(token / 成本 / 延迟),治理动作(熔断降级)可被看见,三支柱以 traceId 关联。

架构

                外部请求
                   │
          ┌────────▼────────┐
          │  aiflow-gateway  │  :8080  统一入口 + 路由 + Sentinel 限流
          └────────┬────────┘
                   │ 路由
          ┌────────▼──────────┐  OpenFeign   ┌──────────────────────┐
          │ aiflow-order-svc   │─────────────▶│ aiflow-inventory-svc │ :8082 (慢查询靶子)
          │ :8081 调用链起点     │              └──────────────────────┘
          │ Sentinel 熔断降级   │  OpenFeign   ┌──────────────────────┐
          └────────────────────┘─────────────▶│ aiflow-service       │ :8083
                                               │ Spring AI 调大模型     │ (AI超时靶子)
                                               └──────────────────────┘

  数据采集(三条独立链路,各司其职):
    链路  ── SkyWalking 原生 Agent(-javaagent) ──────────▶ SkyWalking OAP
    指标  ── Micrometer(/actuator/prometheus) ──── Prometheus 抓取
    日志  ── Promtail 读日志文件 ───────────────────────▶ Loki
    AI    ── Micrometer/OTel ──▶ OTel Collector ────────▶ Langfuse
    展示  ── Grafana 统一(接 Prometheus / Loki / SkyWalking)

模块

模块 说明
aiflow-observability-starter ★核心★ 自定义 Starter,引入即自动接入(指标/日志格式/AI埋点/采样)
aiflow-gateway 网关:路由 + Sentinel 限流
aiflow-order-service 订单:调用链起点,OpenFeign + Sentinel 熔断降级
aiflow-inventory-service 库存:内置慢查询故障靶子
aiflow-service AI 工作流:Spring AI 调大模型,采集 token/成本/延迟

快速开始

1. 准备环境变量

cp .env.example .env
# 编辑 .env,填入大模型 API(AI_API_BASE_URL/AI_API_KEY/AI_MODEL)
# 及 Langfuse 密钥(LANGFUSE_PUBLIC_KEY/SECRET_KEY,登录 Langfuse 后创建项目获取)

⚠️ 密钥一律走环境变量,.env 已被 .gitignore 忽略,严禁硬编码入库。

2. 启动基础设施(Docker)

docker compose -f docker/docker-compose.yml --env-file .env up -d

首次启动较慢(拉镜像 + SkyWalking OAP/Langfuse 初始化)。包含: Nacos · SkyWalking(OAP+UI+BanyanDB) · Prometheus · Loki + Promtail · OTel Collector · Alertmanager + 钉钉转换器 · Grafana · Langfuse(web+worker+Postgres+ClickHouse+Redis+MinIO)

💡 Langfuse 首次需在 UI(http://localhost:3002)注册账号、建项目、拿 API key 填入 .env。

3. 构建微服务

mvn clean install -DskipTests

4. 启动微服务(挂 SkyWalking Agent)

链路追踪依赖 SkyWalking 原生 Agent,启动时用 -javaagent 挂载。 Agent 位于 agents/skywalking-agent/(从 apache/skywalking-java-agent:9.5.0-java21 镜像提取)。

# 设置环境变量(或从 .env 导出)
export SW_AGENT_COLLECTOR_BACKEND_SERVICES=127.0.0.1:11800
export SW_AGENT_TRACE_IGNORE_PATH="/actuator/**,/v1/**"
export NACOS_SERVER_ADDR=127.0.0.1:8848
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
# AI 相关(aiflow-service 需要)
export AI_API_BASE_URL=... AI_API_KEY=... AI_MODEL=agnes-2.0-flash

AGENT=$(pwd)/agents/skywalking-agent/skywalking-agent.jar
java -javaagent:$AGENT -Dskywalking.agent.service_name=aiflow-inventory-service -jar aiflow-inventory-service/target/*.jar &
java -javaagent:$AGENT -Dskywalking.agent.service_name=aiflow-service           -jar aiflow-service/target/*.jar &
java -javaagent:$AGENT -Dskywalking.agent.service_name=aiflow-order-service     -jar aiflow-order-service/target/*.jar &
java -javaagent:$AGENT -Dskywalking.agent.service_name=aiflow-gateway           -jar aiflow-gateway/target/*.jar &

5. 跑闭环演示

bash docker/demo.sh   # 触发慢查询/AI超时靶子,演示排障与治理闭环

观察入口

组件 地址 说明
网关入口 http://localhost:8080 业务入口(POST /api/order?sku=X)
Grafana http://localhost:3001 admin/admin,统一大屏(指标/日志)
SkyWalking UI http://localhost:8088 链路/拓扑图
Langfuse http://localhost:3002 AI 调用明细(prompt/token/成本)
Prometheus http://localhost:9090 指标 PromQL 查询
Nacos http://localhost:8848/nacos 服务注册/配置

三支柱怎么看

支柱 在哪看 怎么查
指标 Grafana 大屏 / Prometheus QPS、P99延迟、错误率、JVM、AI token/成本
链路 SkyWalking UI(Trace/Topology) 调用链瀑布图、服务拓扑
日志 Grafana Explore(Loki) {service_name="aiflow-order-service"} | json | line_format "[{{.level}}] {{.message}}"
AI Langfuse 每次 AI 调用的 prompt/output/token/cost

关联:日志携带 SkyWalking 格式 traceId(TID 字段),可与 SkyWalking 链路关联。 (注:Langfuse 用独立的 W3C traceId 体系,与 SkyWalking 靠时间维度关联)

告警通知

链路:Prometheus(规则) → Alertmanager(分组/去重/路由) → 钉钉转换器 → 钉钉群

指标异常持续满足阈值 → 触发告警 → 推送到钉钉
  • 告警规则:docker/prometheus/alert-rules.yml — 已配 3 条:
    • HighP99Latency 服务 P99 延迟 > 1s(慢查询靶子触发)
    • HighErrorRate 5xx 错误率 > 5%
    • HighAiLatency AI 模型延迟 > 5s(AI 超时靶子触发)
    • 均含 for: 1m(持续满足才触发,避免抖动误报)
  • 通知渠道:docker/dingtalk/config.yml 填钉钉机器人 webhook。 钉钉/飞书格式与 Alertmanager 不兼容,故用 prometheus-webhook-dingtalk 转换器桥接; 企业微信则 Alertmanager 原生支持(wechat_configs),无需转换器。
  • 入口:Alertmanager UI http://localhost:9093
  • ⚠️ 钉钉机器人若设"自定义关键词",消息需含该词(本项目告警标题带"告警"); 时区由转换器容器 TZ=Asia/Shanghai 控制。

环境变量

变量 说明
AI_API_BASE_URL / AI_API_KEY / AI_MODEL 大模型 API(必填,base-url 不含 /v1)
NACOS_SERVER_ADDR Nacos 地址
SW_AGENT_COLLECTOR_BACKEND_SERVICES SkyWalking OAP 地址(11800)
OTEL_EXPORTER_OTLP_ENDPOINT OTLP 出口(→ Collector,供 AI trace)
LANGFUSE_OTEL_ENDPOINT / LANGFUSE_AUTH_STRING Langfuse OTLP 接入(AUTH=base64(pk:sk))
OTEL_TRACES_SAMPLER_ARG 采样率(本地 1.0,生产按比例)

完整清单见 .env.example。

版本

组件 版本
Java 21 (LTS,启用虚拟线程)
Spring Boot 3.2.x
Spring Cloud / Alibaba 2023.0.x (Nacos / Sentinel)
Spring AI 1.0.0 (GA)
SkyWalking OAP 10.4.0 + Agent 9.5.0 + BanyanDB 0.10
Langfuse v3

进阶

  • 新增微服务如何白拿可观测性 — 脚手架核心用法
  • 设计决策与踩坑记录:openspec/changes/add-observability-scaffold/design.md (版本兼容、traceId 对齐、Sentinel 自调用、Langfuse/MinIO、filter 降噪等)

About

AI 感知的微服务可观测性 + 治理脚手架：SkyWalking 链路 · Prometheus/Loki/Grafana 指标日志 · Langfuse AI 观测（token/成本/延迟）· Spring Cloud Alibaba 治理（Nacos + Sentinel 熔断降级）；引入自研 observability-starter 即自动接入，三支柱以 traceId 关联。

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages