linkong/planet
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

release: bump version to 0.52.0

Browse Source
This commit is contained in:
linkong
2026-05-12 17:15:02 +08:00
parent b15d097b9c
commit b87cb310fd
70 changed files with 5589 additions and 2187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

816
docs/technical/en/manual.md
View File

@@ -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)