release: bump version to 0.42.0
This commit is contained in:
rayd1o
489
docs/technical/en/manual.md
Normal file
489
docs/technical/en/manual.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user