{"id":51185732,"url":"https://github.com/vvb7456/erocraft_manager","last_synced_at":"2026-06-27T10:00:49.335Z","repository":{"id":301127065,"uuid":"1008222256","full_name":"vvb7456/Erocraft_Manager","owner":"vvb7456","description":"Server rental management platform whose only runtime dependency is Wings. Vue 3 + FastAPI.","archived":false,"fork":false,"pushed_at":"2026-06-21T04:32:40.000Z","size":5183,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T05:22:45.855Z","etag":null,"topics":["billing","fastapi","pterodactyl-wings","server-management","vue3"],"latest_commit_sha":null,"homepage":"https://www.erocraft.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vvb7456.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-25T08:04:07.000Z","updated_at":"2026-06-21T04:32:13.000Z","dependencies_parsed_at":"2025-07-23T07:18:56.561Z","dependency_job_id":"82f48233-661a-4701-b5d8-2703dbf9c2c9","html_url":"https://github.com/vvb7456/Erocraft_Manager","commit_stats":null,"previous_names":["vvb7456/ptero_manager","vvb7456/erocraft_manager"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/vvb7456/Erocraft_Manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvb7456%2FErocraft_Manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvb7456%2FErocraft_Manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvb7456%2FErocraft_Manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvb7456%2FErocraft_Manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vvb7456","download_url":"https://codeload.github.com/vvb7456/Erocraft_Manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vvb7456%2FErocraft_Manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34848932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["billing","fastapi","pterodactyl-wings","server-management","vue3"],"created_at":"2026-06-27T10:00:43.278Z","updated_at":"2026-06-27T10:00:49.326Z","avatar_url":"https://github.com/vvb7456.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Erocraft Manager\n\n[中文](README.zh-CN.md) · **English**\n\n![Preview](preview.png)\n\nServer rental management platform whose only runtime dependency is Wings. Adds an end-user UI for console / files / billing / registration / renewal, plus an admin console for servers, users, hosts, certificates, alerting and billing.\n\n---\n\n## 1. Overview\n\n### 1.1 Components\n\nThis repository ships two independently deployable units:\n\n| Unit | Path | Purpose |\n|---|---|---|\n| Manager | repo root | Backend API + scheduled jobs + Vue SPA. Runs on host A. |\n| Agent | `agent/` | Per-node host metrics, probes, certificate deployment, Wings service control. Runs on every Wings node. |\n\nThe Manager backend is two processes:\n\n- `manager-web`: FastAPI + Uvicorn, listens on `:5001`. REST API + console WebSocket.\n- `manager-jobs`: APScheduler in its own process. Runs metrics pull, auto-suspend, auto-delete, certificate renewals, etc.\n\nBoth share the same `app/` codebase and database, and run independently of each other.\n\n### 1.2 External Dependencies\n\n**Hard runtime dependencies** :\n\n| Dependency | Used for |\n|---|---|\n| Wings | Container lifecycle, power, console, files (per node; Manager calls `:8443` HTTPS and console WS directly) |\n| MySQL / MariaDB | Sole datastore. Manager's own tables use the `manager_` prefix; the server / node records Wings needs live in the same database |\n| nginx | Public reverse proxy; also serves the SPA static files |\n| acme.sh | Certificate issuance / renewal, invoked by Manager via CLI |\n\n**Relationship with Pterodactyl Panel**: Manager runs independently of the Panel process and interacts with the system only through the database and Wings. The database table / column names Manager uses, and the Laravel encryption format of Wings's `daemon_token`, are de-facto conventions of the Wings ecosystem. Pterodactyl Panel may be co-deployed and share the same database; in that case Panel's admin UI can be kept as a low-level fallback. When deploying Manager alone, you are responsible for initializing the schema and aligning keys with Wings.\n\n### 1.3 Process Topology\n\n```\n            browser\n              │\n              ↓\n         nginx :80/:443\n              │\n   ┌──────────┴───────────┐\n   │                      │\n   ↓                      ↓\nSPA (static files)   manager-web :5001  ──direct R/W──→  MySQL\n                          │\n                          ├──HTTPS──→  Wings :8443    (per node)\n                          │\n                          └──HTTPS──→  Agent :48765   (per node)\n                          ↑\n                          │\n                manager-jobs (APScheduler)  ─── periodic agent pull / automation\n```\n\n### 1.4 Tech Stack\n\n| Layer | Choice |\n|---|---|\n| Backend | Python 3.12, FastAPI, SQLAlchemy 2 (async), Pydantic v2, APScheduler, Alembic |\n| Frontend | Vue 3.5, Vite 6, TypeScript, vue-i18n, ECharts, xterm.js, CodeMirror 6 |\n| Database | MySQL / MariaDB |\n| Agent | Python 3 + FastAPI + psutil + httpx |\n| Certificates | acme.sh |\n\n### 1.5 Repository Layout\n\n```\napp/                FastAPI backend\n  api/routers/      HTTP routes\n  services/         business logic (panel_db, wings, agent_client, cert_manager, billing, ...)\n  jobs/             manager-jobs entrypoint and scheduler config\n  schemas/          Pydantic models\n  db/               ORM models + AsyncSession\n  core/             config, security, time helpers\nagent/              Node agent source\nalembic/            Database migrations\nfrontend/           Vue 3 SPA\ndocs/               Architecture \u0026 design docs (ARCHITECTURE_V3 is authoritative)\ntemplates/          Email template JSON\nmanager.sh          Backend service control script\n.env.example        Environment template\n```\n\n---\n\n## 2. Deployment\n\n### 2.1 Prerequisites\n\n- Linux x86_64 (verified on Debian 12 / Ubuntu 22.04+)\n- At least one Wings node and a reachable MySQL / MariaDB instance (schema follows Wings ecosystem conventions; typically initialized by Pterodactyl Panel)\n- Python 3.12+, Node.js 20+, nginx\n- Network reach from host A to that MySQL (local or remote)\n- acme.sh installed\n\n### 2.2 Manager Backend\n\n```bash\nsudo mkdir -p /opt/erocraft_manager\nsudo chown $USER:$USER /opt/erocraft_manager\ngit clone https://github.com/vvb7456/Erocraft_Manager.git /opt/erocraft_manager\ncd /opt/erocraft_manager\n\npython3.12 -m venv venv\nvenv/bin/pip install --upgrade pip\nvenv/bin/pip install -r requirements.txt\n\ncp .env.example .env\n$EDITOR .env\n```\n\nRequired `.env` fields:\n\n| Variable | Description |\n|---|---|\n| `SECRET_KEY` | ≥32 chars. Generate with `python -c \"import secrets; print(secrets.token_hex(32))\"` |\n| `DB_HOST` / `DB_PORT` / `DB_USER` / `DB_PASSWORD` / `DB_NAME` | Database connection |\n| `PANEL_APP_KEY` | The Laravel `APP_KEY` used by the Wings ecosystem. Decrypts `nodes.daemon_token` and similar fields; if you share the database with Pterodactyl Panel, this must equal Panel's `.env` `APP_KEY`. |\n| `CERT_ACME_SH_HOME` | acme.sh install directory |\n| `CERT_ACME_SH_BIN` | acme.sh executable path |\n\nStart:\n\n```bash\nbash manager.sh start          # starts web + jobs; runs `alembic upgrade head` first\nbash manager.sh status\n```\n\nArtifacts: `erocraft_manager_web.pid`, `erocraft_manager_jobs.pid`. Logs in `logs/`.\n\n### 2.3 Frontend\n\n```bash\ncd frontend\nnpm ci\nnpx vite build           # outputs to ../static/dist/\nbash build-fonts.sh      # rebuild Material Symbols subset\n```\n\n### 2.4 nginx\n\nMinimal config (add `listen 443 ssl;` + cert paths for HTTPS):\n\n```nginx\nserver {\n    listen 80;\n    server_name panel.example.com;\n\n    # Cert deployment endpoints can take \u003e120s\n    location /api/admin/certificates {\n        proxy_pass http://127.0.0.1:5001;\n        proxy_set_header Host $host;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_read_timeout 400s;\n    }\n\n    # API + console WS\n    location /api/ {\n        proxy_pass http://127.0.0.1:5001;\n        proxy_http_version 1.1;\n        proxy_set_header Upgrade $http_upgrade;\n        proxy_set_header Connection \"upgrade\";\n        proxy_set_header Host $host;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_read_timeout 120s;\n    }\n\n    location / {\n        root /opt/erocraft_manager/static/dist;\n        try_files $uri /index.html;\n    }\n}\n```\n\n### 2.5 Per-Node Agent\n\nEvery Wings node needs an Agent. By convention it runs from `/opt/erocraft-agent` (note the dash; distinct from the in-repo `agent/`).\n\n```bash\nsudo mkdir -p /opt/erocraft-agent\ncd /opt/erocraft-agent\npython3 -m venv venv\nvenv/bin/pip install -r /path/to/erocraft_manager/agent/requirements.txt\nsudo cp -r /path/to/erocraft_manager/agent ./agent\n\nsudo cp agent/config.example.yaml ./agent.yaml\nsudo $EDITOR ./agent.yaml\n```\n\nKey `agent.yaml` fields:\n\n| Field | Meaning |\n|---|---|\n| `agent.role` | `wings_node` / `generic_host` / `synology_dsm` |\n| `agent.bind` | Listen address; default `0.0.0.0:48765` |\n| `agent.token` | Bearer token. High-entropy random string. Manager stores it encrypted. |\n| `agent.allow_ips` | Optional source-IP allowlist |\n| `wings.config_path` | Required when `role=wings_node`; points to wings config |\n\nsystemd:\n\n```bash\nsudo cp agent/erocraft-agent.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now erocraft-agent\n```\n\nRegister: in admin → Hosts → New, enter the agent endpoint URL (`http://\u003cnode\u003e:48765`) and token. A probe runs automatically on save.\n\n### 2.6 Agent Redeploy\n\nThe running agent does not auto-sync from the repo; push changes manually with the helper script:\n\n```bash\nbash scripts/deploy-agent.sh              # local\nbash scripts/deploy-agent.sh \u003cnode-host\u003e  # remote node\n```\n\n### 2.7 Database Migrations\n\n`manager.sh start` runs migrations automatically. Manual:\n\n```bash\nvenv/bin/alembic -c alembic.ini current\nvenv/bin/alembic -c alembic.ini history\nvenv/bin/alembic -c alembic.ini upgrade head\nvenv/bin/alembic -c alembic.ini revision --autogenerate -m \"...\"\n```\n\nAll Manager-owned tables use the `manager_` prefix; migrations operate only on those tables.\n\n---\n\n## 3. Operations\n\n### 3.1 Service Control\n\n```bash\nbash manager.sh start | stop | restart | status            # web + jobs\nbash manager.sh start-web | stop-web | status-web\nbash manager.sh start-jobs | stop-jobs | status-jobs\n```\n\nStartup runs `alembic upgrade head` first; if migration fails, check `logs/manager-web.log`.\n\n### 3.2 Logs\n\n| File / command | Contents |\n|---|---|\n| `logs/manager-web.log` | uvicorn access + application |\n| `logs/manager-jobs.log` | scheduler jobs |\n| `journalctl -u erocraft-agent` | node agent |\n| `journalctl -u wings` | Wings |\n\nLog level controlled by `LOG_LEVEL` in `.env` (`DEBUG / INFO / WARNING / ERROR`).\n\n### 3.3 Scheduled Jobs\n\n`manager-jobs` runs:\n\n| Job | Trigger | Source |\n|---|---|---|\n| Metrics pull (all hosts) | every `MONITOR_INTERVAL_SEC` (default 60) | `.env` + runtime setting |\n| Metrics pruning | daily | `MONITOR_RETENTION_DAYS` (default 30 days) |\n| Auto-suspend / delete / reminder mail | daily at `AUTOMATION_RUN_HOUR:MINUTE` | runtime setting overrides |\n| Certificate renewal \u0026 expiry alerts | daily | acme.sh + scanner |\n\n`.env` is bootstrap fallback only. Runtime configuration lives in the database (admin → Settings).\n\n### 3.4 Certificates\n\n- **Source**: scan `CERT_ACME_SH_HOME` + acme.sh metadata\n- **Renewal**: invokes `CERT_ACME_SH_BIN`\n- **Targets**: local file / remote nginx (via Agent, with reload) / Synology DSM API\n- **Webhook**: acme.sh `reloadcmd` or `deploy hook` calls `/api/public/cert-webhook`. Configure `CERT_WEBHOOK_TOKEN`.\n- **Alert recipients**: `CERT_ALERT_EMAIL_ADMIN_IDS` or runtime setting\n\n### 3.5 Hosts / Nodes\n\n| Action | Path |\n|---|---|\n| Add a node | Admin → Hosts → New (endpoint + token) |\n| Edit Wings config | Host detail → Wings tab; on save Manager writes the `nodes` table then pushes to wings `/api/update` |\n| Restart Wings | Host detail → Wings → Restart (Agent triggers `systemctl restart wings`) |\n| Allocations | Host detail → Allocations tab |\n| Alert thresholds | Host detail → Settings tab (per-host overrides on top of global defaults) |\n\n### 3.6 Backups\n\n| Item | Command / path |\n|---|---|\n| Database | `mysqldump \u003cDB_NAME\u003e \u003e db.sql` |\n| Config | `.env`, `agent.yaml` (per node), nginx site files |\n| Certificates | full `CERT_ACME_SH_HOME` |\n| Container volumes | `/var/lib/pterodactyl/volumes` on each node |\n\n### 3.7 Upgrade\n\n```bash\ncd /opt/erocraft_manager\ngit pull\nvenv/bin/pip install -r requirements.txt\ncd frontend \u0026\u0026 npm ci \u0026\u0026 npx vite build \u0026\u0026 cd ..\nbash manager.sh restart                     # auto-migrates\nbash scripts/deploy-agent.sh                # only when agent/ changed\n```\n\n### 3.8 Troubleshooting\n\n| Symptom | Where to look |\n|---|---|\n| `manager.sh start` fails immediately | `logs/manager-web.log`; usually a missing `.env` field or migration failure |\n| User console fails to connect | Verify nginx forwards `Upgrade/Connection` headers; verify wings `:8443` reachability from Manager |\n| No monitoring data | Host detail → Settings → Probe; `systemctl status erocraft-agent`; verify token match |\n| Certificate not renewed | grep `cert` in `logs/manager-jobs.log`; manually run `${CERT_ACME_SH_BIN} --renew -d \u003cdomain\u003e --force` |\n| Server creation fails | `lifecycle` entries in `logs/manager-web.log`; failures auto-rollback |\n| Panel field decryption errors | confirm `PANEL_APP_KEY` matches the `APP_KEY` Wings was given when its `daemon_token` was generated (when sharing the database with Pterodactyl Panel, that means Panel's `.env` `APP_KEY`) |\n\n### 3.9 One-liners\n\n```bash\nvenv/bin/alembic -c alembic.ini current                      # current migration revision\ntail -f logs/manager-jobs.log                                # tail jobs log\ncurl -fsS http://127.0.0.1:5001/api/version                  # health check\n```\n\n---\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvb7456%2Ferocraft_manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvvb7456%2Ferocraft_manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvvb7456%2Ferocraft_manager/lists"}