Service Reseller Panel

A self-hosted PHP service-delivery and reseller-management panel for 3x-ui/Xray and MikroTik UserManager, with Plan-based XUI sales, reseller credit accounting, public customer delivery, TON payments, and an optional direct-sales Shop.

Current release: 2.1.0-rc7 — production-oriented release candidate. Stage against your real 3x-ui, MikroTik UserManager, and TON payment environment before production cutover.

Why this project exists

3x-ui and MikroTik UserManager are excellent infrastructure tools, but they are not a complete reseller/customer commercial layer. Service Reseller Panel sits above them and deliberately separates infrastructure from what resellers/end-users buy:

• XUI infrastructure is imported as inbound templates and composed into XUI Plans.
• MikroTik UserManager profiles remain an independent UM product catalog.
• Resellers are given explicit permissions to sell selected Plans and/or UM profiles.
• Every sale is recorded as a customer/service with credit, audit, sync, and delivery state.
• Direct Shop customers remain admin-owned and are never mixed into reseller ownership.

Highlights

XUI / 3x-ui

• XUI Plans built from one or many imported inbounds.
• Multi-inbound and multi-node service assignments.
• Capability-driven modern/legacy 3x-ui API compatibility.
• Current 3x-ui Hosts/external endpoints support; default inbound config is suppressed when usable external Hosts exist.
• Per-node HTTP, HTTPS, and SOCKS5 proxy support for authentication and all XUI API operations.
• Safe client create/update/delete, traffic sync, status sync, links, provisioning verification, compensation, and reconciliation.
• Shared-strict, aggregate-soft, and per-node quota modes.
• Config-title templates at Plan or inbound level with variables such as {client}, {plan}, {server}, {host}, and {host_remark}.
• Per-inbound Update action to refresh source data without destructive re-import.

MikroTik UserManager

• Separate UM profile/template catalog; never mixed into XUI Plans.
• REST and internal RouterOS API compatibility paths.
• Profile import and per-profile Update.
• Create, update/toggle, delete, usage sync, username/password delivery, and reseller permissions.
• UM billing remains profile/template based while using the same reseller wallet.

Reseller operations

• Shared GB-credit wallet with serialized mutations and audit ledger.
• XUI reseller billing by configurable GB-credit multiplier per allocated GB.
• Independent reseller permissions for XUI Plans and UM profiles.
• Customer/service lifecycle, search, sync, disable/enable, delete, and activity history.
• Reseller API v2 with XUI Plan / UM product separation.
• Tickets, notices, profile tools, Telegram integration, and transaction history.

TON payments and direct Shop

• Optional reseller deposits using GRAM or USDT on TON.
• Provider invoice re-verification before settlement.
• Automatic USD→GB reseller credit conversion using admin policy.
• Idempotent webhook/polling settlement protection.
• Optional public Shop with USD-priced Products backed by either an XUI Plan or a UM profile.
• Direct-sale customers have no reseller owner and remain admin-only.
• Phone/email + PIN customer retrieval after automated fulfillment.

Public delivery and UI

• Modern responsive public landing page configurable from Admin → Settings.
• /get customer self-service access.
• XUI subscription/config delivery, QR support, and decorated config titles.
• UM credential delivery.
• Mobile-friendly admin and reseller interfaces.

Security / consistency

• Authenticated SecretVault using libsodium secretbox when available, AES-256-GCM fallback otherwise.
• Encrypted node/proxy/API/payment/Telegram/panel-sync/customer credentials at rest.
• CSRF protection, session regeneration, trusted-proxy handling, HSTS on secure requests, and atomic application rate limiting.
• Lock-protected JSON persistence, atomic writes, and rollback-capable local transaction journal.
• Remote compensation/reconcile for operations that cannot participate in a local transaction.
• API-key encrypted storage + one-way lookup hash.

Requirements

Recommended production baseline:

• PHP 8.1+
• Extensions: curl, json, session, openssl
• sodium strongly recommended
• zip recommended for full ZIP backups
• mbstring recommended
• Apache 2.4+ or Nginx + PHP-FPM
• HTTPS/TLS in production
• Writable storage/ for the PHP worker

No SQL database is required. The current persistence layer stores one JSON file per record under storage/data/ with locks and atomic writes. See Architecture for scaling limits.

Quick start

unzip service_reseller_panel_v2.1.0-production-rc6.zip
cd service_reseller_panel_v2.1.0-rc7

1. Point your web server DocumentRoot to public/.
2. Make storage/ writable by the PHP worker.
3. Browse to /install and create the first administrator.
4. Set the canonical HTTPS URL and timezone in Admin → Settings.
5. Add and test XUI and/or UM servers.
6. Import XUI inbounds / UM profiles.
7. Create XUI Plans from imported XUI targets.
8. Grant reseller permissions to Plans and/or UM profiles.
9. Create a staging service and verify its full lifecycle before onboarding real users.

