AS Panel

Project status: early stage and evolving quickly. Expect breaking changes and incomplete features.

Below are a brief introduction generated by AI.

========

A modern Minecraft server management panel built with FastAPI (Python) and Vue 3 (Vite + TypeScript). It integrates live chat bridging (Socket.IO, OneBot/QQ), player and server management, plugin/mod utilities, archiving, basic statistics, and a role-based access model.

Key Features

• Backend: FastAPI, SQLAlchemy, Socket.IO (ASGI via python-socketio).
• Frontend: Vite + Vue 3 + TypeScript + Element Plus UI.
• Role-based access: GUEST, USER, HELPER, ADMIN, OWNER.
• User management (ADMIN): avatars, username/QQ/email edits, bind to MC player, role changes, reset password, batch delete.
• Player management: list players (official/offline), aggregate playtime, filters, name edits for offline players.
• Servers: list and basic lifecycle hooks (via MCDR integration), plugin/mod tools, server link groups.
• Chat: unified web chat with Socket.IO; QQ bridge via OneBot reverse WebSocket; optional game-side relay (MCDR reporter).
• Storage: self-contained storages/ directory for DB, avatars, archives, temp files (git-ignored by default).

Architecture Overview

• backend/ — FastAPI application. ASGI entry: backend/main.py → main_asgi_app (Socket.IO + FastAPI).
  • HTTP API base path: /api.
  • Static mounts: /avatars/ (user avatars), /archives/ (archives).
  • WebSocket (Socket.IO): /ws/socket.io (used by frontend chat/telemetry).
  • MCDR reporter endpoint (WebSocket): /aspanel/mcdr (expects an external plugin to push events).
  • OneBot reverse WebSocket endpoint: /aspanel/onebot/ws (QQ bridge in/out).
• frontend/ — Vite + Vue 3 SPA.
• storages/ — runtime data:
  • storages/asPanel.db (SQLite DB)
  • storages/avatars/ (user avatars), storages/avatars/mc/ (fetched MC heads)
  • storages/archives/ (archive store)
  • storages/temp/, storages/logs/, etc.

Directory Layout

• backend/ — API, services, models and routers
  • backend/main.py — application assembly and middlewares
  • backend/models.py, backend/schemas.py — SQLAlchemy models and Pydantic v2 schemas
  • backend/routers/ — HTTP API endpoints (users, servers, tools, chat, etc.)
  • backend/services/ — WS bridge and background services (ws.py, onebot.py, stats, etc.)
• frontend/ — Vue 3 app (Vite)
• storages/ — runtime data (auto-created)

Prerequisites

• Python 3.10+
• Node.js 18+
• Java runtime if you use MCDReforged/MC servers integration (not covered here)

Quick Start (Development)

Backend

• Create venv and run ASGI with auto-reload:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
uvicorn backend.main:main_asgi_app --host 0.0.0.0 --port 8000 --reload

• Health check: GET http://localhost:8000/api/health → { "status": "ok" }

Frontend

• Vite dev server with proxying to backend:

cd frontend
npm install
# optional: cp .env.example .env.development and customize
npm run dev

Development defaults

• API: requests use relative /api (proxied to http://localhost:8000)
• Socket.IO: client path is /ws/socket.io

Configuration & Security

• JWT secret:
  • Environment variable: ASPANEL_SECRET_KEY (or SECRET_KEY)
  • If absent, a random secret is created and persisted at storages/secret.key
• CORS: adjust ALLOWED_ORIGINS in backend/core/config.py for production
• Timezone: override with ASPANEL_TIMEZONE (e.g., Asia/Shanghai, UTC)
• Storage: storages/ is git-ignored by default

User & Access Model

• Roles: GUEST < USER < HELPER < ADMIN < OWNER
• Registration (public API): POST /api/users/register
  • Body: { username, password, qq (required, digits), email? , player_name? }
  • When player_name matches an existing player, the user is bound to that player
• Login: POST /api/token (OAuth2 password grant), then attach Authorization: Bearer <token>
• Who am I: GET /api/users/me

User Management (ADMIN)

• Frontend view: “User Management” under “Player Management” in the sidebar
• Table actions: inline edit (avatar/username/QQ/email/bind player), role change (with constraints), reset password, delete, batch delete
• Role change constraints:
  • ADMIN can set only among GUEST/USER/HELPER and cannot change ADMIN/OWNER targets
  • OWNER can set up to ADMIN; setting OWNER is globally unique (at most 1 OWNER); cannot demote the last OWNER

Chat, QQ Bridge and Game Relay

• Socket.IO channel for web chat and presence (client path /ws/socket.io)
• QQ bridge: OneBot v11 Reverse WS endpoint /aspanel/onebot/ws
  • Incoming group messages are stored and broadcast to web clients
  • If QQ account matches an AS Panel user bound to a player, messages display as MCName(Nickname)@QQ in web, and relay to game as [QQ] <MCName> message
  • Avatar order: user avatar → bound MC avatar → default
• Game relay (optional): if you use an MCDR reporter, connect it to /aspanel/mcdr. Selected events are bridged to web/QQ.

Minecraft Permissions Check

• Endpoint: GET /api/users/permissions/check (ADMIN)
• Purpose: verify that users’ bound MC names are placed into the correct buckets inside each server’s permission.yml:

default_level: user

owner:
admin:
helper:
user:
- CalciumSilicate
guest:

• The checker inspects all servers from DB, loads <server_path>/permission.yml, and reports mismatches for roles (GUEST / HELPER / ADMIN / OWNER). It does not auto-fix; you can extend it to write back if desired.

Production Deployment

Build frontend:

cd frontend
npm install && npm run build

Run backend (example):

source .venv/bin/activate
pip install -r requirements.txt
uvicorn backend.main:main_asgi_app --host 0.0.0.0 --port 8000 --workers 1

Nginx snippet:

location / { root /path/to/frontend/dist; try_files $uri /index.html; }
location /api/ { proxy_pass http://127.0.0.1:8000; }
location /ws/socket.io {
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_http_version 1.1;
  proxy_read_timeout 600s;
  proxy_pass http://127.0.0.1:8000;
}

Notes & Limitations

• Early-stage software; APIs and UI flow may change.
• MCDReforged/Java server lifecycle is out of scope here; ensure your environment and plugins are properly configured.
• The SQLite DB and storage layout are designed for a single-node deployment. For multi-user internet-facing setups, consider hardening, rate limiting, and RBAC audits.

Contributing

Issues and PRs are welcome. Please keep changes scoped and aligned with the tech stack (FastAPI, SQLAlchemy, Pydantic v2, Vue 3 + Vite).