Repair live server operations console
This commit is contained in:
npc0-hue
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-08-03
|
||||
@@ -0,0 +1,50 @@
|
||||
## Context
|
||||
|
||||
Server cards and server detail headers already consume `GET /api/v1/metrics/server-instances`, but the Platform service currently synthesizes online server values from instance identity and config version when no Run sample exists. The repository already has durable metric sample ingest/query, log stream metadata, cursor-based log queries, job polling, and a SCUM Source RCON dispatch path. The change should connect those existing primitives to the operator UI without adding raw shell access or leaking machine details.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- Make per-server metrics represent the latest real Run sample or a clearly empty/stale state.
|
||||
- Refresh server list and detail operational data automatically at bounded intervals.
|
||||
- Keep `编辑部署` on the server list and remove deployment editing from the server detail page.
|
||||
- Replace the low-value detail overview surface with direct operational sections and drawers for live logs and management terminal.
|
||||
- Keep logs and commands readable in the existing game-operations theme and shared console primitives.
|
||||
|
||||
**Non-Goals:**
|
||||
- No browser-direct shell, raw socket console, host-path display, credential display, or Run endpoint address display.
|
||||
- No new run executor source tree, cloud-provider workflow, billing, or marketplace expansion.
|
||||
- No platform-side game-specific command execution beyond routing through existing plugin/platform-mediated capabilities such as Source RCON.
|
||||
|
||||
## Decisions
|
||||
|
||||
### Decision 1: Latest sample beats synthetic projection
|
||||
|
||||
`ListServerMetricsForSession` will select the most recent persisted `MetricSample` for each visible server. If no sample exists, the response returns only safe identity/online/source/timestamp metadata with no fabricated player, TPS, latency, or resource percentages. The UI will render `--`, `等待上报`, or `指标过期` based on sample freshness.
|
||||
|
||||
Alternative considered: keep deterministic placeholders and label them as simulated. This still makes the server card look operational when it is not, so it is rejected.
|
||||
|
||||
### Decision 2: Polling over new transports
|
||||
|
||||
The frontend will use bounded polling: server cards refresh metrics/jobs every few seconds, detail headers refresh the same projections, and live logs tail with `/log-streams/query` using `afterSeq`. This reuses existing routes and avoids adding WebSocket/SSE infrastructure in the same change.
|
||||
|
||||
Alternative considered: introduce WebSockets for true streaming. That is better long-term, but it would require new transport contracts and channel ownership beyond this targeted repair.
|
||||
|
||||
### Decision 3: Drawers for live operational windows
|
||||
|
||||
Server list actions open drawers/dialogs for `实时日志` and `管理终端`. These windows do not resize cards, cover metrics inside the card, or create a tall action stack. The log drawer supports source selection, pause/resume, manual refresh, clear visible buffer, and autoscroll. The terminal drawer provides command history-like output and uses the existing SCUM Source RCON dispatch for SCUM servers; unsupported plugins show a safe unsupported state.
|
||||
|
||||
Alternative considered: route every action through the detail page. Operators asked for card-level fast access, so drawers preserve context without forcing navigation.
|
||||
|
||||
### Decision 4: Detail page starts as an operations workspace
|
||||
|
||||
The detail page no longer exposes deployment editing and does not keep a default overview panel. Its navigation starts on live logs and keeps configuration, plugin controls, AI assistant, operation history, and runtime controls as explicit sections. Runtime binding and distribution controls remain available where they are operational controls, not the create/list deployment editor.
|
||||
|
||||
Alternative considered: keep overview but empty it down. That preserves a tab the user already identified as low-value, so it is removed.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [Risk] Existing local/demo data may have no metric samples and therefore show fewer numbers. → Mitigation: render clear pending/stale labels and retain manual refresh.
|
||||
- [Risk] Polling can create noisy requests on many cards. → Mitigation: use bounded intervals, reuse existing list endpoints, and clear timers on unmount.
|
||||
- [Risk] Operators may expect a raw terminal. → Mitigation: label it `管理终端`, show the mediated command target, and make unsupported/direct-shell boundaries explicit in the UI.
|
||||
- [Risk] CSS changes could drift from the theme. → Mitigation: use shared console/drawer/button primitives and keep CSS declarations compact per repository rules.
|
||||
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
Server management currently presents live-looking server values that are not live: per-server players, TPS, latency, CPU, memory, and disk are projected from deterministic platform placeholders when no Run metric sample exists. Operators also need fast log and command access from the server list without losing the safe Platform-mediated boundaries.
|
||||
|
||||
## What Changes
|
||||
|
||||
- Replace placeholder per-server metrics with latest authorized Run metric samples, including clear empty/stale states when no fresh sample exists.
|
||||
- Add automatic refresh for server list and server detail operational data so cards, task status, and detail headers do not remain frozen until manual refresh.
|
||||
- Update server cards to show CPU, memory, and disk with visible progress meters and replace the detail/deployment action cluster with direct `实时日志` and `管理终端` entry points while keeping `编辑部署` available only on the server list.
|
||||
- Remove the low-value server detail overview surface; the detail page becomes an operations workspace focused on logs, management terminal, runtime controls, configuration, plugin controls, AI assistance, and history.
|
||||
- Introduce a safe live log drawer that tails platform log streams through cursor polling rather than exposing host paths, sockets, or Run credentials.
|
||||
- Introduce a safe management terminal drawer that sends plugin/platform-mediated commands, starting with the existing SCUM Source RCON command path, and shows task submission/status without exposing raw shell access.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `server-live-operations-console`: Real server metric projection, refresh cadence, live log tailing, and safe management terminal behavior for 服务器管理.
|
||||
|
||||
### Modified Capabilities
|
||||
- None.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected roots: `platform/` for per-server metric projection, `platform_web/` for server list/detail interaction, polling, logs, terminal UI, and focused tests.
|
||||
- Existing Run metric ingest, log stream cursor query, job tracking, and SCUM Source RCON command APIs are reused; no new run source tree or browser-direct shell is introduced.
|
||||
- Verification: focused Go tests for metrics projection, frontend tests/typecheck/build as needed, `scripts/check-structure.sh`, and `openspec validate repair-server-live-operations-console --strict`.
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Server metrics use real samples
|
||||
The system SHALL display per-server players, TPS, latency, CPU, memory, and disk from the latest authorized Run metric sample, and SHALL NOT fabricate live-looking values when no sample exists.
|
||||
|
||||
#### Scenario: Fresh metric sample exists
|
||||
- **WHEN** a visible server has a latest Run metric sample
|
||||
- **THEN** the server list and detail header show that sample's players, TPS, latency, CPU, memory, and disk values with the sample collection time available to the UI
|
||||
|
||||
#### Scenario: No metric sample exists
|
||||
- **WHEN** a visible server has no persisted metric sample
|
||||
- **THEN** the server list and detail header show pending or placeholder states instead of deterministic player, TPS, latency, CPU, memory, or disk values
|
||||
|
||||
#### Scenario: Stale metric sample exists
|
||||
- **WHEN** a visible server's latest metric sample is older than the frontend freshness threshold
|
||||
- **THEN** the UI marks the metrics as stale while preserving the last safe values and collection time
|
||||
|
||||
### Requirement: Server operations refresh automatically
|
||||
The system SHALL refresh server operational projections on a bounded cadence instead of requiring manual refresh for every data update.
|
||||
|
||||
#### Scenario: Server list is open
|
||||
- **WHEN** an operator is viewing the server list
|
||||
- **THEN** metrics and task/job status refresh automatically at a bounded interval and stop refreshing when the page unmounts
|
||||
|
||||
#### Scenario: Server detail is open
|
||||
- **WHEN** an operator is viewing a server detail workspace
|
||||
- **THEN** the header metrics and job state refresh automatically at a bounded interval and stop refreshing when the page unmounts
|
||||
|
||||
### Requirement: Server list exposes live operation entry points
|
||||
The server list SHALL keep `编辑部署` on server cards and SHALL provide direct live log and management terminal entry points without moving deployment editing into the detail page.
|
||||
|
||||
#### Scenario: Server card actions render
|
||||
- **WHEN** an operator views a server card
|
||||
- **THEN** the card includes `编辑部署`, `实时日志`, and `管理终端` actions using compact controls that do not reflow the card into a command tower
|
||||
|
||||
#### Scenario: Server detail actions render
|
||||
- **WHEN** an operator views the server detail workspace
|
||||
- **THEN** the detail header does not render an `编辑部署` action or deployment save workflow
|
||||
|
||||
### Requirement: Live logs tail through platform cursors
|
||||
The live log window SHALL read platform log streams and entries through authorized platform APIs using bounded cursor polling.
|
||||
|
||||
#### Scenario: Live log drawer opens
|
||||
- **WHEN** an operator opens `实时日志` for a server
|
||||
- **THEN** the UI lists authorized log streams for that server and tails selected stream entries using `afterSeq` cursor polling
|
||||
|
||||
#### Scenario: Live log controls are used
|
||||
- **WHEN** an operator pauses, resumes, clears, filters, or manually refreshes live logs
|
||||
- **THEN** the UI updates only the visible log window state and does not expose host paths, raw sockets, credentials, or Run endpoint addresses
|
||||
|
||||
### Requirement: Management terminal is platform-mediated
|
||||
The management terminal SHALL dispatch commands only through platform-authorized plugin or lifecycle command paths and SHALL NOT provide browser-direct shell access.
|
||||
|
||||
#### Scenario: SCUM command submitted
|
||||
- **WHEN** an operator submits a SCUM management command from the terminal
|
||||
- **THEN** the UI dispatches the command through the existing Source RCON command API and displays safe submission/job status
|
||||
|
||||
#### Scenario: Unsupported command target
|
||||
- **WHEN** a server plugin has no supported management terminal command path
|
||||
- **THEN** the terminal shows an unsupported state instead of exposing a raw shell or arbitrary command input
|
||||
|
||||
### Requirement: Detail overview is removed
|
||||
The server detail workspace SHALL omit the low-value overview panel and start from operational sections.
|
||||
|
||||
#### Scenario: Detail navigation renders
|
||||
- **WHEN** an operator opens server detail
|
||||
- **THEN** the section navigation excludes `概览` and provides operational sections such as logs, runtime controls, configuration, plugin controls, AI assistant, and operation history
|
||||
@@ -0,0 +1,26 @@
|
||||
## 1. Backend Metrics Projection
|
||||
|
||||
- [x] 1.1 Update per-server metrics listing to return the latest authorized persisted metric sample instead of deterministic placeholder values.
|
||||
- [x] 1.2 Add/adjust service tests for latest-sample projection and no-sample placeholder behavior.
|
||||
|
||||
## 2. Frontend Refresh And Metrics Presentation
|
||||
|
||||
- [x] 2.1 Add bounded automatic refresh for server list metrics/jobs and server detail header/job projections.
|
||||
- [x] 2.2 Update server cards and detail header to show metric freshness, placeholders, and CPU/memory/disk progress meters.
|
||||
|
||||
## 3. Live Logs And Management Terminal
|
||||
|
||||
- [x] 3.1 Add a live log drawer that lists server log streams and tails selected entries with cursor polling plus pause, clear, filter, and manual refresh controls.
|
||||
- [x] 3.2 Add a management terminal drawer that dispatches SCUM commands through the existing Source RCON API and shows safe unsupported state for other plugins.
|
||||
- [x] 3.3 Wire server list card actions to `编辑部署`, `实时日志`, and `管理终端` without reflowing cards or moving deployment editing into detail.
|
||||
|
||||
## 4. Server Detail Workspace
|
||||
|
||||
- [x] 4.1 Remove the server detail overview section/tab and deployment edit button while keeping operational sections available.
|
||||
- [x] 4.2 Reuse the live log and management terminal components from detail where appropriate.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run focused backend/frontend tests covering metrics, page contracts, and command/log UI.
|
||||
- [x] 5.2 Run `scripts/check-structure.sh`.
|
||||
- [x] 5.3 Run `openspec validate repair-server-live-operations-console --strict`.
|
||||
Reference in New Issue
Block a user