Full production instructions: docs/DEPLOYMENT.md.

Service model

XUI

XUI Server
   └── Imported Inbound(s)
          └── XUI Plan
                 └── Customer Service
                        └── Service Assignment(s)
                               └── Remote XUI client state

A Plan is what is sold. An Inbound is infrastructure. A Service Assignment records what was actually provisioned on each target so partial failures can be detected and repaired.

MikroTik UserManager

UM Server
   └── Imported UM Profile
          └── Customer Service
                 └── Remote UM user/profile binding

UM intentionally stays independent from XUI Plans.

Config-title templates

An XUI Plan or inbound template can define a customer-facing config-title template. Plan-level configuration wins over inbound-level configuration; blank values preserve the default remote title.

Example:

⚡ {plan} • {server} • {host_remark}

Common variables:

{client} {email} {plan} {plan_code} {inbound} {inbound_id}
{server} {protocol} {host} {host_remark} {traffic_gb} {expires_at}

See XUI Plans.

Scheduled jobs

Maintenance dispatcher:

* * * * * /usr/bin/php /srv/service-panel/scripts/cron.php >/dev/null 2>&1

TON payment reconciliation fallback when commerce is enabled:

*/2 * * * * /usr/bin/php /srv/service-panel/scripts/payment_cron.php >/dev/null 2>&1

Panel Sync and Telegram polling have dedicated helpers; see Operations.

Reseller API v2

The canonical catalog endpoint is:

GET /api/reseller/services

It returns separate catalogs:

{
  "xui_plans": [],
  "um_profiles": []
}

New XUI sales require service_type=xui_plan + plan_id. Raw XUI inbound/template sales are rejected. UM sales require service_type=um + template_id.

See docs/API_V2.md for endpoints, request/response format, API encryption, deposits, and ownership rules.

Repository layout

app/
  PanelApp.php                 Main request/application coordinator
  traits/                      Plan, XUI service, and commerce domains
  lib/                         Persistence, security, XUI/UM/payment adapters
  views/                       Server-rendered PHP views
public/
  index.php                    Web front controller
  assets/                      CSS / JavaScript
scripts/                       Cron, payment, panel-sync, Telegram helpers
storage/                       Runtime state (ignored by Git except .gitkeep)
tests/                         Lint, core regression, clean-install HTTP smoke
docs/                          Operator, architecture, API and developer docs
.github/                       CI and contribution templates

A detailed source map is available in docs/CODE_MAP.md.

Development and tests

Run from repository root:

bash tests/lint.sh
php tests/run.php
python3 -m pip install requests beautifulsoup4 cryptography
python3 tests/http_smoke.py

The HTTP suite creates a temporary clean install. It does not mutate your working runtime data and does not contact real XUI/UM servers.

See Development Guide.

Documentation

Start at docs/INDEX.md.

Core documents:

• Production Deployment
• Admin Guide
• Reseller Guide
• XUI Plans
• MikroTik UserManager
• Customer Delivery
• TON Commerce
• Operations
• Security
• Reseller API v2
• Troubleshooting
• Architecture
• Code Map
• Landing Page
• Migration

Production cautions

• Prefer public/ as the only web-accessible directory.
• Never commit runtime storage/data, storage/config, logs, backups, or local secrets.
• Treat application backups as sensitive: a restorable backup must contain key material required to decrypt protected secrets.
• Use allow_insecure_tls only as a temporary diagnostic exception.
• Do not run two independent control panels as authoritative writers for the same remote customer set.
• Keep one payment-settlement authority for a TON Console application.
• Test every 3x-ui/RouterOS version you actually operate before production cutover.

GitHub / contribution workflow

Repository hygiene files, issue templates, pull-request template, and CI are included. Before publishing publicly:

1. Choose and add the license you intend to grant. No open-source license is assumed by this repository.
2. Review SECURITY.md and replace the generic private-reporting instruction with your preferred security contact if needed.
3. Remove any private historical material you do not want public.
4. Run the full test suite.
5. Verify git status does not include runtime storage/ data or credentials.

See CONTRIBUTING.md and docs/RELEASE_PROCESS.md.

Release status

2.1.0-rc7 keeps the RC6 functional/UI baseline and fixes the protected JavaScript asset path so it is fully compatible with the panel's strict Content Security Policy. The protected route no longer reconstructs source through dynamic code execution, so Chrome can execute the mobile sidebar handlers without requiring unsafe-eval. The responsive drawer, cache-versioned assets, service-table containment, provisioning, billing, TON/shop, reseller API, Panel Sync, server, customer ownership, and service-lifecycle behavior remain unchanged. It remains a release candidate rather than a formal security certification or a promise of zero defects.