┌─────────────────────────────────────────────────────────────────────┐
│                         浏览器展示与运维层                            │
│  ┌──────────────────────────────┐  ┌──────────────────────────────┐ │
│  │ Web Earth                    │  │ React 运维台                  │ │
│  │ frontend/public/earth        │  │ frontend/src                  │ │
│  │ Three.js 地球 / HUD / 新闻    │  │ 数据源 / 告警 / AI 设置       │ │
│  │ 国界精度 / 品牌内容配置       │  │ 提示词配置 / 用户与系统配置   │ │
│  └──────────────────────────────┘  └──────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
                       │ REST / WebSocket
                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                       FastAPI 业务与编排后端                          │
│  ┌────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ │
│  │ 数据 API 与认证     │ │ Earth 新闻增强      │ │ 告警与态势简报   │ │
│  │ JWT / 权限 / 审计   │ │ 位置推断 / 本地化   │ │ BGP / 告警研判   │ │
│  └────────────────────┘ └────────────────────┘ └─────────────────┘ │
│  ┌────────────────────┐ ┌────────────────────┐ ┌─────────────────┐ │
│  │ 系统运行配置        │ │ 默认提示词注册表     │ │ 未来 Agent Runtime│ │
│  │ system_settings     │ │ 代码发布 + DB 覆盖  │ │ 工具/证据/工作流   │ │
│  └────────────────────┘ └────────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
        │ SQLAlchemy / Redis Stream            │ 纯净 LLM 调用
        ▼                                      ▼
┌──────────────────────────────┐      ┌──────────────────────────────┐
│ PostgreSQL / Redis            │      │ aiprovider                   │
│ 用户、配置、采集结果、新闻     │      │ provider + protocol adapter  │
│ Stream、缓存、运行状态         │      │ OpenAI / MiniMax / Ollama 等 │
└──────────────────────────────┘      └──────────────────────────────┘
        ▲
        │ 采集器 / 外部数据源
        ▼
┌─────────────────────────────────────────────────────────────────────┐
│ RSS 新闻、BGP 观测、公开数据源、后续 WebSearch/OCR/语音识别等工具      │
└─────────────────────────────────────────────────────────────────────┘

架构边界:

backend 负责业务语义、证据收集、提示词选择、AI 任务编排、权限和数据落库。
aiprovider 只负责把纯净模型请求适配到不同供应商或协议，不内置具体业务提示词。
默认提示词随代码发布并保存在 backend/app/ai_tasks/default_prompts.json，运维台可在数据库中保存覆盖值，重置时回到当前代码版本的默认提示词。
Earth 新闻保留英文原文，中文展示结果存入 localizations，前端默认展示 zh-CN 的 display_title、display_summary 和中文地域/状态文案。
Earth LLM 指令、语音识别、多角色态势研判属于后续 Agent Runtime 方向，计划见 docs/plans/agents-earth-command-runtime-plan.md。

四大核心要素

层级	要素	描述
L1	新兴技术支撑	AI算力、模型生态、云基础设施
L2	关键基础设施	卫星、海底光缆、IXP、路由
L3	组织制度资源	规则制定权、顶层设计
L4	文化内容供给	新闻、社交视频、舆论情绪

技术栈

后端 (Python FastAPI)

组件	版本	用途
FastAPI	0.109+	Web 框架
SQLAlchemy	2.0+	ORM
uv	-	Python 依赖与命令运行
Redis	7.0+	缓存、Stream 与运行协调
PyJWT	-	认证
APScheduler / 后台任务	-	采集、增强与运行时任务

前端 (React Admin)

组件	用途
React 18	UI 框架
Ant Design Pro	管理后台组件
Axios	HTTP 客户端
Socket.io-client	WebSocket 客户端
ECharts	统计图表
Three.js	Earth 3D 地球渲染
Bun	前端包管理与脚本运行

前端工程统一使用 Bun：

安装依赖使用 bun install
运行脚本使用 bun run <script>
不使用 npm、pnpm、yarn

