NanamiAdmin
783b06ff94
Add new endpoint `/userMgr/list` to retrieve all users with superuser permission. Includes handler implementation, database query function, and API documentation update.
570 lines
13 KiB
Markdown
570 lines
13 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` and `/login`)
|
|
- Timestamps are in milliseconds (Unix timestamp)
|
|
|
|
---
|
|
|
|
## 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",
|
|
"type": "superuser"
|
|
},
|
|
{
|
|
"userID": 2,
|
|
"username": "new_user",
|
|
"type": "admin"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
{
|
|
"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)
|
|
**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
|
|
{
|
|
"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)
|
|
**Permission Level:** Admin
|
|
|
|
Retrieve a list of all frpc instances.
|
|
|
|
**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`
|