EdgeCluster One — 架构图

五层架构总览

绿色实线框 = 已完成并运行；虚线框 = 规划中

已完成 & 运行中

云端上游（当前临时方案）

规划中，尚未实现

✓ 已完成 14 个组件 / 33 个 · AMD 395 (Windows/Ollama) 已接入 · L2 多节点在线

▶ 当前已实现范围 (MVP)

L4 客户端层 ✓ 已接入

Kilo Code

VS Code AI 编程插件

OpenAI Compatible + MCP SSE

✓ 已配置

Claude Code

Anthropic CLI Agent

Anthropic SDK / OpenAI SDK

✓ 兼容接入

Hermes Agent

企业 Agent 框架

OpenAI Compatible

⏳ 规划

OpenCode

开源编程 Agent

OpenAI Compatible

⏳ 规划

↓ LLM 请求 POST /v1/chat/completions · Bearer ec-dev ↓ MCP 工具调用 HTTP/SSE JSON-RPC 2.0

L3 LLM LiteLLM Proxy ✓ 运行中 :8080

OpenAI 兼容

POST /v1/chat/completions

✓ 运行

模型路由

别名 → 上游 mapping

✓ 5 个别名

API Key 鉴权

LITELLM_MASTER_KEY

✓ 运行

重试 & Fallback

429/5xx 最多重试 2 次

✓ num_retries=2

参数清理

drop_params=true

✓ 运行

审计日志 DB

需 PostgreSQL（Prisma）

⏳ 规划

L3 MCP agentgateway ✓ 运行中 :8081 / :15000

MCP SSE 端点

HTTP/SSE · JSON-RPC 2.0

:8081/sse

✓ 运行

stdio 包装

npx MCP Server 子进程

✓ 运行

Tool 审计 UI

Admin 可观测性

:15000/ui

✓ 运行

filesystem × 14

read/write/search 等工具

✓ 已验证

GitHub MCP

@mcp/server-github

⏳ 已预留槽位

EdgeCluster Ops

自研运维 MCP Server

⏳ 规划

↓ OpenAI-Compatible API · BIGMODEL_API_KEY · 当前上游

L2 推理层 ✓ AMD 395 已接入 (Windows/Ollama)

BigModel API

智谱 GLM-4.6 / GLM-4-Flash

open.bigmodel.cn

✓ 云端上游

Ollama (AMD 395 · Windows)

10.253.212.178 · Ollama v0.21.1 · 已接入 ✅

gemma4:latest (8B Q4_K_M) · edgecluster-gemma4

:11434 · think=false / think=true 双模式

✓ 在线

Ollama (AMD 395 · 更多模型)

同一节点 · ROCm 加速待验证

Llama 3.3 70B · Qwen2.5 72B 待拉取

:11434/v1 · OpenAI-compatible

⏳ 待拉取模型

vLLM 节点 (PoC)

4× DGX Spark · TP=4 · 70B

:8000/v1 · 配置已预留

⏳ 待硬件

vLLM 300B 集群

16 节点 · TP=4 PP=4

多节点负载均衡

⏳ 规划

⏳ 规划范围

↓ GPU 计算 · 推理引擎 · Tensor Parallel

L1 硬件层 ✓ AMD 395 已接入

AMD Ryzen AI Max 395

Strix Halo · 40-core RDNA3.5 iGPU · 128GB 统一内存

Windows · Ollama v0.21.1 · gemma4:latest ✅

10.253.212.178:11434 · 已注册 EdgeCluster 节点

✓ 在线 · ROCm 待验证

DGX Spark (NVIDIA)

128GB 统一内存 / 节点

vLLM · TP=4

⏳ 采购中

AMD RX 9070 XT

16GB GDDR6 · ROCm

⏳ 规划

摩尔线程 MTT S80

80GB · 国产化首选

⏳ 规划

高速互联

25/100GbE · RDMA RoCE v2

⏳ 规划

L5 运维管理层 ⏳ 规划

管理后台

React + Ant Design

⏳ 规划

SSO

LDAP / SAML / OIDC

⏳ 规划

审计日志

PostgreSQL · Prisma

⏳ 规划

监控告警

Prometheus + Grafana

⏳ 规划

Token 统计

用量报表 · Chargeback

⏳ 规划

L3 网关层 — 组件内部结构

