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

Forward Management API

Forwards are port forwarding rules created by users on their assigned tunnels.

POST /api/v1/forward/list

List forwards. Non-admin users see only their own forwards.

Request:

{
  "page": 1,
  "pageSize": 20,
  "keyword": "",
  "status": -1
}

status filter:

• -1 = All
• 0 = Paused
• 1 = Running

Response:

{
  "code": 0,
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 2,
        "tunnel_id": 1,
        "tunnel_name": "HK-US-Tunnel",
        "name": "my-web-server",
        "in_port": 10001,
        "remote_addr": "192.168.1.100:80",
        "strategy": "fifo",
        "status": 1,
        "speed_id": 0,
        "speed_name": "",
        "in_flow": 1073741824,
        "out_flow": 2147483648,
        "created_at": 1706659200000,
        "updated_at": 1706659200000
      }
    ],
    "total": 1
  }
}

POST /api/v1/forward/create

Create a new forward.

Request:

{
  "name": "my-web-server",
  "tunnelId": 1,
  "remoteAddr": "192.168.1.100:80",
  "strategy": "fifo",
  "inPort": 0,
  "speedId": 0
}

Fields:

Field	Type	Required	Description
name	string	Yes	Forward name
tunnelId	number	Yes	Tunnel to use
remoteAddr	string	Yes	Target address(es), comma-separated for load balancing
strategy	string	No	"fifo" or "round" (default: "fifo")
inPort	number	No	Entry port (0 = auto-assign)
speedId	number	No	Speed limit rule ID (0 = no limit)

Strategy:

• fifo = First target only
• round = Round-robin load balancing across targets

Remote Address Format:

• Single: 192.168.1.100:80
• Multiple: 192.168.1.100:80,192.168.1.101:80,192.168.1.102:80

Response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 1,
    "in_port": 10001
  }
}

POST /api/v1/forward/update

Update forward settings.

Request: Same as create, with id field required.

{
  "id": 1,
  "name": "my-web-server-updated",
  "remoteAddr": "192.168.1.100:8080",
  "strategy": "round",
  "speedId": 2
}

POST /api/v1/forward/delete

Delete a forward.

Request:

{"id": 1}

POST /api/v1/forward/force-delete

Force delete a forward (even if in use).

Request:

{"id": 1}

POST /api/v1/forward/pause

Pause a forward (stops traffic but keeps configuration).

Request:

{"id": 1}

Response:

{"code": 0, "msg": "success"}

POST /api/v1/forward/resume

Resume a paused forward.

Request:

{"id": 1}

POST /api/v1/forward/diagnose

Diagnose forward connectivity (TCP ping to target).

Request:

{"id": 1}

Response:

{
  "code": 0,
  "data": {
    "reachable": true,
    "latency_ms": 15,
    "error": ""
  }
}

POST /api/v1/forward/update-order

Reorder forwards.

Request:

{
  "orders": [
    {"id": 1, "order": 0},
    {"id": 2, "order": 1}
  ]
}

Batch Operations

POST /api/v1/forward/batch-delete

{"ids": [1, 2, 3]}

POST /api/v1/forward/batch-pause

{"ids": [1, 2, 3]}

POST /api/v1/forward/batch-resume

{"ids": [1, 2, 3]}

POST /api/v1/forward/batch-redeploy

Recreate forwarding services on nodes.

{"ids": [1, 2, 3]}

POST /api/v1/forward/batch-change-tunnel

Move forwards to a different tunnel.

{
  "ids": [1, 2, 3],
  "tunnelId": 5
}

Traffic Units

Field	Unit	Notes
in_flow	Bytes	Upload traffic
out_flow	Bytes	Download traffic

Convert to GB: in_flow / 1073741824

Example: Create Forward with Load Balancing

# Create forward with 3 backend servers
curl -s -X POST "${FLVX_BASE_URL}/api/v1/forward/create" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-cluster",
    "tunnelId": 1,
    "remoteAddr": "10.0.0.1:80,10.0.0.2:80,10.0.0.3:80",
    "strategy": "round"
  }'

Example: Check Forward Status and Traffic

curl -s -X POST "${FLVX_BASE_URL}/api/v1/forward/list" \
  -H "Authorization: ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}' | jq '.data.list[] | {
    name,
    tunnel: .tunnel_name,
    entry_port: .in_port,
    target: .remote_addr,
    status: (if .status == 1 then "running" else "paused" end),
    upload_gb: (.in_flow / 1073741824 | floor),
    download_gb: (.out_flow / 1073741824 | floor)
  }'