feat(instanceMgr): add getInfo endpoint to retrieve instance details

Implement new GET endpoint `/frpcAct/instanceMgr/getInfo` to fetch frpc instance information Add documentation for the new API endpoint in docs/api.md The handler returns different information based on user permission level
2026-03-25 22:20:32 +08:00
parent 25f88249c2
commit e83436fe9b
3 changed files with 182 additions and 0 deletions
@@ -1165,6 +1165,91 @@ X-Timestamp: 1704067200000

 ---

+## Get frpc Instance Information
+
+**Endpoint:** `/frpcAct/instanceMgr/getInfo`  
+**Method:** GET  
+**Auth Required:** Yes (token)  
+**Permission Level:** Visitor
+
+Retrieve information about a specific frpc instance. Returns different information based on user permission level.
+
+**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 get information for |
+
+**Response (Admin/Superuser):**
+```json
+{
+  "success": true,
+  "message": "Instance info retrieved successfully",
+  "data": {
+    "name": "my_frpc",
+    "serviceName": "superfrpc_admin_my_frpc",
+    "createdAt": "2024-01-01T00:00:00Z",
+    "createdBy": "admin",
+    "isRunning": true,
+    "serverAddr": "127.0.0.1",
+    "serverPort": "7000",
+    "auth_method": "token",
+    "bootAtStart": true,
+    "runUser": "root",
+    "configPath": "./configs/superfrpc_admin_my_frpc.toml"
+  }
+}
+```
+
+**Response (Visitor):**
+```json
+{
+  "success": true,
+  "message": "Instance info retrieved successfully",
+  "data": {
+    "name": "my_frpc",
+    "serviceName": "superfrpc_admin_my_frpc",
+    "createdAt": "2024-01-01T00:00:00Z",
+    "createdBy": "admin",
+    "isRunning": true,
+    "auth_method": "token",
+    "bootAtStart": true,
+    "runUser": "root",
+    "configPath": "./configs/superfrpc_admin_my_frpc.toml"
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| name | string | Name of the frpc instance |
+| serviceName | string | Service name |
+| createdAt | string | Instance creation time (ISO 8601 format) |
+| createdBy | string | Username of the user who created this instance |
+| isRunning | bool | Instance running status: true (running) or false (stopped) |
+| serverAddr | string | frps server address (only returned for admin/superuser) |
+| serverPort | string | frps server port (only returned for admin/superuser) |
+| auth_method | string | Authentication method |
+| bootAtStart | bool | Whether the instance starts automatically on system boot |
+| runUser | string | User that the instance runs as |
+| configPath | string | Path to the instance's configuration file |
+
+---
+
 ## Real-time Log Streaming (WebSocket)

 **Endpoint:** `/system/getLogs`