185 lines
6.7 KiB
Markdown
185 lines
6.7 KiB
Markdown
# Local Debug Workspace
|
|
|
|
The local debug workspace runs the real platform API, run worker, platform_web console, and the development game plugin fixture together. It is for API-backed local proof, not demo-only fallback.
|
|
|
|
## Scope
|
|
|
|
- Platform listens on `http://127.0.0.1:18080` by default.
|
|
- platform_web listens on `http://127.0.0.1:5173` by default and proxies `/api/v1` plus `/healthz` to platform.
|
|
- Run worker is loaded from `RUN_REPO_DIR`, defaulting to the ignored nested `./run` checkout, and registers as `run-local-debug`.
|
|
- Disposable state lives under `.local-debug/`.
|
|
- Logs live under `.local-debug/logs/`.
|
|
- PIDs live under `.local-debug/pids/`.
|
|
- Go build cache for local services lives under `.local-debug/go-build-cache/`.
|
|
- The dev plugin fixture is `plugins/examples/dev-game-plugin/manifest.json`.
|
|
|
|
The workflow does not require Docker-only infrastructure, external cloud services, real game binaries, raw credentials, raw AI keys, direct run sockets, or browser/plugin direct access to run.
|
|
|
|
## Port Discipline
|
|
|
|
Use the managed local debug scripts for browser-facing verification. Do not start extra ad hoc platform or platform_web processes on random ports when the standard stack is already available.
|
|
|
|
- Default platform API: `http://127.0.0.1:18080`.
|
|
- Default platform_web: `http://127.0.0.1:5173`.
|
|
- Default local debug root: `.local-debug/`.
|
|
- Restart with `scripts/local-debug-stop.sh` followed by `scripts/local-debug-start.sh`.
|
|
- Use `LOCAL_DEBUG_PLATFORM_PORT`, `LOCAL_DEBUG_WEB_PORT`, and `LOCAL_DEBUG_ROOT` only when a task explicitly needs an isolated stack.
|
|
- When debugging an already-running local page, prefer the current `5173`/`18080` stack and inspect `.local-debug/logs/` before starting anything else.
|
|
|
|
## Start
|
|
|
|
```bash
|
|
git clone git@git.npc0.com:admin343/run.git run # once, if the ignored local checkout is missing
|
|
scripts/local-debug-start.sh
|
|
```
|
|
|
|
The script prints the resolved platform URL, platform_web URL, log files, and the exact local account for browser login:
|
|
|
|
- Account: `operator.local@example.test`
|
|
- Password: `operator-local`
|
|
|
|
Useful defaults can be overridden before running the script:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_PLATFORM_PORT=18081 LOCAL_DEBUG_WEB_PORT=5174 scripts/local-debug-start.sh
|
|
```
|
|
|
|
## Environment
|
|
|
|
The scripts source `scripts/local-debug-env.sh`.
|
|
|
|
Key platform variables:
|
|
|
|
- `PLATFORM_ADDR=127.0.0.1:18080`
|
|
- `PLATFORM_STORAGE_BACKEND=file`
|
|
- `PLATFORM_DATA_DIR=.local-debug/platform`
|
|
- `PLATFORM_METADATA_PATH=.local-debug/platform/metadata.json`
|
|
- `PLATFORM_LOG_BODY_BACKEND=file`
|
|
- `PLATFORM_LOG_DIR=.local-debug/platform/logs`
|
|
- `GOCACHE=.local-debug/go-build-cache`
|
|
|
|
Key run variables:
|
|
|
|
- `RUN_REPO_DIR=./run`
|
|
- `RUN_MODE=worker`
|
|
- `RUN_PLATFORM_URL=http://127.0.0.1:18080`
|
|
- `RUN_ENDPOINT_ID=run-local-debug`
|
|
- `RUN_WORKSPACE_ROOT=.local-debug/run/workspace`
|
|
- `RUN_SPOOL_ROOT=.local-debug/run/spool`
|
|
|
|
Key frontend variables:
|
|
|
|
- `PLATFORM_API_PROXY=http://127.0.0.1:18080`
|
|
- `VITE_PLATFORM_API_BASE_URL=/api/v1`
|
|
- `VITE_ENABLE_LOCAL_AUTH_FALLBACK=false`
|
|
|
|
`VITE_ENABLE_LOCAL_AUTH_FALLBACK=false` is required. Local fallback data is a smoke failure for this workspace.
|
|
|
|
## Smoke
|
|
|
|
Start the stack, then run:
|
|
|
|
```bash
|
|
scripts/local-debug-smoke.sh
|
|
```
|
|
|
|
For one-command verification in environments that clean up background processes when a command returns, run:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_SELF_START=true scripts/local-debug-smoke.sh
|
|
```
|
|
|
|
The smoke command verifies:
|
|
|
|
- platform health at `/healthz`.
|
|
- API-backed login for the seeded local platform administrator.
|
|
- dev plugin manifest validation and registration through `POST /api/v1/game-plugins/register-manifest`.
|
|
- run endpoint heartbeat through `GET /api/v1/run/endpoints?status=online`.
|
|
- server lifecycle fixture setup through `POST /api/v1/server-instances/workflows/create`.
|
|
- job, log stream, artifact, marketplace, and server list references.
|
|
- `PLATFORM_API_PROXY` and `VITE_PLATFORM_API_BASE_URL=/api/v1`.
|
|
- `VITE_ENABLE_LOCAL_AUTH_FALLBACK=false`.
|
|
- absence of forbidden fragments in API evidence: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details.
|
|
|
|
Smoke evidence is written to `.local-debug/smoke/`.
|
|
|
|
## Automated Browser Acceptance
|
|
|
|
Run the automated browser acceptance suite when you need repeatable proof for the API-backed console routes:
|
|
|
|
```bash
|
|
LOCAL_DEBUG_PLATFORM_PORT=18189 LOCAL_DEBUG_WEB_PORT=5183 LOCAL_DEBUG_ROOT=/private/tmp/browser-local-debug-acceptance scripts/browser-acceptance.sh
|
|
```
|
|
|
|
By default the command safely resets the configured local debug root, starts platform, run worker, and platform_web, runs `scripts/local-debug-smoke.sh`, verifies browser-facing route contracts, and cleans up the self-started stack. Set `BROWSER_ACCEPTANCE_SELF_START=false` to run against an already-started local debug stack.
|
|
|
|
Acceptance evidence is written to:
|
|
|
|
```text
|
|
<LOCAL_DEBUG_ROOT>/browser-acceptance/browser-acceptance-evidence.json
|
|
```
|
|
|
|
The evidence records stack URLs, the smoke seed evidence directory, first-party route checks, plugin/server operation proof, fallback scans, and forbidden-fragment scans.
|
|
|
|
## Browser Walkthrough
|
|
|
|
After `scripts/local-debug-smoke.sh` passes, open platform_web:
|
|
|
|
```text
|
|
http://127.0.0.1:5173
|
|
```
|
|
|
|
Required walkthrough:
|
|
|
|
- Login with `operator.local@example.test` / `operator-local`.
|
|
- Confirm no local fallback banner, local fallback workspace, or demo-only session is visible.
|
|
- Open 首页.
|
|
- Open 服务器管理.
|
|
- Open 插件市场.
|
|
- Open 用户管理.
|
|
- Open AI 提供商管理.
|
|
- Inspect `server-local-debug` server detail, plugin controls or marketplace detail, operation history, log references, and artifact references.
|
|
- Scan visible browser text for forbidden fragments: `/Users/`, `/private/`, `unix://`, `tcp://`, `Bearer `, `sk-`, `password=`, `apiKeyRef`, `rawApiKey`, run session tokens, direct run URLs, and plugin-owned transport details.
|
|
|
|
Acceptance requires logical IDs, platform routes, job refs, log refs, artifact refs, and safe metadata only.
|
|
|
|
## Stop
|
|
|
|
```bash
|
|
scripts/local-debug-stop.sh
|
|
```
|
|
|
|
## Reset
|
|
|
|
```bash
|
|
scripts/local-debug-reset.sh
|
|
```
|
|
|
|
Reset stops the local debug processes and deletes only the documented local debug root. By default that root is:
|
|
|
|
```text
|
|
.local-debug
|
|
```
|
|
|
|
The reset script refuses unexpected roots. It allows only:
|
|
|
|
- `<repo>/.local-debug`
|
|
- `/private/tmp/browser-local-debug-*`
|
|
- `/tmp/browser-local-debug-*`
|
|
|
|
## Manual Commands
|
|
|
|
The start script wraps these commands with the local debug environment:
|
|
|
|
```bash
|
|
(cd platform && go run ./cmd/platform)
|
|
(cd "${RUN_REPO_DIR:-./run}" && go run ./cmd/run)
|
|
npm --prefix platform_web run dev -- --port 5173
|
|
```
|
|
|
|
The dev plugin fixture validation command is:
|
|
|
|
```bash
|
|
cd plugins && npm run validate:manifest
|
|
```
|