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

## 项目概述

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

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

## 系统架构

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

## WSL / Windows 局域网访问

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

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

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

端口占用、`iphlpsvc` / portproxy、摄像头和依赖问题的集中排障入口见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。

### 1. 在 WSL 中启动服务

```bash
./planet.sh start --allow-lan
```

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

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

在 WSL 中执行：

```bash
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 中执行：

```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`：

```powershell
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 防火墙：

```powershell
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
```

检查转发规则是否生效：

```powershell
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 中执行：

```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。

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

```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 健康检查等待次数与间隔，默认 `60` 次、`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

待定