release: bump version to 0.52.0
This commit is contained in:
linkong
@@ -336,17 +336,50 @@ AIS 观测写入后不会直接替换最终船只记录，而是先保存为 raw
|
||||
- 位置、速度、航向等动态字段会按 freshness 和来源优先级选择。
|
||||
- 静态字段优先保留非空值；冲突候选会记录到详情接口，便于排查多源差异。
|
||||
|
||||
Earth 使用的接口仍是：
|
||||
Earth 船只展示现在使用受控快照接口和实时增量通道：
|
||||
|
||||
```http
|
||||
GET /api/v1/visualization/geo/vessels
|
||||
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/visualization/vessels/{mmsi}
|
||||
GET /api/v1/visualization/vessels/{mmsi}/track
|
||||
GET /api/v1/visualization/vessels/{mmsi}/conflicts
|
||||
GET /api/v1/visualization/vessels/aggregation/diagnostics
|
||||
```
|
||||
|
||||
`/geo/vessels` 会合并 raw observation 聚合结果和 legacy BarentsWatch latest position 结果，避免只接入 AISStream 后把历史 BarentsWatch 船只遮蔽掉。
|
||||
`/api/v1/vessels/snapshot` 必须携带 `bbox` 和 `zoom`，默认 `limit=1000`，最大 `limit=5000`。它只消费 `ais_raw_observations` 聚合结果，不再读取 legacy `vessel_position` / `vessel_static` 作为兜底。旧 `/api/v1/visualization/geo/vessels` 已下线并返回 `410 Gone`。
|
||||
|
||||
实时增量通过 `/ws` 的 `vessels` channel 推送。客户端订阅时必须带当前视口：
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "subscribe",
|
||||
"data": {
|
||||
"channel": "vessels",
|
||||
"bbox": [120.8, 30.7, 122.1, 31.8],
|
||||
"zoom": 12,
|
||||
"limit": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
后端按连接保存轻量订阅条件，只向 bbox 命中的连接发送船只更新。collector 广播会先进入 1 秒节流队列，同一 MMSI 在一个 flush 周期内只保留最新位置，避免高频实时流拖垮 WebSocket。
|
||||
|
||||
### 图层接口与全量统计分离
|
||||
|
||||
Earth 后续迁移到两类接口：
|
||||
|
||||
```http
|
||||
GET /api/v1/data-products
|
||||
GET /api/v1/data-products/{product_id}/status
|
||||
GET /api/v1/layers/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/cables?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/landing-points?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/satellites?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/bgp/anomalies?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/bgp/incidents?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
GET /api/v1/layers/bgp/collectors?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
```
|
||||
|
||||
`/api/v1/data-products/*` 面向聚合面板，统计口径是全量/全局，不受地图 bbox 影响。`/api/v1/layers/*` 面向地图渲染，必须携带 `bbox` 和 `zoom`，默认 `limit=1000`，最大 `limit=5000`；低 zoom 会降级到更小的返回上限，并在 `diagnostics` 中暴露 `degraded`、`truncated`、`limit_clamped` 和 `stats_scope=viewport`。当前版本的非船只图层先复用已有 GeoJSON 转换再做保护层，后续可继续把 bbox 下推到各产品专用查询。
|
||||
|
||||
## 十、采集器设置与连接验证
|
||||
|
||||
@@ -418,4 +451,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
批量采集使用：
|
||||
|
||||
```http
|
||||
POST /api/v1/datasources/trigger-batch
|
||||
```
|
||||
|
||||
请求体可以传 `source_ids` 精确触发选中项；如果不传 `source_ids`，后端按 `product`、`module`、`is_active`、`run_status`、`collected`、`credential_status` 和 `q` 过滤后触发。接口会跳过禁用源、正在运行且未 `force` 的源，以及未到频率窗口的源，并返回 `triggered`、`skipped`、`failed` 三组结果。
|
||||
|
||||
**核心文件**: `backend/app/api/v1/datasources.py`
|
||||
|
||||
@@ -290,6 +290,16 @@ AISStream 使用 WebSocket 实时流，采集器只写入 `ais_raw_observations`
|
||||
|
||||
连接验证会读取保存配置、环境变量和 `~/.zshrc` 中的 `AISSTREAM_API_KEY`。正式采集时，推荐把 API Key 保存到采集器设置；如果只写在 `~/.zshrc`，需要确认后端进程实际继承了该变量，否则连接验证可能可用但 collector 运行时拿不到 key。
|
||||
|
||||
连接验证和正式采集是两个不同动作。设置页出现 `AISStream 凭证已配置，WebSocket endpoint 格式有效` 只说明配置可以用于连接；运行状态仍可能是 `disconnected`。只有 `aisstream_vessels` collector 任务处于 `streaming` / `connected`，并且 `本轮消息数`、`last_seen_at` 持续更新时，全球 AIS 数据才会不断写入本地库。
|
||||
|
||||
新版本不再使用 legacy `/api/v1/visualization/geo/vessels` 作为船只列表入口。Earth 初始状态应调用：
|
||||
|
||||
```http
|
||||
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
```
|
||||
|
||||
该接口只查询本地 `ais_raw_observations` 聚合结果。实时更新走 `/ws` 的 `vessels` channel，订阅时必须提供 `bbox`、`zoom` 和 `limit`。服务端按连接过滤 bbox，并对 collector 广播做 1 秒合并，同一 MMSI 只推送最新位置。
|
||||
|
||||
## 自定义 REST / WebSocket 映射运行时
|
||||
|
||||
文件：
|
||||
|
||||
@@ -286,8 +286,9 @@ AIS 船只图层入口：
|
||||
|
||||
船只图层当前负责：
|
||||
|
||||
- 请求 `/api/v1/visualization/geo/vessels`
|
||||
- 将聚合后的 AIS GeoJSON 转为地球局部坐标 marker 数据；请求默认不传 `limit`，后端和前端都不再默认裁剪到 5000 艘
|
||||
- 请求 `/api/v1/vessels/snapshot` 获取当前视口初始快照；请求必须携带 `bbox`、`zoom`，并传入受控 `limit`
|
||||
- 通过 `/ws` 的 `vessels` channel 订阅后续增量；订阅 payload 同样必须携带当前视口 `bbox`、`zoom`、`limit`
|
||||
- 将聚合后的 AIS GeoJSON 转为地球局部坐标 marker 数据；后端默认 `limit=1000`，最大 `limit=5000`
|
||||
- 通过 `createInteractableLayer()` 注册 Interactable 图标层
|
||||
- 用按航向分桶的 `THREE.Points` 批量渲染普通船只 marker
|
||||
- 按船型映射颜色；`vessels.js` 会用 `vessel_type_name` 和 AIS `vessel_type` 数字共同归一化船型
|
||||
@@ -310,6 +311,10 @@ AIS 船只图层入口：
|
||||
|
||||
AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但船型通常来自低频 `ShipStaticData.Type`。后端会把 `MetaData.ShipName` 补进船名，并将类型码映射为 Cargo / Tanker / Passenger / Fishing / Military；仍缺失的船型需要等待静态 AIS 消息或后续船舶资料 enrichment，不能在前端凭颜色之外的信息臆造细分类。
|
||||
|
||||
旧 `/api/v1/visualization/geo/vessels` 已下线并返回 `410 Gone`。前端打开船只图层时应先按当前视口拉一次 `/api/v1/vessels/snapshot`，再用 WebSocket 接收同一视口内的 upsert 增量；地图拖动或缩放后应重新拉取 snapshot 并重发 vessels 订阅。后端不再把 legacy `vessel_position` / `vessel_static` 合并进船只快照，前端也不应依赖旧表里的 BarentsWatch-only 兜底数据。
|
||||
|
||||
新的图层接口族是 `/api/v1/layers/*`，用于把地图渲染数据和聚合面板统计分开。地图层请求必须带 `bbox`、`zoom` 和受控 `limit`，响应会返回 `visible_count`、`returned_count` 和 `diagnostics`，其中 `degraded/truncated/limit_clamped` 用于前端提示降级。右侧聚合统计不要从图层响应累加，应读取 `/api/v1/data-products` 或 `/api/v1/data-products/{product_id}/status`，因为这些统计保持全量/全局口径，不随当前视口变化。
|
||||
|
||||
船只 hover / click 也不再对渲染对象做 `raycaster.intersectObjects()`。`main.js` 只负责传入当前 Earth、camera、pointer 和命中半径，实际命中计算由 `interactable.js` 的图标层接口完成：
|
||||
|
||||
1. 拖动地球或惯性旋转时跳过 hover picking。
|
||||
|
||||
@@ -163,7 +163,25 @@
|
||||
- 文档内部链接应通过 `transformLink` 转成 `/docs/:slug`
|
||||
- 标题锚点由 `getHeadingId` 注入，避免渲染器自己理解路由状态
|
||||
|
||||
### 6. `TableActions`
|
||||
### 6. `ConnectionTestInput`
|
||||
|
||||
文件：
|
||||
|
||||
- [ConnectionTestInput.tsx](/home/ray/dev/linkong/planet/frontend/src/components/ConnectionTestInput/ConnectionTestInput.tsx)
|
||||
|
||||
用途：
|
||||
|
||||
- Endpoint、Base URL 这类“输入值 + 连接验证”的控制台表单项
|
||||
- AI Provider 和 WebSearch 的连接测试入口
|
||||
- 后续采集器配置如果把连接测试放进输入框，也应复用它
|
||||
|
||||
当前约束：
|
||||
|
||||
- 输入框末端只显示一个插头/连接器图标，不再并排放“测试连接”文字按钮
|
||||
- 禁用的集成能力必须同时置灰输入框和连接测试按钮
|
||||
- 组件只负责输入框与测试入口组合，不保存业务状态；调用方仍负责表单值、loading、disabled 和连接请求
|
||||
|
||||
### 7. `TableActions`
|
||||
|
||||
文件：
|
||||
|
||||
@@ -205,10 +223,13 @@
|
||||
职责：
|
||||
|
||||
- `/ai` 独立承载 LLM Provider、AI Tool 配置和测试台，不再放在 `/settings` 的系统配置 tabs 中
|
||||
- `模型供应商` tab 管理默认 provider、模型、base URL、provider key、本地 `aiprovider` 代理和连接测试
|
||||
- `工具` tab 管理 WebSearch provider、搜索 key、base URL、超时、结果数和高级 provider 参数
|
||||
- `模型供应商` tab 管理默认 provider、模型、base URL、provider key、本地 `aiprovider` 代理和连接测试；provider 和模型输入使用可输入组合框，models.dev 目录停更时用户仍可手动填新 provider/model
|
||||
- `工具` tab 先通过下拉菜单选择工具，再管理对应配置；当前包含 WebSearch 和 OCR
|
||||
- WebSearch 配置包含 provider、搜索 key、base URL、超时、结果数和高级 provider 参数
|
||||
- OCR 配置包含 provider、Base URL、API Key、模型/engine、语言、超时、文件大小上限和输出格式
|
||||
- `测试台` tab 嵌入原 Playground 的真实会话、预设请求和 AI Provider 状态调试
|
||||
- 页面复用 Settings 的单屏 tabs、panel card 和内部滚动样式
|
||||
- AI Provider / WebSearch 的连接测试使用 `ConnectionTestInput`，连接器图标固定在 Base URL 输入框末端；WebSearch 未启用时，除开关外的配置项和测试入口都置灰
|
||||
|
||||
旧的 `/settings?tab=ai` 应跳转到 `/ai?tab=providers`。
|
||||
旧的 `/playground` 应跳转到 `/ai?tab=playground`。
|
||||
|
||||
@@ -1,543 +1,92 @@
|
||||
# Planet 使用手册
|
||||
|
||||
这份手册面向日常使用、演示、开发联调和本地运维。它覆盖四个核心入口：
|
||||
这份手册面向 Planet 的最终用户。从打开浏览器开始，覆盖注册账号、登录、配置数据采集器、配置 AI、使用 Earth 和控制台、阅读文档站。所有操作都在浏览器里完成。
|
||||
|
||||
- `planet.sh`：本地启动、停止、重启、健康检查和日志入口
|
||||
- Earth：公开 3D 地球态势页面
|
||||
- 控制台：登录后的管理后台
|
||||
- Docs：后端 Gatekeeper 受控的文档站，基础使用文档公开，开发/运维文档按权限组开放
|
||||
|
||||
快速启动路径见 [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)。常见排障见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
|
||||
如果你是负责部署或值班的运维，请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)，里面是 shell 命令、日志位置、SMTP 兜底创建用户等内容。
|
||||
|
||||
## 入口总览
|
||||
|
||||
默认启动后，常用地址如下：
|
||||
|
||||
| 名称 | 地址 | 是否需要登录 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| Earth | `http://localhost:3000/earth` | 否 | 3D 地球、图层、BGP、卫星、海缆、新闻态势 |
|
||||
| Docs | `http://localhost:3000/docs` | 部分需要 | 使用手册公开；开发、后端、运维文档按 Gatekeeper 权限组开放 |
|
||||
| FAQ | `http://localhost:3000/docs/faq` | 否 | Windows / WSL、端口、依赖、动捕、凭证和权限排障 |
|
||||
| 控制台 | `http://localhost:3000/admin` | 是 | 数据、配置、告警、日志和专题观测 |
|
||||
| AI | `http://localhost:3000/ai` | 是 | 模型供应商、AI 工具和测试台 |
|
||||
| 后端 API 文档 | `http://localhost:8000/docs` | 视接口而定 | FastAPI / OpenAPI 文档 |
|
||||
| Earth | `http://<域名>/earth` | 否 | 公开 3D 地球态势页面 |
|
||||
| Docs | `http://<域名>/docs` | 部分需要 | 公共文档免登录，开发/运维文档按 Gatekeeper 权限组开放 |
|
||||
| 注册 / 登录 / 找回密码 | `/register`、`/login`、`/forgot-password` | 否 | 自助开通和恢复账号 |
|
||||
| 控制台 | `http://<域名>/admin` | 是 | 数据、采集器、告警、AI、用户、设置 |
|
||||
| AI | `http://<域名>/ai` | 是 | 模型供应商、工具和测试台 |
|
||||
| 后端 API 文档 | `http://<域名>:8000/docs` | 视接口而定 | FastAPI / OpenAPI |
|
||||
|
||||
## planet.sh
|
||||
下面所有 URL 都基于本机演示的默认地址 `http://localhost:3000`，部署到正式环境时把前缀换成你们的访问域名即可。
|
||||
|
||||
`planet.sh` 是本地开发和演示的主控脚本。优先使用它管理服务，而不是手动分别启动前端、后端、数据库和 AI Provider。
|
||||
## 注册账号
|
||||
|
||||
### 启动
|
||||
1. 打开 `http://localhost:3000/login`，点击表单下方"注册账户"。
|
||||
2. 在 `/register` 填写：
|
||||
- **用户名**：3–50 位字符，登录时使用
|
||||
- **邮箱**：用于接收验证码，可在账户设置中修改
|
||||
- **密码**：至少 8 位
|
||||
3. 提交后会跳到验证页，已将 6 位验证码发到你的邮箱。10 分钟内有效。
|
||||
4. 输入验证码，点击"验证并登录"。验证通过后系统会自动写入登录态并跳到控制台。
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
如果 60 秒内没收到邮件：
|
||||
|
||||
默认行为：
|
||||
- 检查垃圾邮件、订阅推广、企业邮件网关
|
||||
- 验证页右下角的"重新发送验证码"会显示 60 秒倒计时，倒计时结束后可重发
|
||||
- 连续输错 5 次后该验证码会失效，需要重发新码
|
||||
|
||||
- 启动 PostgreSQL 和 Redis
|
||||
- 启动 AI Provider
|
||||
- 启动后端 API
|
||||
- 启动前端 Vite dev server
|
||||
- 输出 Earth、控制台、Playground 和后端 API 文档入口
|
||||
如果系统提示"邮件服务尚未配置"，说明管理员还没填 SMTP，请联系管理员开通 SMTP 或在控制台 `/settings -> SMTP 邮件` 完成配置。
|
||||
|
||||
可指定端口：
|
||||
默认注册角色为 `viewer`，可以登录控制台浏览公共内容。要看采集器、用户管理、系统设置等管理类页面，需要 `admin` 或 `super_admin` 在 `/users` 给你升角色。
|
||||
|
||||
```bash
|
||||
./planet.sh start -b 8001 -f 3001 -a 8101
|
||||
```
|
||||
## 登录与找回密码
|
||||
|
||||
参数含义：
|
||||
### 登录
|
||||
|
||||
| 参数 | 含义 |
|
||||
| --- | --- |
|
||||
| `-b <port>` | 后端端口 |
|
||||
| `-f <port>` | 前端端口 |
|
||||
| `-a <port>` | AI Provider 端口 |
|
||||
| `--allow-lan` | 允许局域网访问 |
|
||||
| `--verbose` | 在执行过程中显示更多命令输出 |
|
||||
打开 `/login`，输入用户名和密码即可。登录成功后跳到 `/admin`。
|
||||
|
||||
### AI Provider 环境变量和构建
|
||||
如果提示"邮箱未验证"，页面会自动跳到 `/verify-email`，按提示输入验证码完成验证。
|
||||
|
||||
AI Provider 的运行期配置可以放在两处：
|
||||
### 忘记密码
|
||||
|
||||
| 位置 | 适合内容 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `aiprovider/.env` | 团队约定的本地默认配置 | Docker Compose 会作为 `env_file` 读取 |
|
||||
| `~/.zshrc` | 个人机器上的 provider、模型、密钥和代理变量 | `planet.sh` 启动时会读取常见的 `AI_*`、`SERVICE_*`、`PYTHON_IMAGE`、`UV_IMAGE`、代理变量 |
|
||||
1. 在 `/login` 点击"忘记密码？"，或直接打开 `/forgot-password`。
|
||||
2. 输入注册邮箱，点击"发送验证码"。无论邮箱是否注册，页面都会显示同一句提示（避免账号枚举）。
|
||||
3. 收到验证码后，在下一步填入验证码 + 新密码（至少 8 位），点击"重置密码"。
|
||||
4. 系统会跳回 `/login`，用新密码登录即可。
|
||||
|
||||
推荐写法：
|
||||
## 账户设置
|
||||
|
||||
```bash
|
||||
export AI_PROVIDER=minimax
|
||||
export AI_PROVIDER_API=anthropic-messages
|
||||
export AI_BASE_URL=https://api.example.com/anthropic
|
||||
export AI_API_KEY=sk-change-me
|
||||
export AI_MODEL=MiniMax-M2.7
|
||||
export AI_PROVIDER_SERVICE_TOKEN=change_me
|
||||
```
|
||||
控制台右上角点击你的用户名进入账户设置，可以：
|
||||
|
||||
默认情况下，`planet.sh` 只静态解析 `~/.zshrc` 中简单的 `export KEY=value` 或 `KEY=value` 行，避免 shell 主题、插件或交互初始化拖慢启动。如果变量依赖复杂 shell 展开，可以显式启用 source 模式：
|
||||
- 修改密码：输入当前密码 + 新密码
|
||||
- 修改邮箱：输入新邮箱后系统会发验证码到新地址，验证通过后才生效
|
||||
- 查看权限组：列出你目前拥有的 Gatekeeper 权限组（`docs_user` / `docs_developer` / `docs_admin`）
|
||||
- 登出：清除当前会话
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
||||
```
|
||||
## 控制台总览
|
||||
|
||||
如需完全忽略 `~/.zshrc`：
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
||||
```
|
||||
|
||||
AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改 `aiprovider/.env` 或 `~/.zshrc` 中的模型、密钥、Base URL 不会触发镜像重建；重启 AI Provider 即可让容器读取新配置：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
构建较慢时，优先判断当前卡在哪一层：
|
||||
|
||||
| 现象 | 常见原因 | 处理方式 |
|
||||
| --- | --- | --- |
|
||||
| `transferring context` 很大 | Docker build context 包含前端资源、PDF、数据目录等无关文件 | 当前仓库通过 `.dockerignore` 只发送 AI Provider 必需文件 |
|
||||
| `uv sync` 下载依赖较慢 | 首次构建或缓存为空，网络访问 Python 包较慢 | 等待首次构建完成；后续会复用 BuildKit 的 uv 下载缓存 |
|
||||
| 改密钥后仍显示旧配置 | 容器尚未重启 | 执行 `./planet.sh restart -a` |
|
||||
|
||||
### 停止
|
||||
|
||||
```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
|
||||
- 局域网其他机器访问同一个开发实例
|
||||
|
||||
`--allow-lan` 只负责让前端和后端监听 `0.0.0.0`。如果服务运行在 WSL 中，Windows 本机通常可以通过 `localhost` 访问，但手机或其他电脑访问 `http://<Windows局域网IP>:3000` 还依赖 Windows 端口转发和防火墙放行。
|
||||
|
||||
推荐按顺序判断：
|
||||
|
||||
```bash
|
||||
# 在 WSL 或运行 Planet 的 shell 中
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
如果这里能看到 `0.0.0.0:3000` 和 `0.0.0.0:8000`，但局域网 IP 访问失败，请在管理员 PowerShell 中配置：
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 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 观测
|
||||
- 卫星
|
||||
- AIS 船只
|
||||
- 轨迹
|
||||
- 地形
|
||||
|
||||
部分图层存在依赖关系：
|
||||
|
||||
- 地形依赖高清材质
|
||||
- 轨迹依赖卫星
|
||||
- 高清材质关闭时，地球会显示基座地图和边缘识别效果
|
||||
|
||||
### 图例
|
||||
|
||||
左下角图例会跟随当前聚焦或启用的图层切换。
|
||||
|
||||
当前已覆盖：
|
||||
|
||||
- 海缆
|
||||
- 卫星
|
||||
- 国界线
|
||||
- 算力中心
|
||||
- BGP
|
||||
- AIS 船只
|
||||
|
||||
AIS 船只图例按船型显示颜色：
|
||||
|
||||
- 货轮
|
||||
- 油轮
|
||||
- 客船
|
||||
- 渔船
|
||||
- 军舰
|
||||
- 停泊/低速
|
||||
- 其他船只
|
||||
|
||||
船只图例中的三角形对应地图上的航行船只标记，圆点对应停泊或低速状态。
|
||||
|
||||
### 搜索
|
||||
|
||||
Earth 搜索支持查找当前地球对象，例如：
|
||||
|
||||
- 海缆
|
||||
- 登陆点
|
||||
- 卫星
|
||||
- 算力中心
|
||||
- BGP 事件
|
||||
- BGP 观测站
|
||||
|
||||
搜索结果可以用于快速定位对象，并打开对应详情。
|
||||
|
||||
### 位置候选采集
|
||||
|
||||
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后，使用详情卡中的 `自动采集坐标候选` 或 `重新自动采集坐标` 按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选位置；这些常规来源没有候选时，会使用当前默认 AI Provider 做一次 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。
|
||||
|
||||
候选可以直接在 Earth 上预览。算力中心候选点击 `保存` 后会写入 `compute_center_locations` 维表，并立即刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量；点击后可查看列表，单条采集候选，或用 `一键采用` 从上到下保存最高置信候选。没有可用候选的记录会留在列表中，不会被国家中心点或硬编码 hint 伪造位置。详细流程见 [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)。
|
||||
|
||||
### 设置
|
||||
|
||||
设置面板包含：
|
||||
|
||||
- 旋转模式 / 巡航模式 / 动捕模式
|
||||
- 巡航模块：BGP、新闻、算力中心、船只、海缆、卫星
|
||||
- 视图设置：卫星显示风格、日夜模式、面板显示开关
|
||||
- 动捕调试模式、动捕输入源、只显示骨骼
|
||||
- 地球默认大小
|
||||
- 地形透明度
|
||||
- 重置设置
|
||||
|
||||
这些设置会保存在浏览器本地存储中。换浏览器或清理站点数据后会恢复默认值。
|
||||
|
||||
### 视角控制
|
||||
|
||||
Earth 支持鼠标、触控板和触屏操作。
|
||||
|
||||
常用控制方式：
|
||||
|
||||
| 操作 | 作用 |
|
||||
| --- | --- |
|
||||
| 鼠标左键拖动 | 旋转地球 |
|
||||
| 手指单指拖动 | 在触屏设备上旋转地球 |
|
||||
| 鼠标滚轮 | 放大或缩小视角 |
|
||||
| 双指捏合 | 在触屏设备上放大或缩小视角 |
|
||||
| 缩放按钮 | 按固定步长调整缩放 |
|
||||
| 点击缩放百分比 | 重置到默认缩放 |
|
||||
|
||||
缩放时，顶部胶囊会短暂显示当前缩放比例，例如 `缩放 180%`。这个提示只表示当前视角缩放，不代表数据加载进度；如果页面正在加载数据，加载提示优先显示，缩放提示不会打断加载状态。
|
||||
|
||||
拖动灵敏度会根据当前缩放自动调整。默认视角附近保持常规旋转速度；放大后拖动会逐步变细，适合检查某个区域、船只、卫星或 BGP 事件；缩小后拖动会略快，方便快速浏览全球态势。
|
||||
|
||||
### 动作捕捉控制
|
||||
|
||||
Earth 预留了动作捕捉控制入口，面向大屏和未来 3D 展示。实时链路有两种输入源：默认的 `浏览器摄像头` 会直接用网页 `getUserMedia` 在本机浏览器识别；高级的 `Motion Agent` 会走 `摄像头/RTSP/HTTP -> 本地 Agent -> 本地 WebSocket -> Earth 页面`。两种模式都不会把摄像头帧或实时手势发到云端，也不会复用新闻/RSS 聚合接口。
|
||||
|
||||
默认不自动启用。打开设置里的 `动捕调试模式`，或用 `?motion=1` 打开 Earth 动捕连接后，系统会启动当前选择的输入源。输入源默认是 `浏览器摄像头`，无需安装应用，但页面必须运行在 HTTPS 或 localhost，且用户需要允许浏览器摄像头权限。需要双摄、USB index、手机/网络摄像头流或客户端/边缘设备时，可在设置中切到 `Motion Agent`。默认 Agent 地址是 `ws://127.0.0.1:8765/ws/gestures`，也可用 URL 参数 `motionAgent` 覆盖。
|
||||
|
||||
URL 参数也可以直接指定输入源：`?motion=1&motionProvider=browser` 使用浏览器摄像头；`?motion=1&motionProvider=agent` 使用 Motion Agent；传入 `motionAgent=ws://...` 时会自动选择 Motion Agent。
|
||||
|
||||
当前手势语义：
|
||||
|
||||
| 手势事件 | 作用 |
|
||||
| --- | --- |
|
||||
| `rotate_left` | 地球向左旋转 |
|
||||
| `rotate_right` | 地球向右旋转 |
|
||||
| `rotate_up` | 地球向上旋转 |
|
||||
| `rotate_down` | 地球向下旋转 |
|
||||
| `zoom_in` | 放大视角 |
|
||||
| `zoom_out` | 缩小视角 |
|
||||
| `focus_prev` / `focus_next` | 在当前动捕图层内切换可交互目标 |
|
||||
| `layer_prev` / `layer_next` | 切换动捕候选图层，并巡航到新图层最近目标 |
|
||||
| `confirm` | 确认当前已选目标；当前浏览器识别暂未启用双手上举确认 |
|
||||
|
||||
设置面板中的 `动捕调试模式` 会打开调试面板。浏览器摄像头输入源会在面板内显示本机实时预览，并在其上绘制关节点和连线；`Motion Agent` 输入源只发送归一化骨架事件，不发送原始视频帧。面板里的 `只显示骨骼` 会隐藏视频预览、只保留深色背景和骨架；`停止匹配动作` 会暂停手势触发，但摄像头预览和骨架绘制仍可继续用于调试。未匹配动作时骨架为红色，匹配后变绿并显示当前动作名称。该入口和 `动捕输入源` 控件都已预留 Gatekeeper 权限标记，后续可接入鉴权控制。
|
||||
|
||||
### 巡航模式
|
||||
|
||||
巡航模式会让 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，左侧菜单按工作域组织。
|
||||
|
||||
常见入口：
|
||||
控制台 `http://localhost:3000/admin` 使用 React + Ant Design，左侧菜单按工作域组织。
|
||||
|
||||
| 页面 | 路由 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| 仪表盘 | `/admin` | 系统概览 |
|
||||
| Earth | `/earth` | 打开公开 Earth 页面 |
|
||||
| 数据源 | `/datasources` | 查看数据源和触发采集 |
|
||||
| 采集数据 | `/data` | 查看采集后的数据 |
|
||||
| BGP 观测 | `/bgp` | 查看 BGP 专题数据 |
|
||||
| Earth | `/earth` | 跳到公开 Earth 页面 |
|
||||
| 数据源 | `/datasources` | 数据源目录、触发采集 |
|
||||
| 采集数据 | `/data` | 已落库的数据 |
|
||||
| BGP 观测 | `/bgp` | BGP 专题观测 |
|
||||
| 系统告警 | `/alerts/system` | 系统级告警 |
|
||||
| BGP 告警 | `/alerts/bgp` | BGP 相关告警 |
|
||||
| 态势告警 | `/alerts/situational` | 态势研判告警 |
|
||||
| AI | `/ai` | 模型供应商、WebSearch 等工具和测试台 |
|
||||
| 系统日志 | `/logs` | 查看系统日志，通常仅 super admin 可见 |
|
||||
| 用户管理 | `/users` | 管理用户 |
|
||||
| 系统配置 | `/settings` | 系统配置和电视直播源等设置 |
|
||||
| AI | `/ai` | 模型供应商、工具、测试台 |
|
||||
| 系统日志 | `/logs` | 通常仅 super admin 可见 |
|
||||
| 用户管理 | `/users` | 创建/删除/改角色/调权限组 |
|
||||
| 系统配置 | `/settings` | 系统、SMTP、TV、采集器设置 |
|
||||
|
||||
### 数据源
|
||||
权限不足时菜单项会自动隐藏。如果发现某个菜单看不到，先确认自己的角色和 Gatekeeper 权限组。
|
||||
|
||||
`/datasources` 用于查看采集来源和触发采集。当前页面是“数据源目录”，会把内置数据源和自定义数据源放在同一张列表里展示。
|
||||
## 配置数据采集器
|
||||
|
||||
常见操作：
|
||||
`/settings?tab=collector_credentials` 是"采集器设置"页。这里统一维护所有采集器的连接配置，不仅是凭证。
|
||||
|
||||
- 查看数据源状态
|
||||
- 触发采集
|
||||
- 查看最近采集任务
|
||||
- 打开详情抽屉查看 endpoint、请求头、基础配置和是否为内置数据源
|
||||
|
||||
如果 Earth 上某类对象缺失，通常先到这里确认数据源是否可用。
|
||||
|
||||
数据源列表中的名称点击后只打开信息抽屉，不再承担编辑入口。接口地址、凭证、请求头和自定义数据源配置统一到 `/settings` 的“采集器设置”里维护。
|
||||
|
||||
当有采集任务正在运行时，总体进度下方会出现 `采集中 N` 标签。这个标签和其他状态标签放在同一排，但带有可点击样式；点击后会弹出当前采集中任务列表，显示每个任务的阶段、进度和处理数量。
|
||||
|
||||
### 采集数据
|
||||
|
||||
`/data` 用于查看采集后的数据表。
|
||||
|
||||
适合排查：
|
||||
|
||||
- 数据是否已经进入系统
|
||||
- 数据更新时间是否符合预期
|
||||
- 某个数据源是否产出了有效记录
|
||||
|
||||
### BGP 观测
|
||||
|
||||
`/bgp` 是 BGP 专题页面。
|
||||
|
||||
它和 Earth 的 BGP 图层互补：
|
||||
|
||||
- Earth 强调空间态势和可视聚焦
|
||||
- 控制台 BGP 页面强调列表、状态、详情和研判
|
||||
|
||||
### 告警
|
||||
|
||||
告警入口包括：
|
||||
|
||||
- `/alerts/system`
|
||||
- `/alerts/bgp`
|
||||
- `/alerts/situational`
|
||||
|
||||
用于查看系统、网络和态势相关告警。
|
||||
|
||||
### 系统配置
|
||||
|
||||
`/settings` 用于管理系统级配置。
|
||||
|
||||
当前常见用途包括：
|
||||
|
||||
- 系统设置
|
||||
- 电视直播源配置
|
||||
- 采集器设置
|
||||
|
||||
### AI
|
||||
|
||||
`/ai` 用于管理 AI 运行链路，已经从系统配置中独立出来。旧链接 `/playground` 会跳转到 `/ai?tab=playground`。
|
||||
|
||||
当前包含：
|
||||
|
||||
- `模型供应商`：默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
|
||||
- `工具`：WebSearch provider、搜索 API Key、Base URL、最大结果数、超时和高级 provider 参数
|
||||
- `测试台`：AI Provider 状态、预设请求和真实分析链路调试
|
||||
|
||||
旧链接 `/settings?tab=ai` 会跳转到 `/ai?tab=providers`。
|
||||
|
||||
具体可用配置取决于当前登录用户权限。
|
||||
|
||||
#### 采集器设置
|
||||
|
||||
`/settings?tab=collector_credentials` 当前显示为“采集器设置”。这里统一维护所有采集器的连接配置，而不是只维护凭证。
|
||||
|
||||
使用方式：
|
||||
操作步骤：
|
||||
|
||||
1. 在下拉框选择采集器。
|
||||
2. 查看状态标签：
|
||||
@@ -545,167 +94,242 @@ http://localhost:3000/admin
|
||||
- 所属模块
|
||||
- `启用` / `禁用`
|
||||
- `未检查` / `可用` / `不可用`
|
||||
3. 点击下拉框右侧的插头图标执行健康检查。
|
||||
4. 如果检查通过，状态会变为 `可用`。
|
||||
5. 修改 endpoint、请求头、超时或重试次数后保存。
|
||||
3. 点击下拉框右侧的插头图标执行健康检查。检查通过状态变为 `可用`。
|
||||
4. 修改 endpoint、请求头、超时、重试次数等，然后保存。
|
||||
|
||||
对于免费且不需要凭证的采集器，连接检查会直接请求对应 endpoint。对于需要凭证的采集器，连接检查会走对应凭证链路；如果凭证或 endpoint 相比上次验证成功时发生变化，需要重新点击连接。
|
||||
对于免费且不需要凭证的采集器，连接检查直接打 endpoint；对于需要凭证的采集器走对应凭证链路。如果凭证或 endpoint 相比上次验证成功时发生变化，需要重新点击连接。
|
||||
|
||||
系统判断“已连接”的条件是：
|
||||
系统判断"已连接"的条件：
|
||||
|
||||
- 当前配置已经成功采集过数据；或
|
||||
- 当前配置已经点击过连接按钮并验证成功。
|
||||
- 当前配置已经成功采集过数据，或
|
||||
- 当前配置已经点击过连接按钮并验证成功
|
||||
|
||||
#### BarentsWatch AIS 凭证
|
||||
### BarentsWatch AIS 凭证
|
||||
|
||||
`BarentsWatch AIS` 是需要凭证的内置采集器。选择该采集器后，凭证区域会显示在基础配置上方。
|
||||
|
||||
配置项：
|
||||
`BarentsWatch AIS` 是需要凭证的内置采集器。选择该采集器后，凭证区域显示在基础配置上方：
|
||||
|
||||
- `Client ID`
|
||||
- `Client Secret`
|
||||
- `Endpoint`
|
||||
|
||||
如果已经配置过 secret，输入框会显示脱敏预览。保存时如果保持这个脱敏预览不变，系统会保留原 secret；只有输入新的 secret 才会替换。
|
||||
|
||||
BarentsWatch AIS 支持从以下位置读取凭证：
|
||||
|
||||
1. 控制台采集器设置中保存的凭证。
|
||||
2. 后端环境变量：
|
||||
- `BARENTSWATCH_CLIENT_ID`
|
||||
- `BARENTSWATCH_CLIENT_SECRET`
|
||||
- 兼容历史拼写：`BARRENTSWATCH_CLIENT_ID`、`BARRENTSWATCH_CLIENT_SECRET`
|
||||
3. `~/.zshrc` 中的同名 `export`。
|
||||
如果已配置过 secret，输入框会显示脱敏预览。保存时保持脱敏预览不变就会保留原 secret；只有输入新的 secret 才会替换。
|
||||
|
||||
如果连接失败，页面会弹出凭证获取教程。教程支持：
|
||||
|
||||
- 查看默认教程。
|
||||
- 点击“教程不好用”让 AI Provider 根据默认 prompt 重新生成教程。
|
||||
- 点击“重置”恢复默认教程。
|
||||
- 查看默认教程
|
||||
- 点击"教程不好用"让 AI Provider 用默认 prompt 重新生成
|
||||
- 点击"重置"恢复默认教程
|
||||
|
||||
默认教程以 BarentsWatch 官方 tutorial 为准，并提醒 Live AIS 应选择 `AIS - API`，不是普通 `BarentsWatch - API`。
|
||||
默认教程以 BarentsWatch 官方 tutorial 为准，并提醒 Live AIS 应选择 `AIS - API`。
|
||||
|
||||
### 系统日志
|
||||
### AISStream 实时船舶
|
||||
|
||||
`/logs` 用于查看系统日志。若菜单中不可见，通常是当前用户角色没有权限。
|
||||
`AISStream 实时船舶` 是全球 AIS WebSocket 采集器。连接测试通过只说明 API Key 和 endpoint 格式可用；真正的全球船只数据来自后台 `aisstream_vessels` collector 长连接运行并写入 `ais_raw_observations`。
|
||||
|
||||
排查问题时常用组合：
|
||||
操作步骤：
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log
|
||||
```
|
||||
1. `/settings?tab=collector_credentials` 选择 `AISStream 实时船舶 : aisstream_vessels`
|
||||
2. 在 `AISStream 凭证` 填入 API Key
|
||||
3. Endpoint 保持默认 `wss://stream.aisstream.io/v0/stream`
|
||||
4. 点击插头图标进行连接测试，确认显示 `可用`
|
||||
5. 保存采集器设置
|
||||
6. 到采集调度入口运行 `aisstream_vessels` collector
|
||||
7. 在 `AISStream 运行状态` 中观察：
|
||||
- `streaming` / `connected` 表示正在接收实时流
|
||||
- `本轮消息数` 应持续增长
|
||||
- 如果显示 `disconnected` 且错误为 `ConnectionResetError`，需要重新触发或等待重连
|
||||
|
||||
再进入 `/logs` 查看更结构化的运行信息。
|
||||
## 配置 AI 凭证
|
||||
|
||||
## Docs
|
||||
`/ai?tab=providers` 是 AI 模型管理入口。包含两个核心子 tab：
|
||||
|
||||
文档站入口：
|
||||
- `模型供应商`：默认 LLM provider、模型、Base URL、API Key、本地 `aiprovider` 代理和连接测试
|
||||
- `工具`：通过下拉菜单选择具体工具，当前支持 WebSearch 和 OCR
|
||||
|
||||
```text
|
||||
http://localhost:3000/docs
|
||||
```
|
||||
### 模型供应商
|
||||
|
||||
Docs 正文由后端 API 按权限读取，不再把全部 Markdown 直接打进前端构建产物。当前文档源文件仍位于：
|
||||
provider 和模型既可选预设也可直接输入自定义 id/name。常用字段：
|
||||
|
||||
```text
|
||||
docs/technical/zh/*.md
|
||||
docs/technical/en/*.md
|
||||
```
|
||||
- Provider：例如 `minimax`、`openai`、`anthropic`、`ollama`
|
||||
- 协议适配：`OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
|
||||
- Base URL：模型 API 地址
|
||||
- 默认模型：例如 `gpt-5.1`、`MiniMax-M2.7`
|
||||
- API Key：填入后保存；保存的 Key 在 UI 中显示为脱敏预览
|
||||
- Max Tokens、Anthropic Version：可保持默认
|
||||
- Timeout / Retry：超时和重试次数
|
||||
|
||||
未登录访客默认只能看到 `public` 文档，例如首页、快速开始和使用手册。登录用户如果被分配 Gatekeeper 权限组，可以看到更多技术文档：
|
||||
Base URL 输入框尾端的插头图标会触发连接测试。测试通过会显示当前模型返回的简短回复。
|
||||
|
||||
- `docs_user`：用户操作类文档。
|
||||
- `docs_developer`：Earth、前端、后端、采集器和 AI Provider 等开发文档。
|
||||
- `docs_admin`：服务控制、运维、环境变量和敏感操作文档。
|
||||
### 工具
|
||||
|
||||
`admin` 默认拥有管理文档权限，`super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在控制台“用户管理”中配置。
|
||||
- **WebSearch**：provider、API Key、Base URL、最大结果数、超时、高级 provider 参数。未启用时除"启用"开关外其它配置项和连接测试都会置灰
|
||||
- **OCR**：provider、Base URL、API Key、模型/engine、识别语言、超时、最大文件大小、输出格式
|
||||
|
||||
Docs 支持：
|
||||
旧链接 `/settings?tab=ai` 会跳到 `/ai?tab=providers`。
|
||||
|
||||
- 分类导航
|
||||
- Markdown 渲染
|
||||
- 表格和代码块
|
||||
- 文档内目录
|
||||
- 对当前可见文档搜索
|
||||
- technical 文档之间的内部链接跳转
|
||||
## 系统设置
|
||||
|
||||
如果新增 technical 文档，应同步检查：
|
||||
`/settings` 用于管理系统级配置，常用子 tab：
|
||||
|
||||
- 是否有清晰的一级标题
|
||||
- 是否需要加入后端 Docs metadata 的人工分类和排序
|
||||
- 应归入 `public`、`docs_user`、`docs_developer` 还是 `docs_admin`
|
||||
- **系统显示**：系统名称、刷新间隔、数据保留天数、最大并发任务
|
||||
- **通知策略**：告警邮件开关、收件邮箱、严重/警告/每日摘要通知
|
||||
- **安全策略**：会话超时、最大登录尝试、密码策略
|
||||
- **SMTP 邮件**：注册和找回密码所需的发件配置（仅 `admin` / `super_admin` 可见）
|
||||
- **电视直播**：电视直播源管理
|
||||
- **AI / WebSearch / OCR**：见上节
|
||||
|
||||
## 开发命令约定
|
||||
### SMTP 邮件设置
|
||||
|
||||
前端命令必须使用 Bun：
|
||||
公开注册和验证码功能依赖这一项。`admin` 或 `super_admin` 用户在 `/settings` 进入 `SMTP 邮件` 子 tab，填：
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
bun install
|
||||
bun run dev
|
||||
bun run build
|
||||
```
|
||||
- SMTP 主机、端口
|
||||
- 账号、密码
|
||||
- 发件地址（必填）、发件人名称
|
||||
- STARTTLS（端口 587 常用） 或 隐式 TLS（端口 465）
|
||||
- 超时秒数
|
||||
|
||||
不要使用 `npm run ...`。项目在 WSL / Windows 混合环境中优先依赖 Bun，避免 Node/npm 路径差异带来的兼容问题。
|
||||
填完保存，再点"发送测试邮件"按钮，输入收件人地址试发一封。测试通过后即可让普通用户走 `/register` 自助注册。
|
||||
|
||||
验证前端构建：
|
||||
如果保留密码字段中的脱敏预览不动，保存时不会覆盖原密码；要换密码就输入新值。
|
||||
|
||||
```bash
|
||||
source ~/.zshrc && bun run build
|
||||
```
|
||||
## 用户管理（管理员）
|
||||
|
||||
## 故障排查顺序
|
||||
`/users` 仅 `super_admin` 可创建/删除用户。该页支持：
|
||||
|
||||
遇到问题时，建议按这个顺序排查：
|
||||
- 查看用户列表（用户名、邮箱、角色、是否激活、邮箱是否已验证）
|
||||
- 创建用户：与公开注册等价，但跳过邮箱验证（管理员认账）
|
||||
- 修改角色：`viewer` / `operator` / `admin` / `super_admin`
|
||||
- 调整 Gatekeeper 权限组：`docs_user` / `docs_developer` / `docs_admin`，影响 Docs 站可见文档范围
|
||||
- 禁用 / 启用账号
|
||||
|
||||
1. 看服务状态：
|
||||
要让普通用户能看开发或运维文档，进 `/users` 给他加 `docs_developer` 或 `docs_admin`。
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
## 数据探索
|
||||
|
||||
2. 看最近日志：
|
||||
- `/datasources`：数据源目录。可以按产品域、层级、启用状态、最近执行状态、是否已有采集数据和关键词筛选；勾选多行后可批量采集选中项，未勾选时“采集当前筛选”只触发当前筛选范围。点击名称打开信息抽屉查看 endpoint、请求头、基础配置和是否内置；接口、凭证、请求头的编辑统一在 `/settings` 的"采集器设置"。总体进度下方的 `采集中 N` 标签可点击，展开当前采集任务列表
|
||||
- `/data`：采集后数据表，适合排查"数据是否已经进入系统"、"更新时间是否符合预期"、"某个数据源是否产出有效记录"
|
||||
- `/bgp`：BGP 专题页面，列表 + 详情 + 研判，与 Earth 的 BGP 图层互补
|
||||
- `/alerts/system`、`/alerts/bgp`、`/alerts/situational`：系统、BGP、态势告警
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
## AI 测试台
|
||||
|
||||
3. 按模块查看日志：
|
||||
`/ai?tab=playground` 用于真实分析链路调试。可以：
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
- 选择当前 provider
|
||||
- 用预设请求或自定义 prompt 触发分析
|
||||
- 观察 AI Provider 状态和返回内容
|
||||
|
||||
4. 只重启有问题的模块：
|
||||
旧链接 `/playground` 会跳到这里。
|
||||
|
||||
```bash
|
||||
./planet.sh restart -f
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -a
|
||||
```
|
||||
## Earth 公开页面
|
||||
|
||||
5. 如果数据库或缓存异常，再重启数据库：
|
||||
Earth `http://localhost:3000/earth` 是公开 3D 态势页面，不需要登录。React 路由中的 `/earth` 用 iframe 承载独立前端（位于 `frontend/public/earth/`）。
|
||||
|
||||
```bash
|
||||
./planet.sh restart -d
|
||||
```
|
||||
### 主要用途
|
||||
|
||||
6. 仍无法恢复时，执行全量重启：
|
||||
在一个地球视图中观察：BGP 事件与观测态势、卫星和轨迹、海缆与登陆点、算力中心、国界线/经纬线/高清材质/云图/地形、新闻直播和态势新闻、搜索和聚焦对象详情。
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
### 图层控制
|
||||
|
||||
右侧图层面板用于打开或关闭图层。常见图层：经纬线、国界线、高清材质、大气云图、海缆、算力中心、BGP 观测、卫星、AIS 船只、轨迹、地形。
|
||||
|
||||
依赖关系：
|
||||
|
||||
- 地形依赖高清材质
|
||||
- 轨迹依赖卫星
|
||||
- 高清材质关闭时，地球显示基座地图和边缘识别效果
|
||||
|
||||
### 图例
|
||||
|
||||
左下角图例会跟随当前聚焦或启用的图层切换。已覆盖：海缆、卫星、国界线、算力中心、BGP、AIS 船只。
|
||||
|
||||
AIS 船只图例按船型显示颜色：货轮、油轮、客船、渔船、军舰、停泊/低速、其他船只。三角形对应航行船只标记，圆点对应停泊或低速状态。
|
||||
|
||||
### 搜索
|
||||
|
||||
支持查找海缆、登陆点、卫星、算力中心、BGP 事件、BGP 观测站。结果可快速定位并打开详情。
|
||||
|
||||
### 位置候选采集
|
||||
|
||||
算力中心和 BGP 观测站详情卡支持自动采集坐标候选。点击对象后用"自动采集坐标候选"或"重新自动采集坐标"按钮，后端会从源坐标、开放组织注册 API 和在线地理编码中整理候选；常规来源没有候选时使用当前默认 AI Provider 做 LLM factcheck 兜底。BGP 观测站的已存储位置只用于补齐查询上下文，不会作为候选直接返回。
|
||||
|
||||
候选可以直接在 Earth 预览。算力中心候选点击"保存"后写入 `compute_center_locations` 维表并刷新图层。算力中心图层左上角的通知气泡显示无法渲染的待定位数量；点击查看列表，单条采集候选，或用"一键采用"从上到下保存最高置信候选。没有可用候选的记录会留在列表中，不会被国家中心点或硬编码 hint 伪造位置。详细流程见 [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)。
|
||||
|
||||
### 设置
|
||||
|
||||
设置面板包含：旋转模式 / 巡航模式 / 动捕模式、巡航模块（BGP/新闻/算力中心/船只/海缆/卫星）、视图设置（卫星显示风格、日夜模式、面板显示开关）、动捕调试模式 / 输入源 / 只显示骨骼、地球默认大小、地形透明度、重置设置。
|
||||
|
||||
这些设置保存在浏览器本地存储，换浏览器或清理站点数据后会恢复默认值。
|
||||
|
||||
### 视角控制
|
||||
|
||||
| 操作 | 作用 |
|
||||
| --- | --- |
|
||||
| 鼠标左键拖动 | 旋转地球 |
|
||||
| 手指单指拖动 | 触屏旋转地球 |
|
||||
| 鼠标滚轮 | 放大或缩小 |
|
||||
| 双指捏合 | 触屏放大或缩小 |
|
||||
| 缩放按钮 | 固定步长调整缩放 |
|
||||
| 点击缩放百分比 | 重置到默认缩放 |
|
||||
|
||||
缩放时顶部胶囊会短暂显示当前缩放比例。这个提示不代表数据加载进度；如果页面正在加载数据，加载提示优先显示。
|
||||
|
||||
拖动灵敏度会根据当前缩放自动调整：默认视角附近保持常规旋转速度；放大后拖动会逐步变细，缩小后拖动会略快。
|
||||
|
||||
### 动作捕捉控制
|
||||
|
||||
Earth 预留了动作捕捉控制入口。实时链路两种输入源：
|
||||
|
||||
- **浏览器摄像头**（默认）：直接用网页 `getUserMedia` 在本机浏览器识别；无需安装应用，但页面必须运行在 HTTPS 或 localhost，且需允许浏览器摄像头权限
|
||||
- **Motion Agent**：摄像头/RTSP/HTTP → 本地 Agent → 本地 WebSocket → Earth 页面；用于双摄、USB index、手机/网络摄像头流
|
||||
|
||||
打开方式：设置中开启"动捕调试模式"，或加 URL 参数 `?motion=1` 打开 Earth 动捕连接。Motion Agent 默认地址 `ws://127.0.0.1:8765/ws/gestures`，可用 `motionAgent` URL 参数覆盖。也可以直接 `?motion=1&motionProvider=browser` 或 `?motion=1&motionProvider=agent`。
|
||||
|
||||
两种模式都不会把摄像头帧或实时手势发到云端，也不会复用新闻/RSS 聚合接口。
|
||||
|
||||
手势语义：
|
||||
|
||||
| 手势事件 | 作用 |
|
||||
| --- | --- |
|
||||
| `rotate_left/right/up/down` | 地球向对应方向旋转 |
|
||||
| `zoom_in/out` | 放大或缩小视角 |
|
||||
| `focus_prev/next` | 在当前动捕图层内切换可交互目标 |
|
||||
| `layer_prev/next` | 切换动捕候选图层并巡航到新图层最近目标 |
|
||||
| `confirm` | 确认当前已选目标 |
|
||||
|
||||
调试面板中：浏览器摄像头输入会显示本机实时预览并绘制关节点和连线；Motion Agent 只发归一化骨架事件，不发原始帧。"只显示骨骼"会隐藏视频预览只保留骨架；"停止匹配动作"会暂停手势触发但保留预览和骨架。未匹配时骨架红色，匹配后变绿并显示动作名称。
|
||||
|
||||
### 巡航模式
|
||||
|
||||
巡航模式让 Earth 自动轮播聚焦目标。当前巡航模块：BGP、新闻、算力中心、船只、海缆、卫星。适合演示、监控大屏或无人值守。
|
||||
|
||||
### 移动端
|
||||
|
||||
移动端抽屉布局：图层控制进入移动抽屉，搜索、设置、详情使用移动端面板。主要交互仍围绕地球对象点击、搜索和图层开关。
|
||||
|
||||
### 常见问题
|
||||
|
||||
- **Earth 打不开**：先确认前端服务是否在线；如果端口不是 `3000`，使用启动输出的实际端口
|
||||
- **图层没有数据**：进 `/datasources` 看数据源状态、是否已采集和最近执行结果，再到 `/data` 或 `/bgp` 看是否有记录
|
||||
- **卫星 / BGP / 海缆加载慢**：这些图层依赖后端接口和外部数据源，首次加载需要等启动任务完成
|
||||
|
||||
## Docs 文档站
|
||||
|
||||
文档站 `http://localhost:3000/docs` 由后端按权限读取，不再把全部 Markdown 直接打进前端构建产物。
|
||||
|
||||
未登录访客默认只能看到 `public` 文档：首页、快速开始、使用手册、常见问题、Earth 位置候选采集使用手册。登录用户被分配 Gatekeeper 权限组后可以看到更多技术文档：
|
||||
|
||||
- `docs_user`：用户操作类文档
|
||||
- `docs_developer`：Earth、前端、后端、采集器和 AI Provider 等开发文档
|
||||
- `docs_admin`：服务控制、运维、环境变量和敏感操作文档（包括运维手册）
|
||||
|
||||
`admin` 默认拥有 `docs_admin`，`super_admin` 拥有全部 Docs 权限。Gatekeeper 权限组在"用户管理"中配置。
|
||||
|
||||
Docs 支持分类导航、Markdown 渲染、表格和代码块、文档内目录、对当前可见文档搜索、technical 文档间内部链接跳转。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [快速开始](/home/ray/dev/linkong/planet/docs/technical/zh/quickstart.md)
|
||||
- [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
|
||||
- [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
|
||||
- [Earth 图层样式属性索引](/home/ray/dev/linkong/planet/docs/technical/zh/earth-layer-style-reference.md)
|
||||
- [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
|
||||
- [Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
|
||||
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
|
||||
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
|
||||
- [数据源、采集器设置与连接验证](/home/ray/dev/linkong/planet/docs/technical/zh/datasource-collector-settings-connectivity.md)
|
||||
- [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
|
||||
|
||||
244
docs/technical/zh/ops-runbook.md
Normal file
244
docs/technical/zh/ops-runbook.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Planet 运维手册
|
||||
|
||||
这份手册面向部署、值班和二次开发的运维人员。客户面向的 UI 使用流程见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)，本手册只覆盖 shell、Docker、日志、环境变量和故障排查。
|
||||
|
||||
## 首次启动
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
|
||||
默认行为：
|
||||
|
||||
- 启动 PostgreSQL 和 Redis
|
||||
- 启动 AI Provider
|
||||
- 启动后端 API
|
||||
- 启动前端 Vite dev server
|
||||
- 输出 Earth、控制台、Playground 和后端 API 文档入口
|
||||
|
||||
首次启动会自动写入两个默认账号（见 `backend/app/db/session.py` 的 `DEFAULT_LOGIN_USERS`）：
|
||||
|
||||
| 用户名 | 密码 | 角色 |
|
||||
| --- | --- | --- |
|
||||
| `admin` | `admin123` | `super_admin` |
|
||||
| `linkong` | `12345678` | `super_admin` |
|
||||
|
||||
两个默认账号 `email_verified` 为 `true`，可直接登录控制台。任何在该列表之外的账号都必须走公开注册 + 邮箱验证流程（见使用手册），或用 `./planet.sh createuser` 命令式创建。
|
||||
|
||||
可指定端口：
|
||||
|
||||
```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 # 全量
|
||||
./planet.sh restart -b # 后端
|
||||
./planet.sh restart -f # 前端
|
||||
./planet.sh restart -a # AI Provider
|
||||
./planet.sh restart -d # 数据库
|
||||
```
|
||||
|
||||
按模块重启适合日常开发，能避免无关服务被打断。
|
||||
|
||||
## 健康检查
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
会检查：
|
||||
|
||||
- `planet_*` 容器状态
|
||||
- 后端 `/health`
|
||||
- AI Provider `/health`
|
||||
- 前端页面可达性
|
||||
|
||||
如果某项显示 offline，优先看对应日志。
|
||||
|
||||
## 日志
|
||||
|
||||
最近日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
持续跟随：
|
||||
|
||||
```bash
|
||||
./planet.sh log -f # 前端: /tmp/planet_frontend.log
|
||||
./planet.sh log -b # 后端: /tmp/planet_backend.log
|
||||
./planet.sh log -a # AI Provider: planet_aiprovider 容器日志
|
||||
```
|
||||
|
||||
## 命令式创建用户
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
交互式提示用户名、密码、角色，直接落库并标记 `email_verified = TRUE`。
|
||||
|
||||
适用场景：
|
||||
|
||||
- SMTP 还没配置好，但需要先发账号给一名管理员
|
||||
- 想批量预置内部测试账号
|
||||
- 公开注册流程因任何原因不可用，需要应急兜底
|
||||
|
||||
正式用户开通推荐走控制台 `/settings -> SMTP 邮件` 配好发件后，让用户在 `/register` 自助注册。
|
||||
|
||||
## 局域网 / WSL 访问
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
适用于：
|
||||
|
||||
- WSL 中启动，Windows 浏览器访问
|
||||
- 手机或平板演示 Earth
|
||||
- 局域网其他机器访问同一开发实例
|
||||
|
||||
`--allow-lan` 只负责让前端和后端监听 `0.0.0.0`。WSL 中运行时，Windows 本机一般可以通过 `localhost` 访问，但局域网其他机器访问 `http://<Windows局域网IP>:3000` 还需要 Windows 端口转发和防火墙放行。
|
||||
|
||||
建议按顺序排查：
|
||||
|
||||
```bash
|
||||
# 在运行 Planet 的 shell 中
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
如果看到 `0.0.0.0:3000` 和 `0.0.0.0:8000`，但局域网 IP 仍访问失败，在管理员 PowerShell 中配置：
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## AI Provider 环境变量与构建
|
||||
|
||||
AI Provider 运行期配置可以放在两处：
|
||||
|
||||
| 位置 | 适合内容 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `aiprovider/.env` | 团队约定的本地默认配置 | Docker Compose 作为 `env_file` 读取 |
|
||||
| `~/.zshrc` | 个人 provider、模型、密钥、代理 | `planet.sh` 启动时读取常见 `AI_*`、`SERVICE_*`、`PYTHON_IMAGE`、`UV_IMAGE` |
|
||||
|
||||
推荐写法：
|
||||
|
||||
```bash
|
||||
export AI_PROVIDER=minimax
|
||||
export AI_PROVIDER_API=anthropic-messages
|
||||
export AI_BASE_URL=https://api.example.com/anthropic
|
||||
export AI_API_KEY=sk-change-me
|
||||
export AI_MODEL=MiniMax-M2.7
|
||||
export AI_PROVIDER_SERVICE_TOKEN=change_me
|
||||
```
|
||||
|
||||
`planet.sh` 默认只静态解析 `~/.zshrc` 中简单的 `export KEY=value` 或 `KEY=value` 行。需要复杂 shell 展开时显式启用：
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
||||
```
|
||||
|
||||
完全忽略 `~/.zshrc`：
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
||||
```
|
||||
|
||||
AI Provider 镜像只在代码、Dockerfile、Compose 配置或相关 Python 依赖变化时重建。修改密钥或 Base URL 后只需重启容器：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
构建较慢时按层排查：
|
||||
|
||||
| 现象 | 常见原因 | 处理方式 |
|
||||
| --- | --- | --- |
|
||||
| `transferring context` 很大 | build context 含前端资源等无关文件 | `.dockerignore` 只发送必需文件 |
|
||||
| `uv sync` 下载较慢 | 首次构建或缓存为空 | 等待首次完成，后续复用 BuildKit 缓存 |
|
||||
| 改密钥后仍是旧配置 | 容器未重启 | `./planet.sh restart -a` |
|
||||
|
||||
## SMTP 邮件（公开注册依赖）
|
||||
|
||||
公开注册和邮箱验证依赖 SMTP。管理员在控制台 `/settings -> SMTP 邮件` 子 tab 中填写主机、端口、账号、密码、发件地址、TLS 模式，然后用"发送测试邮件"按钮验证。配置同时写入 `system_settings.smtp` 表行。
|
||||
|
||||
未配置时 `POST /api/v1/auth/register` 返回 `503 EMAIL_PROVIDER_NOT_CONFIGURED`，前端的注册流程会给出明确提示。运维兜底方式是 `./planet.sh createuser`。
|
||||
|
||||
OTP 一次性验证码走 Redis，key 格式 `otp:{purpose}:{email}`，TTL 600 秒。错误尝试 5 次后该 key 失效；重发冷却 60 秒，由 `otp_rate:{purpose}:{email}` 控制。
|
||||
|
||||
## 故障排查顺序
|
||||
|
||||
```bash
|
||||
./planet.sh health # 1. 看服务状态
|
||||
./planet.sh log # 2. 看最近日志
|
||||
./planet.sh log -f # 3. 按模块查看
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
./planet.sh restart -f # 4. 只重启有问题的模块
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -a
|
||||
./planet.sh restart -d # 5. 数据库 / 缓存异常时
|
||||
./planet.sh restart # 6. 仍无法恢复时全量重启
|
||||
```
|
||||
|
||||
## 开发命令约定
|
||||
|
||||
前端必须使用 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
|
||||
```
|
||||
|
||||
后端依赖通过 uv 管理：
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run pytest backend/tests/test_otp_service.py
|
||||
```
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [planet.sh 启动机制](/home/ray/dev/linkong/planet/docs/technical/zh/ops-planet-sh-startup.md)
|
||||
- [系统服务控制](/home/ray/dev/linkong/planet/docs/technical/zh/backend-system-service-control.md)
|
||||
- [Docker + Compose + Buildx 升级](/home/ray/dev/linkong/planet/docs/technical/zh/ops-docker-compose-buildx-upgrade.md)
|
||||
- [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
|
||||
@@ -1,236 +1,66 @@
|
||||
# 快速开始
|
||||
|
||||
这份快速开始面向第一次启动 Planet 的开发者或演示操作者。目标是用最短路径把服务跑起来，并知道应该打开哪些入口。
|
||||
这份快速开始面向 Planet 的最终用户：你拿到了管理员给的访问地址，要从打开浏览器到第一次完成配置之间的最短路径。所有操作都在浏览器里完成。
|
||||
|
||||
如果遇到端口占用、Windows / WSL 局域网访问、`uv` / `bun`、摄像头或 Docs 权限问题，先看 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
|
||||
如果你是负责部署或运维的同事，请改读 [Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)。
|
||||
|
||||
## 前置条件
|
||||
## 1. 打开访问地址
|
||||
|
||||
推荐在 WSL / Linux shell 中运行。
|
||||
打开管理员给的 URL，例如 `http://planet.example.com`。本地演示一般是 `http://localhost:3000`。
|
||||
|
||||
需要具备：
|
||||
入口分两类：
|
||||
|
||||
- Docker / Docker Compose 可用
|
||||
- 当前 shell 能访问 `uv` 和 `bun`
|
||||
- 仓库已 clone 到本机
|
||||
- 公开页：`/earth`（3D 态势）、`/docs`（公共文档）
|
||||
- 登录后：`/admin`（控制台）、`/ai`（AI）、`/settings`（系统配置）
|
||||
|
||||
如果是新机器，优先执行仓库自带初始化脚本：
|
||||
## 2. 注册账号
|
||||
|
||||
```bash
|
||||
./scripts/bootstrap-dev.sh
|
||||
```
|
||||
1. 打开 `/login`，点击表单下方"注册账户"。
|
||||
2. 在 `/register` 填用户名、邮箱、密码（至少 8 位）。
|
||||
3. 提交后，到邮箱查收 6 位验证码（10 分钟内有效）。
|
||||
4. 在验证页输入验证码，点击"验证并登录"，系统会自动跳到控制台。
|
||||
|
||||
这个脚本会检查并同步常用依赖，并在缺少时生成：
|
||||
收不到邮件时：
|
||||
|
||||
- `backend/.env`
|
||||
- `aiprovider/.env`
|
||||
- `frontend/.env.local`
|
||||
- 看一下垃圾邮件或企业邮件网关
|
||||
- 验证页右下角的"重新发送验证码"会显示倒计时，结束后可以重发
|
||||
- 提示"邮件服务尚未配置"时联系管理员开 SMTP
|
||||
|
||||
AI Provider 的个人配置也可以放在 `~/.zshrc`。`planet.sh` 会读取简单的 `export AI_...=...` 或 `AI_...=...` 行，并在启动 AI Provider 时传给容器。修改模型、密钥或 Base URL 后，通常只需要重启 AI Provider：
|
||||
默认角色是 `viewer`，可登录但只能看公共内容。要看采集器、用户管理、系统设置，请联系管理员升级角色或加 Gatekeeper 权限组。
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
## 3. 第一次登录
|
||||
|
||||
AISStream、BarentsWatch 等采集器凭证也可以先写在 `~/.zshrc` 里供连接验证读取，例如：
|
||||
进入 `/admin` 仪表盘后，建议按这个顺序熟悉控制台：
|
||||
|
||||
```bash
|
||||
export AISSTREAM_API_KEY="..."
|
||||
export BARENTSWATCH_CLIENT_ID="..."
|
||||
export BARENTSWATCH_CLIENT_SECRET="..."
|
||||
```
|
||||
1. `/settings?tab=collector_credentials`：选一个采集器，点插头图标做连接测试。免费 collector（开源 BGP 等）通常直接可用；像 `AISStream`、`BarentsWatch` 这类需要凭证的，需要先填 API Key/Client Secret
|
||||
2. `/ai?tab=providers`：填一个 LLM provider（例如 `minimax` / `openai`）、模型名、Base URL、API Key，点 Base URL 末端的插头测试连接。WebSearch / OCR 工具可选
|
||||
3. `/datasources` 或 `/data`：看采集器是否已经产出数据
|
||||
4. `/alerts/system`：看系统告警是否正常
|
||||
5. `/users`（仅 `super_admin`）：根据需要给同事开账号或调权限组
|
||||
|
||||
正式采集更推荐在控制台 `设置 -> 采集器设置` 保存凭证，尤其是 AISStream 这类长连接 WebSocket collector。这样连接验证、后端采集任务和 Earth 实时船只聚合会使用同一份配置。
|
||||
## 4. 打开 Earth
|
||||
|
||||
## 1. 启动服务
|
||||
访问 `/earth`，公开页面，不需要登录。
|
||||
|
||||
在仓库根目录执行：
|
||||
进入后建议确认：
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
|
||||
启动完成后，常用入口是：
|
||||
|
||||
| 入口 | 默认地址 | 用途 |
|
||||
| --- | --- | --- |
|
||||
| Earth | `http://localhost:3000/earth` | 公开 3D Earth 可视化页面 |
|
||||
| 控制台 | `http://localhost:3000/admin` | 登录后的管理后台 |
|
||||
| 文档站 | `http://localhost:3000/docs` | 使用手册公开；开发/运维文档按 Gatekeeper 权限组开放 |
|
||||
| AI | `http://localhost:3000/ai` | 登录后的模型供应商、工具和测试台入口 |
|
||||
| 后端 API 文档 | `http://localhost:8000/docs` | FastAPI / OpenAPI 接口文档 |
|
||||
|
||||
如果默认端口被占用，可以指定端口：
|
||||
|
||||
```bash
|
||||
./planet.sh start -f 3001 -b 8001 -a 8101
|
||||
```
|
||||
|
||||
后端 `8000` 被 Windows listener 或旧 portproxy 占用时，排查顺序见 [常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)。
|
||||
|
||||
## 2. 创建登录用户
|
||||
|
||||
控制台需要登录。首次使用可以执行：
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
按提示输入用户名、密码和角色。
|
||||
|
||||
如果需要阅读开发或运维文档，用 `super_admin` 登录控制台后，在“用户管理”里给目标用户分配 Gatekeeper 权限组：`docs_developer` 用于开发文档，`docs_admin` 用于服务控制和运维文档。
|
||||
|
||||
## 3. 打开 Earth
|
||||
|
||||
访问：
|
||||
|
||||
```text
|
||||
http://localhost:3000/earth
|
||||
```
|
||||
|
||||
Earth 是公开页面，不需要登录。
|
||||
|
||||
进入后可以先确认：
|
||||
|
||||
- 地球正常显示
|
||||
- 右侧图层控制可打开/关闭图层
|
||||
- 地球正常显示，右侧图层面板可以打开/关闭
|
||||
- 搜索可以查找海缆、卫星、算力中心、BGP 事件
|
||||
- 算力中心和 BGP 观测站详情卡可以自动采集并预览坐标候选；常规来源无候选时会用当前默认 AI Provider 做 LLM factcheck 兜底；算力中心待定位气泡可以打开列表并保存候选
|
||||
- 鼠标拖动、滚轮缩放和缩放百分比提示正常工作
|
||||
- 设置面板可以切换旋转 / 巡航 / 动捕模式、日夜模式、卫星显示风格；动捕调试模式下浏览器摄像头可显示本机预览和骨架
|
||||
- 算力中心和 BGP 观测站详情卡可以自动采集坐标候选，并能在 Earth 上预览
|
||||
- 鼠标拖动、滚轮缩放、缩放百分比提示工作正常
|
||||
- 设置面板的旋转 / 巡航 / 动捕模式可以切换
|
||||
|
||||
## 4. 打开控制台
|
||||
## 5. 找回密码
|
||||
|
||||
访问：
|
||||
忘记密码时打开 `/forgot-password`，输入邮箱并接收验证码，再输入验证码 + 新密码即可。系统对未注册的邮箱也会返回同样的提示（防止账号枚举）。
|
||||
|
||||
```text
|
||||
http://localhost:3000/admin
|
||||
```
|
||||
## 6. 看文档
|
||||
|
||||
控制台用于数据源、采集数据、专题观测、告警、系统日志和配置管理。
|
||||
|
||||
首次排查建议查看：
|
||||
|
||||
- `/datasources`：数据源目录和采集触发；接口、请求头和凭证配置在 `/settings` 的“采集器设置”
|
||||
- `/data`：已采集数据
|
||||
- `/bgp`：BGP 专题观测
|
||||
- `/ai`：AI，管理模型供应商、WebSearch 等工具和测试台
|
||||
- `/alerts/system`：系统告警
|
||||
- `/settings`：系统配置
|
||||
|
||||
## 5. 查看运行状态
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
这个命令会显示容器状态，并检查：
|
||||
|
||||
- 后端
|
||||
- AI Provider
|
||||
- 前端
|
||||
|
||||
## 6. 查看日志
|
||||
|
||||
最近日志：
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
持续查看某个服务：
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
|
||||
含义：
|
||||
|
||||
- `-f`：前端日志
|
||||
- `-b`：后端日志
|
||||
- `-a`：AI Provider 日志
|
||||
|
||||
## 7. 常用重启
|
||||
|
||||
只重启前端：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -f
|
||||
```
|
||||
|
||||
只重启后端：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -b
|
||||
```
|
||||
|
||||
只重启 AI Provider：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
只重启数据库：
|
||||
|
||||
```bash
|
||||
./planet.sh restart -d
|
||||
```
|
||||
|
||||
全量重启：
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
|
||||
## 8. 局域网访问
|
||||
|
||||
如果希望 Windows 浏览器、手机或同一局域网的其他设备访问：
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
这会让前端和后端监听局域网可访问地址。
|
||||
|
||||
注意：`--allow-lan` 只负责让 Planet 服务监听 `0.0.0.0`，不等于自动把 WSL 服务暴露到 Windows 局域网 IP。常见情况是：
|
||||
|
||||
- WSL 内 `localhost:3000` / `localhost:8000` 能访问
|
||||
- Windows 本机 `localhost:3000` / `localhost:8000` 能访问
|
||||
- 但手机或其他电脑访问 `http://<Windows局域网IP>:3000` 失败
|
||||
|
||||
这通常说明 Windows 端还缺少端口转发或防火墙放行。
|
||||
|
||||
如果访问失败，先在运行 Planet 的 shell 中检查：
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
如果确认 WSL 中已监听 `0.0.0.0:3000` 和 `0.0.0.0:8000`，但局域网 IP 仍不能访问，请在管理员 PowerShell 中配置 Windows 端转发和防火墙：
|
||||
|
||||
```powershell
|
||||
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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## 9. 停止服务
|
||||
|
||||
```bash
|
||||
./planet.sh stop
|
||||
```
|
||||
|
||||
停止后会关闭前端、后端、AI Provider、PostgreSQL 和 Redis。
|
||||
`/docs` 是文档站。未登录可看：本快速开始、使用手册、常见问题。登录后被分配 `docs_user` / `docs_developer` / `docs_admin` 权限组的用户可以看更多技术文档。
|
||||
|
||||
## 下一步
|
||||
|
||||
- 完整操作说明见 [Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
|
||||
- 控制台结构见 [控制台前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/frontend-admin-frontend-context.md)
|
||||
- Earth 结构见 [Earth 前端结构](/home/ray/dev/linkong/planet/docs/technical/zh/earth-frontend-context.md)
|
||||
- 后端采集器见 [数据采集系统](/home/ray/dev/linkong/planet/docs/technical/zh/backend-collectors.md)
|
||||
- 完整 UI 操作说明：[Planet 使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/manual.md)
|
||||
- 排障与配置疑问：[常见问题](/home/ray/dev/linkong/planet/docs/technical/zh/faq.md)
|
||||
- Earth 坐标候选采集详细流程：[Earth 位置候选采集使用手册](/home/ray/dev/linkong/planet/docs/technical/zh/location-pipeline-user.md)
|
||||
- 部署 / 运维相关命令：[Planet 运维手册](/home/ray/dev/linkong/planet/docs/technical/zh/ops-runbook.md)
|
||||
|
||||
Reference in New Issue
Block a user