Super-frpc/backend

Fork 0

Files

NanamiAdmin 933c12fca1 feat(system): add restart server endpoint with authentication

2026-05-10 18:09:49 +08:00

43 KiB

Raw Blame History

API Documentation

All API responses are returned in JSON format:

Success Response:

{
  "success": true,
  "message": "success message",
  "data": { ... }
}

Error Response:

{
  "success": false,
  "message": "error message"
}

Important Notes:

All endpoints are relative to the base URL /api
For all requests: Authentication token and timestamp are sent in HTTP headers (prefixed with X-)
For POST requests: Other data is sent in the request body as JSON
For GET requests: All data is sent in HTTP headers (prefixed with X-)
All requests require authentication (except /register, /login, /system/getStatus, /system/getSoftwareInfo)
Timestamps are in milliseconds (Unix timestamp)

Get System Status

Endpoint: /system/getStatus
Method: GET
Auth Required: No
Permission Level: None

Get the current system status.

Response:

{
  "success": true,
  "message": "getStatus",
  "data": {
    "Status": "Online"
  }
}

Field	Type	Description
Status	string	System status: "Online" or "Offline"

Get Software Info

Endpoint: /system/getSoftwareInfo
Method: GET
Auth Required: No
Permission Level: None

Get software version and build information.

Response:

{
  "success": true,
  "message": "getSoftwareInfo",
  "data": {
    "Name": "Super-frpc",
    "Version": "0.0.1",
    "Developer": "Madobi Nanami",
    "BuildVer": 1,
    "Description": "",
    "BuildType": "debug"
  }
}

Field	Type	Description
Name	string	Software name
Version	string	Software version
Developer	string	Developer name
BuildVer	int16	Build version number
Description	string	Software description
BuildType	string	Build type: "debug" or "release"

Self Check

Endpoint: /system/selfCheck
Method: POST
Content-Type: application/json Permission Level: Visitor

Check the system configuration and frpc binary.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response (Success):

{
  "success": true,
  "message": "Self check passed"
}

If there were any errors, the response will be in error format.

Response (Error):

{
  "success": false,
  "message": "error message"
}

Restart Server

Endpoint: /system/restart Method: GET Permission Level: Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Restarting server..."
}

Register User

Endpoint: /register
Method: POST
Content-Type: application/json Permission Level: None

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "username": "your_username",
  "passwd": "YourPass123!"
}

Header	Type	Required	Description
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
username	string	Yes	Username (no special characters)
passwd	string	Yes	Password (must contain uppercase, lowercase, digit, and special character, min 8 chars)
type	string	No	User type: superuser, admin, visitor (default: visitor)

Response:

{
  "success": true,
  "message": "user registered successfully",
  "data": {
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}

New user only can register as visitor, superuser and admin need to contact the administrator to apply.

Endpoint: /login
Method: POST
Content-Type: application/json
Permission Level: None

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "username": "your_username",
  "passwd": "YourPass123!"
}

Header	Type	Required	Description
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
username	string	Yes	Username
passwd	string	Yes	Password

Response:

{
  "success": true,
  "message": "login successful",
  "data": {
    "token": "xxxxxxxxxxxxx",
    "userID": 1,
    "username": "your_username",
    "type": "admin"
  }
}

Logout

Endpoint: /logout
Method: GET
Auth Required: Yes (token) Permission Level: None

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Logout successful"
}

Create User

Endpoint: /userMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "username": "new_user",
  "passwd": "NewPass123!",
  "type": "admin"
}

Response:

{
  "success": true,
  "message": "User created successfully",
  "data": {
    "userID": 2,
    "username": "new_user",
    "type": "admin"
  }
}

Remove User

Endpoint: /userMgr/remove
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "targetUserID": 2
}

Response:

{
  "success": true,
  "message": "User removed successfully"
}

Modify User

Endpoint: /userMgr/modify Method: POST Content-Type: application/json Auth Required: Yes (token)
Permission Level: visitor

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "userID": 1,
  "username": "user123",
  "passwd": "NewPass123!"
}

