release: bump version to 0.42.0
This commit is contained in:
rayd1o
488
docs/technical/zh/manual.md
Normal file
488
docs/technical/zh/manual.md
Normal file
@@ -0,0 +1,488 @@
|
||||
# Planet 使用手册
|
||||
|
||||
这份手册面向日常使用、演示、开发联调和本地运维。它覆盖四个核心入口：
|
||||
|
||||
- `planet.sh`：本地启动、停止、重启、健康检查和日志入口
|
||||
- Earth：公开 3D 地球态势页面
|
||||
- 控制台：登录后的管理后台
|
||||
- Docs：公开开发文档与使用手册
|
||||
|
||||
快速启动路径见 [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/quickstart.md)。
|
||||
|
||||
## 入口总览
|
||||
|
||||
默认启动后，常用地址如下：
|
||||
|
||||
| 名称 | 地址 | 是否需要登录 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| Earth | `http://localhost:3000/earth` | 否 | 3D 地球、图层、BGP、卫星、海缆、新闻态势 |
|
||||
| Docs | `http://localhost:3000/docs` | 否 | 开发文档、技术说明、使用手册 |
|
||||
| 控制台 | `http://localhost:3000/admin` | 是 | 数据、配置、告警、日志和专题观测 |
|
||||
| AI Playground | `http://localhost:3000/playground` | 是 | AI Provider 状态和调试 |
|
||||
| 后端 API 文档 | `http://localhost:8000/docs` | 视接口而定 | FastAPI / OpenAPI 文档 |
|
||||
|
||||
## planet.sh
|
||||
|
||||
`planet.sh` 是本地开发和演示的主控脚本。优先使用它管理服务，而不是手动分别启动前端、后端、数据库和 AI Provider。
|
||||
|
||||
### 启动
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
|
||||
默认行为：
|
||||
|
||||
- 启动 PostgreSQL 和 Redis
|
||||
- 启动 AI Provider
|
||||
- 启动后端 API
|
||||
- 启动前端 Vite dev server
|
||||
- 输出 Earth、控制台、Playground 和后端 API 文档入口
|
||||
|
||||
可指定端口：
|
||||
|
||||
```bash
|
||||
./planet.sh start -b 8001 -f 3001 -a 8101
|
||||
```
|
||||
|
||||
参数含义：
|
||||
|
||||
| 参数 | 含义 |
|
||||
| --- | --- |
|
||||
| `-b <port>` | 后端端口 |
|
||||
| `-f <port>` | 前端端口 |
|
||||
| `-a <port>` | AI Provider 端口 |
|
||||
| `--allow-lan` | 允许局域网访问 |
|
||||
| `--verbose` | 在执行过程中显示更多命令输出 |
|
||||
|
||||
### 停止
|
||||
|
||||
```bash
|
||||
./planet.sh stop
|
||||
```
|
||||
|
||||
会停止：
|
||||
|
||||
- 后端
|
||||
- AI Provider
|
||||
- 前端
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
|
||||
### 重启
|
||||
|
||||
全量重启：
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
|
||||
按模块重启：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -f
|
||||
./planet.sh restart -a
|
||||
./planet.sh restart -d
|
||||
```
|
||||
|
||||
| 参数 | 作用 |
|
||||
| --- | --- |
|
||||
| `-b` | 只重启后端 |
|
||||
| `-f` | 只重启前端 |
|
||||
| `-a` | 只重启 AI Provider |
|
||||
| `-d` | 只重启数据库 |
|
||||
|
||||
按模块重启适合日常开发，能避免无关服务被打断。
|
||||
|
||||
### 创建用户
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
用于首次进入控制台前创建登录账号。脚本会交互式提示用户名、密码和角色。
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
会检查：
|
||||
|
||||
- `planet_*` 容器状态
|
||||
- 后端 `/health`
|
||||
- AI Provider `/health`
|
||||
- 前端页面可达性
|
||||
|
||||
如果某项显示 offline，优先查看对应日志。
|
||||
|
||||
### 日志
|
||||
|
||||
最近日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
持续跟随日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
|
||||
| 参数 | 日志来源 |
|
||||
| --- | --- |
|
||||
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
|
||||
| `-b` / `--backend` | `/tmp/planet_backend.log` |
|
||||
| `-a` / `--ai-provider` | `planet_aiprovider` 容器日志 |
|
||||
|
||||
### 局域网访问
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
适合：
|
||||
|
||||
- WSL 中启动，Windows 浏览器访问
|
||||
- 手机或平板演示 Earth
|
||||
- 局域网其他机器访问同一个开发实例
|
||||
|
||||
启动后注意检查防火墙和 WSL 网络转发。
|
||||
|
||||
## Earth
|
||||
|
||||
Earth 是公开的 3D 态势页面，入口：
|
||||
|
||||
```text
|
||||
http://localhost:3000/earth
|
||||
```
|
||||
|
||||
它是独立前端，实际页面位于：
|
||||
|
||||
- `frontend/public/earth/index.html`
|
||||
- `frontend/public/earth/js/`
|
||||
- `frontend/public/earth/css/`
|
||||
|
||||
React 路由中的 `/earth` 只是用 iframe 承载它。
|
||||
|
||||
### 主要用途
|
||||
|
||||
Earth 用于在一个地球视图中观察：
|
||||
|
||||
- BGP 事件、异常和观测态势
|
||||
- 卫星和轨迹
|
||||
- 海缆与登陆点
|
||||
- 算力中心
|
||||
- 国界、经纬线、高清材质、云图、地形
|
||||
- 新闻直播和态势新闻
|
||||
- 搜索和聚焦对象详情
|
||||
|
||||
### 图层控制
|
||||
|
||||
右侧图层面板用于打开或关闭可视图层。
|
||||
|
||||
常见图层包括：
|
||||
|
||||
- 经纬线
|
||||
- 国界
|
||||
- 高清材质
|
||||
- 大气云图
|
||||
- 海缆
|
||||
- 算力中心
|
||||
- BGP 观测
|
||||
- 卫星
|
||||
- 轨迹
|
||||
- 地形
|
||||
|
||||
部分图层存在依赖关系：
|
||||
|
||||
- 地形依赖高清材质
|
||||
- 轨迹依赖卫星
|
||||
- 高清材质关闭时，地球会显示基座地图和边缘识别效果
|
||||
|
||||
### 搜索
|
||||
|
||||
Earth 搜索支持查找当前地球对象，例如：
|
||||
|
||||
- 海缆
|
||||
- 登陆点
|
||||
- 卫星
|
||||
- 算力中心
|
||||
- BGP 事件
|
||||
- BGP 观测站
|
||||
|
||||
搜索结果可以用于快速定位对象，并打开对应详情。
|
||||
|
||||
### 设置
|
||||
|
||||
设置面板包含：
|
||||
|
||||
- 旋转模式 / 巡航模式
|
||||
- 巡航模块：BGP、新闻
|
||||
- 卫星显示风格：自身发光、真实地表覆盖
|
||||
- 日夜模式
|
||||
- 面板显示开关
|
||||
- 地球默认大小
|
||||
- 地形透明度
|
||||
- 重置设置
|
||||
|
||||
这些设置会保存在浏览器本地存储中。换浏览器或清理站点数据后会恢复默认值。
|
||||
|
||||
### 巡航模式
|
||||
|
||||
巡航模式会让 Earth 自动轮播聚焦目标。
|
||||
|
||||
当前巡航模块包括：
|
||||
|
||||
- BGP
|
||||
- 新闻
|
||||
|
||||
适合演示、监控大屏或无人值守展示。
|
||||
|
||||
### 移动端
|
||||
|
||||
Earth 有移动端抽屉布局。小屏下：
|
||||
|
||||
- 图层控制进入移动抽屉
|
||||
- 搜索、设置、详情会使用移动端面板
|
||||
- 主要交互仍围绕地球对象点击、搜索和图层开关
|
||||
|
||||
### 常见问题
|
||||
|
||||
#### Earth 打不开
|
||||
|
||||
先检查前端是否在线：
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log -f
|
||||
```
|
||||
|
||||
如果前端端口不是 `3000`，使用启动时输出的实际端口。
|
||||
|
||||
#### 图层没有数据
|
||||
|
||||
检查后端和数据源：
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log -b
|
||||
```
|
||||
|
||||
然后进入控制台查看：
|
||||
|
||||
- `/datasources`
|
||||
- `/data`
|
||||
- `/bgp`
|
||||
|
||||
#### 卫星、BGP 或海缆加载慢
|
||||
|
||||
这些图层可能依赖后端接口、外部数据源或首次加载任务。先等待启动任务完成，再查看日志和控制台数据源状态。
|
||||
|
||||
## 控制台
|
||||
|
||||
控制台入口：
|
||||
|
||||
```text
|
||||
http://localhost:3000/admin
|
||||
```
|
||||
|
||||
控制台需要登录。首次使用先创建用户：
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
### 页面结构
|
||||
|
||||
控制台使用 React + Ant Design，左侧菜单按工作域组织。
|
||||
|
||||
常见入口：
|
||||
|
||||
| 页面 | 路由 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| 仪表盘 | `/admin` | 系统概览 |
|
||||
| Earth | `/earth` | 打开公开 Earth 页面 |
|
||||
| 数据源 | `/datasources` | 管理数据源和触发采集 |
|
||||
| 采集数据 | `/data` | 查看采集后的数据 |
|
||||
| BGP 观测 | `/bgp` | 查看 BGP 专题数据 |
|
||||
| 系统告警 | `/alerts/system` | 系统级告警 |
|
||||
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
|
||||
| 态势告警 | `/alerts/situational` | 态势研判告警 |
|
||||
| AI Playground | `/playground` | AI Provider 调试 |
|
||||
| 系统日志 | `/logs` | 查看系统日志，通常仅 super admin 可见 |
|
||||
| 用户管理 | `/users` | 管理用户 |
|
||||
| 系统配置 | `/settings` | 系统配置和电视直播源等设置 |
|
||||
|
||||
### 数据源
|
||||
|
||||
`/datasources` 用于查看和管理采集来源。
|
||||
|
||||
常见操作：
|
||||
|
||||
- 查看数据源状态
|
||||
- 触发采集
|
||||
- 查看最近采集任务
|
||||
- 调整配置项
|
||||
|
||||
如果 Earth 上某类对象缺失，通常先到这里确认数据源是否可用。
|
||||
|
||||
### 采集数据
|
||||
|
||||
`/data` 用于查看采集后的数据表。
|
||||
|
||||
适合排查：
|
||||
|
||||
- 数据是否已经进入系统
|
||||
- 数据更新时间是否符合预期
|
||||
- 某个数据源是否产出了有效记录
|
||||
|
||||
### BGP 观测
|
||||
|
||||
`/bgp` 是 BGP 专题页面。
|
||||
|
||||
它和 Earth 的 BGP 图层互补：
|
||||
|
||||
- Earth 强调空间态势和可视聚焦
|
||||
- 控制台 BGP 页面强调列表、状态、详情和研判
|
||||
|
||||
### 告警
|
||||
|
||||
告警入口包括：
|
||||
|
||||
- `/alerts/system`
|
||||
- `/alerts/bgp`
|
||||
- `/alerts/situational`
|
||||
|
||||
用于查看系统、网络和态势相关告警。
|
||||
|
||||
### 系统配置
|
||||
|
||||
`/settings` 用于管理系统级配置。
|
||||
|
||||
当前常见用途包括：
|
||||
|
||||
- 系统设置
|
||||
- 电视直播源配置
|
||||
- 数据源相关配置入口
|
||||
|
||||
具体可用配置取决于当前登录用户权限。
|
||||
|
||||
### 系统日志
|
||||
|
||||
`/logs` 用于查看系统日志。若菜单中不可见，通常是当前用户角色没有权限。
|
||||
|
||||
排查问题时常用组合：
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
再进入 `/logs` 查看更结构化的运行信息。
|
||||
|
||||
## Docs
|
||||
|
||||
公开文档站入口：
|
||||
|
||||
```text
|
||||
http://localhost:3000/docs
|
||||
```
|
||||
|
||||
当前公开内容来自：
|
||||
|
||||
```text
|
||||
docs/technical/*.md
|
||||
```
|
||||
|
||||
Docs 支持：
|
||||
|
||||
- 分类导航
|
||||
- Markdown 渲染
|
||||
- 表格和代码块
|
||||
- 文档内目录
|
||||
- 本地搜索
|
||||
- technical 文档之间的内部链接跳转
|
||||
|
||||
如果新增 technical 文档，应同步检查：
|
||||
|
||||
- 是否有清晰的一级标题
|
||||
- 是否需要加入 `/docs` 的人工分类和排序
|
||||
- 是否包含不适合公开展示的信息
|
||||
|
||||
## 开发命令约定
|
||||
|
||||
前端命令必须使用 Bun：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
bun install
|
||||
bun run dev
|
||||
bun run build
|
||||
```
|
||||
|
||||
不要使用 `npm run ...`。项目在 WSL / Windows 混合环境中优先依赖 Bun，避免 Node/npm 路径差异带来的兼容问题。
|
||||
|
||||
验证前端构建：
|
||||
|
||||
```bash
|
||||
source ~/.zshrc && bun run build
|
||||
```
|
||||
|
||||
## 故障排查顺序
|
||||
|
||||
遇到问题时，建议按这个顺序排查：
|
||||
|
||||
1. 看服务状态：
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
2. 看最近日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
3. 按模块查看日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
|
||||
4. 只重启有问题的模块：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -f
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
5. 如果数据库或缓存异常，再重启数据库：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -d
|
||||
```
|
||||
|
||||
6. 仍无法恢复时，执行全量重启：
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/quickstart.md)
|
||||
- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/frontend-admin-frontend-context.md)
|
||||
- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/earth-frontend-context.md)
|
||||
- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/earth-layer-style-reference.md)
|
||||
- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/backend-system-service-control.md)
|
||||
- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/backend-collectors.md)
|
||||
Reference in New Issue
Block a user