大屏与 3D 展示方向

当前发布优先使用浏览器 Web Earth。UE5 / Cesium for Unreal / Niagara 可作为后续物理大屏方向接入，但不是本地开发闭环的必需组件。

数据库

组件	用途
PostgreSQL 15+	关系数据
Redis 7+	缓存、Stream、运行状态

部署

组件	用途
Docker 24+	容器化
Docker Compose	本地部署
Nginx	反向代理

角色权限

角色	权限范围
超级管理员	全部权限
管理员	除用户管理外的全部
操作员	查看 + 操作
只读用户	仅查看大屏和报表

数据采集策略

优先级	数据源	采集频率
P0	TOP500	每 4 小时
P0	Epoch AI	每小时
P0	Hugging Face	每 2 小时
P0	GitHub	每 4 小时
P0	海底光缆 / IXP / 卫星等基础设施数据	每日或按源刷新
P0	PeeringDB	每 2 小时
P1	Cloudflare Radar / TeleGeography	每小时
P1	CAIDA BGPStream	每 15 分钟

项目结构

├── backend/               # FastAPI 后端
│   ├── app/
│   │   ├── api/          # API 路由
│   │   ├── core/         # 核心配置
│   │   ├── models/       # 数据模型
│   │   ├── schemas/      # Pydantic 模型
│   │   ├── services/     # 业务逻辑与 AI 任务编排
│   │   └── ai_tasks/     # 默认提示词与 AI 任务定义
│   └── tests/
├── aiprovider/            # 独立模型供应商适配层
├── frontend/              # React 管理后台
│   ├── src/
│   │   ├── components/   # 组件
│   │   ├── pages/        # 页面
│   │   ├── services/     # API 服务
│   │   └── store/        # 状态管理
│   ├── public/earth/      # Web Earth 静态应用
│   └── tests/             # 前端测试
├── 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 本机浏览器访问开发服务
同一局域网内的手机或其他电脑访问开发服务

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

端口占用、iphlpsvc / portproxy、摄像头和依赖问题的集中排障入口见常见问题。

1. 在 WSL 中启动服务

./planet.sh start --allow-lan

这会让前端监听 0.0.0.0:3000，后端监听 0.0.0.0:8000，AI Provider 通过 Docker 发布到 0.0.0.0:8010。启动前脚本会检查这三个端口；如果 WSL/Linux 侧无法释放端口，并检测到 Windows 侧 listener 或旧 portproxy，会请求管理员 PowerShell 清理。

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

在 WSL 中执行：

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

预期：

3000 返回前端 HTML
8000/health 返回健康检查 JSON
8010/health 返回 AI Provider 健康检查 JSON
ss 中能看到 0.0.0.0:3000、0.0.0.0:8000 和 0.0.0.0:8010，或 Docker 已发布 8010

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

3. 在 Windows 本机验证 localhost 直通

在 Windows PowerShell 中执行：

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

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

4. 如果需要让局域网设备访问，清理端口和防火墙

./planet.sh start --allow-lan 不再启动额外的 Windows 端口转发进程。它直接让开发服务对 3000 / 8000 / 8010 开放，并在启动前尝试释放这些端口。端口被 Windows 侧 listener 或旧 portproxy 占用时，脚本会请求一次管理员 PowerShell 清理。

如果以前手动配置过持久 portproxy，若自动请求被取消，可以手动清理，避免 iphlpsvc 继续占用端口：

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 delete v4tov4 listenaddress=0.0.0.0 listenport=8010

脚本会检测 Windows 防火墙是否已放行 3000 / 8000 / 8010。如果缺少规则，会触发一次 Windows UAC 管理员 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
New-NetFirewallRule -DisplayName "WSL Planet 8010" -Direction Inbound -Action Allow -Protocol TCP -LocalPort 8010

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

在 Windows PowerShell 中执行：

ipconfig

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

局域网其他设备可访问：

http://<Windows局域网IP>:3000/earth
http://<Windows局域网IP>:3000/admin
http://<Windows局域网IP>:8000/health
http://<Windows局域网IP>:8010/health