Response:

{
  "success": true,
  "message": "User updated successfully"
}

Modify User Type

Endpoint: /userMgr/modifyType
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "userID": 2,
  "newType": "superadmin"
}

Response:

{
  "success": true,
  "message": "User type updated successfully"
}

List Users

Endpoint: /userMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Response:

{
  "success": true,
  "message": "User list retrieved successfully",
  "data": [
    {
      "UserID": 1,
      "Username": "admin",
      "Passwd": "",
      "Type": "superuser",
      "CreatedAt": "2024-01-01 12:00:00"
    },
    {
      "UserID": 2,
      "Username": "new_user",
      "Passwd": "",
      "Type": "admin",
      "CreatedAt": "2024-01-02 14:30:00"
    }
  ]
}

Field	Type	Description
UserID	int	User ID
Username	string	Username
Type	string	User type: superuser, admin, visitor
CreatedAt	string	User creation time (YYYY-MM-DD HH:MM:SS format)

List Active Sessions

Endpoint: /sessionMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Superuser, Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Active sessions listed",
  "data": [
    {
      "ID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000",
      "UserID": 1,
      "Username": "admin",
      "ExpireAt": "2024-01-01T01:00:00Z"
    },
    {
      "ID": "session-7c6a180b36896a0a8c010710c0780347-1704067210000",
      "UserID": 2,
      "Username": "new_user",
      "ExpireAt": "2024-01-01T01:00:10Z"
    }
  ]
}

Field	Type	Description
ID	string	Unique session ID
UserID	int	User ID
Username	string	Username
ExpireAt	string	Session expiration time (ISO 8601 format)

Remove Session

Endpoint: /sessionMgr/remove
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "sessionID": "session-5f4dcc3b5aa765d61d8327deb882cf99-1704067200000"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
sessionID	string	Yes	Session ID to remove

Response:

{
  "success": true,
  "message": "Session removed successfully"
}

Note

: This endpoint requires superuser permission. It removes a session by its sessionID and also removes the associated token, forcing the user to re-login.

Create frpc Instance

Endpoint: /frpcAct/instanceMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceInfo": {
    "name": "my_frpc",
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token"
  },
  "bootAtStart": true,
  "runUser": "root",
  "additionalProperties": {
    "pool_count": 5
  }
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceInfo.name	string	Yes	Instance name
instanceInfo.serverAddr	string	Yes	frps server address
instanceInfo.serverPort	string	Yes	frps server port
instanceInfo.auth_method	string	Yes	Authentication method
bootAtStart	bool	No	Auto-start on system boot (default: false)
runUser	string	No	Run as user (default: root)
additionalProperties	object	No	Additional frpc configuration

Response:

{
  "success": true,
  "message": "instance created successfully",
  "data": {
    "name": "my_frpc",
    "configPath": "./configs/superfrpc_1.toml",
    "bootAtStart": true
  }
}

Delete frpc Instance

Endpoint: /frpcAct/instanceMgr/delete
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)

Response:

{
  "success": true,
  "message": "instance deleted successfully",
  "data": {
    "instanceID": 1,
    "name": "my_frpc"
  }
}

Field	Type	Description
instanceID	int	Instance ID
name	string	Name of the deleted frpc instance

Modify frpc Instance

Endpoint: /frpcAct/instanceMgr/modify
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Modify instance configuration. Supports two modification types: configFile (modify frpc config file) and systemConfig (modify system-level settings).

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Type 1: Modify Config File (configFile)

Modify fields in the [common] section of the frpc configuration file. Only [common] section fields can be modified, [[proxies]] sections will not be affected.

Request Body:

{
  "instanceID": "1",
  "type": "configFile",
  "modifiedData": {
    "server_addr": "192.168.1.1",
    "server_port": "7000",
    "auth.method": "token",
    "auth.token": "my_secret_token"
  }
}

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
type	string	Yes	Modification type: `configFile` or `systemConfig`
modifiedData	object	Yes	Key-value pairs of fields to modify in `[common]` section

