release: bump version to 0.52.0
This commit is contained in:
linkong
@@ -309,17 +309,50 @@ AIS observations do not directly replace final vessel records. They are first sa
|
||||
- Dynamic fields such as position, speed, and course are selected by freshness and source priority.
|
||||
- Static fields prefer non-empty values; conflicting candidates are recorded for detail and diagnostics views.
|
||||
|
||||
Earth still reads vessel data from:
|
||||
Earth vessel rendering now consumes the bounded snapshot endpoint and realtime delta channel:
|
||||
|
||||
```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` merges raw observation aggregation with the legacy BarentsWatch latest-position tables so adding AISStream does not hide historical BarentsWatch-only vessels.
|
||||
`/api/v1/vessels/snapshot` requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`. It reads only aggregated `ais_raw_observations`; it no longer merges legacy `vessel_position` / `vessel_static` rows. The old `/api/v1/visualization/geo/vessels` endpoint has been removed and returns `410 Gone`.
|
||||
|
||||
Realtime deltas are sent through the `/ws` `vessels` channel. Clients must subscribe with the current viewport:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "subscribe",
|
||||
"data": {
|
||||
"channel": "vessels",
|
||||
"bbox": [120.8, 30.7, 122.1, 31.8],
|
||||
"zoom": 12,
|
||||
"limit": 1000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The backend stores lightweight subscription filters per connection and only sends vessel updates that match the subscriber bbox. Collector broadcasts enter a 1-second throttle queue; within each flush window, only the latest update per MMSI is retained.
|
||||
|
||||
### Layer APIs And Global Stats
|
||||
|
||||
Earth is moving to two API families:
|
||||
|
||||
```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/*` is for aggregate panels and keeps a global statistics scope independent of the map bbox. `/api/v1/layers/*` is for map rendering, requires `bbox` and `zoom`, defaults to `limit=1000`, and caps `limit` at `5000`; low zoom falls back to a smaller response cap and reports `degraded`, `truncated`, `limit_clamped`, and `stats_scope=viewport` in `diagnostics`. Non-vessel layers currently reuse the existing GeoJSON converters before the guard layer; future product-specific queries can push bbox filtering deeper.
|
||||
|
||||
## X. Collector Settings And Connectivity Validation
|
||||
|
||||
@@ -390,4 +423,12 @@ curl -X POST http://localhost:8000/api/v1/datasources/1/trigger \
|
||||
-H "Authorization: Bearer <token>"
|
||||
```
|
||||
|
||||
Batch collection uses:
|
||||
|
||||
```http
|
||||
POST /api/v1/datasources/trigger-batch
|
||||
```
|
||||
|
||||
The request body may pass `source_ids` for selected rows. Without `source_ids`, the backend filters by `product`, `module`, `is_active`, `run_status`, `collected`, `credential_status`, and `q`. The endpoint skips disabled sources, sources already running without `force`, and sources still inside their frequency window, then returns `triggered`, `skipped`, and `failed` groups.
|
||||
|
||||
**Core file**: `backend/app/api/v1/datasources.py`
|
||||
|
||||
@@ -288,6 +288,16 @@ Normalization:
|
||||
|
||||
Connectivity validation reads saved configuration, environment variables, and `AISSTREAM_API_KEY` from `~/.zshrc`. For actual collection, prefer saving the API key in collector settings. If the key only lives in `~/.zshrc`, confirm that the backend process inherited it; otherwise validation may pass while the collector runtime cannot read the key.
|
||||
|
||||
Connectivity validation and actual collection are separate actions. A banner such as `AISStream credentials configured, WebSocket endpoint format valid` only means the saved settings can be used for a connection attempt; runtime status may still be `disconnected`. Global AIS data is written locally only while the `aisstream_vessels` collector is `streaming` / `connected` and its message count plus `last_seen_at` keep advancing.
|
||||
|
||||
The new vessel list entry point is no longer the legacy `/api/v1/visualization/geo/vessels` route. Earth initial state should call:
|
||||
|
||||
```http
|
||||
GET /api/v1/vessels/snapshot?bbox=lon_min,lat_min,lon_max,lat_max&zoom=12&limit=1000
|
||||
```
|
||||
|
||||
That endpoint reads local aggregated `ais_raw_observations` only. Realtime updates use the `/ws` `vessels` channel; subscriptions must include `bbox`, `zoom`, and `limit`. The server filters updates per connection and merges collector broadcasts every second, keeping only the latest position per MMSI.
|
||||
|
||||
## Custom REST / WebSocket Mapping Runtime
|
||||
|
||||
Files:
|
||||
|
||||
@@ -152,7 +152,11 @@ The `earth:compute-center-location-saved` reconciliation pipeline is deliberatel
|
||||
|
||||
### AIS Vessel Layer
|
||||
|
||||
The vessel layer fetches `/api/v1/visualization/geo/vessels` and renders the aggregated AIS GeoJSON through `createInteractableLayer()`. By default it does not send a `limit` parameter, and `VESSEL_CONFIG.maxRenderedMarkers = 0` means the frontend does not clip the result to 5000 vessels. A positive `options.limit` or positive `maxRenderedMarkers` can still be used as an explicit temporary cap.
|
||||
The vessel layer now uses `/api/v1/vessels/snapshot` for the initial viewport snapshot and the `/ws` `vessels` channel for realtime deltas. Snapshot requests must include `bbox`, `zoom`, and a bounded `limit`; the backend defaults to `limit=1000` and caps it at `5000`. WebSocket subscriptions must include the same viewport fields so the server can filter updates per connection.
|
||||
|
||||
The legacy `/api/v1/visualization/geo/vessels` endpoint has been removed and returns `410 Gone`. Frontend code should fetch a snapshot for the current viewport when the layer opens, then subscribe to `vessels` deltas. After map pan or zoom, reload the snapshot and send a fresh vessels subscription. The backend no longer merges legacy `vessel_position` / `vessel_static` rows into vessel snapshots, so the frontend must not depend on old BarentsWatch-only fallback rows.
|
||||
|
||||
The new layer API family is `/api/v1/layers/*`, which separates map rendering payloads from aggregate panel statistics. Layer requests must include `bbox`, `zoom`, and a bounded `limit`; responses include `visible_count`, `returned_count`, and `diagnostics`, where `degraded`, `truncated`, and `limit_clamped` are the frontend signals for fallback UI. Right-side aggregate panels should not sum the layer response. They should read `/api/v1/data-products` or `/api/v1/data-products/{product_id}/status`, because those statistics stay global and do not change with the viewport.
|
||||
|
||||
Vessel color and vessel type text must use the same normalized classification. `vessels.js` derives `type` from both `vessel_type_name` and the AIS numeric `vessel_type` code; that `type` drives marker color. It also derives `vessel_type_display`, which `main.js` uses for the info card, hover summary, and search result subtitle. Do not make the info card read only the raw `vessel_type_name`, because AISStream can provide a numeric type while the raw name is still `Other`.
|
||||
|
||||
|
||||
@@ -163,7 +163,25 @@ Current constraints:
|
||||
- Internal document links should be converted to `/docs/:slug` through `transformLink`
|
||||
- Heading anchors are injected through `getHeadingId`, keeping route state outside the renderer
|
||||
|
||||
### 6. `TableActions`
|
||||
### 6. `ConnectionTestInput`
|
||||
|
||||
File:
|
||||
|
||||
- [ConnectionTestInput.tsx](/home/ray/dev/linkong/planet/frontend/src/components/ConnectionTestInput/ConnectionTestInput.tsx)
|
||||
|
||||
Purpose:
|
||||
|
||||
- Console form fields that combine an endpoint/Base URL value with a connection check
|
||||
- Connection-test entry points for AI Provider and WebSearch
|
||||
- Future collector configuration fields should reuse it when the test action belongs inside the input
|
||||
|
||||
Current constraints:
|
||||
|
||||
- The input suffix shows a single plug/connector icon, not an adjacent text button
|
||||
- Disabled integrations must grey out both the input and its connection-test action
|
||||
- The component only combines the input and action; callers still own form state, loading, disabled state, and the request itself
|
||||
|
||||
### 7. `TableActions`
|
||||
|
||||
File:
|
||||
|
||||
@@ -205,10 +223,13 @@ File:
|
||||
Responsibilities:
|
||||
|
||||
- `/ai` now owns LLM Provider, AI Tool configuration, and the testbench instead of nesting them under `/settings`
|
||||
- The `模型供应商` tab manages default provider, model, base URL, provider key, local `aiprovider` proxy, and connection test
|
||||
- The `工具` tab manages WebSearch provider, search key, base URL, timeout, result count, and advanced provider options
|
||||
- The `模型供应商` tab manages default provider, model, base URL, provider key, local `aiprovider` proxy, and connection test; provider and model fields use editable comboboxes so users can manually enter new providers/models if the models.dev catalog stops updating
|
||||
- The `工具` tab first selects a tool from a dropdown menu, then renders that tool's configuration; it currently includes WebSearch and OCR
|
||||
- WebSearch configuration includes provider, search key, base URL, timeout, result count, and advanced provider options
|
||||
- OCR configuration includes provider, Base URL, API key, model/engine, languages, timeout, file-size limit, and output format
|
||||
- The `测试台` tab embeds the former Playground real session, preset prompts, and AI Provider status debugging
|
||||
- The page reuses the Settings single-screen tabs, panel card, and internal scrolling style
|
||||
- AI Provider and WebSearch connection tests use `ConnectionTestInput`, with the connector icon fixed at the end of the Base URL input; when WebSearch is disabled, every configuration field and the test entry point are greyed out except the switch
|
||||
|
||||
Legacy `/settings?tab=ai` should redirect to `/ai?tab=providers`.
|
||||
Legacy `/playground` should redirect to `/ai?tab=playground`.
|
||||
|
||||
@@ -1,666 +1,332 @@
|
||||
# Planet Manual
|
||||
|
||||
This manual is for daily use, demos, development integration, and local operations. It covers four core entry points:
|
||||
This manual is for Planet end users. Starting from the browser, it covers account registration, login, configuring collectors, configuring AI, using Earth and the console, and reading the docs site. Every action happens in a browser.
|
||||
|
||||
- `planet.sh`: local start, stop, restart, health check, and log access
|
||||
- Earth: public 3D situational awareness page
|
||||
- Console: admin backend (login required)
|
||||
- Docs: backend Gatekeeper-controlled documentation; basic usage docs are public, while developer and operations docs require permission groups
|
||||
|
||||
For the shortest path to getting started, see [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md). For common troubleshooting, see the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
|
||||
If you are responsible for deployment or on-call duty, read the [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md) instead — it covers shell commands, log paths, and CLI fallbacks for user creation.
|
||||
|
||||
## Entry Overview
|
||||
|
||||
After a default startup, the common URLs are:
|
||||
|
||||
| Name | URL | Login Required | Description |
|
||||
| --- | --- | --- | --- |
|
||||
| Earth | `http://localhost:3000/earth` | No | 3D globe, layers, BGP, satellites, cables, news situational awareness |
|
||||
| Docs | `http://localhost:3000/docs` | Partly | Usage docs are public; developer, backend, and operations docs require Gatekeeper groups |
|
||||
| FAQ | `http://localhost:3000/docs/faq` | No | Windows / WSL, ports, dependencies, motion capture, credentials, and permission troubleshooting |
|
||||
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
|
||||
| AI | `http://localhost:3000/ai` | Yes | Model providers, AI tools, and testbench |
|
||||
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |
|
||||
| Earth | `http://<host>/earth` | No | Public 3D situational awareness page |
|
||||
| Docs | `http://<host>/docs` | Partly | Public docs need no login; developer/ops docs need Gatekeeper groups |
|
||||
| Register / Login / Forgot Password | `/register`, `/login`, `/forgot-password` | No | Self-serve account creation and recovery |
|
||||
| Console | `http://<host>/admin` | Yes | Data, collectors, alerts, AI, users, settings |
|
||||
| AI | `http://<host>/ai` | Yes | Model providers, tools, testbench |
|
||||
| Backend API Docs | `http://<host>:8000/docs` | Depends | FastAPI / OpenAPI |
|
||||
|
||||
## planet.sh
|
||||
URLs below use the local default `http://localhost:3000`. Replace the prefix with your deployment URL in production.
|
||||
|
||||
`planet.sh` is the main control script for local development and demos. Use it to manage services rather than manually starting frontend, backend, database, and AI Provider separately.
|
||||
## Register an Account
|
||||
|
||||
### Start
|
||||
1. Open `http://localhost:3000/login` and click "Register" under the form.
|
||||
2. On `/register`, fill in:
|
||||
- **Username**: 3–50 characters, used to log in
|
||||
- **Email**: receives the verification code; editable later in account settings
|
||||
- **Password**: at least 8 characters
|
||||
3. After submission you are taken to the verify page. A 6-digit code is sent to your email. It expires in 10 minutes.
|
||||
4. Enter the code and click "Verify and Sign In". On success the system stores a session and sends you to the console.
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
If no email arrives within 60 seconds:
|
||||
|
||||
Default behavior:
|
||||
- Check spam, promotions, and any enterprise mail gateway
|
||||
- The "Resend Code" button shows a 60-second countdown; you can resend after it ends
|
||||
- After 5 wrong attempts the code is invalidated; you must resend a new one
|
||||
|
||||
- Starts PostgreSQL and Redis
|
||||
- Starts AI Provider
|
||||
- Starts the backend API
|
||||
- Starts the frontend Vite dev server
|
||||
- Outputs Earth, console, Playground, and backend API doc URLs
|
||||
If you see "Email service not configured", the administrator has not yet set up SMTP. Ask the administrator to fill SMTP at `/settings -> SMTP Email`.
|
||||
|
||||
Specify custom ports:
|
||||
The default role for a self-registered user is `viewer`, which can sign in and view public content. To see collector / user / settings pages, ask an `admin` or `super_admin` to promote your role at `/users`.
|
||||
|
||||
```bash
|
||||
./planet.sh start -b 8001 -f 3001 -a 8101
|
||||
```
|
||||
## Sign In and Recover Password
|
||||
|
||||
Parameters:
|
||||
### Sign In
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-b <port>` | Backend port |
|
||||
| `-f <port>` | Frontend port |
|
||||
| `-a <port>` | AI Provider port |
|
||||
| `--allow-lan` | Enable LAN access |
|
||||
| `--verbose` | Show more command output during execution |
|
||||
Open `/login`, enter username and password. On success you are taken to `/admin`.
|
||||
|
||||
### AI Provider Environment and Builds
|
||||
If you see "Email not verified", the page automatically redirects to `/verify-email` — follow the prompts to enter the code.
|
||||
|
||||
AI Provider runtime configuration can live in `aiprovider/.env` or in matching variables in `~/.zshrc`. `planet.sh` reads simple `export AI_...=...` / `AI_...=...` lines and passes them to the container at startup.
|
||||
### Forgot Password
|
||||
|
||||
Changing model, API key, or base URL does not rebuild the image. Restart only AI Provider to pick up runtime configuration changes:
|
||||
1. On `/login`, click "Forgot Password?", or open `/forgot-password` directly.
|
||||
2. Enter your registered email and click "Send Code". The same confirmation is shown regardless of whether the email is registered (to avoid enumeration).
|
||||
3. After receiving the code, enter it together with a new password (≥ 8 characters) and click "Reset Password".
|
||||
4. The system sends you back to `/login` — sign in with the new password.
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
## Account Settings
|
||||
|
||||
For complex shell expansion in `~/.zshrc`, opt in explicitly:
|
||||
Click your username at the top-right of the console to open account settings:
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
||||
```
|
||||
- Change password: enter current password + new password
|
||||
- Change email: the system sends a verification code to the new address; the change applies only after verification
|
||||
- View Gatekeeper groups: lists current groups (`docs_user` / `docs_developer` / `docs_admin`)
|
||||
- Log out: clears the current session
|
||||
|
||||
To ignore `~/.zshrc` during troubleshooting:
|
||||
## Console Overview
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
||||
```
|
||||
|
||||
The AI Provider Docker build context is intentionally limited to the files required by the service, and `uv sync` uses a BuildKit cache mount so dependency downloads are reused after the first build.
|
||||
|
||||
### Stop
|
||||
|
||||
```bash
|
||||
./planet.sh stop
|
||||
```
|
||||
|
||||
Stops:
|
||||
|
||||
- Backend
|
||||
- AI Provider
|
||||
- Frontend
|
||||
- PostgreSQL
|
||||
- Redis
|
||||
|
||||
### Restart
|
||||
|
||||
Full restart:
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
|
||||
Per-module restart:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -f
|
||||
./planet.sh restart -a
|
||||
./planet.sh restart -d
|
||||
```
|
||||
|
||||
| Flag | Effect |
|
||||
| --- | --- |
|
||||
| `-b` | Backend only |
|
||||
| `-f` | Frontend only |
|
||||
| `-a` | AI Provider only |
|
||||
| `-d` | Database only |
|
||||
|
||||
Per-module restarts are preferred during development — they avoid interrupting unrelated services.
|
||||
|
||||
### Create User
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
Used to create a console login account before first use. The script interactively prompts for username, password, and role.
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
- `planet_*` container status
|
||||
- Backend `/health`
|
||||
- AI Provider `/health`
|
||||
- Frontend reachability
|
||||
|
||||
If something shows offline, check the corresponding logs first.
|
||||
|
||||
### Logs
|
||||
|
||||
Recent logs:
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
Follow logs:
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
|
||||
| Flag | Log source |
|
||||
| --- | --- |
|
||||
| `-f` / `--frontend` | `/tmp/planet_frontend.log` |
|
||||
| `-b` / `--backend` | `/tmp/planet_backend.log` |
|
||||
| `-a` / `--ai-provider` | `planet_aiprovider` container logs |
|
||||
|
||||
### LAN Access
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
Useful for:
|
||||
|
||||
- Starting in WSL, accessing from Windows browser
|
||||
- Demos on phone or tablet
|
||||
- Another machine on the same LAN accessing the same dev instance
|
||||
|
||||
`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but access from a phone or another computer through `http://<Windows LAN IP>:3000` still depends on Windows port forwarding and firewall rules.
|
||||
|
||||
Use this order to diagnose:
|
||||
|
||||
```bash
|
||||
# From WSL or the shell running Planet
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
If this shows `0.0.0.0:3000` and `0.0.0.0:8000`, but the LAN IP still fails, configure Windows from an elevated 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 is the public 3D situational awareness page, accessed at:
|
||||
|
||||
```text
|
||||
http://localhost:3000/earth
|
||||
```
|
||||
|
||||
It is a standalone frontend. The actual page lives at:
|
||||
|
||||
- `frontend/public/earth/index.html`
|
||||
- `frontend/public/earth/js/`
|
||||
- `frontend/public/earth/css/`
|
||||
|
||||
The React route `/earth` simply hosts it in an iframe.
|
||||
|
||||
### Main Uses
|
||||
|
||||
Earth is used to observe in a single globe view:
|
||||
|
||||
- BGP events, anomalies, and situational posture
|
||||
- Satellites and orbital trails
|
||||
- Submarine cables and landing points
|
||||
- Compute centers
|
||||
- AIS vessels
|
||||
- Border lines, grid lines, HD texture, cloud layer, terrain
|
||||
- Live news streams and situational news
|
||||
- Search and focused object details
|
||||
|
||||
### Layer Control
|
||||
|
||||
The right-side layer panel toggles visualization layers on or off.
|
||||
|
||||
Common layers include:
|
||||
|
||||
- Grid lines
|
||||
- Border lines
|
||||
- HD texture
|
||||
- Atmospheric cloud layer
|
||||
- Submarine cables
|
||||
- Compute centers
|
||||
- BGP observation
|
||||
- AIS vessels
|
||||
- Satellites
|
||||
- Orbital trails
|
||||
- Terrain
|
||||
|
||||
Some layers have dependencies:
|
||||
|
||||
- Terrain requires HD texture
|
||||
- Trails require Satellites
|
||||
- When HD texture is off, the globe shows the base map and edge glow effect
|
||||
|
||||
### Legend
|
||||
|
||||
The lower-left legend follows the currently focused or enabled layer.
|
||||
|
||||
Current legend modes include:
|
||||
|
||||
- Cables
|
||||
- Satellites
|
||||
- Border lines
|
||||
- Compute centers
|
||||
- BGP
|
||||
- AIS vessels
|
||||
|
||||
AIS vessel legend entries are grouped by vessel type: cargo, tanker, passenger, fishing, military, anchored/slow, and other. Triangle markers represent moving vessels; dots represent anchored or slow vessels.
|
||||
|
||||
### Search
|
||||
|
||||
Earth search finds current globe objects, such as:
|
||||
|
||||
- Submarine cables
|
||||
- Landing points
|
||||
- Satellites
|
||||
- Compute centers
|
||||
- BGP events
|
||||
- BGP collectors
|
||||
|
||||
Search results can be used to quickly locate objects and open their details.
|
||||
|
||||
### Location Candidate Collection
|
||||
|
||||
Compute-center and BGP collector detail cards can collect candidate coordinates automatically. After clicking an object, use `自动采集坐标候选` or `重新自动采集坐标`; the backend ranks source coordinates, open organization lookups, and Nominatim online search results. If those regular sources return no candidates, the current default AI Provider is used once as an LLM factcheck fallback. Stored BGP collector locations are used as query context only and are not emitted as candidates.
|
||||
|
||||
Candidates can be previewed directly on Earth. Compute-center candidates can be saved into the `compute_center_locations` dimension table from the detail card, then the layer refreshes immediately. The notification badge on the compute-center layer row shows unresolved records that cannot be rendered; clicking it opens the queue, where users can collect individual candidates or use `一键采用` to save the highest-confidence candidate top-to-bottom. Records without candidates stay in the queue and are not replaced by country centroids or hard-coded hints. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md) for the full workflow.
|
||||
|
||||
### Settings
|
||||
|
||||
The settings panel contains:
|
||||
|
||||
- Rotation mode / cruise mode / motion mode
|
||||
- Cruise modules: BGP, News, Compute Centers, Vessels, Cables, Satellites
|
||||
- View settings: satellite display style, day/night mode, panel visibility
|
||||
- Motion Debug Mode, Motion Input Source, skeleton-only debug view
|
||||
- Globe default size
|
||||
- Terrain opacity
|
||||
- Reset settings
|
||||
|
||||
These settings are stored in browser local storage. They revert to defaults if you switch browsers or clear site data.
|
||||
|
||||
### View Controls
|
||||
|
||||
Earth supports mouse, touchpad, and touchscreen interaction.
|
||||
|
||||
Common controls:
|
||||
|
||||
| Action | Result |
|
||||
| --- | --- |
|
||||
| Left-button drag | Rotates the globe |
|
||||
| One-finger drag | Rotates the globe on touch devices |
|
||||
| Mouse wheel | Zooms the view in or out |
|
||||
| Two-finger pinch | Zooms the view on touch devices |
|
||||
| Zoom buttons | Adjust zoom in fixed steps |
|
||||
| Click the zoom percent | Resets to the default zoom |
|
||||
|
||||
When zooming, the top capsule briefly shows the current zoom level, for example `Zoom 180%`. This indicates view zoom only, not data loading progress. Loading status takes priority and will not be interrupted by zoom feedback.
|
||||
|
||||
Drag sensitivity adjusts automatically based on the current zoom. Around the default view it keeps the normal rotation feel; when zoomed in, dragging becomes progressively finer for inspecting a region, vessel, satellite, or BGP event; when zoomed out, dragging is slightly faster for global browsing.
|
||||
|
||||
### Motion Capture Controls
|
||||
|
||||
Earth has a motion-capture control entry point for large-screen and future 3D displays. There are two realtime input sources: the default `Browser Camera` source uses webpage `getUserMedia` and recognizes gestures locally in the browser; the advanced `Motion Agent` source uses `camera/RTSP/HTTP -> local Agent -> local WebSocket -> Earth page`. Neither path sends camera frames or realtime gesture decisions to the cloud, and neither path reuses the news/RSS aggregation APIs.
|
||||
|
||||
It is disabled by default. Enable `Motion Debug Mode` in settings, open Earth with `?motion=1`, or set `planet-earth-motion-control-enabled=true` in browser local storage to start the selected source. The default source is `Browser Camera`; it requires HTTPS or localhost and a granted browser camera permission, but does not require installing an app. For dual cameras, USB indexes, phone/network camera streams, client integration, or edge devices, switch the setting to `Motion Agent`. The default Agent URL is `ws://127.0.0.1:8765/ws/gestures`; the `motionAgent` URL parameter can override it.
|
||||
|
||||
URL parameters can also force the source: `?motion=1&motionProvider=browser` uses the browser camera, `?motion=1&motionProvider=agent` uses Motion Agent, and providing `motionAgent=ws://...` automatically selects Motion Agent.
|
||||
|
||||
Current gesture semantics:
|
||||
|
||||
| Gesture event | Result |
|
||||
| --- | --- |
|
||||
| `rotate_left` | Rotates the globe left |
|
||||
| `rotate_right` | Rotates the globe right |
|
||||
| `rotate_up` | Rotates the globe upward |
|
||||
| `rotate_down` | Rotates the globe downward |
|
||||
| `zoom_in` | Zooms in |
|
||||
| `zoom_out` | Zooms out |
|
||||
| `focus_prev` / `focus_next` | Switches targets within the current motion layer |
|
||||
| `layer_prev` / `layer_next` | Switches the motion candidate layer and cruises to the nearest target in that layer |
|
||||
| `confirm` | Confirms the currently selected target; browser recognition currently keeps the two-hands-up confirm gesture disabled |
|
||||
|
||||
The settings panel also includes `Motion Debug Mode`, which opens the debug panel. With the Browser Camera source, the panel shows a local live preview and draws joints and bones over it. With the Motion Agent source, the Agent sends normalized skeleton events only and does not send raw video frames. The `Skeleton Only` switch hides the video preview and keeps the dark canvas plus skeleton; `Stop Matching Gestures` pauses gesture execution while preview and skeleton drawing can continue for debugging. Unmatched skeletons are red; once a gesture matches, the skeleton turns green and the matched gesture name is shown. Both this entry and the `Motion Input Source` control already carry Gatekeeper permission markers for future authorization control.
|
||||
|
||||
### Cruise Mode
|
||||
|
||||
Cruise mode makes Earth automatically cycle through focus targets.
|
||||
|
||||
Current cruise modules:
|
||||
|
||||
- BGP
|
||||
- News
|
||||
- Compute Centers
|
||||
- Vessels
|
||||
- Cables
|
||||
- Satellites
|
||||
|
||||
Suitable for demos, monitoring displays, or unattended presentations.
|
||||
|
||||
### Mobile
|
||||
|
||||
Earth has a mobile drawer layout. On small screens:
|
||||
|
||||
- Layer controls open in a mobile drawer
|
||||
- Search, settings, and details use mobile panels
|
||||
- Main interactions remain centered on globe object clicks, search, and layer toggles
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Earth Won't Open
|
||||
|
||||
Check whether the frontend is online:
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log -f
|
||||
```
|
||||
|
||||
If the frontend port is not `3000`, use the actual port shown at startup.
|
||||
|
||||
#### Layer Has No Data
|
||||
|
||||
Check the backend and data sources:
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log -b
|
||||
```
|
||||
|
||||
Then open the console and check:
|
||||
|
||||
- `/datasources`
|
||||
- `/data`
|
||||
- `/bgp`
|
||||
|
||||
#### Satellites, BGP, or Cables Load Slowly
|
||||
|
||||
These layers may depend on backend APIs, external data sources, or first-run collection tasks. Wait for startup tasks to finish before checking logs and console data source status.
|
||||
|
||||
## Console
|
||||
|
||||
Console entry point:
|
||||
|
||||
```text
|
||||
http://localhost:3000/admin
|
||||
```
|
||||
|
||||
The console requires login. Create a user first if this is your first time:
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
### Page Structure
|
||||
|
||||
The console uses React + Ant Design, with a left-side menu organized by work domain.
|
||||
|
||||
Common pages:
|
||||
The console at `http://localhost:3000/admin` is built with React + Ant Design. The left menu is organized by work domain.
|
||||
|
||||
| Page | Route | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Dashboard | `/admin` | System overview |
|
||||
| Earth | `/earth` | Opens the public Earth page |
|
||||
| Data Sources | `/datasources` | View data sources and trigger collection |
|
||||
| Collected Data | `/data` | View collected data |
|
||||
| BGP Observation | `/bgp` | BGP situational data |
|
||||
| Earth | `/earth` | Open the public Earth page |
|
||||
| Datasources | `/datasources` | Source directory and collection triggers |
|
||||
| Collected Data | `/data` | Data already ingested |
|
||||
| BGP | `/bgp` | BGP situational view |
|
||||
| System Alerts | `/alerts/system` | System-level alerts |
|
||||
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
|
||||
| Situational Alerts | `/alerts/situational` | Situational assessment alerts |
|
||||
| AI | `/ai` | Model providers, WebSearch-style tools, and testbench |
|
||||
| System Logs | `/logs` | View system logs (typically super admin only) |
|
||||
| Users | `/users` | User management |
|
||||
| Settings | `/settings` | System config and TV live stream sources |
|
||||
| Situational Alerts | `/alerts/situational` | Situational analysis alerts |
|
||||
| AI | `/ai` | Model providers, tools, testbench |
|
||||
| Logs | `/logs` | Usually visible only to super admin |
|
||||
| Users | `/users` | Create/delete users, change roles/groups |
|
||||
| Settings | `/settings` | System, SMTP, TV, collectors |
|
||||
|
||||
### Data Sources
|
||||
Menu items hide automatically when you lack permission. If a menu is missing, check your role and Gatekeeper groups.
|
||||
|
||||
`/datasources` shows collection sources and triggers collection. It is now a data source directory that lists built-in and custom sources in one table.
|
||||
## Configure Data Collectors
|
||||
|
||||
Common operations:
|
||||
`/settings?tab=collector_credentials` is the "Collector Settings" page. It manages connection configuration for every collector, not just credentials.
|
||||
|
||||
- View data source status
|
||||
- Trigger collection
|
||||
- View recent collection tasks
|
||||
- Open the read-only detail drawer for endpoint, headers, runtime config, and built-in/custom source type
|
||||
Steps:
|
||||
|
||||
If a category of objects is missing on Earth, start here to confirm the data source is available.
|
||||
1. Pick a collector in the dropdown.
|
||||
2. Inspect status tags:
|
||||
- `No credentials` / `Credentials required`
|
||||
- Owning module
|
||||
- `Enabled` / `Disabled`
|
||||
- `Unchecked` / `Reachable` / `Unreachable`
|
||||
3. Click the plug icon next to the dropdown to run a health check. On success the status becomes `Reachable`.
|
||||
4. Edit endpoint, headers, timeout, retries; click save.
|
||||
|
||||
The data source name opens an information drawer only. Endpoint, credentials, headers, and custom source configuration are maintained under `/settings` collector settings.
|
||||
For free collectors without credentials, the health check hits the endpoint directly. For credential-bearing collectors it runs the credential flow. If credentials or endpoint changed since the last successful check, click connect again.
|
||||
|
||||
When collection tasks are running, the progress area shows a clickable `Collecting N` pill. Clicking it opens a modal with each running task's phase, progress, and processed count.
|
||||
"Connected" means either: data was successfully collected with the current config, or the connect button passed validation with the current config.
|
||||
|
||||
### Collected Data
|
||||
### BarentsWatch AIS Credentials
|
||||
|
||||
`/data` shows the collected data table.
|
||||
|
||||
Useful for diagnosing:
|
||||
|
||||
- Whether data has entered the system
|
||||
- Whether data update times match expectations
|
||||
- Whether a data source produced valid records
|
||||
|
||||
### BGP Observation
|
||||
|
||||
`/bgp` is the BGP-focused page.
|
||||
|
||||
It complements the BGP layer on Earth:
|
||||
|
||||
- Earth emphasizes spatial posture and visual focus
|
||||
- The console BGP page emphasizes lists, status, details, and assessment
|
||||
|
||||
### Alerts
|
||||
|
||||
Alert entry points:
|
||||
|
||||
- `/alerts/system`
|
||||
- `/alerts/bgp`
|
||||
- `/alerts/situational`
|
||||
|
||||
Used to view system, network, and situational alerts.
|
||||
|
||||
### System Settings
|
||||
|
||||
`/settings` manages system-level configuration.
|
||||
|
||||
Current common uses:
|
||||
|
||||
- System settings
|
||||
- TV live stream source configuration
|
||||
- Collector settings
|
||||
|
||||
### AI
|
||||
|
||||
`/ai` manages the AI runtime chain and is now separate from system settings. Legacy `/playground` redirects to `/ai?tab=playground`.
|
||||
|
||||
It currently contains:
|
||||
|
||||
- `模型供应商`: default LLM provider, model, base URL, API key, local `aiprovider` proxy, and connection test
|
||||
- `工具`: WebSearch provider, search API key, base URL, max results, timeout, and advanced provider options
|
||||
- `测试台`: AI Provider status, preset prompts, and real analysis-chain debugging
|
||||
|
||||
Legacy `/settings?tab=ai` redirects to `/ai?tab=providers`.
|
||||
|
||||
Available configuration depends on the current user's role.
|
||||
|
||||
#### Collector Settings
|
||||
|
||||
`/settings?tab=collector_credentials` is currently displayed as Collector Settings. It manages connection settings for all collectors, not only credentials.
|
||||
|
||||
Use it to:
|
||||
|
||||
1. Select a collector from the dropdown.
|
||||
2. Review tags such as `Requires credentials`, module, enabled state, and `Unchecked` / `Available` / `Unavailable`.
|
||||
3. Click the plug icon next to the selector to run a health check.
|
||||
4. Edit endpoint, request headers, timeout, and retry settings.
|
||||
5. Save the collector settings.
|
||||
|
||||
Free collectors are checked by requesting their endpoint directly. Credentialed collectors use their credential provider. If endpoint or credential fingerprint changes after the last successful validation, the collector must be checked again.
|
||||
|
||||
The system treats a collector as connected when the current configuration has either collected data successfully or passed the manual connection check.
|
||||
|
||||
#### BarentsWatch AIS Credentials
|
||||
|
||||
`BarentsWatch AIS` is a credentialed built-in collector. Its credential card appears above the basic configuration card.
|
||||
|
||||
Configured fields:
|
||||
`BarentsWatch AIS` is a credential-required built-in collector. Selecting it surfaces the credential section above the base configuration:
|
||||
|
||||
- `Client ID`
|
||||
- `Client Secret`
|
||||
- `Endpoint`
|
||||
|
||||
If a secret is already configured, the input shows a masked preview. Keeping that preview unchanged preserves the stored secret; entering a new value replaces it.
|
||||
If a secret was saved previously, the input shows a masked preview. Saving while keeping the preview unchanged preserves the original secret; entering a new secret overwrites it.
|
||||
|
||||
BarentsWatch AIS credentials can be read from:
|
||||
When the connection fails, the page opens a credential guide. You can:
|
||||
|
||||
1. Collector settings saved in the console.
|
||||
2. Backend environment variables:
|
||||
- `BARENTSWATCH_CLIENT_ID`
|
||||
- `BARENTSWATCH_CLIENT_SECRET`
|
||||
- historical spellings: `BARRENTSWATCH_CLIENT_ID`, `BARRENTSWATCH_CLIENT_SECRET`
|
||||
3. matching `export` lines in `~/.zshrc`.
|
||||
- View the default guide
|
||||
- Click "Guide not helpful" to ask AI Provider to regenerate from the default prompt
|
||||
- Click "Reset" to restore the default guide
|
||||
|
||||
If connection fails, the page opens the credential guide. The guide can be regenerated through AI Provider or reset to the default guide. The default guide points users to the official BarentsWatch tutorial and emphasizes selecting `AIS - API`, not the regular `BarentsWatch - API`.
|
||||
The default guide follows the BarentsWatch official tutorial and reminds you to choose `AIS - API` for Live AIS.
|
||||
|
||||
### System Logs
|
||||
### AISStream Realtime Vessels
|
||||
|
||||
`/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.
|
||||
`AISStream Realtime Vessels` is the global AIS WebSocket collector. A passing connection test only confirms API key + endpoint format. Actual global vessel data requires the backend `aisstream_vessels` collector to stay connected and write to `ais_raw_observations`.
|
||||
|
||||
Common troubleshooting sequence:
|
||||
Steps:
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
./planet.sh log
|
||||
```
|
||||
1. Open `/settings?tab=collector_credentials` and select `AISStream Realtime Vessels : aisstream_vessels`
|
||||
2. Fill the AISStream API Key
|
||||
3. Keep the default endpoint `wss://stream.aisstream.io/v0/stream`
|
||||
4. Click the plug icon to test; confirm it reports `Reachable`
|
||||
5. Save collector settings
|
||||
6. Trigger the `aisstream_vessels` collector from the collection scheduler
|
||||
7. Watch the `AISStream Runtime` panel:
|
||||
- `streaming` / `connected` means the live stream is being consumed
|
||||
- `messages this round` should keep growing
|
||||
- `disconnected` with `ConnectionResetError` means the upstream or network dropped; re-trigger or wait for reconnect
|
||||
|
||||
Then open `/logs` for more structured runtime information.
|
||||
## Configure AI Credentials
|
||||
|
||||
## Docs
|
||||
`/ai?tab=providers` is the AI management entry. Two key sub-tabs:
|
||||
|
||||
Documentation site:
|
||||
- `Model Providers`: default LLM provider, model, base URL, API key, local `aiprovider` proxy, connection test
|
||||
- `Tools`: a dropdown for specific tools — currently WebSearch and OCR
|
||||
|
||||
```text
|
||||
http://localhost:3000/docs
|
||||
```
|
||||
### Model Providers
|
||||
|
||||
Docs content is read through backend APIs by permission. The frontend no longer bundles all Markdown files directly. Source files still live in:
|
||||
Providers and models accept presets or arbitrary custom IDs. Common fields:
|
||||
|
||||
```text
|
||||
docs/technical/zh/ (Chinese)
|
||||
docs/technical/en/ (English)
|
||||
```
|
||||
- Provider: e.g. `minimax`, `openai`, `anthropic`, `ollama`
|
||||
- Protocol: `OpenAI Chat Completions` / `Anthropic Messages` / `Ollama Generate`
|
||||
- Base URL: model API URL
|
||||
- Default Model: e.g. `gpt-5.1`, `MiniMax-M2.7`
|
||||
- API Key: stored on save; displayed masked afterwards
|
||||
- Max Tokens, Anthropic Version: keep defaults if unsure
|
||||
- Timeout / Retry: timeout and retry attempts
|
||||
|
||||
Anonymous visitors only see `public` docs such as the overview, quickstart, and manual. Logged-in users can see more technical docs when assigned Gatekeeper groups:
|
||||
The plug icon at the end of the Base URL input runs a connection test. A passing test echoes the model's short reply.
|
||||
|
||||
- `docs_user`: user-operation docs.
|
||||
- `docs_developer`: Earth, frontend, backend, collector, and AI Provider development docs.
|
||||
- `docs_admin`: service control, operations, environment variable, and sensitive-operation docs.
|
||||
### Tools
|
||||
|
||||
`admin` receives admin-doc access by default, and `super_admin` can read all Docs content. Gatekeeper groups are configured in the console Users page.
|
||||
- **WebSearch**: provider, API key, base URL, max results, timeout, advanced provider parameters. While disabled, all fields except the enable switch are greyed out
|
||||
- **OCR**: provider, base URL, API key, model/engine, recognition languages, timeout, max file size, output format
|
||||
|
||||
Docs supports:
|
||||
The legacy link `/settings?tab=ai` redirects to `/ai?tab=providers`.
|
||||
|
||||
- Category navigation
|
||||
- Markdown rendering
|
||||
- Tables and code blocks
|
||||
- In-document table of contents
|
||||
- Search across currently visible docs
|
||||
- Internal links between technical documents
|
||||
## System Settings
|
||||
|
||||
When adding a new technical document, check:
|
||||
`/settings` manages system-level configuration. Sub-tabs:
|
||||
|
||||
- Does it have a clear top-level heading
|
||||
- Does it need to be added to backend Docs metadata for category and ordering
|
||||
- Should it be classified as `public`, `docs_user`, `docs_developer`, or `docs_admin`
|
||||
- **System Display**: name, refresh interval, retention, max concurrent tasks
|
||||
- **Notifications**: alert email switch, recipient, critical/warning/daily summary
|
||||
- **Security**: session timeout, max login attempts, password policy
|
||||
- **SMTP Email**: outgoing email used by registration and password reset (visible to `admin` / `super_admin` only)
|
||||
- **TV Livestream**: TV source management
|
||||
- **AI / WebSearch / OCR**: see above
|
||||
|
||||
## Development Command Conventions
|
||||
### SMTP Email Settings
|
||||
|
||||
Frontend commands must use Bun:
|
||||
Public registration and verification codes depend on this section. An `admin` or `super_admin` opens `/settings -> SMTP Email` and fills:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
bun install
|
||||
bun run dev
|
||||
bun run build
|
||||
```
|
||||
- SMTP host, port
|
||||
- Username, password
|
||||
- From address (required), from name
|
||||
- STARTTLS (typical for port 587) or implicit TLS (port 465)
|
||||
- Timeout in seconds
|
||||
|
||||
Do not use `npm run ...`. The project uses Bun in WSL / Windows mixed environments to avoid Node/npm path compatibility issues.
|
||||
Save, then click "Send Test Email" and enter a recipient address to verify delivery. Once that works, regular users can self-register at `/register`.
|
||||
|
||||
Verify the frontend build:
|
||||
Leaving the masked password preview unchanged keeps the original password. Enter a new value to replace it.
|
||||
|
||||
```bash
|
||||
source ~/.zshrc && bun run build
|
||||
```
|
||||
## User Management (Admins)
|
||||
|
||||
## Troubleshooting Order
|
||||
`/users` is `super_admin`-only for create/delete. The page supports:
|
||||
|
||||
When something goes wrong, follow this sequence:
|
||||
- Listing users (username, email, role, active, email verified)
|
||||
- Creating users (equivalent to public registration but skips email verification — administrator vouching)
|
||||
- Changing roles: `viewer` / `operator` / `admin` / `super_admin`
|
||||
- Editing Gatekeeper groups: `docs_user` / `docs_developer` / `docs_admin`, controlling which docs are visible
|
||||
- Disabling / enabling accounts
|
||||
|
||||
1. Check service status:
|
||||
To let a regular user read developer or operations docs, add `docs_developer` or `docs_admin` at `/users`.
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
## Data Exploration
|
||||
|
||||
2. Check recent logs:
|
||||
- `/datasources`: source directory. It can be filtered by product domain, layer/module, enabled state, last run status, whether collected records exist, and search text. Selecting rows triggers only those sources; with no selected rows, `Collect current filter` triggers the filtered scope. Clicking a name opens an info drawer showing endpoint, headers, base config, and built-in flag; endpoint/credentials editing happens at `/settings -> Collector Settings`. The `Collecting N` tag under the overall progress can be clicked to expand the current collection task list
|
||||
- `/data`: collected data table — used to verify "did data arrive", "is the freshness right", "does a source emit valid records"
|
||||
- `/bgp`: BGP detail page with list + detail + analysis; complements the BGP layer on Earth
|
||||
- `/alerts/system`, `/alerts/bgp`, `/alerts/situational`: system, BGP, and situational alerts
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
## AI Testbench
|
||||
|
||||
3. Check per-module logs:
|
||||
`/ai?tab=playground` is for real-pipeline debugging:
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
- Pick the active provider
|
||||
- Run preset requests or custom prompts
|
||||
- Watch AI Provider status and response
|
||||
|
||||
4. Restart only the affected module:
|
||||
The legacy link `/playground` redirects here.
|
||||
|
||||
```bash
|
||||
./planet.sh restart -f
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -a
|
||||
```
|
||||
## Earth Public Page
|
||||
|
||||
5. If database or cache is abnormal, restart the database:
|
||||
Earth at `http://localhost:3000/earth` is the public 3D situational page; no login required. The React route `/earth` wraps a standalone frontend (in `frontend/public/earth/`) via iframe.
|
||||
|
||||
```bash
|
||||
./planet.sh restart -d
|
||||
```
|
||||
### Primary Uses
|
||||
|
||||
6. If still unrecovered, do a full restart:
|
||||
A single globe view of: BGP events and observations, satellites and tracks, cables and landing points, compute centers, country boundaries / graticules / high-res tiles / clouds / terrain, news live streams and situational news, search and focus details.
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
### Layer Control
|
||||
|
||||
The right-side layer panel toggles layers. Common layers: graticule, country boundaries, high-res tiles, atmospheric clouds, cables, compute centers, BGP, satellites, AIS vessels, tracks, terrain.
|
||||
|
||||
Dependencies:
|
||||
|
||||
- Terrain depends on high-res tiles
|
||||
- Tracks depend on satellites
|
||||
- With high-res tiles disabled, the globe shows the base map with edge highlighting
|
||||
|
||||
### Legend
|
||||
|
||||
The bottom-left legend follows the focused or enabled layer. Covered: cables, satellites, country boundaries, compute centers, BGP, AIS vessels.
|
||||
|
||||
AIS vessel legend colors by type: cargo, tanker, passenger, fishing, military, moored/slow, other. Triangles indicate moving vessels; dots indicate moored or slow targets.
|
||||
|
||||
### Search
|
||||
|
||||
Search finds cables, landing points, satellites, compute centers, BGP events, BGP observers. Results jump to and focus the object.
|
||||
|
||||
### Coordinate Candidate Collection
|
||||
|
||||
Compute center and BGP observer detail cards support automatic coordinate-candidate collection. Click the object then use "Collect Coordinate Candidates" or "Re-collect Coordinates". The backend assembles candidates from source coordinates, public-org registry APIs, and online geocoders. When regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback. BGP observers' stored coordinates only fill query context; they are not returned as candidates.
|
||||
|
||||
Candidates preview on Earth directly. Saving a compute-center candidate writes to the `compute_center_locations` dimension table and refreshes the layer immediately. The notification badge at the top-left of the compute-center layer shows the unresolved count; clicking it opens the queue, supports single collection, or "Adopt All" to save the top-confidence candidates from top to bottom. Records without candidates stay in the queue rather than being faked to country centroids. See [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md).
|
||||
|
||||
### Settings
|
||||
|
||||
The settings panel covers: rotate / cruise / motion mode, cruise modules (BGP/news/compute centers/vessels/cables/satellites), view (satellite display style, day-night mode, panel toggles), motion debug mode / input source / skeleton-only, default globe size, terrain opacity, reset.
|
||||
|
||||
These settings live in browser local storage; switching browsers or clearing site data resets them.
|
||||
|
||||
### View Controls
|
||||
|
||||
| Action | Effect |
|
||||
| --- | --- |
|
||||
| Mouse drag | Rotate the globe |
|
||||
| Single-finger drag | Touch rotate |
|
||||
| Mouse wheel | Zoom in/out |
|
||||
| Pinch | Touch zoom |
|
||||
| Zoom button | Stepped zoom |
|
||||
| Click zoom percentage | Reset to default zoom |
|
||||
|
||||
A small pill at the top briefly shows the current zoom while zooming. This is not a data loading indicator; if data is loading, the loading state takes precedence.
|
||||
|
||||
Drag sensitivity adjusts to zoom: near the default it is normal; zoomed in it is finer for targeted inspection; zoomed out it is slightly faster for global browsing.
|
||||
|
||||
### Motion Capture
|
||||
|
||||
Earth supports motion capture. Two live inputs:
|
||||
|
||||
- **Browser Camera** (default): uses `getUserMedia` in the page. No install needed but the page must run on HTTPS or localhost, and the user must grant camera permission
|
||||
- **Motion Agent**: camera/RTSP/HTTP → local agent → local WebSocket → Earth. Used for dual cameras, USB index, phone/IP camera streams
|
||||
|
||||
Enable via the settings toggle "Motion Debug Mode", or with URL parameter `?motion=1`. Motion Agent defaults to `ws://127.0.0.1:8765/ws/gestures`; override with `motionAgent`. You can also pin the input with `?motion=1&motionProvider=browser` or `?motion=1&motionProvider=agent`.
|
||||
|
||||
Neither mode uploads camera frames or live gestures; neither reuses the news/RSS aggregation API.
|
||||
|
||||
Gesture semantics:
|
||||
|
||||
| Event | Effect |
|
||||
| --- | --- |
|
||||
| `rotate_left/right/up/down` | Rotate accordingly |
|
||||
| `zoom_in/out` | Zoom |
|
||||
| `focus_prev/next` | Cycle focusable targets within the current layer |
|
||||
| `layer_prev/next` | Switch layer and pan to nearest target |
|
||||
| `confirm` | Confirm the current selection |
|
||||
|
||||
In the debug panel: the browser camera input shows the live preview with skeleton overlay; Motion Agent sends only normalized skeleton events, never raw frames. "Skeleton Only" hides the video and keeps just the skeleton; "Stop Matching" pauses gesture firing while keeping preview and skeleton. Unmatched skeleton is red; matched turns green and shows the action name.
|
||||
|
||||
### Cruise Mode
|
||||
|
||||
Cruise mode auto-rotates focused targets. Current modules: BGP, news, compute centers, vessels, cables, satellites. Suitable for demos, control rooms, and unattended displays.
|
||||
|
||||
### Mobile
|
||||
|
||||
Mobile uses a drawer layout: layer control moves into a drawer; search/settings/details use mobile panels. Main interaction is still object tap, search, and layer toggles.
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **Earth does not open**: confirm the frontend is online; if not on port `3000`, use the port printed by the startup log
|
||||
- **Layers have no data**: open `/datasources` to check source status, collected-record state, and the latest run result; then `/data` or `/bgp` for records
|
||||
- **Satellites / BGP / cables load slowly**: those layers depend on backend APIs and external data sources; the first load waits for startup tasks
|
||||
|
||||
## Docs Site
|
||||
|
||||
Docs at `http://localhost:3000/docs` are served by the backend with access control, not bundled into the frontend build.
|
||||
|
||||
Anonymous visitors see only `public` docs: README, Quickstart, Manual, FAQ, Earth Location Candidate Collection User Guide. Authenticated users with Gatekeeper groups see more:
|
||||
|
||||
- `docs_user`: end-user operational docs
|
||||
- `docs_developer`: Earth, frontend, backend, collectors, AI Provider development docs
|
||||
- `docs_admin`: service control, operations, environment variables, sensitive operations (including the Ops Runbook)
|
||||
|
||||
`admin` has `docs_admin` by default; `super_admin` has all docs permissions. Gatekeeper groups are managed at `/users`.
|
||||
|
||||
Docs supports: category navigation, Markdown rendering, tables and code blocks, in-doc table of contents, search across currently visible docs, internal links between technical docs.
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [Quickstart](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
|
||||
- [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
|
||||
- [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
|
||||
- [Earth Layer Style Reference](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
|
||||
- [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md)
|
||||
- [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
|
||||
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
|
||||
- [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
|
||||
- [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md)
|
||||
|
||||
244
docs/technical/en/ops-runbook.md
Normal file
244
docs/technical/en/ops-runbook.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Planet Ops Runbook
|
||||
|
||||
This runbook is for deployment, on-call, and maintenance engineers. End-user UI flows live in the [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md); this document only covers shell, Docker, logs, environment variables, and troubleshooting.
|
||||
|
||||
## First Startup
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
|
||||
Default behavior:
|
||||
|
||||
- Starts PostgreSQL and Redis
|
||||
- Starts AI Provider
|
||||
- Starts the backend API
|
||||
- Starts the frontend Vite dev server
|
||||
- Prints Earth, console, Playground, and backend API doc URLs
|
||||
|
||||
First startup seeds two default accounts (see `DEFAULT_LOGIN_USERS` in `backend/app/db/session.py`):
|
||||
|
||||
| Username | Password | Role |
|
||||
| --- | --- | --- |
|
||||
| `admin` | `admin123` | `super_admin` |
|
||||
| `linkong` | `12345678` | `super_admin` |
|
||||
|
||||
Both seed accounts are created with `email_verified = TRUE` and can log into the console immediately. Any other account must either go through the public registration flow described in the Manual, or be created via `./planet.sh createuser`.
|
||||
|
||||
Specify custom ports:
|
||||
|
||||
```bash
|
||||
./planet.sh start -b 8001 -f 3001 -a 8101
|
||||
```
|
||||
|
||||
| Flag | Meaning |
|
||||
| --- | --- |
|
||||
| `-b <port>` | Backend port |
|
||||
| `-f <port>` | Frontend port |
|
||||
| `-a <port>` | AI Provider port |
|
||||
| `--allow-lan` | Enable LAN access |
|
||||
| `--verbose` | Show extra command output |
|
||||
|
||||
## Stop and Per-Module Restart
|
||||
|
||||
Stop everything:
|
||||
|
||||
```bash
|
||||
./planet.sh stop
|
||||
```
|
||||
|
||||
Stops backend, AI Provider, frontend, PostgreSQL, Redis.
|
||||
|
||||
Per-module restart:
|
||||
|
||||
```bash
|
||||
./planet.sh restart # full
|
||||
./planet.sh restart -b # backend
|
||||
./planet.sh restart -f # frontend
|
||||
./planet.sh restart -a # AI Provider
|
||||
./planet.sh restart -d # database
|
||||
```
|
||||
|
||||
Per-module restart is preferred during development to avoid interrupting unrelated services.
|
||||
|
||||
## Health Check
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
- `planet_*` container status
|
||||
- Backend `/health`
|
||||
- AI Provider `/health`
|
||||
- Frontend reachability
|
||||
|
||||
If anything reports offline, check the corresponding logs first.
|
||||
|
||||
## Logs
|
||||
|
||||
Recent logs:
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
Follow:
|
||||
|
||||
```bash
|
||||
./planet.sh log -f # frontend: /tmp/planet_frontend.log
|
||||
./planet.sh log -b # backend: /tmp/planet_backend.log
|
||||
./planet.sh log -a # AI Provider: planet_aiprovider container logs
|
||||
```
|
||||
|
||||
## CLI User Creation
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
Interactively prompts for username, password, and role; writes the user with `email_verified = TRUE` directly.
|
||||
|
||||
Use when:
|
||||
|
||||
- SMTP is not yet configured but an admin account is needed now
|
||||
- Pre-seeding internal test accounts
|
||||
- Public registration is unavailable for any reason and a fallback is required
|
||||
|
||||
For ordinary user onboarding, configure SMTP at `/settings -> SMTP Email` first and let users self-register at `/register`.
|
||||
|
||||
## LAN / WSL Access
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
Useful for:
|
||||
|
||||
- Starting in WSL, accessing from Windows browser
|
||||
- Demoing Earth from a phone or tablet
|
||||
- Other LAN machines reaching the same dev instance
|
||||
|
||||
`--allow-lan` only makes the frontend and backend listen on `0.0.0.0`. When Planet runs in WSL, Windows can usually reach it through `localhost`, but other LAN machines hitting `http://<Windows LAN IP>:3000` still need Windows port forwarding and firewall rules.
|
||||
|
||||
Diagnose in this order:
|
||||
|
||||
```bash
|
||||
# From the shell running Planet
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
If WSL shows `0.0.0.0:3000` / `0.0.0.0:8000` but the LAN IP still fails, configure Windows from an elevated 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 Environment and Builds
|
||||
|
||||
AI Provider runtime configuration lives in two places:
|
||||
|
||||
| Location | Best for | Notes |
|
||||
| --- | --- | --- |
|
||||
| `aiprovider/.env` | Team-shared local defaults | Read by Docker Compose as `env_file` |
|
||||
| `~/.zshrc` | Personal provider/model/key/proxy | `planet.sh` reads common `AI_*`, `SERVICE_*`, `PYTHON_IMAGE`, `UV_IMAGE` lines |
|
||||
|
||||
Recommended form:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
By default `planet.sh` only statically parses simple `export KEY=value` lines from `~/.zshrc`. When complex shell expansion is required, opt in explicitly:
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=source ./planet.sh start -a
|
||||
```
|
||||
|
||||
To ignore `~/.zshrc` entirely:
|
||||
|
||||
```bash
|
||||
PLANET_LOAD_ZSHRC_ENV=0 ./planet.sh start -a
|
||||
```
|
||||
|
||||
The AI Provider image only rebuilds when code, Dockerfile, Compose config, or Python dependencies change. After changing keys or base URL, restarting the container is enough:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
Diagnose slow builds:
|
||||
|
||||
| Symptom | Common cause | Fix |
|
||||
| --- | --- | --- |
|
||||
| Large `transferring context` | build context includes unrelated frontend / data files | `.dockerignore` ships only required files |
|
||||
| `uv sync` is slow | first build or cold cache | wait for the first build; later runs reuse BuildKit cache |
|
||||
| Old keys still in effect after edit | container not restarted | `./planet.sh restart -a` |
|
||||
|
||||
## SMTP Email (Required for Public Registration)
|
||||
|
||||
Public registration and email verification depend on SMTP. Administrators configure host, port, username, password, from-address, and TLS mode at `/settings -> SMTP Email` in the console, then use the "Send Test Email" button to verify. Settings are persisted in the `system_settings.smtp` row.
|
||||
|
||||
When SMTP is unset, `POST /api/v1/auth/register` returns `503 EMAIL_PROVIDER_NOT_CONFIGURED` and the frontend surfaces a clear error. The operational fallback is `./planet.sh createuser`.
|
||||
|
||||
One-time codes are stored in Redis under `otp:{purpose}:{email}` with a 600-second TTL. The key is invalidated after 5 invalid attempts. Resend cooldown is 60 seconds, enforced via `otp_rate:{purpose}:{email}`.
|
||||
|
||||
## Troubleshooting Order
|
||||
|
||||
```bash
|
||||
./planet.sh health # 1. service state
|
||||
./planet.sh log # 2. recent logs
|
||||
./planet.sh log -f # 3. per-module logs
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
./planet.sh restart -f # 4. restart only the affected module
|
||||
./planet.sh restart -b
|
||||
./planet.sh restart -a
|
||||
./planet.sh restart -d # 5. database / cache issues
|
||||
./planet.sh restart # 6. full restart if still broken
|
||||
```
|
||||
|
||||
## Development Command Conventions
|
||||
|
||||
Frontend must use Bun:
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
bun install
|
||||
bun run dev
|
||||
bun run build
|
||||
```
|
||||
|
||||
Do not use `npm run ...`. In the WSL / Windows mixed environment Bun avoids Node/npm path inconsistencies.
|
||||
|
||||
Validate the frontend build:
|
||||
|
||||
```bash
|
||||
source ~/.zshrc && bun run build
|
||||
```
|
||||
|
||||
Backend dependencies are managed with uv:
|
||||
|
||||
```bash
|
||||
uv sync
|
||||
uv run pytest backend/tests/test_otp_service.py
|
||||
```
|
||||
|
||||
## Related Docs
|
||||
|
||||
- [planet.sh Startup Mechanism](/home/ray/dev/linkong/planet/docs/technical/en/ops-planet-sh-startup.md)
|
||||
- [System Service Control](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
|
||||
- [Docker + Compose + Buildx Upgrade](/home/ray/dev/linkong/planet/docs/technical/en/ops-docker-compose-buildx-upgrade.md)
|
||||
- [Data Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
|
||||
@@ -1,236 +1,66 @@
|
||||
# Quickstart
|
||||
|
||||
This guide is for developers or demo operators starting Planet for the first time. The goal is to get services running via the shortest path and know which URLs to open.
|
||||
This quickstart is for Planet end users who just received an access URL and need the shortest path from "open the browser" to "first useful configuration done". Every action happens in the browser.
|
||||
|
||||
If you run into port conflicts, Windows / WSL LAN access, `uv` / `bun`, camera, or Docs permission issues, start with the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md).
|
||||
If you are responsible for deployment or operations, read the [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md) instead.
|
||||
|
||||
## Prerequisites
|
||||
## 1. Open the URL
|
||||
|
||||
Recommended: run in a WSL / Linux shell.
|
||||
Open the URL your administrator gave you, e.g. `http://planet.example.com`. A local demo is usually `http://localhost:3000`.
|
||||
|
||||
You need:
|
||||
Entry points are split in two:
|
||||
|
||||
- Docker / Docker Compose available
|
||||
- `uv` and `bun` accessible in the current shell
|
||||
- Repository cloned locally
|
||||
- Public: `/earth` (3D situational view), `/docs` (public documentation)
|
||||
- Login required: `/admin` (console), `/ai` (AI), `/settings` (system configuration)
|
||||
|
||||
On a new machine, run the bootstrap script first:
|
||||
## 2. Register
|
||||
|
||||
```bash
|
||||
./scripts/bootstrap-dev.sh
|
||||
```
|
||||
1. Open `/login` and click "Register" under the form.
|
||||
2. On `/register`, fill in username, email, password (≥ 8 characters).
|
||||
3. After submission, check your inbox for a 6-digit verification code (valid for 10 minutes).
|
||||
4. Enter the code on the verify page and click "Verify and Sign In". You are taken to the console automatically.
|
||||
|
||||
This script checks and syncs common dependencies, and generates if missing:
|
||||
If the email does not arrive:
|
||||
|
||||
- `backend/.env`
|
||||
- `aiprovider/.env`
|
||||
- `frontend/.env.local`
|
||||
- Check spam and your enterprise mail gateway
|
||||
- The "Resend Code" button has a countdown; you can resend once it ends
|
||||
- A "Email service not configured" message means your administrator has not yet set up SMTP — please ping them
|
||||
|
||||
Personal AI Provider configuration can also live in `~/.zshrc`. `planet.sh` reads simple `export AI_...=...` / `AI_...=...` lines and passes them to the AI Provider container. After changing model, key, or base URL, restart only AI Provider:
|
||||
The default role is `viewer`: you can sign in but only see public pages. For collectors, user management, or system settings, ask the admin to promote your role or add Gatekeeper groups.
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
## 3. First Sign-In Checklist
|
||||
|
||||
Collector credentials such as AISStream and BarentsWatch can also start in `~/.zshrc` for connectivity validation:
|
||||
After landing on the `/admin` dashboard, here's a recommended walk-through:
|
||||
|
||||
```bash
|
||||
export AISSTREAM_API_KEY="..."
|
||||
export BARENTSWATCH_CLIENT_ID="..."
|
||||
export BARENTSWATCH_CLIENT_SECRET="..."
|
||||
```
|
||||
1. `/settings?tab=collector_credentials`: pick a collector and click the plug icon to test connectivity. Free collectors (e.g. open BGP) usually work right away; credential-bearing ones like `AISStream` or `BarentsWatch` need an API key / client secret first
|
||||
2. `/ai?tab=providers`: fill an LLM provider (e.g. `minimax` / `openai`), model, base URL, API key, and click the plug at the end of the base URL to test. WebSearch / OCR tools are optional
|
||||
3. `/datasources` or `/data`: check whether the collectors have produced data
|
||||
4. `/alerts/system`: verify system alerts look right
|
||||
5. `/users` (super_admin only): open accounts for teammates or adjust their groups
|
||||
|
||||
For actual collection, prefer saving credentials in `Settings -> Collector Settings`, especially for AISStream's long-lived WebSocket collector. That keeps connectivity validation, backend collection tasks, and Earth realtime vessel aggregation on the same configuration source.
|
||||
## 4. Open Earth
|
||||
|
||||
## 1. Start Services
|
||||
|
||||
From the repository root:
|
||||
|
||||
```bash
|
||||
./planet.sh start
|
||||
```
|
||||
|
||||
After startup, the key URLs are:
|
||||
|
||||
| Entry | Default URL | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Earth | `http://localhost:3000/earth` | Public 3D Earth visualization |
|
||||
| Console | `http://localhost:3000/admin` | Admin console (login required) |
|
||||
| Docs | `http://localhost:3000/docs` | Usage docs are public; developer and operations docs require Gatekeeper groups |
|
||||
| AI | `http://localhost:3000/ai` | Model provider, tool, and testbench entry (login required) |
|
||||
| Backend API Docs | `http://localhost:8000/docs` | FastAPI / OpenAPI interface docs |
|
||||
|
||||
If the default ports are taken, specify custom ports:
|
||||
|
||||
```bash
|
||||
./planet.sh start -f 3001 -b 8001 -a 8101
|
||||
```
|
||||
|
||||
If backend port `8000` is occupied by a Windows listener or an old portproxy rule, follow the [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md) troubleshooting order.
|
||||
|
||||
## 2. Create a Login User
|
||||
|
||||
The console requires login. For first-time use:
|
||||
|
||||
```bash
|
||||
./planet.sh createuser
|
||||
```
|
||||
|
||||
Follow the prompts to enter username, password, and role.
|
||||
|
||||
To read developer or operations docs, log in as `super_admin` and assign Gatekeeper groups from the Users page. Use `docs_developer` for development docs and `docs_admin` for service-control and operations docs.
|
||||
|
||||
## 3. Open Earth
|
||||
|
||||
Visit:
|
||||
|
||||
```text
|
||||
http://localhost:3000/earth
|
||||
```
|
||||
|
||||
Earth is a public page — no login required.
|
||||
Visit `/earth`. This is a public page — no login required.
|
||||
|
||||
Once in, verify:
|
||||
|
||||
- The globe renders correctly
|
||||
- The right-side layer panel can toggle layers on/off
|
||||
- Search can find cables, satellites, compute centers, BGP events
|
||||
- Compute-center and BGP collector detail cards can collect and preview coordinate candidates; when regular sources have no candidate, the current default AI Provider runs one LLM factcheck fallback; the compute-center unresolved badge can open the queue and save candidates
|
||||
- Mouse drag, wheel zoom, and zoom percent feedback work correctly
|
||||
- Settings panel can switch rotate / cruise / motion mode, day/night mode, and satellite display style; Motion Debug Mode can show the local Browser Camera preview plus skeleton overlay
|
||||
- The globe renders, and the right-side layer panel can toggle layers
|
||||
- Search finds cables, satellites, compute centers, BGP events
|
||||
- Compute-center and BGP collector detail cards can collect coordinate candidates and preview them on Earth
|
||||
- Mouse drag, wheel zoom, and the zoom percentage indicator work
|
||||
- The settings panel can switch rotate / cruise / motion modes
|
||||
|
||||
## 4. Open the Console
|
||||
## 5. Recover a Lost Password
|
||||
|
||||
Visit:
|
||||
Open `/forgot-password`, enter your email, receive a code, then enter the code plus a new password. The same confirmation is shown for unknown emails (to avoid enumeration).
|
||||
|
||||
```text
|
||||
http://localhost:3000/admin
|
||||
```
|
||||
## 6. Read the Docs
|
||||
|
||||
The console manages data sources, collected data, situational observation, alerts, system logs, and configuration.
|
||||
|
||||
First-time inspection checklist:
|
||||
|
||||
- `/datasources`: data source directory and collection triggers; endpoint, headers, and credentials are configured under `/settings` collector settings
|
||||
- `/data`: collected data
|
||||
- `/bgp`: BGP situational view
|
||||
- `/ai`: AI page for model providers, WebSearch-style tools, and the testbench
|
||||
- `/alerts/system`: system alerts
|
||||
- `/settings`: system configuration
|
||||
|
||||
## 5. Check Service Health
|
||||
|
||||
```bash
|
||||
./planet.sh health
|
||||
```
|
||||
|
||||
This shows container status and checks:
|
||||
|
||||
- Backend
|
||||
- AI Provider
|
||||
- Frontend
|
||||
|
||||
## 6. View Logs
|
||||
|
||||
Recent logs:
|
||||
|
||||
```bash
|
||||
./planet.sh log
|
||||
```
|
||||
|
||||
Follow a specific service:
|
||||
|
||||
```bash
|
||||
./planet.sh log -f
|
||||
./planet.sh log -b
|
||||
./planet.sh log -a
|
||||
```
|
||||
|
||||
Flags:
|
||||
|
||||
- `-f`: frontend logs
|
||||
- `-b`: backend logs
|
||||
- `-a`: AI Provider logs
|
||||
|
||||
## 7. Common Restarts
|
||||
|
||||
Frontend only:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -f
|
||||
```
|
||||
|
||||
Backend only:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -b
|
||||
```
|
||||
|
||||
AI Provider only:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -a
|
||||
```
|
||||
|
||||
Database only:
|
||||
|
||||
```bash
|
||||
./planet.sh restart -d
|
||||
```
|
||||
|
||||
Full restart:
|
||||
|
||||
```bash
|
||||
./planet.sh restart
|
||||
```
|
||||
|
||||
## 8. LAN Access
|
||||
|
||||
To allow a Windows browser, phone, or another device on the same network:
|
||||
|
||||
```bash
|
||||
./planet.sh start --allow-lan
|
||||
```
|
||||
|
||||
This makes the frontend and backend listen on a LAN-accessible address.
|
||||
|
||||
Note: `--allow-lan` only makes Planet listen on `0.0.0.0`; it does not automatically expose WSL services through the Windows LAN IP. A common pattern is:
|
||||
|
||||
- `localhost:3000` / `localhost:8000` works inside WSL
|
||||
- `localhost:3000` / `localhost:8000` works on Windows
|
||||
- `http://<Windows LAN IP>:3000` fails from a phone or another computer
|
||||
|
||||
That usually means Windows still needs port forwarding or firewall rules.
|
||||
|
||||
If access fails, check from the shell running Planet:
|
||||
|
||||
```bash
|
||||
curl http://localhost:3000
|
||||
curl http://localhost:8000/health
|
||||
ss -ltnp | grep -E ':3000|:8000'
|
||||
```
|
||||
|
||||
If WSL is listening on `0.0.0.0:3000` and `0.0.0.0:8000` but the LAN IP still fails, configure Windows forwarding and firewall rules from an elevated 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
|
||||
```
|
||||
|
||||
## 9. Stop Services
|
||||
|
||||
```bash
|
||||
./planet.sh stop
|
||||
```
|
||||
|
||||
This shuts down the frontend, backend, AI Provider, PostgreSQL, and Redis.
|
||||
`/docs` is the docs site. Without login you can read: this Quickstart, the Manual, the FAQ. Authenticated users with `docs_user` / `docs_developer` / `docs_admin` groups see additional technical documents.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Full usage guide: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
|
||||
- Console structure: [Admin Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
|
||||
- Earth structure: [Earth Frontend Context](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
|
||||
- Backend collectors: [Backend Collectors](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
|
||||
- Full UI walkthrough: [Planet Manual](/home/ray/dev/linkong/planet/docs/technical/en/manual.md)
|
||||
- Troubleshooting and configuration questions: [FAQ](/home/ray/dev/linkong/planet/docs/technical/en/faq.md)
|
||||
- Detailed Earth coordinate candidate flow: [Earth Location Candidate Collection User Guide](/home/ray/dev/linkong/planet/docs/technical/en/location-pipeline-user.md)
|
||||
- Deployment / operations commands: [Planet Ops Runbook](/home/ray/dev/linkong/planet/docs/technical/en/ops-runbook.md)
|
||||
|
||||
Reference in New Issue
Block a user