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

244
docs/technical/en/ops-runbook.md Normal file
View 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)