LiteLLM（LLM 流量）与 agentgateway（MCP 工具流量）并列运行，互不依赖

LiteLLM Proxy

port 8080

入口端点

POST /v1/chat/completions ← 主要入口

GET /v1/models

GET /health/liveliness ← 健康检查（无鉴权）

请求处理管线

鉴权校验

Bearer token = LITELLM_MASTER_KEY

401 → 拒绝

模型路由

model_name → litellm_params（api_base + key）

edgecluster-glm → GLM-4.6

参数清理

drop_params=true：丢弃上游不支持字段

reasoning_content 等 GLM 专有字段

转发至上游

HTTP POST → BigModel / vLLM

支持 stream=true SSE 透传

重试逻辑

429 / 5xx → 最多 2 次重试，retry_after=0

⚠ 注意：Anthropic 透传

/anthropic/v1/messages → 直连真实 Anthropic，不走 model_list
如需路由到 BigModel，使用 /v1/chat/completions + Claude 别名

agentgateway

port 8081 · admin 15000

入口端点

GET /sse ← SSE 连接（客户端订阅）

POST / ← JSON-RPC 请求端点

GET /ui ← Admin UI（:15000）

MCP 会话生命周期

SSE 握手

GET /sse → 建立持久事件流

客户端收到 endpoint 事件

initialize

协商协议版本、声明能力

protocolVersion: 2024-11-05

tools/list

返回 14 个 filesystem 工具描述

name + description + inputSchema

tools/call（循环）

{"name":"read_file","arguments":{...}}

转发至 stdio MCP Server 子进程

stdio → 子进程

npx @modelcontextprotocol/server-filesystem

作用域: /Users/xiaopingfeng

扩展 MCP Server

在 agentgateway/config.yaml 的 targets 下追加即可：
GitHub、EdgeCluster 运维工具等（已预留注释槽位）

端到端数据流

LLM 推理请求（左）与 MCP 工具调用（右）并行独立运行

🧠 LLM 推理请求流 OpenAI API

Kilo Code

POST /v1/chat/completions
Authorization: Bearer ec-dev
{"model":"edgecluster-glm","stream":true}

↓

HTTP · 本地 127.0.0.1

LiteLLM Proxy :8080

① 鉴权 Bearer token
② 查找 model_name → litellm_params
③ drop_params 清理字段
④ 构造上游请求 + BIGMODEL_API_KEY

↓

HTTPS · open.bigmodel.cn/api/paas/v4

BigModel API (GLM-4.6)

推理执行
reasoning_content（内部消耗）
→ content token 流式输出

↓

SSE 流 · data: {"choices":[{"delta":{...}}]}

LiteLLM（SSE 透传）

直接透传 SSE 流至客户端
无额外转换开销

↓

SSE 流 · HTTP 分块传输

Kilo Code

实时渲染 streaming token
显示在编辑器内联

🔧 MCP 工具调用流 JSON-RPC 2.0

Kilo Code Agent

LLM 决策需要调用工具
e.g. 读取文件辅助推理

↓

GET /sse · 建立 SSE 持久连接

agentgateway :8081

① initialize 握手
② tools/list → 返回 14 个工具清单
③ tools/call 分发至目标

↓

JSON-RPC over stdin/stdout

MCP Server（Node.js 子进程）

@modelcontextprotocol/server-filesystem
作用域: /Users/xiaopingfeng
执行实际文件系统操作

↓

stdout · JSON-RPC result

agentgateway

封装结果 → SSE 事件推送
同时写入 audit log（Admin UI）

↓

SSE 事件 · tool result JSON

Kilo Code Agent

工具结果注入 Agent 上下文
继续向 LiteLLM 发起下一轮推理

启动序列

停止旧进程

lsof 查找 :8080 / :8081 → kill PID

启动 LiteLLM + agentgateway