Response:

{
  "success": true,
  "message": "Config file modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml"
  }
}

Type 2: Modify System Config (systemConfig)

Modify system-level settings such as instance name, boot-at-start configuration, and run user. These changes will also update the operating system service configuration.

Request Body:

{
  "instanceID": "1",
  "type": "systemConfig",
  "modifiedData": {
    "name": "new_frpc_name",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
type	string	Yes	Modification type: `configFile` or `systemConfig`
modifiedData.name	string	No	New instance name (renames config file if changed)
modifiedData.bootAtStart	bool	No	Auto-start on system boot
modifiedData.runUser	string	No	User to run the frpc instance as

Response:

{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml",
    "bootAtStart": true,
    "runUser": "www-data"
  }
}

Response with bootServiceError (when boot service operations fail):

{
  "success": true,
  "message": "System config modified successfully",
  "data": {
    "instanceName": "new_frpc_name",
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml",
    "bootAtStart": true,
    "runUser": "www-data",
    "bootServiceError": "Failed to create boot service: unsupported init system"
  }
}

Note about bootServiceError:

The bootServiceError field appears in the response when boot service operations (create/remove) fail

This field is only present when there is an error; it will not be included in the response if operations succeed

The overall request still returns success: true because the system config modification (database update, config file rename, etc.) succeeded

Common scenarios where bootServiceError may appear:

Enabling bootAtStart when the init system is not supported (e.g., on Windows or systems without systemd/init.d)

Disabling bootAtStart when the service file cannot be removed due to permission issues

Changing instance name or run user when bootAtStart is enabled (requires removing old service and creating new one)

The error message provides detailed information about what went wrong, which should be displayed to the user

Frontend applications should check for this field and display the error message to the user, even though the request was technically successful

Start frpc Instance

Endpoint: /frpcAct/instanceMgr/start
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Start a frpc instance. The instance can be started as a background process on Windows (hidden window) or as a systemd/init.d service on Linux.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	ID of the instance to start

Response (Windows):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance started successfully",
  "data": {}
}

Stop frpc Instance

Endpoint: /frpcAct/instanceMgr/stop
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Stop a running frpc instance. On Windows, this stops the frpc process. On Linux, this stops the systemd/init.d service.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	ID of the instance to stop

Response (Windows):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance stopped successfully",
  "data": {}
}

Restart frpc Instance

Endpoint: /frpcAct/instanceMgr/restart
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Restart a frpc instance. This stops and then starts the instance again.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	ID of the instance to restart

Response (Windows):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

Response (Linux systemd):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

Response (Linux init.d):

{
  "success": true,
  "message": "Instance restarted successfully",
  "data": {}
}

Get frpc Instance Status

Endpoint: /frpcAct/instanceMgr/status
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Check the running status of a frpc instance.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Query Parameters:

instanceID=1

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Parameter	Type	Required	Description
instanceID	string	Yes	ID of the instance to check

Response (running):

{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": true
  }
}

Response (stopped):

{
  "success": true,
  "message": "Instance status retrieved successfully",
  "data": {
    "name": "my_frpc",
    "initSystem": "systemd",
    "serviceName": "superfrpc_admin_my_frpc",
    "isRunning": false
  }
}

Field	Type	Description
name	string	Name of the frpc instance
initSystem	string	Operating system init system: "windows", "systemd", or "init.d"
serviceName	string	Service name (Linux only)
isRunning	boolean	Instance running status: true (running) or false (stopped)

Create Proxy

Endpoint: /frpcAct/proxyMgr/create
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Create a new proxy configuration for an existing frpc instance. The proxy configuration will be appended to the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1",
  "proxyInfo": {
    "name": "ssh_proxy",
    "type": "tcp",
    "localIP": "127.0.0.1",
    "localPort": "22",
    "remotePort": "6000"
  }
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
proxyInfo.name	string	Yes	Proxy name
proxyInfo.type	string	Yes	Proxy type (e.g., tcp, udp, http, https)
proxyInfo.localIP	string	Yes	Local IP address to forward to
proxyInfo.localPort	string	Yes	Local port to forward from
proxyInfo.remotePort	string	Yes	Remote port on frps to expose

