354 lines
17 KiB
Markdown
354 lines
17 KiB
Markdown
# 智能星球计划 - 面向数据博弈的"智能软关基"态势感知系统
|
||
|
||
## 项目概述
|
||
|
||
**核心愿景：** 构建人类智能空间的"实时全景图"
|
||
|
||
在智能时代，人类认识宇宙的方式本身发生了变化。我们不再只生活在一个由物理空间、自然资源和地理边界所构成的现实层宇宙之中。我们同时生活在一个由信息流、传播结构与智能系统共同塑造的认知层宇宙里。这两个层级的宇宙相互叠加、持续耦合，通过智能系统不断重构人类对存在、秩序与意义的理解。
|
||
|
||
## 系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 物理大屏展示层 │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 偏振片3D大屏 (2m×3m, 4K, 120Hz, 眼镜式) │ │
|
||
│ │ ┌─────────────────────────────────────────────────────────┐ │ │
|
||
│ │ │ 虚幻引擎 UE5 客户端 │ │ │
|
||
│ │ │ ├── 3D地球渲染 (Cesium for UE) │ │ │
|
||
│ │ │ ├── 算力点可视化 (GPU集群、智算中心) │ │ │
|
||
│ │ │ ├── 连接弧线 (光缆、路由、数据流向) │ │ │
|
||
│ │ │ ├── 粒子效果 (数据流动、告警提示) │ │ │
|
||
│ │ │ └── 自动巡航相机 + 交互控制 │ │ │
|
||
│ │ └─────────────────────────────────────────────────────────┘ │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
▲
|
||
│ WebSocket (实时推送)
|
||
│ 120Hz 心跳 / 数据帧同步
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 数据中台服务层 (FastAPI) │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ API Gateway (Redis 限流) │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
│ │ │
|
||
│ ┌───────────────────┬──────────────────────────┬──────────────────┐ │
|
||
│ │ 数据采集服务 │ 核心业务服务 │ 运维管理服务 │ │
|
||
│ │ ┌─────────────┐ │ ┌─────────────────┐ │ ┌─────────────┐ │ │
|
||
│ │ │ 调度中心 │ │ │ WebSocket 服务 │ │ │ 用户管理 │ │ │
|
||
│ │ │ (Celery) │ │ │ (FastAPI) │ │ │ (JWT Auth) │ │ │
|
||
│ │ └─────────────┘ │ └─────────────────┘ │ └─────────────┘ │ │
|
||
│ │ ┌─────────────┐ │ ┌─────────────────┐ │ ┌─────────────┐ │ │
|
||
│ │ │ 采集器池 │ │ │ 数据查询 API │ │ │ 数据源配置 │ │ │
|
||
│ │ │ (10+源) │ │ │ (REST) │ │ │ 监控告警 │ │ │
|
||
│ │ └─────────────┘ │ └─────────────────┘ │ └─────────────┘ │ │
|
||
│ │ ┌─────────────┐ │ ┌─────────────────┐ │ ┌─────────────┐ │ │
|
||
│ │ │ 消息队列 │ │ │ 态势分析引擎 │ │ │ 系统配置 │ │ │
|
||
│ │ │ (Kafka) │ │ │ (计算/聚合) │ │ │ 日志审计 │ │ │
|
||
│ │ └─────────────┘ │ └─────────────────┘ │ └─────────────┘ │ │
|
||
│ └───────────────────┴──────────────────────────┴──────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
▲
|
||
│ 内部 API 调用
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ Web管理端 (React Admin) │
|
||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 登录页 │ 仪表盘 │ 用户管理 │ 数据源配置 │ 任务监控 │ 系统配置 │ │
|
||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
▲
|
||
│ PostgreSQL / Redis
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────┐
|
||
│ 数据存储层 │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ PostgreSQL │ │ TimescaleDB │ │ Redis │ │ MinIO │ │
|
||
│ │ (用户/配置) │ │ (时序数据) │ │ (缓存/会话) │ │ (文件存储) │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 四大核心要素
|
||
|
||
| 层级 | 要素 | 描述 |
|
||
|------|------|------|
|
||
| L1 | 新兴技术支撑 | AI算力、模型生态、云基础设施 |
|
||
| L2 | 关键基础设施 | 卫星、海底光缆、IXP、路由 |
|
||
| L3 | 组织制度资源 | 规则制定权、顶层设计 |
|
||
| L4 | 文化内容供给 | 新闻、社交视频、舆论情绪 |
|
||
|
||
## 技术栈
|
||
|
||
### 后端 (Python FastAPI)
|
||
|
||
| 组件 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| FastAPI | 0.109+ | Web 框架 |
|
||
| SQLAlchemy | 2.0+ | ORM |
|
||
| Alembic | - | 数据库迁移 |
|
||
| Celery | 5.3+ | 任务队列 |
|
||
| Redis | 7.0+ | 缓存/消息 |
|
||
| Kafka | 3.0+ | 事件流 |
|
||
| PyJWT | - | 认证 |
|
||
|
||
### 前端 (React Admin)
|
||
|
||
| 组件 | 用途 |
|
||
|------|------|
|
||
| React 18 | UI 框架 |
|
||
| Ant Design Pro | 管理后台组件 |
|
||
| Axios | HTTP 客户端 |
|
||
| Socket.io-client | WebSocket 客户端 |
|
||
| ECharts | 统计图表 |
|
||
| Bun | 前端包管理与脚本运行 |
|
||
|
||
前端工程统一使用 Bun：
|
||
|
||
- 安装依赖使用 `bun install`
|
||
- 运行脚本使用 `bun run <script>`
|
||
- 不使用 `npm`、`pnpm`、`yarn`
|
||
|
||
### 虚幻引擎客户端
|
||
|
||
| 组件 | 版本 | 用途 |
|
||
|------|------|------|
|
||
| Unreal Engine 5 | 5.3+ | 3D 渲染引擎 |
|
||
| Cesium for Unreal | 1.5+ | 地理可视化 |
|
||
| Niagara | - | 粒子系统 |
|
||
|
||
### 数据库
|
||
|
||
| 组件 | 用途 |
|
||
|------|------|
|
||
| PostgreSQL 15+ | 关系数据 |
|
||
| TimescaleDB | 时序数据扩展 |
|
||
| Redis 7+ | 缓存/会话 |
|
||
| MinIO | S3 兼容存储 |
|
||
|
||
### 部署
|
||
|
||
| 组件 | 用途 |
|
||
|------|------|
|
||
| Docker 24+ | 容器化 |
|
||
| Docker Compose | 本地部署 |
|
||
| Nginx | 反向代理 |
|
||
|
||
## 角色权限
|
||
|
||
| 角色 | 权限范围 |
|
||
|------|----------|
|
||
| **超级管理员** | 全部权限 |
|
||
| **管理员** | 除用户管理外的全部 |
|
||
| **操作员** | 查看 + 操作 |
|
||
| **只读用户** | 仅查看大屏和报表 |
|
||
|
||
## 数据采集策略
|
||
|
||
| 优先级 | 数据源 | 采集频率 |
|
||
|--------|--------|----------|
|
||
| P0 | TOP500 | 每 4 小时 |
|
||
| P0 | Epoch AI | 每小时 |
|
||
| P0 | Hugging Face | 每 2 小时 |
|
||
| P0 | GitHub | 每 4 小时 |
|
||
| P0 每日 |
|
||
| P0 | PeeringDB | 每 2 小时 |
|
||
| P1 | Cloudflare Radar | | TeleGeography | 每小时 |
|
||
| P1 | CAIDA BGPStream | 每 15 分钟 |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
├── backend/ # FastAPI 后端
|
||
│ ├── app/
|
||
│ │ ├── api/ # API 路由
|
||
│ │ ├── core/ # 核心配置
|
||
│ │ ├── models/ # 数据模型
|
||
│ │ ├── schemas/ # Pydantic 模型
|
||
│ │ ├── services/ # 业务逻辑
|
||
│ │ └── tasks/ # Celery 任务
|
||
│ └── tests/
|
||
├── frontend/ # React 管理后台
|
||
│ ├── src/
|
||
│ │ ├── components/ # 组件
|
||
│ │ ├── pages/ # 页面
|
||
│ │ ├── services/ # API 服务
|
||
│ │ └── store/ # 状态管理
|
||
│ └── tests/
|
||
├── unreal/ # UE5 大屏客户端
|
||
│ ├── Content/
|
||
│ ├── Source/
|
||
│ └── Plugins/
|
||
├── data/ # 数据文件
|
||
├── docs/ # 文档
|
||
├── scripts/ # 脚本
|
||
├── docker-compose.yml
|
||
├── AGENTS.md
|
||
└── README.md
|
||
```
|
||
|
||
## 快速启动
|
||
|
||
```bash
|
||
# 新机器首次初始化
|
||
./scripts/bootstrap-dev.sh
|
||
# 会自动安装/检查 uv、bun，并同步 Python/前端依赖
|
||
# 会在缺少时生成 backend/.env、aiprovider/.env、frontend/.env.local
|
||
|
||
# 启动前后端服务
|
||
./planet.sh start
|
||
|
||
# 仅重启后端
|
||
./planet.sh restart -b
|
||
|
||
# 仅重启前端
|
||
./planet.sh restart -f
|
||
|
||
# 交互创建用户
|
||
./planet.sh createuser
|
||
|
||
# 查看服务状态
|
||
./planet.sh health
|
||
```
|
||
|
||
前端命令约定：
|
||
|
||
```bash
|
||
cd frontend
|
||
bun install
|
||
bun run dev
|
||
bun run build
|
||
```
|
||
|
||
不要使用 `npm run ...`，避免在 WSL/Windows 混合环境里触发 `cmd.exe` 路径兼容问题。
|
||
|
||
## API 文档
|
||
|
||
启动服务后访问: `http://localhost:8000/docs`
|
||
|
||
## 启动容错参数
|
||
|
||
`planet.sh` 现在为依赖安装、数据库、AI Provider 启动加入了有限次重试，并会在数据库与 `aiprovider` 启动后额外等待 Docker healthcheck。
|
||
|
||
可通过环境变量临时调整:
|
||
|
||
```bash
|
||
# 例: 放宽 AI Provider 与数据库在网络抖动下的自愈次数
|
||
AI_PROVIDER_START_MAX_RETRIES=5 \
|
||
AI_PROVIDER_RETRY_INTERVAL=10 \
|
||
DATABASE_START_MAX_RETRIES=5 \
|
||
DATABASE_RETRY_INTERVAL=10 \
|
||
./planet.sh restart
|
||
```
|
||
|
||
常用参数:
|
||
|
||
- `DEPENDENCY_INSTALL_MAX_RETRIES` / `DEPENDENCY_INSTALL_RETRY_INTERVAL`: 控制 `uv sync`、`bun install` 的重试次数与间隔，默认 `3` 次、`5` 秒
|
||
- `DATABASE_START_MAX_RETRIES` / `DATABASE_RETRY_INTERVAL`: 控制 `postgres`、`redis` 的启动/重启与健康检查自愈，默认 `3` 次、`5` 秒
|
||
- `AI_PROVIDER_START_MAX_RETRIES` / `AI_PROVIDER_RETRY_INTERVAL`: 控制 `aiprovider` 的构建/启动与容器重启自愈，默认 `3` 次、`5` 秒
|
||
- `BACKEND_MAX_RETRIES`: 控制后端进程启动重试次数，默认 `3`
|
||
- `FRONTEND_MAX_RETRIES`: 控制前端 dev server 启动重试次数，默认 `3`
|
||
- `BACKEND_HEALTH_CHECK_ATTEMPTS` / `BACKEND_HEALTH_CHECK_INTERVAL`: 控制后端 HTTP 健康检查等待次数与间隔，默认 `10` 次、`2` 秒
|
||
- `FRONTEND_HEALTH_CHECK_ATTEMPTS` / `FRONTEND_HEALTH_CHECK_INTERVAL`: 控制前端 HTTP 可访问检查等待次数与间隔，默认 `10` 次、`2` 秒
|
||
- `AI_PROVIDER_HEALTH_CHECK_ATTEMPTS` / `AI_PROVIDER_HEALTH_CHECK_INTERVAL`: 控制 `aiprovider` HTTP 健康检查等待次数与间隔，默认 `10` 次、`2` 秒
|
||
|
||
## AI 接口预留
|
||
|
||
项目现在采用“两层”设计:
|
||
|
||
- 主后端暴露稳定业务接口: `GET /api/v1/ai/provider/status`、`POST /api/v1/ai/situational-awareness/analyze`
|
||
- 独立 `aiprovider` 服务负责适配具体模型供应商
|
||
|
||
这样前端和业务代码不直接依赖 OpenAI、本地模型网关或其他订阅服务，后续切换部署方式只需要调整环境变量。
|
||
|
||
主后端建议配置:
|
||
|
||
```env
|
||
AI_PROVIDER_SERVICE_URL=http://localhost:8010
|
||
AI_PROVIDER_SERVICE_TOKEN=change_me
|
||
AI_PROVIDER_TIMEOUT_SECONDS=60
|
||
```
|
||
|
||
`aiprovider` 服务建议配置:
|
||
|
||
```env
|
||
AI_PROVIDER=openai_compatible
|
||
AI_BASE_URL=https://api.openai.com/v1
|
||
AI_API_KEY=your_api_key
|
||
AI_MODEL=gpt-4o-mini
|
||
AI_TIMEOUT_SECONDS=60
|
||
AI_PROVIDER_SERVICE_TOKEN=change_me
|
||
```
|
||
|
||
OpenAI 兼容场景推荐使用:
|
||
|
||
- `AI_PROVIDER=openai_compatible`
|
||
|
||
Claude 兼容场景推荐使用:
|
||
|
||
- `AI_PROVIDER=anthropic`
|
||
- `AI_PROVIDER=anthropic_compatible`
|
||
- `AI_PROVIDER=claude_compatible`
|
||
|
||
Ollama 原生场景推荐使用:
|
||
|
||
- `AI_PROVIDER=ollama`
|
||
|
||
比如 MiniMax 或其他 Claude 兼容网关，可以这样配置:
|
||
|
||
```env
|
||
AI_PROVIDER=claude_compatible
|
||
AI_BASE_URL=https://your-claude-compatible-endpoint.example.com
|
||
AI_API_KEY=your_api_key
|
||
AI_MODEL=your-claude-compatible-model
|
||
AI_TIMEOUT_SECONDS=60
|
||
AI_MAX_TOKENS=1200
|
||
AI_ANTHROPIC_VERSION=2023-06-01
|
||
AI_PROVIDER_SERVICE_TOKEN=change_me
|
||
```
|
||
|
||
如果你要本地直接起模型适配层，项目里已经补了模板:
|
||
|
||
- [aiprovider/.env.example](/home/ray/dev/linkong/planet/aiprovider/.env.example)
|
||
- [docker-compose.local-model.yml](/home/ray/dev/linkong/planet/docker-compose.local-model.yml)
|
||
|
||
推荐映射关系:
|
||
|
||
- `vLLM` / `LM Studio` / `One API`: `AI_PROVIDER=openai_compatible`
|
||
- `MiniMax` / Claude 兼容网关: `AI_PROVIDER=claude_compatible`
|
||
- `Ollama`: `AI_PROVIDER=ollama`
|
||
|
||
运行与调用补充:
|
||
|
||
- `./planet.sh start` 默认会启动 `aiprovider`
|
||
- 其他服务优先调用主后端 `POST /api/v1/ai/situational-awareness/analyze`
|
||
- `backend -> aiprovider` 会透传 `X-Request-ID`
|
||
- `backend -> aiprovider` 与 `aiprovider -> 模型供应商` 都带轻量重试
|
||
|
||
详细文档:
|
||
|
||
- [docs/technical/agents-aiprovider.md](/home/ray/dev/linkong/planet/docs/technical/agents-aiprovider.md)
|
||
- [aiprovider/README.md](/home/ray/dev/linkong/planet/aiprovider/README.md)
|
||
- [docs/technical/frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)
|
||
- [docs/plans/frontend-ai-playground-development-plan.md](/home/ray/dev/linkong/planet/docs/plans/frontend-ai-playground-development-plan.md)
|
||
- [docs/plans/agents-situational-awareness-foundation-plan.md](/home/ray/dev/linkong/planet/docs/plans/agents-situational-awareness-foundation-plan.md)
|
||
|
||
## 前端页面布局规范
|
||
|
||
管理后台页面默认遵循“单屏工作区”原则：
|
||
|
||
- 页头、摘要区、主工作区应在一屏内形成稳定结构
|
||
- 主表格 / 主图表 / 主分析区应占据页面主要可视空间
|
||
- 模块内容超出时优先在卡片、表格、标签页内部滚动
|
||
- 不依赖整页纵向撑开来容纳主要工作区
|
||
|
||
当前推荐参考实现：
|
||
|
||
- [frontend/src/pages/BGP/BGP.tsx](/home/ray/dev/linkong/planet/frontend/src/pages/BGP/BGP.tsx)
|
||
- [docs/technical/frontend-layout-guidelines.md](/home/ray/dev/linkong/planet/docs/technical/frontend-layout-guidelines.md)
|
||
|
||
## License
|
||
|
||
待定
|