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:

{
  "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

go build -o super-frpc

For Linux:

GOOS=linux GOARCH=amd64 go build -o super-frpc

Run

./super-frpc -config ./config.json -db ./database.db

API Documentation

All API responses are returned in JSON format:

Success Response:

{
  "success": true,
  "message": "success message",
  "data": { ... }
}

Error Response:

{
  "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)

---

1. Register User

Endpoint: /register
Method: POST
Content-Type: application/json

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "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:

{
  "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.

---

2. Login

Endpoint: /login
Method: POST
Content-Type: application/json

Request Headers:

X-Timestamp: 1704067200000

Request Body:

{
  "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:

{
  "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 Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "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:

{
  "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/delete
Method: POST
Content-Type: application/json
Auth Required: Yes (token)

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceName": "my_frpc"
}

Response:

{
  "success": true,
  "message": "instance deleted successfully",
  "data": {
    "name": "my_frpc"
  }
}

---

5. Modify frpc Instance

Endpoint: /frpcAct/instanceMgr/modify/{field}
Method: POST
Content-Type: application/json
Auth Required: Yes (token)

You can modify multiple fields at once:

Request Headers:

X-Token: your_token
X-Timestamp: 1704067200000

Request Body:

{
  "instanceName": "my_frpc",
  "name": "new_name",
  "serverAddr": "192.168.1.1",
  "serverPort": "7000",
  "auth_method": "token",
  "runUser": "www-data",
  "bootAtStart": false
}

Response:

{
  "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 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):

{
  "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):

{
  "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