Response:

{
  "success": true,
  "message": "Proxy created successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the created proxy

Config File Format:

The proxy configuration will be appended to the instance's config file in the following format:

[[proxies]]
name = ssh_proxy
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6000

Note:

The proxy configuration is appended to the existing config file

The instance must already exist before creating a proxy

This endpoint does not modify the database, only the config file

The frpc service needs to be restarted for changes to take effect

Modify Proxy

Endpoint: /frpcAct/proxyMgr/modify
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Modify an existing proxy configuration for an frpc instance. The proxy configuration will be updated in the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1",
  "proxyInfo": {
    "oldName": "ssh_proxy",
    "newName": "ssh_proxy123",
    "type": "tcp",
    "localIP": "127.0.0.1",
    "localPort": "22",
    "remotePort": "6001"
  }
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
proxyInfo.oldName	string	Yes	Proxy old name (used to identify which proxy to modify)
proxyInfo.newName	string	Yes	Proxy new name (used to identify which proxy to modify to)
proxyInfo.type	string	Yes	Proxy type (e.g., tcp, udp, http, https)
proxyInfo.localIP	string	Yes	Local IP address to forward to
proxyInfo.localPort	string	Yes	Local port to forward from
proxyInfo.remotePort	string	Yes	Remote port on frps to expose

Response:

{
  "success": true,
  "message": "Proxy modified successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml",
    "proxyName": "ssh_proxy123"
  }
}

Field	Type	Description
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the modified proxy

Config File Format:

The proxy configuration in the config file will be updated to the following format:

[[proxies]]
name = ssh_proxy123
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = 6001

Note:

The proxy configuration is updated in the existing config file

The instance must already exist before modifying a proxy

This endpoint does not modify the database, only the config file

The frpc service needs to be restarted for changes to take effect

The proxy name is used to identify which proxy to modify; if the proxy is not found, an error will be returned

Delete Proxy

Endpoint: /frpcAct/proxyMgr/delete
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Admin

Delete an existing proxy configuration from an frpc instance. The proxy configuration will be removed from the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceID": "1",
  "proxyName": "ssh_proxy"
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Field	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)
proxyName	string	Yes	Name of the proxy to delete

Response:

{
  "success": true,
  "message": "Proxy deleted successfully",
  "data": {
    "instanceID": 1,
    "configPath": "./configs/superfrpc_1.toml",
    "proxyName": "ssh_proxy"
  }
}

Field	Type	Description
instanceID	int	Instance ID
configPath	string	Path to the configuration file
proxyName	string	Name of the deleted proxy

Note:

The proxy configuration is removed from the existing config file

The instance must already exist before deleting a proxy

This endpoint does not modify the database, only the config file

The frpc service needs to be restarted for changes to take effect

List Proxies

Endpoint: /frpcAct/proxyMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Retrieve a list of all proxy configurations for a specific frpc instance. The proxy configurations are read from the instance's config file.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Query Parameters:

?instanceID=1

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Parameter	Type	Required	Description
instanceID	string	Yes	Instance ID (the ID of the frpc instance)

Response:

{
  "success": true,
  "message": "Proxies listed successfully",
  "data": {
    "instanceID": 1,
    "proxyCount": 2,
    "proxies": [
      {
        "name": "ssh_proxy",
        "type": "tcp",
        "localIP": "127.0.0.1",
        "localPort": "22",
        "remotePort": "6000"
      },
      {
        "name": "web_proxy",
        "type": "http",
        "localIP": "127.0.0.1",
        "localPort": "8080",
        "remotePort": "80"
      }
    ]
  }
}

Field	Type	Description
instanceID	int	Instance ID
proxyCount	int	Number of proxies
proxies	array	List of proxy configurations

Proxy Object:

