platform/: backend control plane for users, game management plugins, server instances, AI providers, jobs, artifacts, logs, and audit.
run/: machine-side executor for scoped process, file, artifact, log, and lifecycle work.
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.

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.

Governance

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, run channels, 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/ and run/.
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 run && 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 the API-backed local debug workspace when you need platform, run, platform_web, and the dev plugin fixture together:

scripts/local-debug-start.sh
scripts/local-debug-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/local-debug-smoke.sh when you need the smoke command to own the temporary local stack for the duration of the verification.

Start local processes:

(cd platform && go run ./cmd/platform)
(cd run && go run ./cmd/run)
(cd platform_web && npm run dev)

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 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, audit events, 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, or run identity, edit docker-compose.yml. 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
run/.env.example
platform_web/.env.example

Typical local debugging:

cp platform/.env.example platform/.env
cp run/.env.example run/.env
cp platform_web/.env.example platform_web/.env

(cd platform && set -a && source .env && set +a && go run ./cmd/platform)
(cd run && set -a && source .env && set +a && go run ./cmd/run)
(cd platform_web && npm run dev)

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 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 audit. 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
openspec validate <change> --strict

If a change adds new required directories, contracts, generated artifacts, or architectural rules, update scripts/check-structure.sh in the same change.

OpenSpec Stream

The bootstrap proposal and delivery stream live at:

openspec/changes/bootstrap-game-server-platform-architecture/
openspec/changes/architecture-delivery-stream/

Use openspec/changes/architecture-delivery-stream/delivery-plan.md to pick the next implementation change.