490 lines
11 KiB
Markdown
490 lines
11 KiB
Markdown
# Planet Manual
|
|
|
|
This manual is for daily use, demos, development integration, and local operations. It covers four core entry points:
|
|
|
|
- `planet.sh`: local start, stop, restart, health check, and log access
|
|
- Earth: public 3D situational awareness page
|
|
- Console: admin backend (login required)
|
|
- Docs: public developer documentation and manual
|
|
|
|
For the shortest path to getting started, see [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md).
|
|
|
|
## 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` | No | Developer docs, technical reference, usage manual |
|
|
| Console | `http://localhost:3000/admin` | Yes | Data, config, alerts, logs, and situational observation |
|
|
| AI Playground | `http://localhost:3000/playground` | Yes | AI Provider status and debugging |
|
|
| Backend API Docs | `http://localhost:8000/docs` | Depends on endpoint | FastAPI / OpenAPI documentation |
|
|
|
|
## planet.sh
|
|
|
|
`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.
|
|
|
|
### Start
|
|
|
|
```bash
|
|
./planet.sh start
|
|
```
|
|
|
|
Default behavior:
|
|
|
|
- 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
|
|
|
|
Specify custom ports:
|
|
|
|
```bash
|
|
./planet.sh start -b 8001 -f 3001 -a 8101
|
|
```
|
|
|
|
Parameters:
|
|
|
|
| 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 |
|
|
|
|
### 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
|
|
|
|
After starting, check your firewall and WSL network forwarding if access fails.
|
|
|
|
## 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
|
|
- Country borders, 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
|
|
- Country borders
|
|
- HD texture
|
|
- Atmospheric cloud layer
|
|
- Submarine cables
|
|
- Compute centers
|
|
- BGP observation
|
|
- 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
|
|
|
|
### 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.
|
|
|
|
### Settings
|
|
|
|
The settings panel contains:
|
|
|
|
- Rotation mode / cruise mode
|
|
- Cruise modules: BGP, News
|
|
- Satellite display style: self-glow, real ground footprint
|
|
- Day/night mode
|
|
- Panel visibility toggles
|
|
- 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.
|
|
|
|
### Cruise Mode
|
|
|
|
Cruise mode makes Earth automatically cycle through focus targets.
|
|
|
|
Current cruise modules:
|
|
|
|
- BGP
|
|
- News
|
|
|
|
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:
|
|
|
|
| Page | Route | Purpose |
|
|
| --- | --- | --- |
|
|
| Dashboard | `/admin` | System overview |
|
|
| Earth | `/earth` | Opens the public Earth page |
|
|
| Data Sources | `/datasources` | Manage data sources and trigger collection |
|
|
| Collected Data | `/data` | View collected data |
|
|
| BGP Observation | `/bgp` | BGP situational data |
|
|
| System Alerts | `/alerts/system` | System-level alerts |
|
|
| BGP Alerts | `/alerts/bgp` | BGP-related alerts |
|
|
| Situational Alerts | `/alerts/situational` | Situational assessment alerts |
|
|
| AI Playground | `/playground` | AI Provider debugging |
|
|
| System Logs | `/logs` | View system logs (typically super admin only) |
|
|
| Users | `/users` | User management |
|
|
| Settings | `/settings` | System config and TV live stream sources |
|
|
|
|
### Data Sources
|
|
|
|
`/datasources` shows and manages collection sources.
|
|
|
|
Common operations:
|
|
|
|
- View data source status
|
|
- Trigger collection
|
|
- View recent collection tasks
|
|
- Adjust configuration
|
|
|
|
If a category of objects is missing on Earth, start here to confirm the data source is available.
|
|
|
|
### Collected Data
|
|
|
|
`/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
|
|
- Data source configuration entry points
|
|
|
|
Available configuration depends on the current user's role.
|
|
|
|
### System Logs
|
|
|
|
`/logs` views system logs. If the menu item is not visible, the current user likely lacks the required role.
|
|
|
|
Common troubleshooting sequence:
|
|
|
|
```bash
|
|
./planet.sh health
|
|
./planet.sh log
|
|
```
|
|
|
|
Then open `/logs` for more structured runtime information.
|
|
|
|
## Docs
|
|
|
|
Public documentation site:
|
|
|
|
```text
|
|
http://localhost:3000/docs
|
|
```
|
|
|
|
Current public content comes from:
|
|
|
|
```text
|
|
docs/technical/zh/ (Chinese)
|
|
docs/technical/en/ (English)
|
|
```
|
|
|
|
Docs supports:
|
|
|
|
- Category navigation
|
|
- Markdown rendering
|
|
- Tables and code blocks
|
|
- In-document table of contents
|
|
- Local search
|
|
- Internal links between technical documents
|
|
|
|
When adding a new technical document, check:
|
|
|
|
- Does it have a clear top-level heading
|
|
- Does it need to be added to the `/docs` manual category and ordering
|
|
- Does it contain information that should not be publicly displayed
|
|
|
|
## Development Command Conventions
|
|
|
|
Frontend commands must use Bun:
|
|
|
|
```bash
|
|
cd frontend
|
|
bun install
|
|
bun run dev
|
|
bun run build
|
|
```
|
|
|
|
Do not use `npm run ...`. The project uses Bun in WSL / Windows mixed environments to avoid Node/npm path compatibility issues.
|
|
|
|
Verify the frontend build:
|
|
|
|
```bash
|
|
source ~/.zshrc && bun run build
|
|
```
|
|
|
|
## Troubleshooting Order
|
|
|
|
When something goes wrong, follow this sequence:
|
|
|
|
1. Check service status:
|
|
|
|
```bash
|
|
./planet.sh health
|
|
```
|
|
|
|
2. Check recent logs:
|
|
|
|
```bash
|
|
./planet.sh log
|
|
```
|
|
|
|
3. Check per-module logs:
|
|
|
|
```bash
|
|
./planet.sh log -f
|
|
./planet.sh log -b
|
|
./planet.sh log -a
|
|
```
|
|
|
|
4. Restart only the affected module:
|
|
|
|
```bash
|
|
./planet.sh restart -f
|
|
./planet.sh restart -b
|
|
./planet.sh restart -a
|
|
```
|
|
|
|
5. If database or cache is abnormal, restart the database:
|
|
|
|
```bash
|
|
./planet.sh restart -d
|
|
```
|
|
|
|
6. If still unrecovered, do a full restart:
|
|
|
|
```bash
|
|
./planet.sh restart
|
|
```
|
|
|
|
## Related Docs
|
|
|
|
- [quickstart.md](/home/ray/dev/linkong/planet/docs/technical/en/quickstart.md)
|
|
- [frontend-admin-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/frontend-admin-frontend-context.md)
|
|
- [earth-frontend-context.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-frontend-context.md)
|
|
- [earth-layer-style-reference.md](/home/ray/dev/linkong/planet/docs/technical/en/earth-layer-style-reference.md)
|
|
- [backend-system-service-control.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-system-service-control.md)
|
|
- [backend-collectors.md](/home/ray/dev/linkong/planet/docs/technical/en/backend-collectors.md)
|