nohup 后台启动，PID 写入 /tmp/edgecluster/*.pid

等待 LiteLLM 就绪

curl /health/liveliness · 超时 30s → 报错

等待 agentgateway 就绪

MCP initialize 探针（需带 Content-Type + Accept 头）

模型路由机制

客户端发送的 model 名 → LiteLLM 路由 → 实际上游，上游切换对客户端透明

客户端 model 名	路由到	实际上游	用途
edgecluster-glm	openai/glm-4.6	BigModel	主力推理，Kilo Code 默认配置
edgecluster-glm-flash	openai/glm-4-flash	BigModel	轻量快速，节约成本场景
claude-3-5-sonnet-20241022	openai/glm-4.6	BigModel	Kilo Code / Claude Code 默认请求名
claude-sonnet-4-5	openai/glm-4.6	BigModel	Anthropic SDK 别名
claude-3-haiku-20240307	openai/glm-4-flash	BigModel	映射到 Flash 变体节约成本
edgecluster-70b ⏳	openai/edgecluster-70b	vLLM :8000	PoC 阶段，硬件就绪后启用
edgecluster-300b ⏳	openai/edgecluster-300b	vLLM 多节点	生产阶段，same-name 多后端 → 负载均衡

Kilo Code 接入（OpenAI 模式）

        Provider : OpenAI Compatible

        Base URL : http://127.0.0.1:8080/v1

        API Key  : ec-dev

        Model ID : edgecluster-glm

        MCP URL  : http://127.0.0.1:8081/sse

Claude Code 接入（环境变量）

        ANTHROPIC_BASE_URL=

          http://127.0.0.1:8080

        ANTHROPIC_API_KEY=ec-dev

        ⚠ /anthropic/* 透传真实 Anthropic

        ✓ 改用 /v1/ + claude 别名绕过

同名多后端 — 负载均衡原理

在 model_list 中注册相同 model_name 的多个 litellm_params，LiteLLM Router 自动 simple-shuffle（随机分发）：

# litellm/config.yaml — 规划：vLLM 多节点
- model_name: edgecluster-300b
  litellm_params:
    model: openai/edgecluster-300b
    api_base: http://192.168.1.11:8000/v1   # node-01
- model_name: edgecluster-300b   # 同名 = 自动负载均衡
  litellm_params:
    model: openai/edgecluster-300b
    api_base: http://192.168.1.12:8000/v1   # node-02

演进路径

三个阶段，上游切换只需改配置，客户端零改动

当前 ✓

MVP

本地开发验证

·LiteLLM :8080
·agentgateway :8081
·Kilo Code 接入
·BigModel GLM-4.6 上游
·filesystem MCP × 14 工具
·start-all.sh 一键启动

⏳ PoC 阶段

本地 vLLM

4× DGX Spark · 70B 推理

·取消注释 vLLM 配置
·TP=4 张量并行
·Llama-3 70B AWQ
·PostgreSQL 审计日志
·Prometheus + Grafana
·LiteLLM UI 用量统计

⏳ 生产阶段

300B 集群

16 节点 · TP=4 PP=4

·300B AWQ Q4 量化
·多节点负载均衡
·100GbE + RDMA 互联
·SSO 登录（LDAP/OIDC）
·合规审计 + Chargeback
·标杆客户部署

⚡ 切换到本地 vLLM — 只需改 3 行配置，重启 LiteLLM

# litellm/config.yaml

model_list:
  # 现有 BigModel 配置保持不变（可作为 Fallback）
  - model_name: edgecluster-glm
    litellm_params:
      model: openai/glm-4.6
      api_base: https://open.bigmodel.cn/api/paas/v4
      api_key: os.environ/BIGMODEL_API_KEY

  # 取消下面注释 ↓ 填入真实 vLLM 节点 IP
  - model_name: edgecluster-70b
    litellm_params:
      model: openai/edgecluster-70b
      api_base: http://192.168.1.11:8000/v1    ← 填入实际 IP
      api_key: none

# 重启: ./start-all.sh
# Kilo Code 侧 model 改为 edgecluster-70b，其余不变

里程碑

里程碑	目标周期	关键交付	状态
M0 — MVP	已完成	LiteLLM + agentgateway + Kilo Code 全栈接通	✓ Done
M1 — PoC	4 周	4 节点 DGX Spark + vLLM 70B + 基础监控	⏳ 待硬件
M2 — Alpha	8 周	管理后台 + SSO + Prometheus + VS Code 插件 PoC	⏳ 规划
M3 — Beta	12 周	300B 集群 + 审计合规 + 首个标杆客户	⏳ 规划

📋 开发进展日志

每次任务完成后更新 · 自动同步到 GitHub Pages

2026-04-24

✓ 完成 L5 Admin Console 系统监控修复 & 升级

· 提取 deps.py 解决循环 import（routers → main → routers）
· 新增 routers/system.py：CPU/内存/GPU 检测（macOS + Linux + ROCm + NVIDIA）
· 仪表盘 stat cards 接入真实系统数据（内存占用、GPU 型号、进程在线数）
· 新增「系统资源监控」页：主机资源 + GPU 卡片 + 进程状态表

✓ 完成 L2 + L1：Ollama & AMD Ryzen AI Max 395 加入架构

· L2 推理层新增 Ollama（:11434 OpenAI-compatible，支持 Llama 3.3 70B / Qwen2.5 72B）
· L1 硬件层新增 AMD Ryzen AI Max 395（Strix Halo · 40-core RDNA3.5 · 128GB 统一内存）
· litellm/config.yaml 新增 Ollama 注释配置段（取消注释即接入）

✓ 完成 GitHub Pages 部署

· 创建公开仓库 fxp/edgecluster-arch
· 启用 GitHub Pages → fxp.github.io/edgecluster-arch
· 每次任务完成后自动同步（update-pages.sh）

✓ 完成 L5 Admin Console MVP 开发

· FastAPI 后端（port 9090）：health / models / keys / spend / logs / system 6 个路由
· 深色主题 SPA 前端：仪表盘、服务健康、模型列表、API Key 管理、用量统计、审计日志
· 整合 LiteLLM API + Ollama API + agentgateway 健康探针

✓ 完成架构图发布 + 完成状态标注

· 5 标签页架构图：系统总览、网关层详图、数据流、模型路由、演进路径
· 总览图每个组件标注完成状态（绿色实线 = 运行中，虚线 = 规划）
· 图例、计数、"当前已实现范围" 分割线

✓ 完成 MVP 全栈验证（LiteLLM + agentgateway + Kilo Code）

· LiteLLM :8080 — 5 模型别名，BigModel GLM-4.6，OpenAI 兼容 ✅
· agentgateway :8081 — MCP SSE，filesystem × 14 工具 ✅
· Kilo Code MCP 配置写入（mcp_settings.json），VS Code 接入 ✅
· start-all.sh 一键启动全栈（LiteLLM + agentgateway + Admin）

2026-04-26

✓ 完成 L5 Admin — 用量统计仪表盘

· 新增 /spend/summary 今日/本月汇总接口
· 新增 /spend/daily 7天趋势接口
· 前端三标签视图：按模型 / 按 Key / 7天趋势（CSS 横向条形图）
· 顶部 stat cards：今日请求、Token 数、费用

✓ 完成 L5 Admin — API Key 完整配额管理

· 新增 PUT /keys/{key} 更新预算/模型/限速
· 新增 POST /keys/{key}/block|unblock 禁用/恢复
· 前端：预算进度条、RPM 显示、复制密钥、编辑弹窗、禁用/恢复按钮
· 创建 Key 时支持 RPM + TPM 限速字段

✓ 完成 L3 agentgateway — MCP 网关管理页

· 新增 routers/mcp.py：解析 config.yaml + 检测 agentgateway 在线状态
· 前端：MCP 网关状态卡、已注册 Server 列表（类型/命令/URL）
· 审计日志页完善（MCP JSONL + LLM 日志双视图）

✓ 完成 Prometheus + Grafana 监控接入

· 新增 GET /api/metrics（Prometheus text format）
· 导出：内存、服务在线状态、平台信息等指标
· 新建 monitoring/docker-compose.yml（Prometheus :9091 + Grafana :3000）
· Admin UI 新增「Prometheus 指标」页（实时预览 + 配置示例）

✓ 完成 SSO 登录页 + 多节点管理

· 登录覆盖层：输入 Admin Key → localStorage 持久化，支持登出
· 新增 routers/nodes.py：节点注册表 CRUD（JSON 文件存储）
· 节点注册/移除/Ping，实时健康检测（异步并发）
· 前端「节点管理」页：本机状态 + 远程节点卡片（延迟、标签、状态）

2026-04-26

✓ 验证全链路集成测试通过（BigModel 作为推理提供方）

· L2 LiteLLM → BigModel GLM：5模型别名，chat/stream/function-calling 全通 ✅
· L3 agentgateway MCP：14个filesystem工具，Session-ID机制正常 ✅
· L2+L3 闭环：LLM 决策工具 → MCP 执行 → 结果回填 → 最终回答（用户提问→读目录→生成答案） ✅
· L4 OpenAI Python SDK 直连 EdgeCluster，流式输出，claude 别名路由均正常 ✅
· L5 Admin Console v0.2 所有 API 真实数据呈现，修复 agentgateway 健康检查误报 ✅
· 发现：glm-4.6 为推理模型，需 max_tokens≥300（推理占约220tok）；glm-4-flash 无推理延迟

2026-04-28

✓ 完成 AMD Ryzen AI Max 395 (Windows/Ollama) — 远程节点接入

· 硬件：AMD Ryzen AI Max 395（Strix Halo · 40-core RDNA3.5 · 128GB · 10.253.212.178）运行 Windows + Ollama v0.21.1，模型 gemma4:latest (8B Q4_K_M)
· LiteLLM 路由：新增 edgecluster-gemma4（think=false）和 edgecluster-gemma4-think（think=true）两个模型别名
· 发现：Gemma4 在中文输入时触发思考模式，reasoning 消耗全部 tokens，content 为空 → 通过 extra_body: think: false 修复
· 节点注册：改写 routers/nodes.py，支持自动探测节点类型（EdgeCluster Admin / Ollama-only）
· 探测顺序：GET /api/health（EdgeCluster）→ GET /api/version（Ollama）→ 返回 node_type / ollama_version / models
· Admin UI 节点卡：展示 node_type 徽章（Ollama/EdgeCluster）、Ollama 版本、模型列表、延迟
· 修复去重 Bug：同一 ID 或同一 URL 注册时均触发更新（不再插入重复条目）
· 验证：注册后 ping 返回 online:true, latency_ms:~70, models:["gemma4:latest"] ✅

2026-04-28

✓ 完成 Admin Console v0.3 — 运维管理层完整实现

· 节点模型管理：GET/POST/DELETE /api/nodes/{id}/models — 列表、Pull（SSE 流式进度）、删除远程 Ollama 节点模型
· 服务生命周期控制：POST /api/system/services/{name}/restart|stop|start — UI 重启 LiteLLM / agentgateway
· 后台健康监控：FastAPI lifespan 启动 asyncio 任务，60s 探测所有服务，内存环形队列存 2h 历史，GET /api/health/history 返回在线率 + Sparkline 数据点
· 实时日志流：GET /api/logs/stream/{service} — SSE tail 日志，支持 ?api_key= query param 鉴权（EventSource 不支持 Header）
· 配置编辑器：GET/PUT /api/config/litellm — 在线编辑 LiteLLM config.yaml，写入前 YAML 校验，保存后自动重启 LiteLLM
· 前端新增 3 页面：服务控制（含在线率 Sparkline）/ 实时日志流（终端仿真）/ 配置编辑器（保存即重启）
· 节点卡片新增「管理模型」按钮 → Modal 内 Pull/删除模型，带进度条
· Dashboard 加入健康历史 Sparkline（后台监控异步注入）
· 双鉴权模式：Bearer Header + ?api_key= Query Param（deps.py 统一支持）

2026-04-29

✓ 完成推理层迁移至 BigModel（AMD 395 暂不在同一网络）

· 全模型别名切换至 BigModel API：edgecluster-gemma4 / gemma4-think / claude-* 均路由至 GLM-4.6 / GLM-4-Flash
· Ollama 条目保留注释（api_base: http://10.253.212.178:11434），回归同局域网时一行取消注释恢复
· 修复 gemma4 离线别名 token 耗尽问题：原别名指向 GLM-4.6（推理模型），在 max_tokens≤200 时 reasoning_content 耗尽 budget，content 为空；改为 GLM-4-Flash（非推理），max_tokens:60 下测试全部正常 ✅
· 发现：GLM-4.6 定位为需要较大 token 预算的推理任务（建议 max_tokens≥500）；日常对话/工具调用推荐 GLM-4-Flash

🔍 根因 gemma4-think 返回 tool_call 而非文字回复 — 根因分析

· 根因：Kilo Code 自动向所有请求注入工具定义（含 answer 工具）；Gemma4 开启思考模式后极度倾向于调用工具而非直接回复，导致返回 {"tool_calls":[{"function":"answer","args":{...}}]}
· 核心矛盾：think 模式 + 外部工具注入 → 模型将"如何回答"也包装成工具调用
· 解决方案：在 Kilo Code 中改用 edgecluster-glm-flash；保留 edgecluster-gemma4-think 用于无工具注入的直接 API 调用场景
· 路由确认方法：① 问模型身份（Gemma4 → "Google DeepMind"，GLM → "ChatGLM"）；② 查响应 model 字段；③ 实时日志流页面查 LiteLLM 路由记录

✓ 修复 LiteLLM 进程启动 — 环境变量传递修复

· 问题：nohup 配合 source .env 在某些 shell 上不能可靠继承环境变量，导致 BIGMODEL_API_KEY 未传入 LiteLLM 进程，返回 AuthenticationError
· 修复：改为 env $(cat .env | grep -v '^#' | xargs) nohup litellm ...，显式将 .env 键值注入子进程
· 启动脚本已知悉，待统一更新 start-all.sh

2026-04-30

✓ 完成 PostgreSQL@16 自动安装 & LiteLLM 数据库初始化（setup-db.sh）

· 幂等安装脚本 bash setup-db.sh：Homebrew 安装 PG@16 → initdb 集群初始化 → 启动 → 创建用户 edgecluster + 数据库 → 写 DATABASE_URL 到 .env → Prisma DB Push — 全程无需手动配置
· Prisma 迁移：prisma db push --schema schema.prisma --skip-generate，首次创建 60 张表（LiteLLM_SpendLogs、LiteLLM_VerificationToken 等），幂等可重复运行
· start-all.sh 集成：新增 _ensure_postgres()，每次启动自动检查并拉起 PG（未安装则打印提示运行 setup-db.sh）
· 关键细节：macOS 需要 LC_ALL="en_US.UTF-8" 才能正常启动 PG（否则 FATAL: postmaster became multithreaded）；脚本中变量全部采用 ${VAR} 形式避免 Unicode 字符解析 Bug

✓ 修复 Admin Console 三项 Bug 修复

· agentgateway 健康探针：原逻辑向 :8081/ POST MCP initialize → SSE 流式响应导致 httpx 超时 → 状态 ❌；改为 GET :15021/healthz/ready（agentgateway 原生就绪探针，约 21ms 返回 200）✅
· 创建 Key 无响应：httpx.HTTPStatusError 的 str(e) 不含响应 body，LiteLLM 的 "DB not connected" 在 body 中被丢弃；修复 _check_db_error() 读取 e.response.text，在无 DB 时抛出 422 + 中文提示；DB 接入后 Key 创建恢复正常并返回完整 sk-... token
· 错误 Toast 样式：showToast(msg, 'error') 新增红色边框 + 自动 6s 关闭（成功 Toast 为 3s），前端 doCreateKey() 增加 try/catch 与 r.ok 判断

🔧 加固 LiteLLM 启动链路加固（遥测挂起 / 环境变量 / 路径空格）

· 启动挂起根因：LiteLLM 启动时向外发出 3× SYN_SENT 遥测请求（目标 127.0.0.2:80），被本地代理拦截 → 挂 2-3 分钟；修复：.env 加 LITELLM_TELEMETRY=False、LITELLM_LOCAL_MODEL_COST_MAP=True，config.yaml 加 telemetry: false，所有启动命令追加 --telemetry False
· 环境变量注入：env $(grep -v '^#' .env | grep '=' | xargs) nohup litellm 确保变量显式注入子进程（规避 nohup 丢变量问题）；注意 .env 注释必须单独一行，不能行内注释
· iCloud 路径空格：system.py/config.py 中用 shlex.quote() 包裹含空格的 iCloud 路径，避免 LiteLLM CLI 把路径中的空格拆成多余参数

⏳ 下一步计划

▸AMD 395 恢复同网络 → Ollama 路由切回 + ROCm 验证

▸AMD 395 拉取 Llama 3.3 70B / Qwen2.5 72B

▸Admin 用量统计页查看真实花费数据（DB 已接入）

▸Grafana 仪表盘 JSON 预配置（自动导入）

▸vLLM 节点接入（DGX Spark 到位后）

▸多节点 LiteLLM 路由聚合（跨节点负载均衡）