docs: move API documentation to separate file
Restructure documentation by moving API details from README.md to docs/api.md Update README.md to reference the new API documentation location
This commit is contained in:
@@ -49,465 +49,8 @@ GOOS=linux GOARCH=amd64 go build -o super-frpc
|
|||||||
|
|
||||||
## API Documentation
|
## API Documentation
|
||||||
|
|
||||||
All API responses are returned in JSON format:
|
For detailed API documentation, please see [docs/api.md](docs/api.md)
|
||||||
|
|
||||||
**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` and `/login`)
|
|
||||||
- Timestamps are in milliseconds (Unix timestamp)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Register User
|
|
||||||
|
|
||||||
**Endpoint:** `/register`
|
|
||||||
**Method:** POST
|
|
||||||
**Content-Type:** application/json
|
|
||||||
|
|
||||||
**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
|
|
||||||
|
|
||||||
**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)
|
|
||||||
|
|
||||||
**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"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
<<<<<<< HEAD
|
|
||||||
### Create frpc Instance
|
|
||||||
=======
|
|
||||||
### 3. Create frpc Instance
|
|
||||||
>>>>>>> 232e87ae368e0437f2f0d82f1d894741f4412ae0
|
|
||||||
|
|
||||||
**Endpoint:** `/frpcAct/instanceMgr/create`
|
|
||||||
**Method:** POST
|
|
||||||
**Content-Type:** application/json
|
|
||||||
**Auth Required:** Yes (token)
|
|
||||||
|
|
||||||
**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)
|
|
||||||
|
|
||||||
**Request Headers:**
|
|
||||||
```
|
|
||||||
X-Token: your_token
|
|
||||||
X-Timestamp: 1704067200000
|
|
||||||
```
|
|
||||||
|
|
||||||
**Request Body:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"instanceName": "my_frpc"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Response:**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "instance deleted successfully",
|
|
||||||
"data": {
|
|
||||||
"name": "my_frpc"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Modify frpc Instance
|
|
||||||
|
|
||||||
**Endpoint:** `/frpcAct/instanceMgr/modify`
|
|
||||||
**Method:** POST
|
|
||||||
**Content-Type:** application/json
|
|
||||||
**Auth Required:** Yes (token)
|
|
||||||
|
|
||||||
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
|
|
||||||
{
|
|
||||||
"instanceName": "my_frpc",
|
|
||||||
"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 |
|
|
||||||
|-------|------|----------|-------------|
|
|
||||||
| instanceName | string | Yes | Current instance name |
|
|
||||||
| instanceID | string | Yes | Instance ID |
|
|
||||||
| 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": {
|
|
||||||
"instanceName": "my_frpc",
|
|
||||||
"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
|
|
||||||
{
|
|
||||||
"instanceName": "my_frpc",
|
|
||||||
"instanceID": "1",
|
|
||||||
"type": "systemConfig",
|
|
||||||
"modifiedData": {
|
|
||||||
"name": "new_frpc_name",
|
|
||||||
"bootAtStart": true,
|
|
||||||
"runUser": "www-data"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
| Field | Type | Required | Description |
|
|
||||||
|-------|------|----------|-------------|
|
|
||||||
| instanceName | string | Yes | Current instance name |
|
|
||||||
| instanceID | string | Yes | Instance ID |
|
|
||||||
| 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": {
|
|
||||||
"instanceName": "new_frpc_name",
|
|
||||||
"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
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### List frpc Instances
|
|
||||||
|
|
||||||
**Endpoint:** `/frpcAct/instanceMgr/list`
|
|
||||||
**Method:** GET
|
|
||||||
**Auth Required:** Yes (token)
|
|
||||||
|
|
||||||
**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": [
|
|
||||||
{
|
|
||||||
"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"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
**Response (visitor):**
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"success": true,
|
|
||||||
"message": "instances retrieved successfully",
|
|
||||||
"data": [
|
|
||||||
{
|
|
||||||
"name": "my_frpc",
|
|
||||||
"bootAtStart": true,
|
|
||||||
"runUser": "root",
|
|
||||||
"configPath": "./configs/superfrpc_user_my_frpc.toml",
|
|
||||||
"createdAt": "2024-01-01T00:00:00Z"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
> Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## User Permissions
|
|
||||||
|
|
||||||
| Permission | superuser | admin | visitor |
|
|
||||||
|------------|-----------|-------|---------|
|
|
||||||
| Create instance | ✓ | ✓ | ✗ |
|
|
||||||
| Delete instance | ✓ | ✓ | ✗ |
|
|
||||||
| Modify instance | ✓ | ✓ | ✗ |
|
|
||||||
| List instances | ✓ | ✓ | ✓ (limited) |
|
|
||||||
| Manage users | ✓ | ✗ | ✗ |
|
|
||||||
|
|
||||||
## 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`
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
GPL-3.0
|
||||||
|
|||||||
+456
@@ -0,0 +1,456 @@
|
|||||||
|
# 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` and `/login`)
|
||||||
|
- Timestamps are in milliseconds (Unix timestamp)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Register User
|
||||||
|
|
||||||
|
**Endpoint:** `/register`
|
||||||
|
**Method:** POST
|
||||||
|
**Content-Type:** application/json
|
||||||
|
|
||||||
|
**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
|
||||||
|
|
||||||
|
**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)
|
||||||
|
|
||||||
|
**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 frpc Instance
|
||||||
|
|
||||||
|
**Endpoint:** `/frpcAct/instanceMgr/create`
|
||||||
|
**Method:** POST
|
||||||
|
**Content-Type:** application/json
|
||||||
|
**Auth Required:** Yes (token)
|
||||||
|
|
||||||
|
**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)
|
||||||
|
|
||||||
|
**Request Headers:**
|
||||||
|
```
|
||||||
|
X-Token: your_token
|
||||||
|
X-Timestamp: 1704067200000
|
||||||
|
```
|
||||||
|
|
||||||
|
**Request Body:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"instanceName": "my_frpc"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "instance deleted successfully",
|
||||||
|
"data": {
|
||||||
|
"name": "my_frpc"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Modify frpc Instance
|
||||||
|
|
||||||
|
**Endpoint:** `/frpcAct/instanceMgr/modify`
|
||||||
|
**Method:** POST
|
||||||
|
**Content-Type:** application/json
|
||||||
|
**Auth Required:** Yes (token)
|
||||||
|
|
||||||
|
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
|
||||||
|
{
|
||||||
|
"instanceName": "my_frpc",
|
||||||
|
"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 |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| instanceName | string | Yes | Current instance name |
|
||||||
|
| instanceID | string | Yes | Instance ID |
|
||||||
|
| 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": {
|
||||||
|
"instanceName": "my_frpc",
|
||||||
|
"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
|
||||||
|
{
|
||||||
|
"instanceName": "my_frpc",
|
||||||
|
"instanceID": "1",
|
||||||
|
"type": "systemConfig",
|
||||||
|
"modifiedData": {
|
||||||
|
"name": "new_frpc_name",
|
||||||
|
"bootAtStart": true,
|
||||||
|
"runUser": "www-data"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|-------|------|----------|-------------|
|
||||||
|
| instanceName | string | Yes | Current instance name |
|
||||||
|
| instanceID | string | Yes | Instance ID |
|
||||||
|
| 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": {
|
||||||
|
"instanceName": "new_frpc_name",
|
||||||
|
"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
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## List frpc Instances
|
||||||
|
|
||||||
|
**Endpoint:** `/frpcAct/instanceMgr/list`
|
||||||
|
**Method:** GET
|
||||||
|
**Auth Required:** Yes (token)
|
||||||
|
|
||||||
|
**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": [
|
||||||
|
{
|
||||||
|
"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"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response (visitor):**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "instances retrieved successfully",
|
||||||
|
"data": [
|
||||||
|
{
|
||||||
|
"name": "my_frpc",
|
||||||
|
"bootAtStart": true,
|
||||||
|
"runUser": "root",
|
||||||
|
"configPath": "./configs/superfrpc_user_my_frpc.toml",
|
||||||
|
"createdAt": "2024-01-01T00:00:00Z"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Note: Visitor users do not see sensitive information (serverAddr, serverPort, auth_method).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## User Permissions
|
||||||
|
|
||||||
|
| Permission | superuser | admin | visitor |
|
||||||
|
|------------|-----------|-------|---------|
|
||||||
|
| Create instance | ✓ | ✓ | ✗ |
|
||||||
|
| Delete instance | ✓ | ✓ | ✗ |
|
||||||
|
| Modify instance | ✓ | ✓ | ✗ |
|
||||||
|
| List instances | ✓ | ✓ | ✓ (limited) |
|
||||||
|
| Manage users | ✓ | ✗ | ✗ |
|
||||||
|
|
||||||
|
## 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`
|
||||||
Reference in New Issue
Block a user