[FEATURE] Create 3x-UI Adapter and Integrate It with the Backend

PoweredDeveloper commented

2026-07-07 21:01:10 +00:00

Owner

The FastAPI Backend and the 3x-UI Panel run on the same Head Server, but the backend has no integration layer for the panel API. Business logic cannot yet provision VPN users, read subscription configs, or query panel operational state (server status, inbounds, nodes, etc.).

Describe the solution you'd like

Implement a TrixUI adapter as an internal Backend module that translates business operations into 3x-UI Panel API calls.

Authentication

Use a persistent API Bearer token on every request (Authorization: Bearer <token>). Do not use cookie/session login or CSRF for programmatic access.

Implementation scope

In scope for this issue (foundation):

Env-based panel URL configuration in config.py
TrixUIClient - async HTTP client with timeout and structured errors (TrixUIClientError)
VpnPanelAdapter protocol + TrixUIAdapter implementation
First working API call: get_server_status() -> GET /panel/api/server/status, parsed into typed ServerStatus
Communicate with the panel over the internal Docker network

Error handling

HTTP errors -> raise_for_status()
Panel { "success": false } responses -> TrixUIClientError
Configurable request timeout

Describe alternatives you've considered

Direct HTTP calls from route handlers - rejected; duplicates auth, error handling, and couples business logic to 3x-UI.

Cookie/session login to the panel - rejected for programmatic use; CSRF complicates automation. Bearer API token is the supported 3x-UI approach for /panel/api/*.

Direct access to the TrixUI PostgreSQL database - rejected; writes must go through the Panel API only (see Database — Synchronization).

Separate microservice for the adapter - rejected; docs specify an internal Backend module, not a standalone service.

Additional context

The adapter is the only component that writes to the 3x-UI Panel on behalf of the Backend.
Backend remains the source of truth for business state; 3x-UI remains the source of truth for VPN operational state.
When adding future adapter methods, business services must update Backend DB first, then call the adapter.
API token must be created manually in the 3x-UI panel and added to .env as XUI_API_TOKEN.

Acceptance criteria

Backend can reach GET /panel/api/server/status from inside Docker using env-configured URL + Bearer token
TrixUIAdapter.get_server_status() returns a typed ServerStatus model
Panel API failures surface as TrixUIClientError, not silent failures
VpnPanelAdapter protocol exists so future panel implementations can be swapped without changing business logic

Checklist

I have checked that this feature is not already requested.
I am willing to help implement it (optional).

## Is your feature request related to a problem? The FastAPI Backend and the 3x-UI Panel run on the same Head Server, but the backend has no integration layer for the panel API. Business logic cannot yet provision VPN users, read subscription configs, or query panel operational state (server status, inbounds, nodes, etc.). ## Describe the solution you'd like Implement a **TrixUI adapter** as an internal Backend module that translates business operations into 3x-UI Panel API calls. ### Authentication Use a **persistent API Bearer token** on every request (`Authorization: Bearer <token>`). Do not use cookie/session login or CSRF for programmatic access. ### Implementation scope **In scope for this issue (foundation):** - [x] Env-based panel URL configuration in `config.py` - [x] `TrixUIClient` - async HTTP client with timeout and structured errors (`TrixUIClientError`) - [x] `VpnPanelAdapter` protocol + `TrixUIAdapter` implementation - [x] First working API call: `get_server_status()` -> `GET /panel/api/server/status`, parsed into typed `ServerStatus` - [x] Communicate with the panel over the internal Docker network ### Error handling - HTTP errors -> `raise_for_status()` - Panel `{ "success": false }` responses -> `TrixUIClientError` - Configurable request timeout ## Describe alternatives you've considered **Direct HTTP calls from route handlers** - rejected; duplicates auth, error handling, and couples business logic to 3x-UI. **Cookie/session login to the panel** - rejected for programmatic use; CSRF complicates automation. Bearer API token is the supported 3x-UI approach for `/panel/api/*`. **Direct access to the TrixUI PostgreSQL database** - rejected; writes must go through the Panel API only (see [Database — Synchronization](docs/database.md#synchronization)). **Separate microservice for the adapter** - rejected; docs specify an internal Backend module, not a standalone service. ## Additional context - The adapter is the **only** component that writes to the 3x-UI Panel on behalf of the Backend. - Backend remains the source of truth for business state; 3x-UI remains the source of truth for VPN operational state. - When adding future adapter methods, business services must **update Backend DB first**, then call the adapter. - API token must be created manually in the 3x-UI panel and added to `.env` as `XUI_API_TOKEN`. ## Acceptance criteria - [x] Backend can reach `GET /panel/api/server/status` from inside Docker using env-configured URL + Bearer token - [x] `TrixUIAdapter.get_server_status()` returns a typed `ServerStatus` model - [x] Panel API failures surface as `TrixUIClientError`, not silent failures - [x] `VpnPanelAdapter` protocol exists so future panel implementations can be swapped without changing business logic ## Checklist - [x] I have checked that this feature is not already requested. - [x] I am willing to help implement it (optional).

PoweredDeveloper added this to the Sprint 1 milestone

2026-07-07 21:01:10 +00:00

PoweredDeveloper added the

infrastructure

enhancement

backend

labels

2026-07-07 21:01:10 +00:00

PoweredDeveloper self-assigned this

2026-07-07 21:01:10 +00:00

PoweredDeveloper added this to the Backend (Core) project

2026-07-07 21:01:10 +00:00