智能星球计划 - 面向数据博弈的"智能软关基"态势感知系统

项目概述

核心愿景： 构建人类智能空间的"实时全景图"

在智能时代，人类认识宇宙的方式本身发生了变化。我们不再只生活在一个由物理空间、自然资源和地理边界所构成的现实层宇宙之中。我们同时生活在一个由信息流、传播结构与智能系统共同塑造的认知层宇宙里。这两个层级的宇宙相互叠加、持续耦合，通过智能系统不断重构人类对存在、秩序与意义的理解。

系统架构

┌─────────────────────────────────────────────────────────────────────────┐
│                           物理大屏展示层                                  │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │         偏振片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
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

快速启动

# 新机器首次初始化
./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

前端命令约定：

cd frontend
bun install
bun run dev
bun run build

不要使用 npm run ...，避免在 WSL/Windows 混合环境里触发 cmd.exe 路径兼容问题。

API 文档

启动服务后访问: http://localhost:8000/docs

WSL / Windows 局域网访问

如果服务运行在 WSL 中，而你希望：

• Windows 本机浏览器访问开发服务
• 同一局域网内的手机或其他电脑访问开发服务

推荐按下面顺序排查和配置。

1. 在 WSL 中启动服务

./planet.sh start --allow-lan

这会让前端监听 0.0.0.0:3000，后端监听 0.0.0.0:8000。

2. 先确认 WSL 内部服务正常

在 WSL 中执行：

curl http://localhost:3000
curl http://localhost:8000/health
ss -ltnp | grep -E ':3000|:8000'

预期：

• 3000 返回前端 HTML
• 8000/health 返回健康检查 JSON
• ss 中能看到 0.0.0.0:3000 和 0.0.0.0:8000

如果这一步不通，先不要继续做 Windows 转发。

3. 在 Windows 本机验证 localhost 直通

在 Windows PowerShell 中执行：

curl http://localhost:3000
curl http://localhost:8000/health

在常见的 WSL2 开发环境下，Windows 通常可以直接通过 localhost 访问 WSL 中的服务。

4. 如果需要让局域网设备访问，再做 Windows 端口转发

注意：下面的命令必须在“以管理员身份运行”的 PowerShell 中执行。

先把 Windows 对外网卡上的 3000 / 8000 转发到 Windows 本机 127.0.0.1：

netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=3000
netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8000

netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=3000 connectaddress=127.0.0.1 connectport=3000
netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=8000 connectaddress=127.0.0.1 connectport=8000

再放行 Windows 防火墙：

New-NetFirewallRule -DisplayName "WSL Planet 3000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 3000
New-NetFirewallRule -DisplayName "WSL Planet 8000" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8000

检查转发规则是否生效：

netsh interface portproxy show all

预期能看到：

• 0.0.0.0:3000 -> 127.0.0.1:3000
• 0.0.0.0:8000 -> 127.0.0.1:8000

5. 查 Windows 局域网 IP，并让其他设备访问

在 Windows PowerShell 中执行：

ipconfig

找到当前联网网卡的 IPv4 地址，例如 192.168.8.228。

局域网其他设备可访问：

• http://<Windows局域网IP>:3000/earth
• http://<Windows局域网IP>:3000/admin

例如：

• http://192.168.8.228:3000/earth

6. 常见现象与判断

• WSL 中 curl localhost:3000 能通，但 Windows 访问 WSL 的局域网 IP:3000 不通：这是正常现象之一，优先验证 Windows 的 localhost:3000
• Windows localhost:3000 能通，但局域网设备访问 Windows 局域网 IP:3000 不通：通常缺少 portproxy 或防火墙放行
• whoami /groups 中 S-1-5-32-544 显示 deny only：说明当前 PowerShell 不是提权管理员窗口

7. 本项目一次性验证顺序

建议固定按这个顺序验证：

1. WSL 中执行 curl http://localhost:3000
2. WSL 中执行 curl http://localhost:8000/health
3. Windows 中执行 curl http://localhost:3000
4. Windows 中执行 curl http://localhost:8000/health
5. 管理员 PowerShell 配置 portproxy 和防火墙
6. 用手机或其他电脑访问 http://<Windows局域网IP>:3000/earth

启动容错参数

planet.sh 现在为依赖安装、数据库、AI Provider 启动加入了有限次重试，并会在数据库与 aiprovider 启动后额外等待 Docker healthcheck。

可通过环境变量临时调整:

# 例: 放宽 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、本地模型网关或其他订阅服务，后续切换部署方式只需要调整环境变量。

主后端建议配置:

AI_PROVIDER_SERVICE_URL=http://localhost:8010
AI_PROVIDER_SERVICE_TOKEN=change_me
AI_PROVIDER_TIMEOUT_SECONDS=60

aiprovider 服务建议配置:

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 兼容网关，可以这样配置:

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
• 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
• aiprovider/README.md
• docs/technical/frontend-layout-guidelines.md
• docs/plans/frontend-ai-playground-development-plan.md
• docs/plans/agents-situational-awareness-foundation-plan.md

前端页面布局规范

管理后台页面默认遵循“单屏工作区”原则：

• 页头、摘要区、主工作区应在一屏内形成稳定结构
• 主表格 / 主图表 / 主分析区应占据页面主要可视空间
• 模块内容超出时优先在卡片、表格、标签页内部滚动
• 不依赖整页纵向撑开来容纳主要工作区

当前推荐参考实现：

• frontend/src/pages/BGP/BGP.tsx
• docs/technical/frontend-layout-guidelines.md

License

待定