docs: update README with detailed project documentation
Add comprehensive documentation including features, configuration, build/run instructions, API details, user permissions, and security requirements. The README now serves as complete project reference for users and developers.
This commit is contained in:
@@ -1,2 +1,359 @@
|
||||
# backend
|
||||
# Super-frpc
|
||||
|
||||
A backend application for managing local frpc instances, allowing users to easily start, stop, restart, and perform daily maintenance operations on frpc instances. It also provides automated error handling, such as automatic restart when an instance crashes.
|
||||
|
||||
## Features
|
||||
|
||||
- User authentication with token-based login
|
||||
- Create, delete, and modify frpc instances
|
||||
- Automatic startup configuration (systemd/init.d)
|
||||
- User permission management (superuser/admin/visitor)
|
||||
- SQLite database for data persistence
|
||||
|
||||
## Configuration
|
||||
|
||||
Create a `config.json` file in the project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"listenAddr": "0.0.0.0",
|
||||
"listenPort": "8080",
|
||||
"frpcPath": "/usr/bin/frpc",
|
||||
"instancePath": "./configs"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Description | Default |
|
||||
|-------|-------------|---------|
|
||||
| listenAddr | Server listening address | 0.0.0.0 |
|
||||
| listenPort | Server listening port | 8080 |
|
||||
| frpcPath | Path to frpc executable | /usr/bin/frpc |
|
||||
| instancePath | Path to store instance config files | ./configs |
|
||||
|
||||
## Build
|
||||
|
||||
```bash
|
||||
go build -o super-frpc
|
||||
```
|
||||
|
||||
For Linux:
|
||||
```bash
|
||||
GOOS=linux GOARCH=amd64 go build -o super-frpc
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
./super-frpc -config ./config.json -db ./database.db
|
||||
```
|
||||
|
||||
## 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"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 1. Register User
|
||||
|
||||
**Endpoint:** `/register`
|
||||
**Method:** POST
|
||||
**Content-Type:** application/json
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "your_username",
|
||||
"passwd": "YourPass123!",
|
||||
"timeStamp": 1704067200000,
|
||||
"type": "admin"
|
||||
}
|
||||
```
|
||||
|
||||
| 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) |
|
||||
| timeStamp | int64 | Yes | Client timestamp in milliseconds |
|
||||
| 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Login
|
||||
|
||||
**Endpoint:** `/login`
|
||||
**Method:** POST
|
||||
**Content-Type:** application/json
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "your_username",
|
||||
"passwd": "YourPass123!",
|
||||
"timeStamp": 1704067200000
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| username | string | Yes | Username |
|
||||
| passwd | string | Yes | Password |
|
||||
| timeStamp | int64 | Yes | Client timestamp in milliseconds |
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "login successful",
|
||||
"data": {
|
||||
"token": "xxxxxxxxxxxxx",
|
||||
"userID": 1,
|
||||
"username": "your_username",
|
||||
"type": "admin"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Create frpc Instance
|
||||
|
||||
**Endpoint:** `/frpcAct/instanceMgr/create`
|
||||
**Method:** POST
|
||||
**Content-Type:** application/json
|
||||
**Auth Required:** Yes (token)
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "your_token",
|
||||
"timeStamp": 1704067200000,
|
||||
"instanceInfo": {
|
||||
"name": "my_frpc",
|
||||
"serverAddr": "127.0.0.1",
|
||||
"serverPort": "7000",
|
||||
"auth_method": "token"
|
||||
},
|
||||
"bootAtStart": true,
|
||||
"runUser": "root",
|
||||
"additionalProperties": {
|
||||
"pool_count": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| token | string | Yes | Authentication token |
|
||||
| timeStamp | int64 | Yes | Client timestamp in milliseconds |
|
||||
| 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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Delete frpc Instance
|
||||
|
||||
**Endpoint:** `/frpcAct/instanceMgr/{instanceName}/delete`
|
||||
**Method:** POST
|
||||
**Content-Type:** application/json
|
||||
**Auth Required:** Yes (token)
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "your_token",
|
||||
"timeStamp": 1704067200000
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "instance deleted successfully",
|
||||
"data": {
|
||||
"name": "my_frpc"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Modify frpc Instance
|
||||
|
||||
**Endpoint:** `/frpcAct/instanceMgr/{instanceName}/modify/{field}`
|
||||
**Method:** POST
|
||||
**Content-Type:** application/json
|
||||
**Auth Required:** Yes (token)
|
||||
|
||||
You can modify multiple fields at once:
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "your_token",
|
||||
"timeStamp": 1704067200000,
|
||||
"name": "new_name",
|
||||
"serverAddr": "192.168.1.1",
|
||||
"serverPort": "7000",
|
||||
"auth_method": "token",
|
||||
"runUser": "www-data",
|
||||
"bootAtStart": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"message": "instance modified successfully",
|
||||
"data": {
|
||||
"name": "new_name",
|
||||
"configPath": "./configs/superfrpc_user_new_name.toml"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6. List frpc Instances
|
||||
|
||||
**Endpoint:** `/frpcAct/instanceMgr/list`
|
||||
**Method:** GET
|
||||
**Auth Required:** Yes (token)
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"token": "your_token",
|
||||
"timeStamp": 1704067200000
|
||||
}
|
||||
```
|
||||
|
||||
**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
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user