Field	Type	Description
name	string	Proxy name
type	string	Proxy type (e.g., tcp, udp, http, https)
localIP	string	Local IP address to forward to
localPort	string	Local port to forward from
remotePort	string	Remote port on frps to expose

Note:

The proxy configurations are read from the existing config file

This endpoint does not modify the database, only reads the config file

The returned proxy list represents the current configuration in the file

Changes to the config file will be reflected in subsequent requests

List frpc Instances

Endpoint: /frpcAct/instanceMgr/list
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Retrieve a list of all frpc instances on the server.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "instances retrieved successfully",
  "data": [
    {
      "instanceID": 1,
      "name": "my_frpc",
      "createdAt": "2024-01-01T00:00:00Z",
      "createdBy": "admin",
      "isRunning": true
    }
  ]
}

Field	Type	Description
instanceID	int	Instance ID
name	string	Instance name
createdAt	string	Instance creation time (ISO 8601 format)
createdBy	string	Username of the user who created this instance
isRunning	bool	Instance running status: true (running) or false (stopped)

Get frpc Instance Information

Endpoint: /frpcAct/instanceMgr/getInfo
Method: GET
Auth Required: Yes (token)
Permission Level: Visitor

Retrieve information about a specific frpc instance.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Query Parameters:

instanceID=1

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Parameter	Type	Required	Description
instanceID	string	Yes	ID of the instance to get information for

Response (Admin/Superuser):

{
  "success": true,
  "message": "Instance info retrieved successfully",
  "data": {
    "name": "my_frpc",
    "serviceName": "superfrpc_1",
    "createdAt": "2024-01-01T00:00:00Z",
    "createdBy": "admin",
    "isRunning": true,
    "serverAddr": "127.0.0.1",
    "serverPort": "7000",
    "auth_method": "token",
    "bootAtStart": true,
    "runUser": "root",
    "configPath": "./configs/superfrpc_1.toml"
  }
}

Response (Visitor):

{
  "success": true,
  "message": "Instance info retrieved successfully",
  "data": {
    "name": "my_frpc",
    "serviceName": "superfrpc_1",
    "createdAt": "2024-01-01T00:00:00Z",
    "createdBy": "admin",
    "isRunning": true,
    "auth_method": "token",
    "bootAtStart": true,
    "runUser": "root",
    "configPath": "./configs/superfrpc_1.toml"
  }
}

Field	Type	Description
name	string	Name of the frpc instance
serviceName	string	Service name
createdAt	string	Instance creation time (ISO 8601 format)
createdBy	string	Username of the user who created this instance
isRunning	bool	Instance running status: true (running) or false (stopped)
serverAddr	string	frps server address (only returned for admin/superuser)
serverPort	string	frps server port (only returned for admin/superuser)
auth_method	string	Authentication method
bootAtStart	bool	Whether the instance starts automatically on system boot
runUser	string	User that the instance runs as
configPath	string	Path to the instance's configuration file

Real-time System Log Streaming (WebSocket)

Endpoint: /system/getLogs
Protocol: WebSocket
Auth Required: Yes (token)
Permission Level: None

Establish a WebSocket connection to receive real-time log streaming from the server.

Connection

Connect to ws://localhost:8080/system/getLogs (or wss:// for secure connection).

Query Parameters:

token: Authentication token (optional, for tracking which user is viewing logs)

Example:

ws://localhost:8080/logs?token=your_token_here

Message Format

Logs are sent as JSON messages with the following structure:

{
  "level": 1,
  "content": "Log message content",
  "timestamp": "2024-01-01 12:00:00.000"
}

Field	Type	Description
level	int	Log level: 0=DEBUG, 1=INFO, 2=WARNING, 3=ERROR, 4=FATAL
content	string	Log message content
timestamp	string	Log timestamp (YYYY-MM-DD HH:MM:SS.mmm format)

Log Levels

Level	Name	Description
0	DEBUG	Debug messages (only visible when debug mode is enabled)
1	INFO	Informational messages
2	WARNING	Warning messages
3	ERROR	Error messages
4	FATAL	Fatal/critical messages

