1350 lines
31 KiB
Markdown
1350 lines
31 KiB
Markdown
# 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:**
|
|
- 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" |
|
|
|
|
---
|
|
|
|
## 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"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 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_user_my_frpc.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_user_my_frpc.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_user_new_frpc_name.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_user_new_frpc_name.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_user_my_frpc.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
|
|
|
|
---
|
|
|
|
## 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_user_my_frpc.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:** None (any permission level)
|
|
|
|
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"
|
|
},
|
|
{
|
|
"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:** Admin
|
|
|
|
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 (admin/superuser):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "instances retrieved successfully",
|
|
"data": [
|
|
{
|
|
"instanceID": 1,
|
|
"name": "my_frpc",
|
|
"serverAddr": "127.0.0.1",
|
|
"serverPort": "7000",
|
|
"auth_method": "token",
|
|
"bootAtStart": true,
|
|
"runUser": "root",
|
|
"configPath": "./configs/superfrpc_user_my_frpc.toml",
|
|
"createdAt": "2024-01-01T00:00:00Z",
|
|
"createdBy": "admin"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**Response (visitor):**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"message": "instances retrieved successfully",
|
|
"data": [
|
|
{
|
|
"instanceID": 1,
|
|
"name": "my_frpc",
|
|
"bootAtStart": true,
|
|
"runUser": "root",
|
|
"configPath": "./configs/superfrpc_user_my_frpc.toml",
|
|
"createdAt": "2024-01-01T00:00:00Z",
|
|
"createdBy": "admin"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| instanceID | int | Instance ID |
|
|
| name | string | Instance name |
|
|
| serverAddr | string | frps server address (admin/superuser only) |
|
|
| serverPort | string | frps server port (admin/superuser only) |
|
|
| auth_method | string | Authentication method (admin/superuser only) |
|
|
| bootAtStart | bool | Auto-start on system boot |
|
|
| runUser | string | User to run the frpc instance as |
|
|
| configPath | string | Path to the configuration file |
|
|
| createdAt | string | Instance creation time (ISO 8601 format) |
|
|
| createdBy | string | Username of the user who created this instance |
|
|
|
|
> Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).
|
|
|
|
---
|
|
|
|
## Real-time 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);
|
|
};
|
|
```
|
|
---
|
|
|
|
## User Permissions
|
|
|
|
| Permission | superuser | admin | visitor |
|
|
|------------|-----------|-------|---------|
|
|
| Create instance | ✓ | ✓ | ✗ |
|
|
| Delete instance | ✓ | ✓ | ✗ |
|
|
| Modify instance | ✓ | ✓ | ✗ |
|
|
| List instances | ✓ | ✓ | ✓ (limited) |
|
|
| Manage users | ✓ | ✗ | ✗ |
|
|
| List active sessions | ✓ | ✓ | ✗ |
|
|
| View logs | ✓ | ✓ | ✓ |
|
|
|
|
---
|
|
|
|
## 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_<username>_<instanceName>.toml
|
|
```
|
|
|
|
Example: `superfrpc_admin_my_frpc.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.
|