高性能网络遥测数据平台，负责 Agent 管控、数据采集入库、标签富化、统一查询，内置 SaaS 多租户平台（身份/组织/计费/APM）、NetSentry AI 安全分析（LLM 代理 + 威胁检测）与 MCP 性能分析。
DeepShield-Server/
├── config/
│ └── server.yaml # 统一配置文件（控制器/查询器/入库器/平台）
│
├── cmd/
│ └── server/ # 主入口 — 加载配置、启动 Controller + Querier + Ingester
│
├── controller/ # 控制器主体
│ ├── config/ # 配置结构定义
│ ├── http/ # HTTP REST API
│ │ └── router/
│ │ ├── agent/ # NetSentry Agent 路由（心跳/配置同步/数据上报/LLM代理/告警/IOC/MAZU）
│ │ ├── resource/ # 资源管理路由
│ │ ├── vtap/ # 传统 Agent 管理
│ │ └── ai/ # AI 路由
│ ├── grpc/ # gRPC 服务（Agent 控制面同步）
│ ├── cloud/ # 多云资源同步（阿里云/AWS/Azure/腾讯云/...）
│ ├── db/ # 数据库抽象（MySQL/PostgreSQL/DM）
│ ├── election/ # 主控选举
│ ├── genesis/ # Agent 自发现
│ ├── manager/ # 云平台 & K8s 资源管理器
│ ├── monitor/ # 健康监控 & Agent 自动删除
│ ├── recorder/ # 资源记录器（缓存/事件/自愈）
│ ├── tagrecorder/ # 标签字典刷新 & ClickHouse 同步
│ ├── trisolaris/ # Agent 平台数据推送 & gRPC 端点
│ ├── prometheus/ # Prometheus 指标集成
│ └── statsd/ # 内部统计计数器
│
├── ingester/ # 入库器 — Agent 遥测数据接收 & ClickHouse 写入
│ ├── droplet/ # 数据包分发器（流量/事件/Profile 分路）
│ ├── flow_metrics/ # 流量指标聚合 & 入库
│ ├── flow_tag/ # 流量标签写入
│ ├── event/ # 事件/告警入库
│ ├── profile/ # Continuous Profile 入库
│ ├── ext_metrics/ # 外部指标（Prometheus/Telegraf）入库
│ ├── prometheus/ # Prometheus Remote Write 接收
│ ├── pcap/ # PCAP 存储
│ ├── ckissu/ # ClickHouse Schema 升级（ISSU）
│ ├── exporters/ # 数据导出器
│ └── pkg/ # CK 写入器、解码器、geo 库
│
├── querier/ # 查询器 — 统一 SQL 查询引擎
│ ├── engine/ # ClickHouse 查询引擎（标签/指标描述、SQL 翻译）
│ ├── app/ # API 应用（分布式追踪/Trace Map/Flow Map）
│ ├── db_descriptions/ # ClickHouse 表/字段元数据
│ ├── profile/ # Profile 火焰图查询
│ └── tempo/ # Tempo 兼容查询接口
│
├── platform/ # SaaS 平台模块 — 身份/组织/计费/APM/Guardian
│ ├── handler/ # HTTP Handler（Auth/Org/User/ApiKey/Billing/Agent/APM/Guardian）
│ ├── models.go # GORM 数据模型
│ ├── webauth.go # 会话 & API Key 认证中间件
│ ├── billing.go # 用量计费引擎
│ └── provision.go # 组织预配置（ClickHouse 库/表自动创建）
│
├── mcp/ # MCP Server — AI 性能分析（Profile 数据自动分析报告）
│
├── Algorithm/
│ └── MAZU/ # MAZU 威胁检测算法（Python ML 推理）
│
├── ThreatList/ # 威胁情报
│ ├── Maltrail/ # 恶意流量指标库
│ └── SSLBlackList/ # SSL 证书黑名单
│
├── cli/ # deepshield-ctl 命令行工具
├── libs/ # 公共库（编解码/geo/hmap/pool/stats/queue/...）
├── message/ # Protobuf 消息定义（Agent/Controller/Event）
├── agent-installer/ # Agent 安装脚本 & 二进制分发
├── scripts/ # 运维脚本
├── patch/ # 第三方库补丁（clickhouse-go/hashmap）
├── manifests/ # Docker Compose 部署清单
│ └── deepflow-docker-compose/
├── docs/ # 项目文档
│ ├── deployment.md # Docker 部署指南
│ ├── guides/ # 开发/运维指南
│ ├── design/ # 架构设计文档
│ └── reference/ # 模块参考
│
├── server.yaml # 默认配置文件
├── netsentry_config.yaml # NetSentry Agent 行为配置（LLM/定价/限速）
├── install.sh # 一键安装：依赖 + 编译 + Docker 容器
├── start.sh # 启动/停止/状态管理
├── Makefile # 构建入口
└── go.mod # Go module
- Linux (Ubuntu 20.04+ / CentOS 8+ / Debian 11+)
- Go 1.21+
- Docker Engine ≥ 20.10
- protoc + protoc-gen-gofast
git clone <repo-url> DeepShield-Server && cd DeepShield-Server
sudo bash install.sh
安装脚本自动完成：
| 步骤 |
内容 |
| 1 |
检查 Go 环境 |
| 2 |
安装 protoc-gen-gofast |
| 3 |
下载依赖 & 打 patch（clickhouse-go/hashmap） |
| 4 |
编译 bin/deepshield-server |
| 5 |
创建 schema 软链（/etc/metadb、/etc/db_descriptions） |
| 6 |
创建 MySQL & ClickHouse Docker 容器 |
# 安装
sudo bash install.sh
# 服务管理
./start.sh # 启动（含依赖容器检测 + 等待就绪）
./start.sh stop # 停止
./start.sh restart # 重启
./start.sh status # 查看状态（进程/容器/端口/API）
# 手动编译
make server # 编译 → bin/deepshield-server
make querier # 单独编译查询器
make test # 运行单元测试
make clean # 清理构建产物
cd manifests/deepflow-docker-compose
docker compose up -d
详见 docs/deployment.md。
系统使用 server.yaml 作为主配置，所有模块从此文件读取参数：
# server.yaml 主要 section：
log-file: # 日志路径、级别
controller: # HTTP/gRPC 端口、选举、Agent 管理、NetSentry
mysql: # MySQL 连接（元数据存储）
clickhouse: # ClickHouse 连接（标签字典）
netsentry: # NetSentry Agent 配置文件路径
platform: # SaaS 平台模块（身份/计费/APM）
querier: # 查询器端口、ClickHouse、Profile、Trace Map
ingester: # 入库器（暂用默认值，嵌入 controller 启动）
NetSentry Agent 行为通过 netsentry_config.yaml 单独管理：
# netsentry_config.yaml
llm: # LLM 后端（URL/模型/API Key）
rate_limit: # 速率限制（RPM）
pricing: # Token 定价（倍率/基准价）
hyperparams: # 工具调用超时、最大轮数、流式分块
| 端口 |
模块 |
协议 |
说明 |
| 30417 |
Controller |
HTTP |
REST API（Agent 管控、资源管理） |
| 30035 |
Controller |
gRPC |
Agent 控制面（配置同步、平台数据推送） |
| 30033 |
Ingester |
gRPC |
Agent 数据面（遥测数据上报） |
| 20416 |
Querier |
HTTP |
统一查询 API |
| 20417 |
Platform |
HTTP |
SaaS 平台（身份/组织/计费/APM/Guardian） |
| 30130 |
MySQL |
TCP |
元数据存储 |
| 8123/9000 |
ClickHouse |
HTTP/Native |
时序数据存储 |
| 端点 |
说明 |
GET /v1/vtaps/ |
Agent 列表 |
GET /v1/controllers/ |
Controller 列表 |
GET /v1/health/ |
健康检查 |
POST /v1/vtap-group-configuration/ |
Agent 组配置 |
| 端点 |
说明 |
POST /v1/agents/heartbeat |
Agent 心跳 & 配置下发 |
POST /v1/agents/sync |
全量数据同步 |
POST /v1/agents/ingest |
遥测数据批量上报 |
POST /v1/agents/chat |
LLM 对话代理（SSE 流式） |
POST /v1/agents/alert-rules |
告警规则同步 |
GET /v1/agents/ioc |
IOC 指标下发 |
POST /v1/agents/mazu/detect |
MAZU 威胁检测 |
GET /v1/agents/baseline |
流量基线查询 |
GET /v1/agents/usage |
Agent Token 用量 |
GET /v1/agents/data/query |
反向数据拉取 |
GET /v1/agents/pull/*path |
Agent 数据代理 |
| 端点 |
说明 |
GET /v1/query/ |
统一 SQL 查询（跨 metrics/traces/logs/events） |
POST /v1/trace_map |
分布式追踪拓扑 |
POST /v1/flow_map |
流量拓扑 |
GET /v1/profile/ |
Continuous Profile 查询 |
| 端点 |
说明 |
POST /api/v1/auth/register |
用户注册 |
POST /api/v1/auth/login |
登录 |
POST /api/v1/auth/logout |
登出 |
GET /api/v1/auth/me |
当前用户信息 |
| 端点 |
说明 |
GET /api/v1/users |
用户列表 |
PUT /api/v1/users/:id |
更新用户角色/状态 |
DELETE /api/v1/users/:id |
删除用户 |
GET /api/v1/organization |
组织信息 |
PUT /api/v1/organization |
更新组织 |
| 端点 |
说明 |
GET /api/v1/api-keys |
API Key 列表 |
POST /api/v1/api-keys |
创建 API Key |
DELETE /api/v1/api-keys/:id |
吊销 API Key |
POST /api/v1/api-keys/:id/reveal |
查看 API Key 明文 |
| 端点 |
说明 |
POST /api/v1/agents/register |
Agent 注册（API Key 绑定组织） |
GET /api/v1/agents/status |
Agent 状态列表 |
GET /api/v1/server-info |
服务器连接信息 |
GET /agent/install.sh |
Agent 安装脚本下载 |
| 端点 |
说明 |
GET /api/v1/apm/services |
服务列表 |
GET /api/v1/apm/services/:name |
服务详情 |
GET /api/v1/apm/services/:name/dependencies |
服务依赖拓扑 |
GET /api/v1/apm/operations |
操作列表 |
GET /api/v1/apm/traces |
Trace 查询 |
GET /api/v1/apm/traces/:trace_id |
Trace 详情 |
GET /api/v1/apm/spans/:span_id |
Span 详情 |
GET /api/v1/apm/topology |
全局拓扑 |
GET /api/v1/apm/stats |
APM 统计 |
| 端点 |
说明 |
POST /api/v1/guardian/analyze |
触发安全分析 |
GET /api/v1/guardian/stories |
安全故事列表 |
GET /api/v1/guardian/stories/:id |
故事详情 |
| 端点 |
说明 |
GET /api/v1/billing/plans |
套餐列表 |
POST /api/v1/billing/subscriptions |
创建订阅 |
GET /api/v1/billing/usage |
当前用量 |
GET /api/v1/billing/usage/hourly |
逐小时用量 |
GET /api/v1/billing/estimated-cost |
预估费用 |
GET /api/v1/billing/invoices |
账单列表 |
POST /api/v1/billing/invoices/generate |
生成账单 |
GET /api/v1/billing/alerts |
费用告警 |
| 端点 |
说明 |
GET /api/v1/data/overview |
数据概览 |
GET /api/v1/infra/hosts |
主机列表 |
GET /api/v1/infra/processes |
进程列表 |
GET /api/v1/metrics/list |
指标列表 |
GET /api/v1/metrics/query |
指标查询 |
| 组件 |
技术 |
说明 |
| Controller |
Go + Gin + gRPC |
Agent 管控、资源同步、标签富化、选举、健康监控 |
| Ingester |
Go + gRPC + ClickHouse |
高吞吐遥测数据接收，批量写入 ClickHouse，无消息队列 |
| Querier |
Go + Gin + ClickHouse |
统一 SQL 查询引擎，跨 metrics/traces/logs/events |
| Platform |
Go + Gin + GORM + MySQL |
SaaS 多租户：身份/组织/API Key/计费/APM/Guardian |
| MCP |
Go + mcp-go |
AI 驱动的 Profile 性能分析报告 |
| NetSentry |
Go |
Agent 安全管控：LLM 代理/定价心跳/告警规则/IOC 下发/MAZU |
| MAZU |
Python + ML |
威胁检测算法（异常流量推理） |
| ThreatList |
数据 |
Maltrail 恶意流量指标 + SSL 证书黑名单 |
| 标签富化 |
Go |
K8s metadata / 云资源标签 / 自定义业务标签，入库时解析 |
| 多云同步 |
Go |
阿里云/AWS/Azure/腾讯云/华为云/... 资源自动发现 |
| CLI |
Go |
deepshield-ctl 命令行管理工具 |
| 存储 |
MySQL + ClickHouse |
元数据 + 列式时序数据，支持 Schema 自动升级 |
| 协议 |
Protobuf + gRPC |
Agent ↔ Server 高效通信，自研流控 + exactly-once |
| 认证 |
JWT + Session + API Key |
多租户身份体系，SHA-256 Key 哈希 |
┌─────────────────────────────────────────────┐
│ DeepShield Server │
│ │
Agent ──gRPC───── │ Controller (:30417/30035) │
(NetSentry/ │ ├─ Agent 管控 & 配置同步 │
传统 Agent) │ ├─ 资源同步 (K8s/Cloud) │
│ ├─ 标签富化 & 字典刷新 │
│ ├─ NetSentry 路由 (心跳/LLM/告警/IOC) │
│ └─ 主控选举 & 健康监控 │
│ │
Agent ──gRPC───── │ Ingester (:30033) │
(遥测数据) │ ├─ 流量/指标/事件/Profile 入库 │
│ └─ ClickHouse 批量写入 & Schema 升级 │
│ │
用户/API ──HTTP── │ Querier (:20416) │
│ └─ 统一 SQL 查询 (metrics+traces+logs) │
│ │
Web UI ──HTTP──── │ Platform (:20417) │
│ ├─ 身份/组织/API Key │
│ ├─ APM (服务/追踪/拓扑) │
│ ├─ Guardian (AI 安全分析) │
│ └─ 计费 (用量/订阅/账单) │
│ │
│ MCP Server │
│ └─ Profile 性能分析报告 │
└─────────────┬───────────────────────────────┘
│
┌─────────────┴───────────────┐
│ MySQL │ ClickHouse │
│ (元数据) │ (时序数据) │
└─────────────────────────────┘
| 章节 |
内容 |
| 部署指南 |
Docker Compose 一键部署 |
| 开发指南 |
编译、发布、Agent 运维、性能分析 |
| 架构设计 |
数据流、ClickHouse 追踪设计、数据库优化 |
| 模块参考 |
Agent 配置、控制器架构、DB Schema、命令速查 |
| FAQ |
常见问题 |
见 LICENSE。