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:

(cd platform_web && npm install)
(cd plugins && npm install)

Run all baseline checks from the repository root:

scripts/check-all.sh

Run focused checks when working in one root:

(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:

(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:

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:

scripts/dev-start.sh

Docker Deployment

Use the root compose file for a local all-in-one deployment:

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:

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:

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:

.env.example
platform/.env.example
platform_web/.env.example

Typical local debugging:

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:

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.