189 lines
8.4 KiB
Markdown
189 lines
8.4 KiB
Markdown
# Game Server Management Platform
|
|
|
|
This repository is the game server management platform workspace. It replaces the old SCUM-specific coupling with three browser-owned project roots:
|
|
|
|
- `platform/`: backend control plane for users, game management plugins, server instances, AI providers, jobs, artifacts, and logs.
|
|
- `platform_web/`: management console frontend.
|
|
- `plugins/`: game management plugin workspace. A plugin defines how to create and manage one server type, and one installed plugin can create many server instances.
|
|
|
|
The machine-side executor source lives in the separate `git@git.npc0.com:admin343/run.git` repository. Local debug and Docker workflows can keep the editable source at `./run` as an ignored nested checkout, or use another path through `RUN_SOURCE_DIR` / legacy `RUN_REPO_DIR`. Run distributions refresh the configured repository revision during each platform build, then inject package configuration and compile in the isolated builder workspace.
|
|
|
|
## Product Scope
|
|
|
|
The platform focuses on:
|
|
|
|
- 首页
|
|
- 服务器管理
|
|
- 插件市场
|
|
- 用户管理
|
|
- AI 提供商管理
|
|
|
|
AI 提供商 means model providers such as OpenAI-compatible endpoints, GPT providers, Claude-compatible relays, local model gateways, or custom base URL/key/model configurations. It does not mean run executors, host providers, billing providers, or cloud vendors.
|
|
|
|
## Communication Model
|
|
|
|
The platform must not use one overloaded channel for everything. Run communication is split by workload:
|
|
|
|
- Control: hello, heartbeat, version, capabilities, capacity.
|
|
- Job: claim, ack, progress, result, cancel, reconcile.
|
|
- Logs: compressed batch ingest with sequence ack and local spool.
|
|
- Artifacts: chunked, resumable, checksummed, throttled file transfer.
|
|
- Game client bridge: optional in-game command and snapshot polling for games that require it.
|
|
|
|
Logs are historical data, not a UI-only stream. Browser realtime tail may use platform SSE/WebSocket later, but run-to-platform logs must use durable ingest semantics.
|
|
|
|
## Repository Rules
|
|
|
|
Read `AGENTS.md` before changing code. Each subproject also has a local `AGENTS.md` with stricter rules for that area.
|
|
|
|
The bootstrap skeleton already includes fixed directories for backend DTOs/models/protocols, platform-owned run contracts, frontend API/routes/contracts, and plugin manifests/schemas/SDK files. `scripts/check-structure.sh` checks these required paths so future changes cannot silently drop or bypass them.
|
|
|
|
## Development Baseline
|
|
|
|
Current tool baseline:
|
|
|
|
- Go 1.25.1 for `platform/`. The external run repository uses the same Go baseline.
|
|
- Node 22.17.0 and npm 11.6.1 for `platform_web/` and `plugins/`.
|
|
|
|
Install JavaScript dependencies before the first full check:
|
|
|
|
```bash
|
|
(cd platform_web && npm install)
|
|
(cd plugins && npm install)
|
|
```
|
|
|
|
Run all baseline checks from the repository root:
|
|
|
|
```bash
|
|
scripts/check-all.sh
|
|
```
|
|
|
|
Run focused checks when working in one root:
|
|
|
|
```bash
|
|
(cd platform && go test ./...)
|
|
(cd platform_web && npm run typecheck && npm run test && npm run build)
|
|
(cd plugins && npm run typecheck && npm run test && npm run validate:manifest)
|
|
```
|
|
|
|
Run executor checks are owned by the separate run checkout:
|
|
|
|
```bash
|
|
(cd "${RUN_SOURCE_DIR:-${RUN_REPO_DIR:-./run}}" && go test ./...)
|
|
```
|
|
|
|
Run the API-backed local debug workspace when you need platform, run, platform_web, and the dev plugin fixture together:
|
|
|
|
```bash
|
|
scripts/dev-start.sh
|
|
scripts/dev-smoke.sh
|
|
```
|
|
|
|
See `docs/local-debug-workspace.md` for ports, disposable data roots, log files, reset steps, smoke evidence, and the required browser walkthrough. This workflow treats frontend local auth fallback as a verification failure.
|
|
Use `LOCAL_DEBUG_SELF_START=true scripts/dev-smoke.sh` when you need the smoke command to own the temporary local stack for the duration of the verification.
|
|
|
|
For local debug, prefer the managed scripts because they prepare the Run checkout, start the platform-owned builder, and start the bootstrap worker from the current source:
|
|
|
|
```bash
|
|
scripts/dev-start.sh
|
|
```
|
|
|
|
## Docker Deployment
|
|
|
|
Use the root compose file for a local all-in-one deployment:
|
|
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
Then open:
|
|
|
|
- Web console: `http://127.0.0.1:5173`
|
|
- Platform API health: `http://127.0.0.1:8080/healthz`
|
|
|
|
The compose deployment starts:
|
|
|
|
- `platform`: backend on container port `8080`, published as host port `8080`.
|
|
- `run`: worker mode executor built from `${RUN_REPO_DIR:-./run}` and connected to `http://platform:8080`.
|
|
- `platform-web`: built static console served by Nginx on container port `80`, published as host port `5173`.
|
|
|
|
Persistent Docker data lives in named volumes:
|
|
|
|
- `platform-data`: platform metadata and segmented log bodies.
|
|
- `run-data`: run worker workspace and local spool data.
|
|
|
|
The default Docker storage is file-backed:
|
|
|
|
```text
|
|
PLATFORM_METADATA_PATH=/data/platform/metadata.json
|
|
PLATFORM_LOG_BODY_BACKEND=file
|
|
PLATFORM_LOG_DIR=/data/platform/logs
|
|
RUN_WORKSPACE_ROOT=/data/run/workspace
|
|
RUN_SPOOL_ROOT=/data/run/spool
|
|
```
|
|
|
|
To use MySQL for platform metadata in Docker, edit the existing `platform.environment` block in `docker-compose.yml`:
|
|
|
|
```yaml
|
|
PLATFORM_STORAGE_BACKEND: mysql
|
|
PLATFORM_MYSQL_DSN: platform:platform@tcp(mysql:3306)/platform?parseTime=true
|
|
PLATFORM_LOG_BODY_BACKEND: file
|
|
```
|
|
|
|
Change the existing `PLATFORM_STORAGE_BACKEND: file` line to `mysql`, uncomment/add the `PLATFORM_MYSQL_DSN` line, then uncomment the `mysql` service and the `platform.depends_on.mysql` block in `docker-compose.yml`.
|
|
|
|
MySQL stores platform metadata only: users, plugins, servers, jobs, operational records, log stream cursors, and indexes. Log bodies stay in `PLATFORM_LOG_DIR` as segmented files unless a future `LogBodyStore` adapter such as ClickHouse/Loki/OpenSearch is configured. Do not store hundreds or thousands of servers' log lines as one MySQL row per line.
|
|
|
|
To change Docker ports, storage paths, MySQL DSN, run identity, or the external run checkout path, edit `docker-compose.yml` or set `RUN_REPO_DIR`. Do not put real secrets in committed compose files; use a local untracked `.env` or shell environment for machine-specific values.
|
|
|
|
## Local Debug Configuration
|
|
|
|
Local direct execution uses environment variables, not a hard-required config file. Example files are provided so you can copy and modify them:
|
|
|
|
```text
|
|
.env.example
|
|
platform/.env.example
|
|
platform_web/.env.example
|
|
```
|
|
|
|
Typical local debugging:
|
|
|
|
```bash
|
|
cp platform/.env.example platform/.env
|
|
cp platform_web/.env.example platform_web/.env
|
|
|
|
scripts/dev-start.sh
|
|
scripts/dev-smoke.sh
|
|
```
|
|
|
|
Most common edits:
|
|
|
|
- Platform port: `PLATFORM_ADDR=:8080`.
|
|
- Platform file persistence: `PLATFORM_STORAGE_BACKEND=file`, `PLATFORM_METADATA_PATH`, `PLATFORM_LOG_DIR`.
|
|
- Platform MySQL metadata: `PLATFORM_STORAGE_BACKEND=mysql`, `PLATFORM_MYSQL_DSN=platform:platform@tcp(127.0.0.1:3306)/platform?parseTime=true`.
|
|
- Log body persistence: `PLATFORM_LOG_BODY_BACKEND=file`, `PLATFORM_LOG_DIR`.
|
|
- Run editable source checkout: `RUN_SOURCE_DIR=./run` by default; legacy `RUN_REPO_DIR` is accepted as an alias; `run/` is ignored by the browser repository.
|
|
- Run closed build bucket: `RUN_BUILD_BUCKET_ROOT=.local-debug/run/build-buckets`.
|
|
- Run source repository: `RUN_SOURCE_REPOSITORY=git@git.npc0.com:admin343/run.git`.
|
|
- Run source revision: `RUN_SOURCE_REVISION=main`.
|
|
- Platform builder source repository: `PLATFORM_BUILDER_SOURCE_REPOSITORY` (defaults to the Run repository).
|
|
- Platform builder source revision: `PLATFORM_BUILDER_SOURCE_REVISION` (defaults to `main`).
|
|
- Run bootstrap binary: `RUN_BOOTSTRAP_BIN=.local-debug/run/build-buckets/bootstrap/bin/run`.
|
|
- Run worker mode: `RUN_MODE=worker`.
|
|
- Run-to-platform URL: `RUN_PLATFORM_URL=http://127.0.0.1:8080` locally, `http://platform:8080` in Docker.
|
|
- Run local data: `RUN_WORKSPACE_ROOT`, `RUN_SPOOL_ROOT`.
|
|
- Frontend API: `VITE_PLATFORM_API_BASE_URL=/api/v1`.
|
|
- Vite dev proxy: `PLATFORM_API_PROXY=http://127.0.0.1:8080`.
|
|
|
|
For hundreds or thousands of servers, keep relational databases for platform metadata, stream state, indexes, retention policy, and operational records. Do not store high-volume log bodies as one MySQL row per line; use a future `LogBodyStore` adapter for ClickHouse, Loki, OpenSearch/Elasticsearch, or object-storage segments.
|
|
|
|
The frontend shell touches first-party pages, so UI changes require a browser walkthrough at desktop and mobile widths.
|
|
|
|
Before claiming a change is complete, run:
|
|
|
|
```bash
|
|
scripts/check-structure.sh
|
|
```
|
|
|
|
If a change adds new required directories, contracts, generated artifacts, or architectural rules, update `scripts/check-structure.sh` in the same change.
|