feat(frpLogger): add real-time instance log streaming functionality
Implement cross-platform log streaming for frpc instances with support for Windows, systemd, and init.d systems. Includes WebSocket API endpoint for real-time log streaming, token validation, and instance ownership checks. Update README and API documentation to reflect new functionality. The implementation handles: - Platform-specific log collection (Windows Event Log, journalctl, log files) - WebSocket-based real-time streaming - Token validation and instance access control - Log level parsing and formatting - Historical log retrieval since service start
This commit is contained in:
+91
-2
@@ -1250,7 +1250,7 @@ instanceID=1
|
||||
|
||||
---
|
||||
|
||||
## Real-time Log Streaming (WebSocket)
|
||||
## Real-time System Log Streaming (WebSocket)
|
||||
|
||||
**Endpoint:** `/system/getLogs`
|
||||
**Protocol:** WebSocket
|
||||
@@ -1334,6 +1334,95 @@ socket.onerror = (error) => {
|
||||
```
|
||||
---
|
||||
|
||||
## Real-time frpc Instance Log Streaming (WebSocket)
|
||||
|
||||
**Endpoint:** `/frpcAct/instanceMgr/logs`
|
||||
**Method:** GET
|
||||
**Protocol:** WebSocket
|
||||
**Auth Required:** Yes (token)
|
||||
**Permission Level:** Visitor
|
||||
|
||||
Stream real-time logs from a frpc instance via WebSocket connection. This endpoint upgrades the HTTP connection to WebSocket and streams log messages in real-time.
|
||||
|
||||
**Request:**
|
||||
```
|
||||
ws://host:port/frpcAct/instanceMgr/logs?instanceID=1&token=your_token
|
||||
```
|
||||
|
||||
**Query Parameters:**
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| instanceID | int | Yes | ID of the instance to stream logs from |
|
||||
| token | string | Yes | Authentication token |
|
||||
|
||||
**WebSocket Message Format:**
|
||||
|
||||
Log messages are sent as JSON objects:
|
||||
|
||||
```json
|
||||
{
|
||||
"level": "INFO",
|
||||
"content": "[I] [service.go:XXX] start frpc success",
|
||||
"timestamp": "2024-01-01 12:00:00.000"
|
||||
}
|
||||
```
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| level | string | Log level: "DEBUG", "INFO", "WARN", "ERROR" |
|
||||
| content | string | Log message content |
|
||||
| timestamp | string | Timestamp in "YYYY-MM-DD HH:MM:SS.mmm" format |
|
||||
|
||||
**Error Response (before WebSocket upgrade):**
|
||||
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"message": "Instance not found"
|
||||
}
|
||||
```
|
||||
|
||||
**Common Error Messages:**
|
||||
|
||||
| HTTP Status | Message | Description |
|
||||
|-------------|---------|-------------|
|
||||
| 400 | "instanceID is required" | Missing instanceID parameter |
|
||||
| 400 | "invalid instanceID format" | instanceID is not a valid integer |
|
||||
| 401 | "Token is required" | Missing token parameter |
|
||||
| 401 | "Invalid token: ..." | Token validation failed |
|
||||
| 401 | "User not found" | User associated with token does not exist |
|
||||
| 403 | "You don't have access to this instance" | Instance belongs to another user |
|
||||
| 404 | "Instance not found" | Instance with given ID does not exist |
|
||||
| 500 | "Failed to get service name" | Internal server error |
|
||||
|
||||
**Platform-Specific Behavior:**
|
||||
|
||||
| Platform | Init System | Log Source |
|
||||
|----------|-------------|------------|
|
||||
| Windows | sc | Config file (if `log_file` is set) or Windows Event Log |
|
||||
| Linux | systemd | `journalctl -u <service> -f` |
|
||||
| Linux | init.d | Log files in `/var/log/` or service status monitoring |
|
||||
|
||||
**Connection Lifecycle:**
|
||||
|
||||
1. Client initiates WebSocket connection with `instanceID` and `token`
|
||||
2. Server validates token and instance ownership
|
||||
3. Server upgrades connection to WebSocket
|
||||
4. Server starts streaming logs
|
||||
5. Connection remains open until client disconnects or error occurs
|
||||
6. Server sends log messages as they become available
|
||||
|
||||
**Notes:**
|
||||
|
||||
- Only the instance owner can access the logs (user must own the instance)
|
||||
- The connection will be closed if the token expires during the session
|
||||
- On Windows, if no log file is configured, the service status is monitored instead
|
||||
- On Linux init.d systems, log files are searched in common locations (`/var/log/`, etc.)
|
||||
- Log streaming is real-time; historical logs may be sent initially depending on the platform
|
||||
|
||||
---
|
||||
|
||||
## User Permissions
|
||||
|
||||
| Permission | superuser | admin | visitor |
|
||||
@@ -1400,4 +1489,4 @@ The API implements rate limiting to prevent abuse:
|
||||
- Login attempts: Maximum 5 attempts per minute per IP
|
||||
- All other endpoints: 100 requests per minute per token
|
||||
|
||||
Exceeding rate limits will result in temporary IP or token blocking.
|
||||
Exceeding rate limits will result in temporary IP or token blocking.
|
||||
Reference in New Issue
Block a user