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:
2026-03-26 17:46:50 +08:00
parent 61e4ad6ecc
commit 839bad3c94
11 changed files with 1658 additions and 7 deletions
+91 -2
View File
@@ -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.