flvx/skills/flvx-api/references/federation.md

Federation / Clustering API

Federation allows sharing nodes between FLVX panels. One panel can share nodes, and another panel can use them as remote nodes.

Share Management (Admin)

POST /api/v1/federation/share/list

List all peer shares.

Request: {}

Response:

{
  "code": 0,
  "data": [
    {
      "id": 1,
      "name": "Share-to-Partner",
      "node_id": 1,
      "node_name": "HK-Node-1",
      "token": "share-token-abc123",
      "max_bandwidth": 107374182400,
      "expiry_time": 1767225600000,
      "port_range_start": 10000,
      "port_range_end": 20000,
      "allowed_domains": "example.com,api.example.com",
      "allowed_ips": "10.0.0.0/8,192.168.0.0/16",
      "status": 1,
      "created_at": 1706659200000
    }
  ]
}

POST /api/v1/federation/share/create

Create a peer share (share a node with another panel).

Request:

{
  "name": "Share-to-Partner",
  "nodeId": 1,
  "maxBandwidth": 107374182400,
  "expiryTime": 1767225600000,
  "portRangeStart": 10000,
  "portRangeEnd": 20000,
  "allowedDomains": "example.com,api.example.com",
  "allowedIps": "10.0.0.0/8,192.168.0.0/16"
}

Fields:

Field	Type	Required	Description
name	string	Yes	Share name
nodeId	number	Yes	Node to share
maxBandwidth	number	No	Max traffic in bytes (0 = unlimited)
expiryTime	number	No	Expiry timestamp in ms (0 = never)
portRangeStart	number	No	Allowed port range start
portRangeEnd	number	No	Allowed port range end
allowedDomains	string	No	Comma-separated domains
allowedIps	string	No	Comma-separated IPs/CIDRs

Response:

{
  "code": 0,
  "data": {
    "id": 1,
    "token": "share-token-abc123"
  }
}

The token is what the remote panel uses to connect.

POST /api/v1/federation/share/update

Update a peer share.

Request: Same as create, with id field required.

POST /api/v1/federation/share/delete

Delete a peer share.

Request:

{"id": 1}

POST /api/v1/federation/share/reset-flow

Reset traffic counter for a share.

Request:

{"id": 1}

POST /api/v1/federation/share/remote-usage/list

List remote node usage statistics.

Request: {}

---

Federation Runtime (Peer-to-Peer)

These endpoints use Bearer token authentication (different from JWT).

POST /api/v1/federation/connect

Connect to a remote panel and get share info.

Headers:

Authorization: Bearer <share-token>

Request: {}

Response:

{
  "code": 0,
  "data": {
    "nodeName": "HK-Node-1",
    "allowedPorts": [10000, 20000],
    "allowedDomains": ["example.com"],
    "allowedIps": ["10.0.0.0/8"]
  }
}

POST /api/v1/federation/tunnel/create

Create a federation tunnel on the remote node.

Headers:

Authorization: Bearer <share-token>

Request:

{
  "tunnelId": 1,
  "role": "entry"
}

POST /api/v1/federation/runtime/reserve-port

Reserve a port on the remote node.

Request:

{
  "port": 15000,
  "tunnelId": 1
}

POST /api/v1/federation/runtime/apply-role

Apply for a role (entry/chain/exit) on the remote node.

Request:

{
  "tunnelId": 1,
  "role": "exit"
}

POST /api/v1/federation/runtime/release-role

Release a role on the remote node.

Request:

{
  "tunnelId": 1
}

POST /api/v1/federation/runtime/diagnose

TCP ping diagnostics from remote node to target.

Request:

{
  "target": "10.0.0.1:80"
}

POST /api/v1/federation/runtime/command

Execute a command on the remote node.

Request:

{
  "command": "status"
}

---

Node Import (Admin)

POST /api/v1/federation/node/import

Import a remote node from another panel.

Request:

{
  "name": "Remote-HK-Node",
  "remoteUrl": "https://other-panel.example.com",
  "remoteToken": "share-token-abc123"
}

This creates a node with is_remote: 1.

---

Workflow: Share Node with Another Panel

On the sharing panel (Panel A):

# 1. Create a share
SHARE_RESP=$(curl -s -X POST "${FLVX_BASE_URL}/api/v1/federation/share/create" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Share-HK-Node",
    "nodeId": 1,
    "portRangeStart": 10000,
    "portRangeEnd": 20000,
    "allowedIps": "0.0.0.0/0"
  }')

SHARE_TOKEN=$(echo "$SHARE_RESP" | jq -r '.data.token')
echo "Share Token: $SHARE_TOKEN"
echo "Panel URL: ${FLVX_BASE_URL}"

On the receiving panel (Panel B):

# 2. Import the remote node
curl -s -X POST "${FLVX_BASE_URL}/api/v1/federation/node/import" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Remote-HK-Node",
    "remoteUrl": "https://panel-a.example.com",
    "remoteToken": "share-token-abc123"
  }'

# 3. Use the remote node in tunnels like a local node
curl -s -X POST "${FLVX_BASE_URL}/api/v1/tunnel/create" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Federated-Tunnel",
    "type": 1,
    "inNodeId": [1],
    "outNodeId": [2]
  }'