diff --git a/PANEL_GUIDE_SOURCE_OF_TRUTH.md b/PANEL_GUIDE_SOURCE_OF_TRUTH.md index 9617c443..fc7e28c0 100644 --- a/PANEL_GUIDE_SOURCE_OF_TRUTH.md +++ b/PANEL_GUIDE_SOURCE_OF_TRUTH.md @@ -1228,6 +1228,7 @@ Index: - `docs/panel-guide/11-troubleshooting-runbook.md` - `docs/panel-guide/12-change-management-and-rollout.md` - `docs/panel-guide/13-feature-file-map-and-decision-log.md` +- `docs/panel-guide/14-marzban-inspired-roadmap.md` - `docs/panel-guide/99-session-context-transfer-2026-02-18.md` Use those files for day-to-day operations and implementation reference. diff --git a/docs/panel-guide/14-marzban-inspired-roadmap.md b/docs/panel-guide/14-marzban-inspired-roadmap.md new file mode 100644 index 00000000..c9dd38a2 --- /dev/null +++ b/docs/panel-guide/14-marzban-inspired-roadmap.md @@ -0,0 +1,210 @@ +# 14. Marzban-Inspired Roadmap (Implementation Draft) + +## Goal + +Borrow high-impact ideas from Marzban and implement them safely in custom 3x-ui without breaking existing inbound-native workflows. + +## Reference baseline + +This draft is based on Marzban concepts visible in official repo/docs (node architecture, host settings, webhooks, CLI/admin flows), adapted to current 3x-ui architecture and your implemented client-center extension. + +--- + +## Phase 1 (fast, low-risk, high ROI) + +### 1) Plan Presets (User Templates) + +Purpose: +- Reusable client plans (for example: `30d-100GB`, `90d-300GB`, `Unlimited`). + +DB: +- `plan_presets`: + - `id`, `user_id`, `name`, `total_gb`, `duration_days`, `limit_ip`, `enable`, `comment`, `created_at`, `updated_at` + +API: +- `GET /panel/api/plans/list` +- `POST /panel/api/plans/add` +- `POST /panel/api/plans/update/:id` +- `POST /panel/api/plans/del/:id` + +UI: +- Add `Plans` tab/page. +- In `/panel/clients`, add “Apply Plan” selector for create/edit. + +Acceptance: +- Create plan once and apply to new/existing master clients in one click. + +--- + +### 2) Webhook Events + +Purpose: +- External automation (billing, CRM, alerts) decoupled from panel internals. + +DB: +- `webhook_endpoints`: + - `id`, `user_id`, `name`, `url`, `secret`, `enabled`, `event_filter_json`, `created_at`, `updated_at` +- `webhook_deliveries`: + - `id`, `endpoint_id`, `event`, `payload_json`, `status_code`, `success`, `error`, `created_at` + +Events (initial): +- `master_client.created` +- `master_client.updated` +- `master_client.deleted` +- `assignment.created` +- `assignment.updated` +- `assignment.deleted` +- `inbound.client.sync_failed` + +API: +- `GET /panel/api/webhooks/list` +- `POST /panel/api/webhooks/add` +- `POST /panel/api/webhooks/update/:id` +- `POST /panel/api/webhooks/del/:id` +- `GET /panel/api/webhooks/deliveries` +- `POST /panel/api/webhooks/test/:id` + +Implementation note: +- HMAC signature header with endpoint secret. +- Non-blocking async delivery queue + retry policy. + +Acceptance: +- Webhook test succeeds and deliveries are visible/auditable. + +--- + +### 3) Host/Profile Settings Templates + +Purpose: +- Better subscription/profile text rendering with variables. + +DB: +- `host_templates`: + - `id`, `user_id`, `name`, `template_text`, `enabled`, `created_at`, `updated_at` + +Template variables (v1): +- `{{master_name}}` +- `{{email_prefix}}` +- `{{inbound_remark}}` +- `{{protocol}}` +- `{{port}}` +- `{{expiry_time}}` +- `{{days_left}}` +- `{{total_gb}}` +- `{{used_gb}}` +- `{{remaining_gb}}` + +API: +- `GET /panel/api/host-templates/list` +- `POST /panel/api/host-templates/add` +- `POST /panel/api/host-templates/update/:id` +- `POST /panel/api/host-templates/del/:id` +- `POST /panel/api/host-templates/preview` + +UI: +- `Settings -> Subscription` add template manager/preview. + +Acceptance: +- Template preview and rendered subscription info align with selected inbound/client. + +--- + +## Phase 2 (medium effort, operational depth) + +### 4) Bulk Policy Actions + +Purpose: +- Apply +days/+GB/enable/disable/comments to selected master clients. + +API: +- `POST /panel/api/clients/bulk` + - filters: ids, tags, enabled state + - operations: set/adjust fields + +Safety: +- Dry-run mode (`preview=true`) returns mutation summary. + +Acceptance: +- Admin can bulk-modify 100+ clients with preview and audit trail. + +--- + +### 5) Audit Log + +DB: +- `audit_logs`: + - actor, action, target_type, target_id, before_json, after_json, created_at + +Coverage: +- Client-center, plan, webhook, template, inbound sync actions. + +Acceptance: +- Every sensitive action has immutable audit row. + +--- + +## Phase 3 (advanced, higher risk) + +### 6) Multi-admin Ownership / RBAC + +Roles: +- `owner`, `admin`, `operator`, `viewer` + +Scope: +- Per-user ownership of master clients and optional inbound scope controls. + +Acceptance: +- Role matrix enforced on APIs and UI actions. + +--- + +### 7) Node Architecture (Marzban-style inspiration) + +Purpose: +- Manage remote xray nodes from a central control panel. + +Model (initial): +- Central panel keeps desired state. +- Node agent pulls signed config deltas + pushes health/traffic. + +Major components: +- `nodes` table and node auth keys +- Node heartbeat + capability registry +- Config distribution queue +- Health and lag monitoring + +Acceptance: +- One remote node managed reliably with inbound/client sync and health checks. + +--- + +## Cross-cutting engineering rules + +1. Additive-first: keep old APIs/UI working. +2. Feature flags for each new module. +3. Idempotent sync operations. +4. Queue + retries for external IO (webhooks/nodes). +5. Full rollback path (DB backup + binary rollback). + +--- + +## Suggested first implementation sprint (5-7 days) + +1. `plan_presets` DB/API/UI +2. Webhook endpoints + delivery log + test button +3. Host template CRUD + preview +4. Minimal audit logs for these three modules + +Deliverable at sprint end: +- Operators can provision clients faster, integrate billing/automation, and improve subscription profile quality without architecture-breaking changes. + +--- + +## Fit with current custom code + +Already aligned foundations: +- Master client model exists (`MasterClient`, `MasterClientInbound`). +- Central clients API/UI exists (`/panel/clients`, `/panel/api/clients/*`). +- Dev workflow exists (`.air.toml`, `justfile`). + +So this roadmap extends current direction directly, no redesign needed for Phase 1. diff --git a/docs/panel-guide/15-remnawave-hiddify-analysis.md b/docs/panel-guide/15-remnawave-hiddify-analysis.md new file mode 100644 index 00000000..1732fab3 --- /dev/null +++ b/docs/panel-guide/15-remnawave-hiddify-analysis.md @@ -0,0 +1,82 @@ +# 15. Remnawave + Hiddify Analysis + +## Purpose + +This document captures features from `remnawave/panel` and `hiddify/Hiddify-Manager` that can inspire our custom `3x-ui`, with focus on low-breakage adoption. + +## Remnawave (panel) Findings + +### Product shape + +- TypeScript-oriented ecosystem (panel/backend/frontend/node tooling around Xray). +- Strong operator UX around users, nodes, templates, routing rules, squads, and notifications. + +### Standout capabilities + +- Squad model: group-based control over what users can access. +- Template/rule engine: conditional responses and per-client template behavior. +- Webhooks: event delivery for user/node/service/error events. +- Notification tuning: per-channel per-event control. +- HWID device limits and device history/management. +- SDK and automation orientation for external integrations. + +### What to borrow first + +1. Event webhooks in `3x-ui` for user/client/inbound lifecycle changes. +2. Notification matrix (events x channels) rather than global on/off. +3. Device management UI for client anti-sharing controls. +4. A simplified policy-group model (Remnawave squads inspiration) for assigning many inbounds to many clients cleanly. + +## Hiddify-Manager Findings + +### Product shape + +- Operationally heavy Linux stack: panel + generated configs + many services. +- Template generation pipeline for Xray/Sing-box/HAProxy/nginx and helper services. + +### Standout capabilities + +- Broad protocol and transport coverage (including newer stacks). +- HAProxy/nginx map-based dispatch and multiplexing. +- Auto-update/backup and operational scripts. +- Extra operator tooling (short links, helper pages, bot integration). + +### What to borrow first + +1. Template-first config generation mindset for complex transport combinations. +2. Optional HAProxy/nginx routing templates as an advanced deployment profile. +3. Operational guardrails: backup/update helpers and health checks. + +## Fit For Custom 3x-ui + +### Low-risk, high-value (phase 1) + +1. Webhook events and signed delivery. +2. Notification preference matrix. +3. Better client detail pages (usage, devices, assignment visibility). + +### Medium effort (phase 2) + +1. Policy groups for inbound bundles and client assignment. +2. Template/rule editor for client-aware output behavior. +3. More advanced export/subscription templates. + +### High effort / platform-level (phase 3) + +1. Full map-based edge routing orchestration (HAProxy/nginx style). +2. Multi-core orchestration parity (Xray + Sing-box in one control plane). +3. Full installer-grade lifecycle automation comparable to Hiddify. + +## Recommended Direction + +Prefer **Remnawave-inspired UX/control-plane features first** because they map well to our current custom `3x-ui` UI/backend extension path. + +Adopt **Hiddify-inspired ops architecture selectively** as optional deployment modules, not as core assumptions for all users. + +## Safe Implementation Rules + +1. Add each feature behind a feature flag. +2. Keep backward compatibility for existing inbound/client behavior. +3. Add migration scripts with rollback steps. +4. Ship contract tests for webhook payloads and assignment logic. +5. Validate new behavior in local sqlite dev + one staging VPS before production rollout. diff --git a/docs/panel-guide/16-unified-product-roadmap.md b/docs/panel-guide/16-unified-product-roadmap.md new file mode 100644 index 00000000..26b219dd --- /dev/null +++ b/docs/panel-guide/16-unified-product-roadmap.md @@ -0,0 +1,221 @@ +# 16. Unified Product Roadmap (3x-ui Custom) + +## Objective + +Build a production-grade custom `3x-ui` that keeps current compatibility while adding modern client management, automation, policy control, and optional advanced ops capabilities inspired by Marzban, Remnawave, and Hiddify. + +## Source of ideas + +- `3x-ui` baseline: inbound-centric model, compatibility, existing operator workflows. +- Marzban inspiration: node architecture, webhook/admin automation, host/profile concepts. +- Remnawave inspiration: squads/policy groups, template/rule engine, notification matrix, HWID management. +- Hiddify inspiration: template-driven config generation, advanced edge routing, strong operational tooling. + +## Product principles + +1. Backward-compatible by default. +2. Additive changes first, migrations only with rollback. +3. Feature flags for every major module. +4. Safe defaults for exposure, auth, and transport settings. +5. Operator-first UX: fast bulk actions, clear observability, low-click routine tasks. + +## Current baseline (already done) + +- Centralized client page exists (`/panel/clients`) with master client + inbound assignment sync. +- Local dev tooling exists (`justfile`, `air`, sqlite dev flow). +- Documentation split exists under `docs/panel-guide`. + +## Roadmap phases + +## Phase 0: Stabilize Foundation (1 week) + +### Deliverables + +1. Harden current client-center behavior. +2. Add regression tests for assignment/sync paths. +3. Add lightweight structured audit for client mutations. + +### Acceptance criteria + +1. No regression in existing inbound CRUD and client operations. +2. Sync errors are user-visible and recoverable. +3. Automated tests cover add/update/delete + attach/detach flows. + +## Phase 1: Operator Productivity Core (2-3 weeks) + +### Deliverables + +1. Plan presets (`30d-100GB`, `90d-300GB`, `unlimited`) with one-click apply. +2. Bulk client actions: extend expiry, add/reset quota, enable/disable, tag/comment edits. +3. Better client details: assigned inbounds, usage summary, expiry status, quick actions. +4. Audit log UI/API for sensitive changes. + +### Inspiration mapping + +- Marzban: plan-like lifecycle and operational workflows. +- Remnawave: stronger user detail and admin ergonomics. + +### Acceptance criteria + +1. Operator can modify 100+ clients via previewed bulk action safely. +2. Every sensitive operation writes immutable audit records. +3. Average clicks for common tasks reduced (create client, assign inbounds, extend plan). + +## Phase 2: Automation and Integration (2 weeks) + +### Deliverables + +1. Webhook endpoints with per-event filtering and HMAC signatures. +2. Delivery logs, retry policy, and test-send action. +3. Notification matrix (event x channel) with sane defaults. + +### Inspiration mapping + +- Remnawave: webhook scopes + fine-grained notification tuning. +- Marzban: external integration-friendly operator model. + +### Acceptance criteria + +1. Webhook payload contracts are versioned and documented. +2. Failed deliveries are visible with retry status. +3. Operators can disable noisy events without disabling all alerts. + +## Phase 3: Policy Groups and Access Model (2-3 weeks) + +### Deliverables + +1. Policy groups (squad-like) to assign bundles of inbounds/settings to clients. +2. Group-level limits/metadata inheritance with per-client override. +3. Group-based bulk assignment and membership management UI. + +### Inspiration mapping + +- Remnawave: Internal/External squad model. + +### Acceptance criteria + +1. Many-to-many assignment handled without manual per-inbound editing. +2. Inheritance and override behavior is deterministic and documented. +3. Migration from existing direct assignment remains seamless. + +## Phase 4: Template and Subscription Engine (3-4 weeks) + +### Deliverables + +1. Host/profile template manager with preview variables. +2. Output templates by client/app/core (xray/sing-box/mihomo style profiles). +3. Rule-based response behavior (safe subset first): header/app-based template selection. + +### Inspiration mapping + +- Remnawave: templates + response rules. +- Marzban: host/profile customization model. + +### Acceptance criteria + +1. Operators can preview rendered output before publishing. +2. Template changes are versioned and rollbackable. +3. Existing subscription links continue working. + +## Phase 5: Security and Anti-Abuse Layer (2-3 weeks) + +### Deliverables + +1. Device tracking and optional HWID/device limits per client. +2. Risk controls: suspicious device churn alerts, quick revoke flows. +3. Policy options for account sharing tolerance level. + +### Inspiration mapping + +- Remnawave: HWID/device management and anti-sharing controls. + +### Acceptance criteria + +1. Device history is queryable per client. +2. Operators can enforce or relax limits per policy group. +3. Enforcement failures fail safe and are auditable. + +## Phase 6: Advanced Ops Profile (Optional, staged, 4-8 weeks) + +### Deliverables + +1. Template-driven advanced config generation module. +2. Optional edge routing profile (HAProxy/nginx map-based patterns). +3. Optional multi-core orchestration profile (xray + sing-box). +4. Backup/update/health-check operational toolkit. + +### Inspiration mapping + +- Hiddify: config generation and ops automation. + +### Acceptance criteria + +1. Advanced profile is optional and isolated from default path. +2. Health checks and rollback mechanisms are mandatory. +3. Security review passes before enabling in production. + +## Cross-cutting workstreams + +## Data model and migration safety + +1. Every schema change gets forward + rollback migration plan. +2. Soft launch new tables/columns before hard dependencies. +3. Keep legacy APIs until replacement is validated. + +## API design and compatibility + +1. Version new APIs under clear prefixes when behavior differs. +2. Keep old endpoint behavior stable unless explicitly deprecated. +3. Add contract tests for webhook/template/assignment APIs. + +## UI/UX consistency + +1. Preserve current mental model for existing users. +2. Expose advanced controls progressively (basic vs advanced tabs). +3. Add inline docs/tooltips for protocol-sensitive fields. + +## Testing and quality gates + +1. Unit tests for model/service logic. +2. Integration tests for db migrations and sync flows. +3. UI flow tests (Playwright) for client lifecycle and bulk operations. +4. Staging soak test before each phase release. + +## Security controls + +1. HMAC for outbound webhooks. +2. RBAC prep for future multi-admin model. +3. Secret rotation support for API tokens and webhook secrets. +4. Harden defaults for exposed panels and management ports. + +## Release strategy + +1. Release per phase behind feature flags. +2. Rollout order: local sqlite -> staging VPS -> production VPS. +3. Each release ships with: + - migration notes + - rollback procedure + - updated docs in `docs/panel-guide` + - smoke test checklist + +## Success metrics + +1. Time to create + assign a client drops by at least 50%. +2. Bulk operations complete with zero silent failures. +3. Webhook delivery success rate stays above 99% after retries. +4. Support incidents caused by misconfiguration trend downward. +5. No increase in critical outages after enabling new modules. + +## Suggested execution order + +1. Phase 0 + Phase 1 immediately. +2. Phase 2 next (automation unlock). +3. Phase 3 and Phase 4 together only after Phase 1/2 are stable. +4. Phase 5 once policy groups are in place. +5. Phase 6 only as opt-in advanced deployment profile. + +## Non-goals (for now) + +1. Full rewrite of 3x-ui core architecture. +2. Mandatory multi-core or edge-router stack for all users. +3. Breaking changes to existing inbound-native workflows. diff --git a/docs/panel-guide/README.md b/docs/panel-guide/README.md index 47e51181..7dc19c4b 100644 --- a/docs/panel-guide/README.md +++ b/docs/panel-guide/README.md @@ -17,7 +17,10 @@ This folder is the focused replacement for the monolithic `PANEL_GUIDE_SOURCE_OF 11. `11-troubleshooting-runbook.md` 12. `12-change-management-and-rollout.md` 13. `13-feature-file-map-and-decision-log.md` -14. `99-session-context-transfer-2026-02-18.md` +14. `14-marzban-inspired-roadmap.md` +15. `15-remnawave-hiddify-analysis.md` +16. `16-unified-product-roadmap.md` +17. `99-session-context-transfer-2026-02-18.md` ## Recommended read order @@ -32,7 +35,10 @@ This folder is the focused replacement for the monolithic `PANEL_GUIDE_SOURCE_OF 9. Read `11` for incident/debug operation. 10. Read `12` before any risky rollout/migration. 11. Read `13` before modifying custom feature code. -12. Read `99` for full session handoff context. +12. Read `14` for Marzban-inspired implementation roadmap. +13. Read `15` for Remnawave + Hiddify inspiration and adoption phases. +14. Read `16` for the complete unified execution roadmap. +15. Read `99` for full session handoff context. ## Scope note