例如：

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 不通：通常是 Windows 防火墙、网络配置或旧 portproxy 残留
whoami /groups 中 S-1-5-32-544 显示 deny only：说明当前 PowerShell 不是提权管理员窗口

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

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

WSL 中执行 curl http://localhost:3000
WSL 中执行 curl http://localhost:8000/health
WSL 中执行 curl http://localhost:8010/health
Windows 中执行 curl http://localhost:3000
Windows 中执行 curl http://localhost:8000/health
Windows 中执行 curl http://localhost:8010/health
按脚本提示完成 Windows 防火墙或端口清理 UAC 请求
用手机或其他电脑访问 Windows 对外端口，例如 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 健康检查等待次数与间隔，默认 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 与智能体接口

项目现在采用“三段式”边界:

backend: 暴露业务接口，负责选择任务提示词、组织证据、调用工具、保存 AI 设置和结果。
aiprovider: 暴露模型网关接口，只负责 provider / protocol 适配，不写入 BGP、新闻、告警等业务提示词。
模型供应商: OpenAI 兼容、MiniMax、Anthropic、Ollama 或其他兼容网关。

这样前端和业务代码不直接依赖某个模型供应商，后续增加 Agent Runtime、Earth 一键 LLM 指令、语音识别或多角色态势研判时，也可以把业务工作流放在后端，而不是污染模型适配层。

当前已落地的 AI 配置能力:

运维台 AI 设置可维护 provider、模型、协议、超时、token 等运行配置。
运维台 AI 设置中的“提示词”页可选择不同功能入口，手动覆盖提示词，并一键重置到默认值。
默认提示词随代码发布，位于 backend/app/ai_tasks/default_prompts.json。
覆盖值保存在数据库运行配置中，升级代码后可继续保留现场配置，也可重置到新版本默认提示词。
态势摘要、告警研判、新闻本地化等入口应使用各自任务提示词；调用 aiprovider 时只传递当前任务所需的 prompt / system_prompt。

主后端建议配置:

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

aiprovider 服务建议配置:

AI_PROVIDER=minimax
AI_PROVIDER_API=anthropic-messages
AI_BASE_URL=https://api.minimaxi.com/anthropic
AI_API_KEY=your_api_key
AI_MODEL=MiniMax-M2.7
AI_TIMEOUT_SECONDS=60
AI_PROVIDER_SERVICE_TOKEN=change_me

推荐映射关系:

vLLM / LM Studio / One API: AI_PROVIDER=openai + AI_PROVIDER_API=openai-completions
MiniMax: AI_PROVIDER=minimax + AI_PROVIDER_API=anthropic-messages
Claude 兼容网关: AI_PROVIDER=anthropic + AI_PROVIDER_API=anthropic-messages
Ollama: AI_PROVIDER=ollama + AI_PROVIDER_API=ollama-generate

比如 MiniMax 可以这样配置:

AI_PROVIDER=minimax
AI_PROVIDER_API=anthropic-messages
AI_BASE_URL=https://api.minimaxi.com/anthropic
AI_API_KEY=your_api_key
AI_MODEL=MiniMax-M2.7
AI_TIMEOUT_SECONDS=60
AI_MAX_TOKENS=1200
AI_ANTHROPIC_VERSION=2023-06-01

如果你要本地直接起模型适配层，项目里已经补了模板:

运行与调用补充:

./planet.sh start 默认会启动 aiprovider
其他服务优先调用主后端 POST /api/v1/ai/situational-awareness/analyze
backend -> aiprovider 会透传 X-Request-ID
backend -> aiprovider 与 aiprovider -> 模型供应商 都带轻量重试

详细文档:

前端页面布局规范

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

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

当前推荐参考实现：

License

待定

Languages

Python 46.1%

JavaScript 23.4%

TypeScript 14.9%

CSS 6.4%

Shell 4.8%

Other 4.3%

README.md Unescape Escape

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

项目概述

系统架构