Archon

微服务依赖图谱与拓扑分析工具

Archon 解析 OpenAPI 3.0 服务定义，构建服务间调用关系，存入 Neo4j 图谱数据库，并提供 CLI 与 Web UI 两种交互方式，帮助理解微服务系统架构、定位调用链路、评估故障爆炸半径。

功能特性

• OpenAPI 解析 — 解析 OpenAPI 3.0 YAML 定义，提取服务信息、端点、上游依赖（x-* 扩展字段）
• 依赖图谱 — 服务、端点、调用关系建模至 Neo4j，支持 LPM 前缀匹配自动织线（Weave）缝合未解析调用
• 拓扑总览 — 基于 AntV G6 的服务拓扑可视化，支持拖拽、缩放
• 服务查询 — 服务列表、接口详情、上下游关系一键查询
• 故障分析 — 爆炸半径（Blast Radius）级联影响评估
• 链路追踪 — 任意两服务间的调用链（Trace）路径查询
• 双端交互 — Go CLI 命令 + React Web 界面

技术架构

┌─────────────────────────────┐        ┌─────────────────────────────┐
│  Frontend (libs/typescript/)│        │  Backend (Go)               │
│  React 18 + Vite + TS       │  HTTP  │  internal/portal (JSON API) │
│  AntV G6 拓扑图              │───────▶│  internal/service (分析)    │
│  分层侧边栏导航              │  /rest │  internal/repository (Neo4j)│
└─────────────────────────────┘  /api  └──────────────┬──────────────┘
      ┌────────────────────────────────────────────────┘
      ▼
┌─────────────────────────────┐
│  Neo4j (图谱数据库, APOC)    │
└─────────────────────────────┘

开发环境： Vite Dev Server :5173 通过 proxy 转发 /rest/api/* 到 Go 后端 :8080，Go 访问 Neo4j :7687。 生产环境： Nginx 按路径分流 — /rest/api/* → Go 后端，/* → 前端构建产物（libs/typescript/dist/）。

快速开始

环境要求

• Go 1.25+
• Neo4j 数据库（需 APOC 插件）
• Node.js 18+（仅前端开发/构建需要）

1. 配置

cp .env.example .env
# 编辑 .env，填入 Neo4j 连接信息

2. 构建与初始化

# 构建 Go 后端
go build -o archon ./cmd

# 扫描示例服务并自动织线
./archon map -d ./examples --auto-weave

# 启动 API 服务
./archon serve --port 8080

3. 启动前端（开发模式）

cd libs/typescript
npm install
npm run dev        # 打开 http://localhost:5173

4. CLI 使用

./archon --help                      # 帮助
./archon map -f path/to/service.yaml # 扫描单个 OpenAPI 文件
./archon map -d ./specs --auto-weave # 扫描目录并自动织线
./archon weave                       # LPM 拓扑缝合
./archon inspect pay-service         # 查看服务元数据
./archon blast pay-service           # 爆炸半径分析
./archon trace order-service pay-service  # 调用链追踪

前端构建（生产模式）

cd libs/typescript
npm run build        # 产物输出到 dist/

如需部署在子路径下（Nginx context-path），构建时注入前缀：

VITE_API_BASE=/archon/rest/api/v1 VITE_BASE=/archon/ npm run build

Docker 部署

一键启动完整系统（Archon Web UI + Neo4j 含 APOC）：

cp .env.example .env        # 设置 NEO4J_PASSWORD（必填）
docker compose up -d --build
# 打开 http://localhost:8080

CLI 用法（在容器内执行）：

docker compose run --rm archon --help
docker compose run --rm -v "$PWD/examples:/examples:ro" archon map -d /examples --auto-weave
docker compose run --rm archon trace order-service pay-service

Neo4j 密码说明：

• NEO4J_PASSWORD 仅在全新数据卷首次启动时通过 NEO4J_AUTH 初始化生效
• 已有数据卷上修改密码：

docker compose exec neo4j cypher-shell -u neo4j -p <旧密码> "ALTER CURRENT USER SET PASSWORD '<新密码>'"

• 改密后请同步更新 .env 中的 NEO4J_PASSWORD，并重新创建容器：docker compose up -d --build（Neo4j healthcheck 与 archon 启动时均读取该环境变量，不更新会导致 healthcheck 静默失败、archon 无法启动）

• 数据持久化于 Docker 卷 neo4j-data，删除数据卷会重新初始化：docker compose down -v

API 概览

后端仅暴露 JSON API（前缀 /rest/api/v1）：

方法	路径	说明
GET	/rest/api/v1/topology	拓扑图数据（节点 + 边）
GET	/rest/api/v1/services	服务列表
GET	/rest/api/v1/services/{name}	服务详情
GET	/rest/api/v1/services/{name}/relations	上下游关系
GET	/rest/api/v1/services/{name}/blast	爆炸半径
GET	/rest/api/v1/trace?source=&target=	调用链

目录结构

├── cmd/                     # CLI 入口（map / weave / inspect / blast / trace / serve）
├── internal/
│   ├── parser/              # OpenAPI 3.0 解析器
│   ├── repository/          # Neo4j 数据访问（含 LPM weave）
│   ├── service/             # 业务分析（inspect / blast / trace）
│   └── portal/              # JSON API 服务
├── libs/typescript/         # 前端（React + Vite + TypeScript）
│   └── src/
│       ├── api/             # API 客户端
│       ├── components/      # 侧边栏 / 输入 / 结果组件
│       ├── pages/           # 拓扑 / 列表 / 详情 / 关系 / 爆炸 / 追踪
│       └── hooks/           # 数据请求 Hooks
├── examples/                # 示例 OpenAPI 服务定义
└── docs/                    # 设计文档

开发

go test ./...                # 运行全部 Go 测试
go vet ./...                 # Go 静态检查
cd libs/typescript && npx tsc --noEmit   # 前端类型检查

License

Apache 2.0