Super-frpc/backend
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
8a5a647dcc8d2af74cd6a3d5267902f5bfe77bab
backend/docs/api.md

1899 lines
44 KiB
Markdown
Raw Blame History

# API Documentation
All API responses are returned in JSON format:
**Success Response:**
```json
{
"success": true,
"message": "success message",
"data": { ... }
}
```
**Error Response:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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):**
```json
{
"success": true,
"message": "Self check passed"
}
```
> If there were any errors, the response will be in error format.
**Response (Error):**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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.
---
## Login
**Endpoint:** `/login`
**Method:** POST
**Content-Type:** application/json
**Permission Level:** None
**Request Headers:**
```
X-Timestamp: 1704067200000
```
**Request Body:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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**:
```json
{
"username": "new_user",
"passwd": "NewPass123!",
"type": "admin"
}
```
**Response**:
```json
{
"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**:
```json
{
"targetUserID": 2
}
```
**Response**:
```json
{
"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**:
```json
{
"userID": 1,
"username": "user123",
"passwd": "NewPass123!"
}
```
**Response**:
```json
{
"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**:
```json
{
"userID": 2,
"newType": "superadmin"
}
```
**Response**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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**:
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:**
```json
{
"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):**
```json
{
"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:**
```json
{
"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):**
```json
{
"success": true,
"message": "Instance started successfully",
"data": {}
}
```
**Response (Linux systemd):**
```json
{
"success": true,
"message": "Instance started successfully",
"data": {}
}
```
**Response (Linux init.d):**
```json
{
"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:**
```json
{
"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):**
```json
{
"success": true,
"message": "Instance stopped successfully",
"data": {}
}
```
**Response (Linux systemd):**
```json
{
"success": true,
"message": "Instance stopped successfully",
"data": {}
}
```
**Response (Linux init.d):**
```json
{
"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:**
```json
{
"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):**
```json
{
"success": true,
"message": "Instance restarted successfully",
"data": {}
}
```
**Response (Linux systemd):**
```json
{
"success": true,
"message": "Instance restarted successfully",
"data": {}
}
```
**Response (Linux init.d):**
```json
{
"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):**
```json
{
"success": true,
"message": "Instance status retrieved successfully",
"data": {
"name": "my_frpc",
"initSystem": "systemd",
"serviceName": "superfrpc_admin_my_frpc",
"isRunning": true
}
}
```
**Response (stopped):**
```json
{
"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:**
```json
{
"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:**
```json
{
"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:
```toml
[[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:**
```json
{
"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:**
```json
{
"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:
```toml
[[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:**
```json
{
"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:**
```json
{
"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
---
## Proxy Switch
**Endpoint:** `/frpcAct/proxyMgr/switch`
**Method:** POST
**Auth Required:** Yes (token)
**Permission Level:** Admin
Switch the status of a proxy.
**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 |
**Request Body:**
```json
{
"instanceID": 1,
"proxyName": "test",
"action": 1
}
| Field | Type | Description |
|-------|------|-------------|
| instanceID | int | Instance ID |
| proxyName | string | Name of the created proxy |
| action | string | Enable or disable the current proxy. 0 is disable, 1 is enable |
**Response:**
```json
{
"success": true,
"message": "Proxy status has been switched to off."
}
```
---
## 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:**
```json
{
"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",
"enabled": true
},
{
"name": "web_proxy",
"type": "http",
"localIP": "127.0.0.1",
"localPort": "8080",
"remotePort": "80",
"enabled": false
}
]
}
}
```
| 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:**
```json
{
"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):**
```json
{
"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):**
```json
{
"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:
```json
{
"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
1. **On Connection**: The server immediately sends the last 100 log entries
2. **Streaming**: All new log entries are pushed in real-time to all connected clients
3. **Multi-client**: Multiple clients can connect simultaneously and receive the same log stream
4. **History**: Only the most recent 100 log entries are kept in memory
### Example Usage (JavaScript)
```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:
```json
{
"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):**
```json
{
"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:**
1. Client initiates WebSocket connection with `instanceID` and `token`
2. Server validates token and instance ownership
3. Server upgrades connection to WebSocket
4. Server starts streaming logs
5. Connection remains open until client disconnects or error occurs
6. 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):**
```json
{
"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):**
```json
{
"success": true,
"message": "Setting retrieved successfully",
"data": {
"key": "ListenAddr",
"value": "0.0.0.0"
}
}
```
**Error Response (unknown key):**
```json
{
"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:**
```json
{
"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:**
```json
{
"success": true,
"message": "Config saved successfully"
}
```
**Error Response:**
```json
{
"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 |
Reference in New Issue View Git Blame Copy Permalink