项目地址 ：github.com/iweidujiang...（欢迎 Star）
当前版本 ：
0.3.0（Maven Central）· 监测中心镜像ghcr.io/iweidujiang/spring-insight-server:0.3.0
一、它是什么、不是什么
做微服务久了，大概都碰到过这种情况：
下单接口变慢了。网关 → 订单 → 用户 → 积分，到底慢在哪一跳？日志翻了半小时，还在猜。
业界答案很多：SkyWalking、OpenTelemetry + Jaeger、老一点的 Sleuth + Zipkin......都很强，也都很「重」------协议、采样、存储、鉴权、部署手册一摞。很多中小项目、本地联调，其实只想先回答三件事：
- 谁调用了谁
- 这条请求耗时卡在哪
- 哪里报错了
Spring Insight 就是冲着这个缺口写的：业务侧加一个 Starter，旁边用 Docker 起一个轻量监测中心，打开浏览器就能看拓扑和链路。
它不是 可观测性平台，也不打算替代 SkyWalking / OTel。能力有边界，但已经能在自己的 Spring 微服务里把调用关系、慢请求和错误看清楚。
当前正式版是0.3.0：Starter 在 Maven Central，Server 镜像在 GHCR。
主线 Boot 3.5 / JDK 21；还在 Boot 2.7 / Java 8 的，走 0.3.0-boot2。
从 0.1.0 能看链路，到 0.2.0 能留数据、可选加锁，再到现在 RestTemplate / RestClient 出站、可选告警和实验性的 Trace 解释，一步步把监测中心用顺了。
二、两步跑起来
第一步：Docker 起监测中心
bash
docker run --rm -p 9966:9966 \
-e SPRING_INSIGHT_SERVER_STORAGE_MODE=file \
-e SPRING_INSIGHT_SERVER_STORAGE_FILE_PATH=/data/spans.json \
-v spring-insight-data:/data \
ghcr.io/iweidujiang/spring-insight-server:0.3.0浏览器打开：http://localhost:9966/
默认把 Span 落到数据卷里，容器重启数据还在；不想落盘就把 STORAGE_MODE 改成 memory。
想用 SQLite，mode 换成 sqlite，文件指到 /data/insight.db，同样挂卷即可。
仓库根目录也有 compose.yaml，一条 docker compose up -d 等效。
告警、邮件、AI 解释这些，优先在控制台侧栏 设置 页打开，配置写进数据目录的 runtime-settings.json，重启不丢。
第二步：业务服务加依赖
Spring Boot 3 / JDK 21：
xml
<dependency>
<groupId>io.github.iweidujiang</groupId>
<artifactId>spring-insight-agent-starter</artifactId>
<version>0.3.0</version>
</dependency>
yaml
spring:
application:
name: order-service
insight:
server-url: http://localhost:9966还在 Boot 2.7 / Java 8？换成兼容线坐标即可：
xml
<dependency>
<groupId>io.github.iweidujiang</groupId>
<artifactId>spring-insight-agent-starter-boot2</artifactId>
<version>0.3.0-boot2</version>
</dependency>造几笔跨服务调用，等几秒（异步批量上报），刷新控制台------拓扑边和 Trace 列表应该就出来了。
只用新出站埋点（RestTemplate / RestClient）时需要升级 Agent；只想用告警、设置页、AI 解释，可以只换 Server 镜像。
三、跑起来之后能看见什么
仪表盘
慢调用、错误调用的摘要入口，方便从「现象」点进「某条链路」。
服务拓扑
谁调了谁、边上看调用次数；点节点或边可以下钻到相关 Trace。0.3.0 起 RestTemplate / RestClient 出站也会打 CLIENT Span，拓扑不再只靠 Feign 和 Gateway。
链路追踪
列表按 Trace 聚合，支持筛选；详情里是瀑布时间线，以及 Span 的 tags / 错误信息。详情页还可以复制这条 Trace 的 Context。
错误分析
有失败调用时，可以按 HTTP 状态码、异常类收口，再回链路上定位。
设置（0.3.0）
侧栏 设置 里可以打开 Webhook / SMTP 告警，以及可选的「解释 Trace」（OpenAI 兼容，含 DeepSeek）。默认全关；保存后下一轮扫描或解释即生效，不必为改邮箱去重打镜像。
Agent 侧目前覆盖得比较实用：Servlet MVC、OpenFeign、RestTemplate / RestClient、WebFlux / WebClient、Spring Cloud Gateway，以及线程池 Trace 透传；可选导出 spring.insight.* 给 Micrometer / Prometheus。
四、架构为什么要「独立 Server」
有人会问：能不能只引依赖、不另起进程？
技术上可以做进程内嵌入，但跨服务拓扑需要一个大家共用的汇聚点。Sleuth + Zipkin 其实也是同一思路：库负责埋点，Zipkin 负责存和看。
text
业务微服务 × N ──Starter──► 埋点、异步批量上报
独立进程 × 1 ──Docker──► insight-server :9966和 Prometheus 也可以分工：链路 / 拓扑看 Insight，JVM / 连接池 / QPS 继续交给 Actuator + Micrometer。
五、版本发布历史
从画饼到现在的 0.3.0，正式版都发在 Maven Central 和 GHCR 上。兼容线 Boot2 的版本号带 -boot2 后缀，和主线错开，避免坐标打架。
| 版本 | 时间 | 这一版主要解决什么 |
|---|---|---|
| 画饼 | 2026 年初 | 一个还没写代码的开源项目，我先来"画个饼"：Spring Insight |
| 0.1.0 | 2026-09 | 能装、能跑、能看。Starter + Docker 监测中心，拓扑 / 链路 / 瀑布图；Boot2 0.1.0-boot2。发布说明 |
| 0.2.0 | 2026-09-14 | 数据留得住、门口守得住。SQLite / 按时间裁旧、可选上报 Token 与控制台登录、容量可见、错误分析可下钻、Trace Context 可复制 |
| 0.2.1 | 2026-09-17 | 修体验。登录后账户菜单和退出、关于页版本号自动读取、侧栏图标补齐 |
| 0.3.0 | 2026-09-18 | 出站更全、监测中心能开口。RestTemplate / RestClient 埋点；可选 Webhook / SMTP 告警；可选 AI 解释 Trace；控制台设置页 |
完整条目以仓库 CHANGELOG.md 为准。
六、当前边界
- 仍然是轻量辅助排查，不是 OTel / SkyWalking 替代品
- Span 有条数上限；不配落盘时重启会清空（Docker 推荐挂卷 +
file或sqlite） - 告警是阈值 + Webhook / 邮件，不是完整规则引擎，也没有值班表和密钥保险箱
- AI 解释默认关，输出须人工核对
- JVM / JDBC 采集默认关闭（实验开关）
- 没有多租户、OIDC 那一套生产级账号体系（可选 Token / 简易登录从 0.2 开始有）
欢迎开 Issue / PR 。
七、坐标与链接（收藏向）
| 用途 | 地址 |
|---|---|
| 源码 | github.com/iweidujiang... |
| Boot3 Starter | io.github.iweidujiang:spring-insight-agent-starter:0.3.0 |
| Boot2 Starter | io.github.iweidujiang:spring-insight-agent-starter-boot2:0.3.0-boot2 |
| Server 镜像 | ghcr.io/iweidujiang/spring-insight-server:0.3.0 |
| Central（Starter） | central.sonatype.com/artifact/io... |
| 发版说明 | github.com/iweidujiang... |
| SCA 演示工程 | github.com/iweidujiang... |
八、写在最后
这个项目最早只是一篇「还没写代码」的画饼------《一个还没写代码的开源项目，我先来"画个饼"：Spring Insight》。
从画饼到 0.1.0 能装、能跑、能看见调用链，再到 0.2.0 把数据和门口补上、0.3.0 把更多出站和可选告警接进来，中间改过不少需求，也踩过一堆土坑：GPG 签名、PowerShell 拆坏 Maven 参数、Docker 镜像上传......有些坑后来都写进了文档。
今天你只需要 Central 上的 Starter 和 GHCR 上的镜像，两步就能在自己的 Spring 微服务里看「谁调了谁、慢在哪、错在哪」。觉得有用欢迎 Star；有任何问题，可以直接把 Issue 甩过来，感谢不尽！