Web Management Console
Relevant source files
The following files were used as context for generating this wiki page:
The Web Management Console (@onebots/web) provides a graphical user interface for administrative tasks within the OneBots project. It operates as a Vue 3 application that communicates with the management service to handle environment monitoring, configuration lifecycle management, and extension installation.
This console allows you to manage platform accounts, protocol outlets, and system resources without direct modification of configuration files. It acts as the primary interface for the management service, which remains active even if the core gateway process fails.
Sources: AGENTS.md:10-12, AGENTS.md:32-35, packages/web/package.json
System Monitoring and Observability
The console tracks the health and resource utilization of the management service host. The SystemOverview component visualizes real-time metrics, including Node.js environment details, CPU architecture, memory distribution, and disk capacity.
Resource Monitoring Components
Data is categorized into four primary areas to provide a comprehensive view of the host environment:
| Category | Monitored Metrics | UI Representation |
|---|---|---|
| Runtime Environment | Node.js version, OS platform, release, and manager uptime. | IconServer Card |
| Hardware Info | Hostname, CPU model, and logical processor count. | IconDeviceDesktop Card |
| System Memory | Total, free, manager process RSS, and JS heap usage. | IconCpu Card with Progress Bar |
| Workspace Disk | Used, total, and available space on the file system. | IconDatabase Card |
Sources: packages/web/src/components/SystemOverview.vue:24-85, packages/core/src/app-observability.ts:167-175
Data Flow for Observability
The management service exposes specific endpoints that the console consumes to display system status.
The diagram shows the interaction between the Web Management Console and the core observability endpoints to retrieve system health and resource data.
Sources: packages/core/src/app-observability.ts:241-265, packages/web/src/components/SystemOverview.vue:5-8
Configuration Lifecycle Management
The ControlConfigurationPanel manages the process of updating the gateway configuration. It uses a draft-based system where changes are prepared locally, validated, and then explicitly applied to the production runtime.
The Configuration Workflow
The console enforces a three-step sequence to ensure configuration integrity:
- Save Draft: Persists local field modifications to the server-side draft storage.
- Validate Configuration: Checks for missing mandatory fields and validates connection parameters (e.g., protocol exports, platform credentials).
- Apply Version: Creates a new configuration version and updates the running gateway instance.
The configuration sequence diagram illustrates the required steps to transition from local edits to a live gateway update.
Sources: packages/web/src/components/ControlConfigurationPanel.vue:157-178, packages/web/src/components/ControlConfigurationPanel.vue:197-205
Workspace Organization
The configuration interface is divided into functional tabs:
- Accounts: Management of platform-specific credentials and bot identities.
- Protocols: Configuration of OneBot, Satori, or Milky protocol outlets.
- Runtime: Service-level parameters and loader settings.
- Review: Final validation and application interface.
Sources: packages/web/src/components/ControlConfigurationPanel.vue:104-128
Extension and Installation Management
The console manages the installation of adapters and protocols through an immutable runtime generation process. The ControlInstallPlanPreview component allows administrators to review proposed changes before they are executed.
Installation Plan Features
- Dependency Tracking: Lists all package versions and required peer dependencies.
- Removal Verification: Explicitly highlights extensions that will be removed when applying the new plan.
- Secure Authentication: Provides a field for GitHub Packages tokens (read:packages) when downloading private or protected extensions.
Sources: packages/web/src/components/ControlInstallPlanPreview.vue:13-55
Installation Restrictions
The console blocks installation actions under specific conditions:
- Busy State: An operation is already in progress.
- Insecure Transport: Private tokens are blocked if the connection is not via HTTPS or local loopback.
- Mutation Lock: Structural modifications are disabled if the current configuration source is read-only.
Sources: packages/web/src/components/ControlInstallPlanPreview.vue:60-64, packages/web/src/components/ControlConfigurationPanel.vue:81-88
Technical Implementation Summary
The console is built using a modern frontend stack designed for developer experience and performance.
| Technology | Role | Source Citation |
|---|---|---|
| Vue 3 | Component framework and state management. | web/package.json:25 |
| Vite | Build tool and development server. | web/package.json:34 |
| Tailwind CSS v4 | Utility-first styling with design tokens. | AGENTS.md:34 |
| Tabler Icons | Visual representation of system components. | web/package.json:24 |
| Xterm.js | Integrated terminal functionality for gateway logs. | web/package.json:18-20 |
Sources: packages/web/package.json:18-34, AGENTS.md:32-35
The Web Management Console ensures that the management of IM adapters and protocols remains decoupled from the message-processing gateway, providing a resilient administrative layer for the OneBots framework.
Sources: AGENTS.md:9-14, CONTRIBUTING.md:46-48