tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-02 14:56:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

文档更新

Browse Source
This commit is contained in:
ryan
2026-06-19 14:43:22 +08:00
parent 9eeeb09d2f
commit cc5e53c51e
48 changed files with 226 additions and 4612 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/deployment/agent.md
-176
View File
@@ -1,176 +0,0 @@
# Access Agent
You will learn: The responsibilities of the Agent, the difference between the two access Tokens, installation script parameters, `agent.json` settings, and how to verify that the node has successfully connected.
The OpenFlare Agent runs on the proxy node. It does not receive arbitrary remote shell commands; instead, it pulls the configuration version published by the control plane via the Agent API, writes files for OpenResty locally, executes configuration validation, reloads, and attempts to roll back to a working configuration if it fails.
## Connection Credentials
| Method | Applicable Scenario |
| --- | --- |
| `discovery_token` | Automatically registers a node for the first time, which the Server exchanges for a node-specific credential |
| `agent_token` | Node has already been created/allocated in the management console, directly uses this node-specific credential |
At least one of `agent_token` or `discovery_token` must be configured.
### Credential Retrieval Path
- **`discovery_token` (Auto Registration Token)**: Log into the management console, navigate to "System Settings" -> "Auto Registration", where you can generate, view, and copy the global auto-registration credential.
- **`agent_token` (Node Specific Token)**: Log into the management console, navigate to "Node Management" -> "Add Node", fill in basic node information, save, and copy the node-specific access Token in the node details.
## One-Click Installation
Using the `discovery_token`:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--discovery-token YOUR_DISCOVERY_TOKEN
```
Using the node-specific `agent_token`:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--agent-token YOUR_AGENT_TOKEN
```
The installation script downloads the latest Agent, writes to `/opt/openflare-agent` by default, generates `agent.json`, and registers `openflare-agent.service` on Linux + systemd environments.
Supported arguments:
| Argument | Description | Default Value |
| --- | --- | --- |
| `--server-url` | Server address (required) | |
| `--discovery-token` | One-time auto-registration Token | |
| `--agent-token` | Node-specific Token | |
| `--install-dir` | Target installation directory | `/opt/openflare-agent` |
| `--openresty-path` | Path to the OpenResty binary; automatically detects `openresty` if unspecified | |
| `--repo` | GitHub repository to download from | `Rain-kl/OpenFlare` |
| `--no-service` | Do not register systemd service | |
## Configuration File
Default configuration file path:
```text
/opt/openflare-agent/agent.json
```
Example local configuration:
```json
{
"server_url": "http://127.0.0.1:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "./data",
"openresty_path": "openresty",
"openresty_observability_port": 18081,
"observability_replay_minutes": 15,
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
Example customized OpenResty paths configuration:
```json
{
"server_url": "http://127.0.0.1:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "/var/lib/openflare-agent",
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
"main_config_path": "/var/lib/openflare-agent/etc/nginx/nginx.conf",
"route_config_path": "/var/lib/openflare-agent/etc/nginx/conf.d/openflare_routes.conf",
"access_log_path": "/var/lib/openflare-agent/var/log/openflare/access.log",
"cert_dir": "/var/lib/openflare-agent/etc/nginx/certs",
"lua_dir": "/var/lib/openflare-agent/etc/nginx/lua",
"runtime_config_dir": "/var/lib/openflare-agent/etc/openflare",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
If `openresty_path` is not configured, the Agent calls `openresty` by default. For the full fields, see [Configurations Reference](../reference/configuration.md#agent-configurations-fields).
## Running in Docker
For Docker deployments, run the Agent image containing built-in OpenResty directly:
```bash
docker pull ghcr.io/rain-kl/openflare-agent:latest
docker rm -f openflare-agent 2>/dev/null || true
docker run -d --name openflare-agent --restart unless-stopped \
-p 80:80 -p 443:443 \
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
ghcr.io/rain-kl/openflare-agent:latest
```
## Start & Validate
In a systemd environment:
```bash
systemctl start openflare-agent
systemctl status openflare-agent
journalctl -u openflare-agent -f
```
Manual execution:
```bash
/opt/openflare-agent/openflare-agent -config /opt/openflare-agent/agent.json
```
Running from source:
```bash
cd openflare-agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
Running compiled binary:
```bash
cd openflare-agent
go build -o openflare-agent ./cmd/agent
export LOG_LEVEL='info'
./openflare-agent -config /path/to/agent.json
```
Confirm in the management console:
| Position | Expected Result |
| --- | --- |
| Node List | Node status is online |
| Node Details | Heartbeat, current version, and basic resource metrics display correctly |
| Apply Logs | Application result displays after publishing |
## Uninstall
To completely uninstall the Agent and wipe local data:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
```
Supported arguments:
| Argument | Description | Default Value |
| --- | --- | --- |
| `--install-dir` | Installation directory | `/opt/openflare-agent` |
| `--service-name` | systemd service name | `openflare-agent` |
The uninstallation script only removes the Agent service, processes, and installation directory; it does not uninstall OpenResty from the host.
## Common Questions
| Symptom | Actions |
| --- | --- |
| `agent_token and discovery_token cannot both be empty` | Check if at least one Token is configured in `agent.json` |
| Node stays offline | Run `curl -I http://your-server:3000` on the Agent node to verify that the Server is reachable |
| OpenResty is not running | Review `journalctl -u openflare-agent`, checking that `openresty_path` is executable and ports 80/443 are not bound |
| Repeated application failures after publishing | The Agent blocks repeated sync attempts of the same failing `version + checksum`; fix the configuration and republish, or activate an older version to roll back |
docs/en/deployment/deployment.md
-287
View File
@@ -1,287 +0,0 @@
# Deployment Guide
You will learn: The recommended deployment strategies for OpenFlare, the system requirements for Server and Agent, how to run from source, integration steps, upgrades, and uninstallation entrypoints.
In production environments, we highly recommend using PostgreSQL as the Server database and explicitly configuring `SESSION_SECRET` for the Server. The recommended Agent deployment method is Docker (which runs the Agent image containing built-in OpenResty); host systemd service installation via script and manual local run are also supported.
## Deployment Topology
### Standard Reverse Proxy Traffic Path
```text
Browser
|
v
OpenFlare Server :3000
|
| Agent API / heartbeat / config pull
v
OpenFlare Agent
|
v
OpenResty binary
|
v
Origin service
```
### Intranet Penetration Traffic Path
```text
Browser
|
v
OpenResty (Agent, WAF/HTTPS Termination) <-- TunnelRelay Node
|
| proxy_pass (127.0.0.1:{vhost_port})
v
OpenFlareRelay (frps process) <-- TunnelRelay Node
|
| frp tunnel protocol
v
OpenFlared (frpc client) <-- Intranet Server
|
v
Internal Service (192.168.x.x)
```
## Prerequisites
Server:
| Item | Requirement |
| --- | --- |
| Go | `1.25+`, required only when running from source |
| Node.js | `18+`, required only when building the admin frontend from source |
| Database | Writable SQLite parent directory, or a reachable PostgreSQL instance |
| Port | Listens on port `3000` by default |
Agent:
| Item | Requirement |
| --- | --- |
| System | The installation script supports Linux and macOS; the systemd service is created only on Linux + systemd environments |
| Architecture | `amd64` or `arm64` |
| OpenResty | Required to have the `openresty` executable when deploying locally, or specify its path via `--openresty-path` |
| Docker | Required only when deploying the Agent via Docker image |
| Network | The Agent node must be able to reach the Server address |
| GeoIP | WAF regional rules rely on the Agent's local MaxMind mmdb; the Agent initializes a built-in library on startup and updates it periodically |
### Hardware Allocation Recommendations
| Component | Minimum Allocation | Recommended Allocation | Note |
| --- | --- | --- | --- |
| **Server Control Plane** | 1 Core CPU / 1 GB RAM / 10 GB Disk | 2 Cores CPU / 4 GB RAM / 50 GB+ Disk | Expand disk allocation according to log retention windows and concurrency. |
| **Agent Data Plane** | 1 Core CPU / 512 MB RAM / 2 GB Disk | 2 Cores CPU / 2 GB RAM / 10 GB+ Disk | Expand according to concurrent reverse proxy connections and WAF workloads. |
| **Relay Node** | 1 Core CPU / 1 GB RAM / 5 GB Disk | 2 Cores CPU / 2 GB RAM / 20 GB Disk | frps throughput is primarily bounded by CPU processing capacity and bandwidth. |
| **OpenFlared Client** | 1 Core CPU / 256 MB RAM / 1 GB Disk | 1 Core CPU / 512 MB RAM / 5 GB Disk | Runs inside the intranet; utilizes minimal CPU/RAM, optimize for network throughput. |
## Docker Compose Deployment for Server
Create a `docker-compose.yml` file:
```yaml
services:
postgres:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: openflare
POSTGRES_USER: openflare
POSTGRES_PASSWORD: replace-with-strong-password
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
interval: 10s
timeout: 5s
retries: 5
openflare:
image: ghcr.io/rain-kl/openflare:latest
container_name: openflare
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
ports:
- "3000:3000"
environment:
SESSION_SECRET: replace-with-a-long-random-string
DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
GIN_MODE: release
LOG_LEVEL: info
volumes:
- openflare-data:/data
volumes:
postgres-data:
openflare-data:
```
Start the Server:
```bash
docker compose up -d
docker compose ps
docker compose logs -f openflare
```
Access `http://localhost:3000` for the first time, using the default credentials `root` / `123456`. Please change the default password immediately after logging in.
## Start Server from Source
First, build the admin frontend:
```bash
cd openflare-server/web
corepack enable
pnpm install
pnpm build
```
Then, launch the Server:
```bash
cd openflare-server
export SESSION_SECRET='replace-with-a-long-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
# Optional: Prefer PostgreSQL by setting DSN
# export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
go run .
```
By default, the Server listens on port `3000`. You can also specify it explicitly:
```bash
go run . --port 3000 --log-dir ./logs
```
## Running Agent in Docker (Recommended)
Docker is the recommended deployment method for the Agent. Running the Agent image directly launches the Agent controller alongside the built-in OpenResty binary. If `node_ip` is left blank, the Agent automatically resolves its outbound public IP via third-party APIs, avoiding registering the Docker bridge address as the node IP.
Mounting the configuration file:
```bash
docker pull ghcr.io/rain-kl/openflare-agent:latest
docker rm -f openflare-agent 2>/dev/null || true
docker run -d --name openflare-agent --restart unless-stopped \
-p 80:80 -p 443:443 \
-v openflare-agent-data:/data \
-v ./agent.json:/etc/openflare/agent.json:ro \
ghcr.io/rain-kl/openflare-agent:latest
```
Using environment variables:
```bash
docker pull ghcr.io/rain-kl/openflare-agent:latest
docker rm -f openflare-agent 2>/dev/null || true
docker run -d --name openflare-agent --restart unless-stopped \
-p 80:80 -p 443:443 \
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
ghcr.io/rain-kl/openflare-agent:latest
```
## Agent Connection via Installation Script
Apart from Docker, you can deploy the Agent directly on a Linux/macOS host using the installation script.
Auto-register using `discovery_token`:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--discovery-token YOUR_DISCOVERY_TOKEN
```
Connect using node-specific `agent_token`:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--agent-token YOUR_AGENT_TOKEN
```
Installation script arguments:
| Argument | Description | Default Value |
| --- | --- | --- |
| `--server-url` | Server address (required) | |
| `--discovery-token` | Auto-registration Token; mutually exclusive with `--agent-token` | |
| `--agent-token` | Node-specific Token; mutually exclusive with `--discovery-token` | |
| `--install-dir` | Target installation directory | `/opt/openflare-agent` |
| `--openresty-path` | Path to the OpenResty binary; automatically detects `openresty` if unspecified | |
| `--repo` | GitHub repository to download from | `Rain-kl/OpenFlare` |
| `--no-service` | Do not register systemd service | |
Confirm service status:
```bash
systemctl status openflare-agent
journalctl -u openflare-agent -f
```
## Running the Agent Manually
Running from source:
```bash
cd openflare-agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
Running compiled binary:
```bash
cd openflare-agent
go build -o openflare-agent ./cmd/agent
export LOG_LEVEL='info'
./openflare-agent -config /path/to/agent.json
```
Minimal `agent.json` example:
```json
{
"server_url": "http://127.0.0.1:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "./data",
"openresty_path": "openresty",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
If `openresty_path` is left blank, the Agent calls `openresty` by default.
By default, the Agent attempts to upgrade the HTTP heartbeat connection to WebSocket once successfully registered. Once upgraded, configuration activations on the Server notify the Agent instantly; if WebSocket disconnects or fails to establish, the Agent gracefully falls back to HTTP polling.
WAF geographical filtering depends on the local `GeoLite2-Country.mmdb`. The Agent automatically writes the built-in database to `data_dir/etc/openflare/GeoLite2-Country.mmdb` on startup and checks for periodic updates. Muted warnings are logged if updates fail, having no impact on Nginx configuration sync or reloads.
## Upgrades & Uninstallation
Server:
* Root users can check and trigger Server upgrades in the top header of the management console.
* To deploy preview releases, manually check the GitHub Releases page.
* You can also trigger upgrades by uploading the compiled Server binary in the console.
Agent:
* By default, the Agent automatically upgrades following stable releases.
* Agent self-updates require the GitHub Release to contain the compiled binary and a matching `.sha256` checksum file; updates are blocked if the downloaded binary fails the SHA-256 validation.
* You can re-execute the installation script to redeploy or force-update the Agent.
* Upgrading to preview releases requires a manual trigger.
Uninstalling the Agent:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
```
The uninstallation script stops the Agent process, removes the systemd service unit, and wipes the installation directory, without uninstalling OpenResty from the host.
docs/en/deployment/index.md
-24
View File
@@ -1,24 +0,0 @@
# Deployment & Upgrade
This section provides detailed deployment guides, configuration instructions, and upgrade maintenance procedures for the OpenFlare Server, Agent, Relay, and the OpenFlared client.
## Content Navigation
### Quick Start
* **[Quick Start](../guide/quick-start.md)**: Start the Server and your first Agent in under 5 minutes using Docker Compose (recommended for new users).
### Server Deployment
* **[Launch Server](./server.md)**: Learn how to build the frontend from source, start the Server, and choose between SQLite or PostgreSQL.
### Agent Deployment
* **[Deploy Agent](./agent.md)**: Explore Agent connection methods, Docker deployment, host script installation, config files, and troubleshooting.
### Tunnel Intranet Penetration Deployment
* **[Deploy Relay](./relay.md)**: View config descriptions, Docker deployment, and host runtime guides for TunnelRelay nodes.
* **[Deploy OpenFlared](./openflared.md)**: Access config descriptions, Docker runtime, and auto-sync mechanisms for the intranet client.
### Upgrade & Maintenance
* **[Upgrade & Maintenance](./upgrade.md)**: Discover upgrading procedures for Server/Agent, data retention rules, and validation commands.
### Reference Manuals
* **[Deployment Guide](./deployment.md)**: Browse deployment topologies, prerequisites, Docker Compose samples, and multiple deployment strategies.
docs/en/deployment/openflared.md
-119
View File
@@ -1,119 +0,0 @@
# Deploy OpenFlared Client
You will learn: The responsibilities of the OpenFlared client, configuration parameters and environment variables, how to run the client via Docker, and how to deploy the client on an intranet server using the compiled host binary.
**OpenFlared** is a tunnel client deployed in the user's intranet environment (LANs, private VPCs, or other environments that cannot be directly accessed from the public internet). Its core responsibility is to establish communication with the control plane (OpenFlare Server) via the `X-Tunnel-Token` header, automatically spawning and managing one or more **frpc (Fast Reverse Proxy Client)** subprocesses locally to securely and stably tunnel HTTP traffic back to public relay nodes.
---
## Prerequisites
1. **Retrieve Tunnel Token**: Create a new tunnel instance on the "Intranet Penetration" or "Tunnel Management" page in the OpenFlare management console; the system will automatically generate a unique `tunnel_id` and a `tunnel_token` (e.g., `tun-<32hex>`).
2. **Outbound Network Permissions**: The intranet server does not require any inbound public IPs or port mappings, but it must be able to reach the **OpenFlare Server URL** and the corresponding **TunnelRelay node control port (default 7000)** over the outbound network.
3. **Software Dependencies** (Host deployment only):
- You must have an executable `frpc` binary locally (recommended version `v0.61.0+` or the latest stable `v0.69.0`), or specify its path explicitly in the configuration.
---
## Configuration & Environment Variables
`openflared` reads `flared.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.
### Configuration Fields Details
| JSON Field | Environment Variable | Description | Default Value |
| --- | --- | --- | --- |
| `server_url` | `OPENFLARE_SERVER_URL` | OpenFlare Server API base URL | **None (Required)** |
| `tunnel_token` | `OPENFLARE_TUNNEL_TOKEN` | Tunnel client dedicated access Token | **None (Required)** |
| `frpc_path` | `OPENFLARE_FRPC_PATH` | Path to the `frpc` executable binary | `"frpc"` |
| `data_dir` | `OPENFLARE_DATA_DIR` | Directory to store local data and generated `frpc_{relayNodeID}.toml` configs | `"./data"` |
| `state_path` | - | Path to store local state JSON file (saving the last applied version) | `"{data_dir}/flared-state.json"` |
| `heartbeat_interval`| - | Heartbeat reporting interval (ms or Go Duration string) | `10000` (10s) |
| `sync_interval` | - | Tunnel config polling interval (ms or Go Duration string) | `30000` (30s) |
| `request_timeout` | - | HTTP request timeout duration | `10000` (10s) |
---
## Docker Deployment (Recommended)
Docker is the simplest and safest way to run the client inside the intranet. The official `openflared` image embeds the client controller and `frpc v0.69.0` out of the box, requiring no environment setup.
```bash
docker pull ghcr.io/rain-kl/openflared:latest
docker rm -f openflared 2>/dev/null || true
docker run -d --name openflared --restart unless-stopped \
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
-e OPENFLARE_TUNNEL_TOKEN=YOUR_TUNNEL_TOKEN \
-v openflared-data:/app/data \
ghcr.io/rain-kl/openflared:latest
```
---
## Manual Host Deployment
If you need to run the client directly on a Linux/macOS/Windows host inside the intranet:
### 1. Compile the Binary
```bash
cd openflared
go build -o flared ./cmd/flared
```
### 2. Prepare `flared.json`
Create a `flared.json` configuration file in the same directory as the executable:
```json
{
"server_url": "http://your-server-ip:3000",
"tunnel_token": "your-tunnel-auth-token",
"frpc_path": "/usr/local/bin/frpc",
"data_dir": "./data",
"heartbeat_interval": "10s",
"sync_interval": "30s"
}
```
### 3. Start the Service
```bash
export LOG_LEVEL='info'
./flared -config ./flared.json
```
---
## Start & Validate
### 1. Auto-Sync Workflow
Once started successfully, OpenFlared operates the following workflow:
- **Heartbeat & Config Fetching**: Periodically polls `/api/flared/heartbeat` and `/api/flared/config` endpoints to validate the Token and evaluate configuration versions.
- **File Rendering**: When a new configuration version (or checksum mismatch) is detected, it pulls the complete tunnel routing rules. If multiple Relays are bound, it renders `frpc_{relayNodeID}.toml` configurations in `data_dir` for each Relay.
- **Hot Reload or Restart**: Spawns the corresponding `frpc` subprocesses, or executes `frpc reload` / restart actions when configurations change, ensuring traffic mappings are kept up to date.
- **Process Auto-Recovery**: If a local `frpc` tunnel process exits unexpectedly, the master program automatically restarts it after a 5-second backoff penalty.
### 2. View Logs & Connection Status
```bash
# Docker container logs
docker logs -f openflared
```
If running correctly, the logs will show output similar to:
```text
flared config loaded ...
detected frpc version v0.69.0
flared process started
applying new tunnel config {"version": "...", "checksum": "..."}
frpc process missing, starting {"relay_id": "..."}
```
### 3. Verify in the Management Console
Open the **"Intranet Penetration"** page in the management console:
- Check the online status of the corresponding tunnel; it should display green as **"Online"**.
- You can inspect which relay nodes the tunnel is connected to, and view the detailed routing configurations of the intranet services.
docs/en/deployment/relay.md
-126
View File
@@ -1,126 +0,0 @@
# Deploy Relay (Tunnel Relay)
You will learn: The responsibilities of a TunnelRelay node, `openflare-relay` configuration parameters and environment variables, how to run the Relay via Docker, and how to build and deploy the Relay from source manually.
In the OpenFlare intranet penetration architecture, the **TunnelRelay node** plays a key role. Unlike standard Edge Nodes, in addition to running the traditional Agent (managing OpenResty for HTTPS/WAF processing), it co-locates the **Relay (frps tunnel manager)** service, responsible for listening to intranet client (OpenFlared) tunnel connections and relaying traffic.
---
## Prerequisites
Before deploying a TunnelRelay node, ensure:
1. **Registered as a TunnelRelay node**: Add a node of type `tunnel_relay` in the OpenFlare management console under "Node Management", and retrieve its node-specific `agent_token` or use the global `discovery_token`.
2. **Network Ports**:
- Ensure `bindPort` (the port frpc clients connect to, default `7000`) is accessible from the public/intranet client networks.
- Ensure `vhostHTTPPort` (the HTTP Vhost port, default `8080`) is free and not bound by other processes, as the Agent routes traffic to frps on this port.
3. **Software Dependencies** (Host deployment only):
- You must have an executable `frps` binary locally (recommended version `v0.61.0+` or the latest stable `v0.69.0`), or specify its path explicitly in the configuration.
---
## Configuration & Environment Variables
`openflare-relay` reads `relay.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.
### Configuration Fields Details
| JSON Field | Environment Variable | Description | Default Value |
| --- | --- | --- | --- |
| `server_url` | `OPENFLARE_SERVER_URL` | OpenFlare Server API base URL | **None (Required)** |
| `agent_token` | `OPENFLARE_AGENT_TOKEN` | Node-specific Token | Mutually exclusive with below |
| `discovery_token` | `OPENFLARE_DISCOVERY_TOKEN` | One-time auto-registration Token | Mutually exclusive with above |
| `node_name` | `OPENFLARE_NODE_NAME` | Custom name for the node | Hostname by default |
| `node_ip` | `OPENFLARE_NODE_IP` | Outbound/listening IP of the node | Automatically detects real outbound IP |
| `frps_path` | `OPENFLARE_FRPS_PATH` | Path to the `frps` executable binary | `"frps"` |
| `data_dir` | `OPENFLARE_DATA_DIR` | Directory to store local data and generated `frps.toml` | `"./data"` |
| `state_path` | - | Path to store local state JSON file | `"{data_dir}/relay-state.json"` |
| `heartbeat_interval`| - | Heartbeat interval (integer ms or Go Duration string) | `10000` (10s) |
| `request_timeout` | - | HTTP request timeout duration | `10000` (10s) |
---
## Docker Deployment (Recommended)
Docker is the most convenient way to deploy a TunnelRelay node. The official Docker image embeds the `openflare-relay` controller and `frps v0.69.0` out of the box.
```bash
docker pull ghcr.io/rain-kl/openflare-relay:latest
docker rm -f openflare-relay 2>/dev/null || true
docker run -d --name openflare-relay --restart unless-stopped \
-p 7000:7000 \
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
-v openflare-relay-data:/var/lib/openflare-relay \
ghcr.io/rain-kl/openflare-relay:latest
```
> [!TIP]
> The `-p 7000:7000` option maps the port `frpc` clients connect to. If a custom `relay_bind_port` is configured in the management console, change this port mapping on the host accordingly.
---
## Manual Host Deployment
If you prefer to run the Relay directly on a physical host or VM:
### 1. Compile the Binary
```bash
cd openflare-relay
go build -o openflare-relay ./cmd/relay
```
### 2. Prepare `relay.json`
Create a `relay.json` configuration file in the same directory as the executable:
```json
{
"server_url": "http://127.0.0.1:3000",
"agent_token": "your-relay-node-agent-token",
"frps_path": "/usr/local/bin/frps",
"data_dir": "./data",
"heartbeat_interval": "10s",
"request_timeout": "10s"
}
```
### 3. Start the Service
```bash
export LOG_LEVEL='info'
./openflare-relay -config ./relay.json
```
---
## Start & Validate
### 1. View Process Logs
```bash
# Docker container logs
docker logs -f openflare-relay
```
If managed via systemd on Linux, execute:
```bash
journalctl -u openflare-relay -f
```
### 2. Verify Runtime Status
Upon starting successfully, the Relay operates as follows:
- Sends HTTP heartbeats to register and go online with the control plane.
- Retrieves the active frps baseline settings (including `bindPort`, `vhostHTTPPort`, and the auto-generated `auth_token`).
- Automatically renders the `data/frps.toml` configuration locally.
- Spawns the subprocess `frps -c data/frps.toml`.
- If the `frps` process crashes, the Relay automatically restarts it after 2 seconds.
### 3. Verify in the Management Console
Log into the management console and navigate to **"Node Management"** to verify:
- The TunnelRelay node status is marked as **"Online"**.
- The Node Type is correctly displayed as **Relay Node** and the frps status displays as **Healthy**.
docs/en/deployment/server.md
-170
View File
@@ -1,170 +0,0 @@
# Launch Server
You will learn: How to build the admin frontend from source, start the OpenFlare Server, choose between SQLite or PostgreSQL, and access Swagger.
OpenFlare Server is a Gin + GORM monolithic control plane, responsible for managing the Admin UI, Admin API, Agent API, configuration rendering, version publishing, data storage, and aggregated queries.
## Prerequisites
| Item | Requirement |
| --- | --- |
| Go | `1.25+` |
| Node.js | `18+` |
| pnpm | Recommended enabling via `corepack enable` |
| Database | SQLite parent directory must be writable, or a reachable PostgreSQL instance |
In production environments, we highly recommend explicitly configuring `SESSION_SECRET` and prioritizing PostgreSQL.
## Build the Admin Frontend
The Go Server hosts static assets located in `openflare-server/web/build`. Before starting the Server from source, build the frontend:
```bash
cd openflare-server/web
corepack enable
pnpm install
pnpm build
```
Common frontend quality checks:
```bash
pnpm lint
pnpm typecheck
pnpm test
```
## Start with SQLite
```bash
cd openflare-server
export SESSION_SECRET='replace-with-a-long-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
go run .
```
By default, the Server listens on port `3000`. Access it at:
```text
http://localhost:3000
```
## Start with PostgreSQL
```bash
cd openflare-server
export SESSION_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:secret@127.0.0.1:5432/openflare?sslmode=disable'
export LOG_LEVEL='info'
go run .
```
If `DSN` is set, it takes precedence over SQLite. When both `DSN` and the legacy `SQL_DSN` exist, `DSN` is prioritized.
If the target PostgreSQL database is empty and a local SQLite database exists at `SQLITE_PATH`, the Server automatically migrates the SQLite data into PostgreSQL during startup, outputting the migration progress in the logs.
## Start with Docker
Deploying with Docker avoids the hassle of setting up local Go and Node.js environments. OpenFlare provides official Dockerfiles and Compose configurations to support independent container startups and multi-service orchestrations.
### 1. Quick Start via Docker Run (SQLite Example)
Ensure that a local directory for persisting databases and logs has been created. Run the following command to start the Server:
```bash
# Create local mount directory
mkdir -p ./openflare-data
# Start the container
docker run -d \
--name openflare-server \
-p 3000:3000 \
-v $(pwd)/openflare-data:/data \
-e SESSION_SECRET='replace-with-a-long-random-string' \
-e SQLITE_PATH='/data/openflare.db' \
-e GIN_MODE='release' \
-e LOG_LEVEL='info' \
ghcr.io/rain-kl/openflare:latest
```
Startup parameters:
* **`-p 3000:3000`**: Maps port `3000` on the host to port `3000` inside the container.
* **`-v $(pwd)/openflare-data:/data`**: Mounts the local directory to `/data` in the container, ensuring that the SQLite database `openflare.db` is not lost when restarting or rebuilding the container.
* **`SESSION_SECRET`**: The session signing hash key (required).
---
### 2. One-click Startup via Docker Compose (Integrated PostgreSQL)
We recommend using Docker Compose in production environments to orchestrate an independent PostgreSQL database and establish high-availability relationships.
Create a `docker-compose.yml` file:
```yaml
services:
postgres:
image: postgres:17-alpine
restart: unless-stopped
environment:
POSTGRES_DB: openflare
POSTGRES_USER: openflare
POSTGRES_PASSWORD: replace-with-strong-password
volumes:
- ./postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
interval: 10s
timeout: 5s
retries: 5
openflare:
image: ghcr.io/rain-kl/openflare:latest
restart: unless-stopped
depends_on:
postgres:
condition: service_healthy
ports:
- "3000:3000"
environment:
SESSION_SECRET: replace-with-random-string
SQLITE_PATH: /data/openflare.db
DSN: postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable
GIN_MODE: release
LOG_LEVEL: info
volumes:
- ./openflare-data:/data
```
Start the services:
```bash
docker compose up -d
```
Compose configuration options:
* **`depends_on` and `healthcheck`**: Uses PostgreSQL's health check (`pg_isready`) to ensure that the database is fully initialized and ready before launching the OpenFlare Server, preventing panics from failed database connection attempts on first launch.
* **Separated Data Volume Mounts**: PostgreSQL data is mounted under `./postgres-data`, and OpenFlare data and backups are mounted under `./openflare-data`, making backups and maintenance simple.
## CLI Arguments
```bash
go run . --port 3000 --log-dir ./logs
```
| Argument | Description | Default Value |
| --- | --- | --- |
| `--port` | The port the Server listens to | `3000` |
| `--log-dir` | The directory to write logs to | Empty, outputs to stdout |
| `--version` | Outputs version and exits | `false` |
| `--help` | Outputs help and exits | `false` |
## First Login
Default credentials:
| Username | Password |
| --- | --- |
| `root` | `123456` |
Please change the default password immediately after your first login.
docs/en/deployment/upgrade.md
-52
View File
@@ -1,52 +0,0 @@
# Upgrade & Maintenance
You will learn: How to upgrade the Server and the Agent, how to clean up observability data, and which validation commands to execute before and after maintenance.
Before upgrading, verify the currently active version, the most recent Agent application results, and your database backup strategy. In production environments, never trigger upgrades while a configuration is being published, during large-scale Agent reconnections, or while database migrations are in progress.
## Server Upgrade
Root users can check and trigger stable Server upgrades in the top header of the management console. You can also trigger upgrades by uploading the compiled Server binary in the console.
To deploy preview releases, manually check the GitHub Releases page. We highly recommend prioritizing stable releases in production environments.
Verify after upgrading:
```bash
docker compose ps
docker compose logs -n 100 openflare
```
If deployed from source, restart the Server and verify that no database migration or startup errors appear in the logs.
## Agent Upgrade
Node Agents automatically update following stable releases by default. Upgrading to preview releases requires a manual trigger.
You can re-execute the installation script to redeploy or force-update the Agent:
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
--server-url http://your-server:3000 \
--agent-token YOUR_AGENT_TOKEN
```
Note: Re-executing the current installation script wipes the entire installation directory, including the existing `agent.json`, local states, cached databases, and downloaded binaries. Ensure you have the node Token handy before executing the script.
Verify after upgrading:
```bash
systemctl status openflare-agent
journalctl -u openflare-agent -n 100 --no-pager
```
## Data Maintenance
The management console's Settings page maintains options for automatic cleanup of observability data:
| Parameter | Description |
| --- | --- |
| `DatabaseAutoCleanupEnabled` | Toggles daily automatic cleanup |
| `DatabaseAutoCleanupRetentionDays` | Data retention duration in days, minimum 1 day |
When enabled, the Server cleans up access logs, metrics snapshots, and request reports at 3:00 AM daily.