Behavior

On Connection: The server immediately sends the last 100 log entries
Streaming: All new log entries are pushed in real-time to all connected clients
Multi-client: Multiple clients can connect simultaneously and receive the same log stream
History: Only the most recent 100 log entries are kept in memory

Example Usage (JavaScript)

const socket = new WebSocket('ws://localhost:8080/logs?token=your_token');

socket.onopen = () => {
  console.log('Connected to log server');
};

socket.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.timestamp}] ${log.content}`);
  
  // Log level example
  const levels = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'FATAL'];
  console.log(`[${levels[log.level]}] ${log.content}`);
};

socket.onclose = () => {
  console.log('Disconnected from log server');
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

Real-time frpc Instance Log Streaming (WebSocket)

Endpoint: /frpcAct/instanceMgr/logs
Method: GET
Protocol: WebSocket
Auth Required: Yes (token)
Permission Level: Visitor

Stream real-time logs from a frpc instance via WebSocket connection. This endpoint upgrades the HTTP connection to WebSocket and streams log messages in real-time.

Request:

ws://host:port/frpcAct/instanceMgr/logs?instanceID=1&token=your_token

Query Parameters:

Parameter	Type	Required	Description
instanceID	int	Yes	ID of the instance to stream logs from
token	string	Yes	Authentication token

WebSocket Message Format:

Log messages are sent as JSON objects:

{
  "level": "INFO",
  "content": "[I] [service.go:XXX] start frpc success",
  "timestamp": "2024-01-01 12:00:00.000"
}

Field	Type	Description
level	string	Log level: "DEBUG", "INFO", "WARN", "ERROR"
content	string	Log message content
timestamp	string	Timestamp in "YYYY-MM-DD HH:MM:SS.mmm" format

Error Response (before WebSocket upgrade):

{
  "success": false,
  "message": "Instance not found"
}

Common Error Messages:

HTTP Status	Message	Description
400	"instanceID is required"	Missing instanceID parameter
400	"invalid instanceID format"	instanceID is not a valid integer
401	"Token is required"	Missing token parameter
401	"Invalid token: ..."	Token validation failed
401	"User not found"	User associated with token does not exist
403	"You don't have access to this instance"	Instance belongs to another user
404	"Instance not found"	Instance with given ID does not exist
500	"Failed to get service name"	Internal server error

Platform-Specific Behavior:

Platform	Init System	Log Source
Windows	sc	Config file (if `log_file` is set) or Windows Event Log
Linux	systemd	`journalctl -u <service> -f`
Linux	init.d	Log files in `/var/log/` or service status monitoring

Connection Lifecycle:

Client initiates WebSocket connection with instanceID and token
Server validates token and instance ownership
Server upgrades connection to WebSocket
Server starts streaming logs
Connection remains open until client disconnects or error occurs
Server sends log messages as they become available

Notes:

Only the instance owner can access the logs (user must own the instance)
The connection will be closed if the token expires during the session
On Windows, if no log file is configured, the service status is monitored instead
On Linux init.d systems, log files are searched in common locations (/var/log/, etc.)
Log streaming is real-time; historical logs may be sent initially depending on the platform

Get Settings

Endpoint: /system/settings/get
Method: GET
Auth Required: Yes (token)
Permission Level: Superuser, Admin

Get system settings. If no key parameter is provided, returns all settings. If key is provided, returns only that specific setting.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Query Parameters (optional):

key=ListenAddr

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Parameter	Type	Required	Description
key	string	No	Specific setting key to retrieve

Response (all settings):

{
  "success": true,
  "message": "Settings retrieved successfully",
  "data": {
    "ListenAddr": "0.0.0.0",
    "ListenPort": "8080",
    "FrpcPath": "/usr/bin/frpc",
    "InstancePath": "./configs",
    "Debug": true,
    "Watchdog.Enabled": true,
    "Notification.Enabled": true,
    "Notification.Method": "webhook",
    "Webhook.Method": "POST",
    "Webhook.URL": "https://example.com/webhook",
    "Webhook.Headers": "Content-Type: application/json",
    "Webhook.Body": "{\"subject\":\"Super-frpc Alert - {{ exceptionType }}\",\"text\":\"Super-frpc Alert\",\"html\":\"{{ serviceName }} - {{ exceptionMsg }}\"}"
  }
}

Response (single setting):

{
  "success": true,
  "message": "Setting retrieved successfully",
  "data": {
    "key": "ListenAddr",
    "value": "0.0.0.0"
  }
}

Error Response (unknown key):

{
  "success": false,
  "message": "Unknown setting key: InvalidKey"
}

Set Settings

Endpoint: /system/settings/set
Method: POST
Content-Type: application/json
Auth Required: Yes (token)
Permission Level: Superuser, Admin

Update system settings. Multiple settings can be updated in a single request.

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "ListenAddr": "127.0.0.1",
  "ListenPort": "9090",
  "Debug": false
}

Header	Type	Required	Description
X-Token	string	Yes	Authentication token
X-Timestamp	int64	Yes	Client timestamp in milliseconds

Response:

{
  "success": true,
  "message": "Config saved successfully"
}

Error Response:

{
  "success": false,
  "message": "Failed to save config"
}

Note: Settings are saved to the config file immediately after update. Unknown keys will be logged as warnings but will not cause the request to fail.

User Permissions

Permission	superuser	admin	visitor
Create instance	✓	✓	✗
Delete instance	✓	✓	✗
Modify instance	✓	✓	✗
List instances	✓	✓	✓ (limited)
Manage users	✓	✗	✗
List active sessions	✓	✓	✗
View logs	✓	✓	✓
Change settings	✓	✓	✗
Get settings	✓	✓	✗

Timestamp Validation

All requests include a timeStamp field (Unix timestamp in milliseconds). The server validates that the timestamp is within ±3000ms of the server time. This prevents replay attacks.

Password Requirements

Passwords must meet the following complexity requirements:

At least 8 characters
At least one uppercase letter (A-Z)
At least one lowercase letter (a-z)
At least one digit (0-9)
At least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?)

Token

Tokens are valid for 1 hour. After expiration, users need to re-login to get a new token.

Generated Config Files

Instance configuration files are saved in the specified instancePath with the naming convention:

superfrpc_<instanceID>.toml

Example: superfrpc_1.toml

Error Codes

Code	Message	Description
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
500	Internal Server Error	Server internal error

Rate Limiting

The API implements rate limiting to prevent abuse:

Login attempts: Maximum 5 attempts per minute per IP
All other endpoints: 100 requests per minute per token

Exceeding rate limits will result in temporary IP or token blocking.

Notification

Available notification methods

Method	Description
`webhook`	Webhook notification

Replacable parameters

Parameter	Description
`{{ exceptionType }}`	Type of exception that triggered the notification
`{{ serviceName }}`	Name of the service that experienced the exception
`{{ exceptionMsg }}`	Detailed exception message

43 KiB Raw Blame History

API Documentation

Get System Status

Get Software Info

Self Check

Restart Server

Register User

Login

Logout

Create User

Remove User

Modify User

Modify User Type

List Users

List Active Sessions

Remove Session

Create frpc Instance

Delete frpc Instance

Modify frpc Instance

Type 1: Modify Config File (configFile)

Type 2: Modify System Config (systemConfig)

Start frpc Instance

Stop frpc Instance

Restart frpc Instance

Get frpc Instance Status

Create Proxy

Modify Proxy

Delete Proxy

List Proxies

List frpc Instances

Get frpc Instance Information

Real-time System Log Streaming (WebSocket)

Connection

Message Format

Log Levels

Behavior

Example Usage (JavaScript)

Real-time frpc Instance Log Streaming (WebSocket)

Get Settings

Set Settings

User Permissions

Timestamp Validation

Password Requirements

Token

Generated Config Files

Error Codes

Rate Limiting

Notification

43 KiB

Raw Blame History