mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-05 23:26:38 +08:00
[优化] 更新文档
This commit is contained in:
ryan
+120
-13
@@ -1,12 +1,12 @@
|
||||
# API Conventions
|
||||
|
||||
You will learn: The response structure, path conventions, authentication methods, and Swagger entry point for OpenFlare management and Agent APIs.
|
||||
You will learn: The response structure, path conventions, authentication methods, and Swagger entrance for the OpenFlare Admin API and Agent API.
|
||||
|
||||
Both the OpenFlare management APIs and Agent APIs use JSON.
|
||||
Both the OpenFlare Admin API and Agent API communicate using JSON.
|
||||
|
||||
## Response Structure
|
||||
|
||||
Both success and failure should return a clear `message`:
|
||||
Both successful and failed API responses must return a clear `message`:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -18,31 +18,138 @@ Both success and failure should return a clear `message`:
|
||||
|
||||
## Path Conventions
|
||||
|
||||
| Type | Convention |
|
||||
| Category | Convention |
|
||||
| --- | --- |
|
||||
| Management API | Authenticated by management console Session |
|
||||
| Agent API | Fixed under `/api/agent/*` |
|
||||
| Read-only API | Use `GET` |
|
||||
| Mutation-type API | Use `POST` |
|
||||
| Admin API | Authenticated via the Admin Session |
|
||||
| Agent API | Located strictly under `/api/agent/*` |
|
||||
| Relay API | Located strictly under `/api/relay/*`, authenticated via `X-Agent-Token` (reusing the Agent's token) |
|
||||
| OpenFlared API | Located strictly under `/api/flared/*`, authenticated via `X-Tunnel-Token` (dedicated tunnel_token) |
|
||||
| Read-only APIs | Use the `GET` method |
|
||||
| Mutating APIs | Use the `POST` method |
|
||||
|
||||
## WAF IP Group APIs
|
||||
|
||||
The Admin WAF IP Group APIs require Admin Session authentication:
|
||||
|
||||
| Method | Path | Description |
|
||||
| --- | --- | --- |
|
||||
| `GET` | `/api/waf/ip-groups` | Query IP groups list |
|
||||
| `GET` | `/api/waf/ip-groups/:id` | Query a single IP group |
|
||||
| `POST` | `/api/waf/ip-groups` | Create a new IP group |
|
||||
| `POST` | `/api/waf/ip-groups/test` | Test automatic IP group Expr rules; returns matching IPs in the lookback window without persisting the config |
|
||||
| `POST` | `/api/waf/ip-groups/:id/update` | Update an existing IP group |
|
||||
| `POST` | `/api/waf/ip-groups/:id/delete` | Delete an IP group; denied if currently referenced by any rule group |
|
||||
| `POST` | `/api/waf/ip-groups/:id/sync` | Manually sync subscription IP groups or execute automatic IP group aggregation |
|
||||
|
||||
The IP group `type` supports `manual`, `automatic`, and `subscription`. The `auto_config` parameter for automatic IP groups is a JSON object:
|
||||
|
||||
```json
|
||||
{
|
||||
"lookback_minutes": 60,
|
||||
"rules": [
|
||||
{
|
||||
"name": "Single IP High-Frequency 404 Scanning",
|
||||
"expr": "request_count > 100 && status_404_ratio >= 0.8"
|
||||
},
|
||||
{
|
||||
"name": "Single IP Direct IP Access Mismatch",
|
||||
"expr": "ip_host_count > 50 && ip_host_ratio > 0.5"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Automatic rules evaluate Expr boolean expressions against metrics aggregated on a per-client-IP basis. The available metrics include `ip`, `request_count`, `status_404_count`, `status_404_ratio`, `ip_host_count`, `ip_host_ratio`, `client_error_count`, `server_error_count`, and `last_seen_unix`. The full syntax is detailed in [WAF Auto IP Group Expressions](../guide/waf-ip-group-expr.md).
|
||||
|
||||
Subscription formats support `text` and `json`: plain text parsing resolves one IP or CIDR per line, ignoring empty lines and comments starting with `#`; JSON parsing decodes arrays, reading the root array by default.
|
||||
|
||||
## Authentication
|
||||
|
||||
The management console continues to reuse the existing login, role, and Session system.
|
||||
The Admin panel continues to reuse the existing login, role, and Session validation.
|
||||
|
||||
Official Agent requests uniformly use the node-exclusive `agent_token`; the first access can use the global `discovery_token`. The Agent request header is fixed as:
|
||||
Agent requests must carry the node-specific `agent_token` (except for first-time registration, which can use the global `discovery_token`). The header is formatted as:
|
||||
|
||||
```http
|
||||
X-Agent-Token: <token>
|
||||
```
|
||||
|
||||
Full Tokens must not be printed in the logs.
|
||||
### Agent WAF IP Group Synchronization
|
||||
|
||||
The Agent heartbeat payload can carry local WAF IP group checksums:
|
||||
|
||||
```json
|
||||
{
|
||||
"waf_ip_group_checksums": {
|
||||
"1": "sha256..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The Server evaluates the checksums against active configurations, returning mismatched IP groups in the heartbeat response:
|
||||
|
||||
```json
|
||||
{
|
||||
"waf_ip_groups": [
|
||||
{
|
||||
"id": 1,
|
||||
"name": "Auto Blacklist",
|
||||
"type": "automatic",
|
||||
"enabled": true,
|
||||
"ip_list": ["203.0.113.10"],
|
||||
"checksum": "sha256..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, the Agent can proactively request differential updates upon applying a new configuration version:
|
||||
|
||||
| Method | Path | Description |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/agent/waf/ip-groups/sync` | Returns mismatched WAF IP groups based on Agent-supplied `ids` and `checksums` |
|
||||
|
||||
When an IP group is updated on the Server, connected Agents receive a WebSocket push containing `type = "waf_ip_groups"` with the changed IP groups array as payload. The Agent updates only the changed groups incrementally.
|
||||
|
||||
## OpenFlared API
|
||||
|
||||
The OpenFlared client communicates with the Server via a dedicated `tunnel_token`, completely decoupled from the Agent authentication system. All endpoints require `X-Tunnel-Token` authentication; requests are denied with `403` if the token is invalid.
|
||||
|
||||
| Method | Path | Description |
|
||||
| --- | --- | --- |
|
||||
| `POST` | `/api/flared/heartbeat` | Client heartbeat, updates online status and retrieves active tunnel config version summaries |
|
||||
| `GET` | `/api/flared/config/active` | Pulls the complete tunnel routing configuration (relay list + frpc proxy definitions) |
|
||||
| `POST` | `/api/flared/apply-log` | Reports configuration application results (success / warning / failed) |
|
||||
| `GET` | `/api/flared/ws` | Upgrades to a WebSocket connection for real-time `active_config` pushes |
|
||||
|
||||
Heartbeat request example:
|
||||
|
||||
```http
|
||||
POST /api/flared/heartbeat
|
||||
X-Tunnel-Token: <tunnel_token>
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"client_version": "v0.2.0",
|
||||
"frp_version": "0.61.0",
|
||||
"tunnel_status": "running",
|
||||
"connected_relays": [
|
||||
{ "relay_node_id": "node-relay-1", "status": "healthy", "proxy_count": 3 }
|
||||
],
|
||||
"current_version": "v1",
|
||||
"current_checksum": "sha256..."
|
||||
}
|
||||
```
|
||||
|
||||
The heartbeat response returns the `active_config` summary and `tunnel_settings` (containing runtime settings like heartbeat intervals and WebSocket upgrade switches). When a new configuration version is published, the Server broadcasts a message `type = "active_config"` with the version summary as payload to all connected Clients over WebSockets, prompting them to fetch and apply the config immediately.
|
||||
|
||||
Full tokens must never be logged.
|
||||
|
||||
## Swagger
|
||||
|
||||
Accessible after logging into the management console:
|
||||
Once logged into the management console, the Swagger page is accessible at:
|
||||
|
||||
```text
|
||||
/swagger/index.html
|
||||
```
|
||||
|
||||
The Swagger files are located in `openflare_server/docs`, generated by `swag init`.
|
||||
The Swagger definition file is stored in `openflare_server/docs`, generated by `swag init`.
|
||||
|
||||
Reference in New Issue
Block a user