mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-01 14:46:36 +08:00
docs(i18n): 同步 24 篇旧英文文档与中文最新内容
guide 9 篇（quick-start/first-site/sso/troubleshooting/tunnel-usage/waf-usage/waf-ip-group-expr/credits/index）、deployment 7 篇（deployment/server/agent/relay/openflared/upgrade/index）、reference 3 篇（configuration/cli/index）、design 5 篇（architecture/agent-design/tunnel-design/waf-design/index）全部按中文最新版重写同步；waf-usage/waf-design 按新版 DAG 模型重写；修复 reference 中文锚点链接；vitepress 构建 43 个英文页面全绿
This commit is contained in:
ryan
+72
-89
@@ -1,26 +1,38 @@
|
||||
# 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.
|
||||
You will learn: the Agent's responsibilities, the difference between the two access Tokens, install script parameters, `agent.json` config, and how to confirm the node is online.
|
||||
|
||||
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.
|
||||
The OpenFlare Agent runs on the proxy node side. It doesn't accept remote shell commands; instead it pulls released config versions from the control plane via the Agent API, writes OpenResty files locally, runs config validation, reloads, and attempts to roll back to a runnable config on failure.
|
||||
|
||||
## Connection Credentials
|
||||
## Connection Methods
|
||||
|
||||
| Method | Applicable Scenario |
|
||||
| Method | Use Case |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
| `discovery_token` | first-time auto-registration; the Server exchanges it for a node-specific credential |
|
||||
| `agent_token` | node already created/assigned in the admin panel; connect with the node-specific credential |
|
||||
|
||||
At least one of `agent_token` or `discovery_token` must be configured.
|
||||
At least one of `agent_token` / `discovery_token` is required.
|
||||
|
||||
### Credential Retrieval Path
|
||||
### Credential Paths
|
||||
|
||||
- **`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.
|
||||
- **`discovery_token` (auto-registration credential)**: log in to the admin panel, navigate to「System Settings」->「Auto Registration」; generate, view, and copy the global auto-registration credential there.
|
||||
- **`agent_token` (node-specific credential)**: log in to the admin panel, navigate to「Node Management」->「Add Node」; after filling in basic info and saving, copy the node-specific access Token on the node detail page.
|
||||
|
||||
## One-Click Installation
|
||||
## One-Click Install
|
||||
|
||||
Using the `discovery_token`:
|
||||
### Interactive Install (recommended)
|
||||
|
||||
Running the install script without any arguments enters interactive mode, with a wizard choosing the install method (local / Docker container) and configuring the Server address and auth Token (if Docker is chosen and Docker isn't installed locally, the script asks and intelligently installs Docker):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash
|
||||
```
|
||||
|
||||
### Automated (non-interactive) Install
|
||||
|
||||
Adding any arguments enters automated install mode with no interaction.
|
||||
|
||||
Local install with `discovery_token`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -28,7 +40,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
Using the node-specific `agent_token`:
|
||||
Local install with node-specific `agent_token`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -36,29 +48,40 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--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.
|
||||
Automated Docker container install:
|
||||
|
||||
Supported arguments:
|
||||
```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 \
|
||||
--docker
|
||||
```
|
||||
|
||||
| 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 | |
|
||||
In local install mode, the script downloads the latest Agent, writes to `/opt/openflare-agent` by default, generates `agent.json`, auto-detects and creates the low-privilege system account `openflare` (granting the whole install dir to it), and creates the `openflare-agent.service` systemd service on Linux + systemd. The service runs as the `openflare` unprivileged user, with Linux Capabilities (`CAP_NET_BIND_SERVICE`) enabling privileged ports (e.g. 80, 443).
|
||||
|
||||
## Configuration File
|
||||
Supported parameters:
|
||||
|
||||
Default configuration file path:
|
||||
| Parameter | Description |
|
||||
| --- | --- |
|
||||
| `--server-url` | Server address |
|
||||
| `--discovery-token` | first-time auto-registration Token |
|
||||
| `--agent-token` | node-specific Token |
|
||||
| `--install-dir` | install dir, default `/opt/openflare-agent` (local install only) |
|
||||
| `--openresty-path` | OpenResty binary path; auto-finds `openresty` when omitted (local install only) |
|
||||
| `--repo` | GitHub repo for downloading the Agent, default `Rain-kl/OpenFlare` |
|
||||
| `--no-service` | don't create the systemd service (local install only) |
|
||||
| `--docker` | install via Docker container |
|
||||
| `--method` | install method: `local` or `docker` (default `local`) |
|
||||
|
||||
## Config File
|
||||
|
||||
Default config file path:
|
||||
|
||||
```text
|
||||
/opt/openflare-agent/agent.json
|
||||
```
|
||||
|
||||
Example local configuration:
|
||||
Local config example:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -67,13 +90,13 @@ Example local configuration:
|
||||
"data_dir": "./data",
|
||||
"openresty_path": "openresty",
|
||||
"openresty_observability_port": 18081,
|
||||
"observability_replay_minutes": 15,
|
||||
"heartbeat_interval": 10000,
|
||||
"observability_replay_minutes": 60,
|
||||
"heartbeat_interval": 3000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
Example customized OpenResty paths configuration:
|
||||
Custom OpenResty path example:
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -87,90 +110,50 @@ Example customized OpenResty paths configuration:
|
||||
"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,
|
||||
"heartbeat_interval": 3000,
|
||||
"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).
|
||||
Without `openresty_path`, the Agent calls `openresty` by default. Full fields: [Configuration Reference](../reference/configuration.md#agent-命令行参数与配置字段).
|
||||
|
||||
## Running in Docker
|
||||
## Running with Docker
|
||||
|
||||
For Docker deployments, run the Agent image containing built-in OpenResty directly:
|
||||
For Docker deployment, directly run the Agent image with a built-in OpenResty:
|
||||
|
||||
```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 \
|
||||
-p 80:80 -p 443:443/tcp -p 443:443/udp \
|
||||
-v openflare-agent-pages:/data/var/lib/openflare/pages \
|
||||
-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 |
|
||||
> [!NOTE]
|
||||
> **Pages persistence**
|
||||
> By default the Pages deployment dir is mounted to the Docker named volume `openflare-agent-pages` (container path `/data/var/lib/openflare/pages`). Rebuilding or upgrading the Agent container doesn't require re-pulling static site packages.
|
||||
|
||||
## Uninstall
|
||||
|
||||
To completely uninstall the Agent and wipe local data:
|
||||
### Interactive Uninstall (recommended)
|
||||
|
||||
Running the uninstall script without any arguments enters interactive mode with a menu choosing the method (local uninstall / Docker container uninstall):
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
Supported arguments:
|
||||
### Docker Container Uninstall
|
||||
|
||||
| Argument | Description | Default Value |
|
||||
| --- | --- | --- |
|
||||
| `--install-dir` | Installation directory | `/opt/openflare-agent` |
|
||||
| `--service-name` | systemd service name | `openflare-agent` |
|
||||
Stop and remove the `openflare-agent` container.
|
||||
|
||||
The uninstallation script only removes the Agent service, processes, and installation directory; it does not uninstall OpenResty from the host.
|
||||
## FAQ
|
||||
|
||||
## Common Questions
|
||||
|
||||
| Symptom | Actions |
|
||||
| Symptom | Handling |
|
||||
| --- | --- |
|
||||
| `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 |
|
||||
| `agent_token and discovery_token cannot both be empty` | check that `agent.json` has at least one Token |
|
||||
| Node stays offline | run `curl -I http://your-server:3000` on the Agent node to confirm the Server address is reachable |
|
||||
| Repeated failure after release | the Agent blocks re-applying the same `version + checksum`; click「Force Sync」in the node detail page, or republish a new version |
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 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.
|
||||
You will learn: OpenFlare's recommended deployment approaches, Server and Agent runtime requirements, source startup, integration steps, and upgrade/uninstall entries.
|
||||
|
||||
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.
|
||||
Production recommends PostgreSQL as the Server DB, with `APP_SESSION_SECRET` etc. configured via `config.yaml` or env vars. The full Docker Compose deployment requires Redis; ClickHouse is optional for massive access logs and observability time series (see the repo root `docker-compose.yaml`). The Agent supports both Docker deployment and a local install script; the Docker image bundles the OpenResty binary. Log-DB determination and switching: [Log Store Decoupling](../design/logstore.md).
|
||||
|
||||
## Deployment Topology
|
||||
|
||||
@@ -31,15 +31,15 @@ Origin service
|
||||
Browser
|
||||
|
|
||||
v
|
||||
OpenResty (Agent, WAF/HTTPS Termination) <-- TunnelRelay Node
|
||||
OpenResty (Agent, WAF/HTTPS termination) <-- TunnelRelay node
|
||||
|
|
||||
| proxy_pass (127.0.0.1:{vhost_port})
|
||||
v
|
||||
OpenFlareRelay (frps process) <-- TunnelRelay Node
|
||||
OpenFlareRelay (frps process) <-- TunnelRelay node
|
||||
|
|
||||
| frp tunnel protocol
|
||||
v
|
||||
OpenFlared (frpc client) <-- Intranet Server
|
||||
OpenFlared (frpc client) <-- intranet server
|
||||
|
|
||||
v
|
||||
Internal Service (192.168.x.x)
|
||||
@@ -47,150 +47,75 @@ Internal Service (192.168.x.x)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Server:
|
||||
### Hardware Recommendations
|
||||
|
||||
| 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 |
|
||||
| Component | Reference (entry) | Reference (production) | Notes |
|
||||
| --- | --- | --- | --- |
|
||||
| **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. |
|
||||
| **Server control plane** | 1 core / 2 GB RAM / 20 GB disk | 2 cores / 4 GB RAM / 50 GB+ disk | expand disk by access-log retention and concurrent traffic |
|
||||
| **Agent data plane** | 1 core / 512 MB RAM / 2 GB disk | 2 cores / 2 GB RAM / 10 GB+ disk | expand by OpenResty concurrent proxy connections and WAF interception |
|
||||
| **Relay node** | 1 core / 1 GB RAM / 5 GB disk | 2 cores / 2 GB RAM / 20 GB disk | frps relay throughput limited by bandwidth and CPU |
|
||||
| **OpenFlared client** | 1 core / 256 MB RAM / 1 GB disk | 1 core / 512 MB RAM / 5 GB disk | runs independently in the intranet, tiny footprint |
|
||||
|
||||
## Docker Compose Deployment for Server
|
||||
## Docker Compose Server Deployment
|
||||
|
||||
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:
|
||||
The repo root provides a full `docker-compose.yaml` (PostgreSQL, Redis, ClickHouse, Jaeger).
|
||||
|
||||
```bash
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
# edit .env; at minimum change APP_SESSION_SECRET and the DB passwords
|
||||
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.
|
||||
First visit `http://localhost:3000`; default account `admin` / `12345678`. Change the default password immediately after login.
|
||||
|
||||
## Start Server from Source
|
||||
## Source Startup
|
||||
|
||||
First, build the admin frontend:
|
||||
First build the admin frontend:
|
||||
|
||||
```bash
|
||||
cd openflare-server/web
|
||||
cd frontend
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm build
|
||||
pnpm build:embed
|
||||
```
|
||||
|
||||
Then, launch the Server:
|
||||
Then start the Server (repo root):
|
||||
|
||||
```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 .
|
||||
cp config.example.yaml config.yaml
|
||||
export APP_SESSION_SECRET='replace-with-a-long-random-string'
|
||||
# optional: use PostgreSQL
|
||||
# export DB_HOST=127.0.0.1 DB_USERNAME=postgres DB_PASSWORD=postgres DB_NAME=openflare
|
||||
go run main.go all
|
||||
```
|
||||
|
||||
By default, the Server listens on port `3000`. You can also specify it explicitly:
|
||||
Listens on `:3000` by default (controlled by `app.addr` in `config.yaml` or `APP_ADDR`).
|
||||
|
||||
```bash
|
||||
go run . --port 3000 --log-dir ./logs
|
||||
```
|
||||
## Run the Agent with Docker (recommended)
|
||||
|
||||
## 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:
|
||||
Docker is the recommended Agent deployment. The Agent image is built on the OpenResty image, bundling the Agent controller and the OpenResty binary. Without an explicit `node_ip`, the Agent prefers fetching the real egress IP via a third-party API, avoiding registering the Docker bridge address as the node IP.
|
||||
|
||||
```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 \
|
||||
-p 80:80 -p 443:443/tcp -p 443:443/udp \
|
||||
-v openflare-agent-pages:/data/var/lib/openflare/pages \
|
||||
-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
|
||||
The named volume `openflare-agent-pages` persists the Pages deployment dir; rebuilding the container doesn't require re-pulling static site packages.
|
||||
|
||||
Apart from Docker, you can deploy the Agent directly on a Linux/macOS host using the installation script.
|
||||
## Agent Access (script install)
|
||||
|
||||
Auto-register using `discovery_token`:
|
||||
Besides Docker, the install script can deploy the Agent to the local host. The script registers the low-privilege `openflare` service account and runs the systemd service as that user, using Linux Capabilities to safely listen on privileged ports 80/443.
|
||||
|
||||
Auto-register with `discovery_token`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -198,7 +123,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
Connect using node-specific `agent_token`:
|
||||
With node-specific `agent_token`:
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
@@ -206,82 +131,21 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--agent-token YOUR_AGENT_TOKEN
|
||||
```
|
||||
|
||||
Installation script arguments:
|
||||
Install script parameters:
|
||||
|
||||
| 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 | |
|
||||
| Parameter | Description |
|
||||
| --- | --- |
|
||||
| `--server-url` | Server address, required |
|
||||
| `--discovery-token` | first-time auto-registration Token, one of two with `--agent-token` |
|
||||
| `--agent-token` | node-specific Token, one of two with `--discovery-token` |
|
||||
| `--install-dir` | install dir, default `/opt/openflare-agent` |
|
||||
| `--openresty-path` | OpenResty binary path; auto-finds `openresty` when omitted |
|
||||
| `--repo` | GitHub repo for downloading the Agent, default `Rain-kl/OpenFlare` |
|
||||
| `--no-service` | don't create the systemd service |
|
||||
|
||||
Confirm service status:
|
||||
Confirm state:
|
||||
|
||||
```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.
|
||||
|
||||
+11
-11
@@ -1,24 +1,24 @@
|
||||
# Deployment & Upgrade
|
||||
# Deployment & Upgrades
|
||||
|
||||
This section provides detailed deployment guides, configuration instructions, and upgrade maintenance procedures for the OpenFlare Server, Agent, Relay, and the OpenFlared client.
|
||||
This section provides detailed deployment guides, configuration notes, and upgrade/maintenance steps for the OpenFlare Server, Agent, Relay, and the OpenFlared intranet penetration 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).
|
||||
* **[Quick Start](../guide/quick-start.md)**: start the Server and your first Agent with Docker Compose in 5 minutes (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.
|
||||
* **[Start the Server](./server.md)**: build the frontend from source, start the Server, choose SQLite or PostgreSQL
|
||||
|
||||
### Agent Deployment
|
||||
* **[Deploy Agent](./agent.md)**: Explore Agent connection methods, Docker deployment, host script installation, config files, and troubleshooting.
|
||||
* **[Access Agent](./agent.md)**: Agent connection methods, Docker deployment, script install, config file, 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.
|
||||
* **[Deploy Relay](./relay.md)**: TunnelRelay node config notes, Docker deployment, and host running guide
|
||||
* **[Deploy OpenFlared](./openflared.md)**: intranet penetration client config notes, Docker running, and self-sync mechanism
|
||||
|
||||
### Upgrade & Maintenance
|
||||
* **[Upgrade & Maintenance](./upgrade.md)**: Discover upgrading procedures for Server/Agent, data retention rules, and validation commands.
|
||||
### Upgrades & Maintenance
|
||||
* **[Upgrade & Maintenance](./upgrade.md)**: Server and Agent upgrade steps, data cleanup policy, verification commands
|
||||
|
||||
### Reference Manuals
|
||||
* **[Deployment Guide](./deployment.md)**: Browse deployment topologies, prerequisites, Docker Compose samples, and multiple deployment strategies.
|
||||
### Reference
|
||||
* **[Deployment Guide](./deployment.md)**: deployment topology, prerequisites, Docker Compose config examples, and an overview of multiple deployment approaches
|
||||
|
||||
@@ -1,42 +1,42 @@
|
||||
# Deploy OpenFlared Client
|
||||
# Deploy the 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.
|
||||
You will learn: OpenFlared's responsibilities, config parameters and env vars, running the client with Docker, and deploying it standalone on an intranet server via 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.
|
||||
**OpenFlared** is the tunnel client deployed in your intranet (LAN, private cloud, or any environment not directly reachable from the public internet). Its core responsibility is communicating with the control plane (OpenFlare Server) via `X-Tunnel-Token`, and locally spawning and managing one or more **frpc (fast reverse proxy client)** processes to securely and stably tunnel intranet HTTP traffic 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.
|
||||
1. **Get a Tunnel Token**: add a node of type **Tunnel** in admin「Node Management」, save it, then open the node detail page to view the dedicated access Token.
|
||||
2. **Outbound network access**: the intranet server needs no public inbound IP or port mapping, but must reach the public **OpenFlare Server address** and the corresponding **TunnelRelay node relay port (default 7000)** over the network.
|
||||
3. **Software dependency** (host deployment only):
|
||||
- an executable `frpc` binary locally, or an explicitly specified path via parameter.
|
||||
|
||||
---
|
||||
|
||||
## Configuration & Environment Variables
|
||||
## Config File and Env Vars
|
||||
|
||||
`openflared` reads `flared.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.
|
||||
`openflared` reads `flared.json` in the current directory by default at startup, fully overridable via env vars.
|
||||
|
||||
### Configuration Fields Details
|
||||
### Config Field Details
|
||||
|
||||
| JSON Field | Environment Variable | Description | Default Value |
|
||||
| JSON field | Env var | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `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) |
|
||||
| `server_url` | `OPENFLARE_SERVER_URL` | OpenFlare Server API service address | **none (required)** |
|
||||
| `tunnel_token` | `OPENFLARE_TUNNEL_TOKEN` | tunnel client's dedicated auth Token | **none (required)** |
|
||||
| `frpc_path` | `OPENFLARE_FRPC_PATH` | frpc executable binary path | `"frpc"` |
|
||||
| `data_dir` | `OPENFLARE_DATA_DIR` | local data and generated `frpc_{relayNodeID}.toml` directory | `"./data"` |
|
||||
| `state_path` | - | local state record file path (last applied config version) | `"{data_dir}/flared-state.json"` |
|
||||
| `heartbeat_interval`| - | state heartbeat report period (ms int or Go Duration string) | `10000` (10s) |
|
||||
| `sync_interval` | - | tunnel config pull/sync period (ms int or Go Duration string) | `30000` (30s) |
|
||||
| `request_timeout` | - | API network request timeout | `10000` (10s) |
|
||||
|
||||
---
|
||||
|
||||
## Docker Deployment (Recommended)
|
||||
## Running with Docker
|
||||
|
||||
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.
|
||||
Docker deployment is the simplest and safest way to run in the intranet. The official `openflared` image bundles the client controller and the `frpc v0.69.0` binary runtime — no extra environment needed.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/rain-kl/openflared:latest
|
||||
@@ -51,59 +51,24 @@ docker run -d --name openflared --restart unless-stopped \
|
||||
|
||||
---
|
||||
|
||||
## Manual Host Deployment
|
||||
## Startup and Verification
|
||||
|
||||
If you need to run the client directly on a Linux/macOS/Windows host inside the intranet:
|
||||
### 1. Auto-Sync Logic
|
||||
|
||||
### 1. Compile the Binary
|
||||
After starting successfully, OpenFlared runs this workflow:
|
||||
- **Heartbeat & config fetch**: periodically syncs with the Server's `/api/v1/tunnel/heartbeat` and `/api/v1/tunnel/config/active` endpoints, validating the Token and detecting config versions.
|
||||
- **File rendering**: when a config version (or checksum) changes, it auto-pulls the tunnel's full route rules. If multiple Relay nodes are bound, it renders `frpc_{relayNodeID}.toml` per Relay under `data_dir`.
|
||||
- **Config-change restart**: when config or checksum changes, it re-spawns the corresponding `frpc` child processes to keep traffic mappings current.
|
||||
- **Abnormal self-recovery**: if a local `frpc` tunnel process exits abnormally, the supervisor restarts it with exponential backoff (initial 1s, cap 60s).
|
||||
|
||||
```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
|
||||
### 2. View Logs and Connection State
|
||||
|
||||
```bash
|
||||
# Docker container logs
|
||||
docker logs -f openflared
|
||||
```
|
||||
|
||||
If running correctly, the logs will show output similar to:
|
||||
If the process runs correctly, you'll see output like:
|
||||
```text
|
||||
flared config loaded ...
|
||||
detected frpc version v0.69.0
|
||||
@@ -112,8 +77,8 @@ applying new tunnel config {"version": "...", "checksum": "..."}
|
||||
frpc process missing, starting {"relay_id": "..."}
|
||||
```
|
||||
|
||||
### 3. Verify in the Management Console
|
||||
### 3. Confirm in the Admin Panel
|
||||
|
||||
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.
|
||||
Open **「Node Management」** in the admin panel and enter the Tunnel node's detail page:
|
||||
- View the node online state and flared runtime state (WebSocket connected / running / offline).
|
||||
- View the current applied version and the latest apply record.
|
||||
|
||||
+45
-79
@@ -1,48 +1,48 @@
|
||||
# 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.
|
||||
You will learn: TunnelRelay node responsibilities, `openflare-relay` config items and env vars, running Relay with Docker, and building/deploying Relay manually from source.
|
||||
|
||||
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.
|
||||
In OpenFlare's intranet penetration system, the **TunnelRelay node** plays a key role. Unlike regular edge nodes, besides running the traditional Agent (hosting OpenResty for HTTPS/WAF processing), it also runs the **Relay (frps tunnel manager)** service on the same machine, listening for tunnel connections from intranet clients (OpenFlared) and relaying traffic.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before deploying a TunnelRelay node, ensure:
|
||||
Before deploying a TunnelRelay node, make sure:
|
||||
|
||||
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.
|
||||
1. **Registered as a TunnelRelay-type node**: in OpenFlare admin「Node Management」, add a node of type `tunnel_relay` and get its dedicated `agent_token`, or use the global `discovery_token`.
|
||||
2. **Network ports**:
|
||||
- `bindPort` (frpc connection port, default `7000`) must be reachable by public/intranet clients.
|
||||
- `vhostHTTPPort` (HTTP Vhost port, default `8080`) must be free; the Agent exchanges traffic with frps on this port.
|
||||
3. **Software dependency** (host deployment only):
|
||||
- an executable `frps` binary locally, or an explicitly specified path via parameter.
|
||||
|
||||
---
|
||||
|
||||
## Configuration & Environment Variables
|
||||
## Config File and Env Vars
|
||||
|
||||
`openflare-relay` reads `relay.json` in the working directory by default on startup. Overriding options via environment variables is fully supported.
|
||||
`openflare-relay` reads `relay.json` in the current directory by default at startup, fully overridable via env vars.
|
||||
|
||||
### Configuration Fields Details
|
||||
### Config Field Details
|
||||
|
||||
| JSON Field | Environment Variable | Description | Default Value |
|
||||
| JSON field | Env var | Description | Default |
|
||||
| --- | --- | --- | --- |
|
||||
| `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) |
|
||||
| `server_url` | `OPENFLARE_SERVER_URL` | OpenFlare Server API service address | **none (required)** |
|
||||
| `agent_token` | `OPENFLARE_AGENT_TOKEN` | node-specific Token | one of these two |
|
||||
| `discovery_token` | `OPENFLARE_DISCOVERY_TOKEN` | auto-registration Token | one of these two |
|
||||
| `node_name` | `OPENFLARE_NODE_NAME` | node identifier name | local hostname by default |
|
||||
| `node_ip` | `OPENFLARE_NODE_IP` | node egress/listen IP | auto-detected real egress IP |
|
||||
| `frps_path` | `OPENFLARE_FRPS_PATH` | frps executable binary path | `"frps"` |
|
||||
| `data_dir` | `OPENFLARE_DATA_DIR` | local data and generated `frps.toml` directory | `"./data"` |
|
||||
| `state_path` | - | local state JSON record file path | `"{data_dir}/relay-state.json"` |
|
||||
| `heartbeat_interval`| - | heartbeat period (ms int or Go Duration string) | `10000` (10s) |
|
||||
| `request_timeout` | - | API request timeout | `10000` (10s) |
|
||||
|
||||
---
|
||||
|
||||
## Docker Deployment (Recommended)
|
||||
## Running with Docker
|
||||
|
||||
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.
|
||||
Docker is the most convenient deployment for a TunnelRelay node. The official image bundles the `openflare-relay` controller and the `frps` runtime — out of the box.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/rain-kl/openflare-relay:latest
|
||||
@@ -50,53 +50,24 @@ docker rm -f openflare-relay 2>/dev/null || true
|
||||
|
||||
docker run -d --name openflare-relay --restart unless-stopped \
|
||||
-p 7000:7000 \
|
||||
-p 17500:17500 \
|
||||
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
|
||||
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
|
||||
-v openflare-relay-data:/var/lib/openflare-relay \
|
||||
-v openflare-relay-data:/app/data \
|
||||
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.
|
||||
> The `-p 7000:7000` mapping is the port frpc clients connect to for relaying. If the admin panel configures a custom `relay_bind_port`, adjust the host port mapping accordingly.
|
||||
|
||||
> [!NOTE]
|
||||
> **Enable the embedded frps Web UI**:
|
||||
> If the Server control panel enables the relay traffic monitoring panel (i.e. `relay_frps_web_ui_enabled` set to `true` in DB/system settings), you need to map the Web port (default `17500`, controlled by `relay_frps_web_ui_port` in system settings) to the host via `-p 17500:17500`.
|
||||
> The Web UI username is fixed to `admin`, and the password is the relay node's `agent_token`.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
## Startup and Verification
|
||||
|
||||
### 1. View Process Logs
|
||||
|
||||
@@ -105,22 +76,17 @@ export LOG_LEVEL='info'
|
||||
docker logs -f openflare-relay
|
||||
```
|
||||
|
||||
If managed via systemd on Linux, execute:
|
||||
```bash
|
||||
journalctl -u openflare-relay -f
|
||||
```
|
||||
### 2. Verify Runtime State
|
||||
|
||||
### 2. Verify Runtime Status
|
||||
After starting successfully, the Relay will:
|
||||
- Send HTTP heartbeats to the control plane to register/go online.
|
||||
- Fetch the latest frps base config from the control plane (including `bindPort`, `vhostHTTPPort`, and the auto-generated tunnel auth credential `auth_token`).
|
||||
- Render the local `data/frps.toml` config file.
|
||||
- Spawn the child process `frps -c data/frps.toml`.
|
||||
- If the process exits unexpectedly, the Relay auto-restarts frps with exponential backoff (initial 1s, cap 60s).
|
||||
|
||||
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. Confirm in the Admin Panel
|
||||
|
||||
### 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**.
|
||||
Log in to the admin panel, navigate to **「Node Management」**, and confirm:
|
||||
- The TunnelRelay node status is marked **「Online」**.
|
||||
- The node type is correctly marked as **Relay node** and the frps runtime state is **Healthy**.
|
||||
|
||||
+250
-120
@@ -1,170 +1,300 @@
|
||||
# Launch Server
|
||||
# Start the Server
|
||||
|
||||
You will learn: How to build the admin frontend from source, start the OpenFlare Server, choose between SQLite or PostgreSQL, and access Swagger.
|
||||
You will learn: how to deploy with Docker (quick start, production-recommended, advanced) and how to deploy the OpenFlare Server locally from source.
|
||||
|
||||
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.
|
||||
The OpenFlare Server is a Gin + GORM monolithic control plane responsible for the admin UI, admin API, Agent API, config rendering, version release, data storage, and aggregation queries.
|
||||
|
||||
## Prerequisites
|
||||
> [!IMPORTANT]
|
||||
> **About external dependencies**:
|
||||
> OpenFlare has built-in support for background async tasks (Asynq framework). Therefore, **regardless of deployment mode, Redis (or Valkey) is required**. The main difference between deployment options is the primary relational DB choice (SQLite vs PostgreSQL) and whether tracing (Jaeger) is enabled.
|
||||
> For high business traffic, ClickHouse is recommended for log storage.
|
||||
|
||||
| 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 |
|
||||
> [!TIP]
|
||||
> **ClickHouse server performance config (recommended mount)**
|
||||
> The control plane is typically a small host (e.g. 3c6g). The `performance.xml` provided in the repo tightens the background merge/mutation thread pools, avoiding high idle CPU or ClickHouse 25.x startup validation failures on small machines.
|
||||
> Mount the local `./config/clickhouse/performance.xml` as a single file at `/etc/clickhouse-server/config.d/performance.xml` to keep the official image's built-in Docker network listening config.
|
||||
|
||||
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:
|
||||
Pull the config locally before deploying:
|
||||
|
||||
```bash
|
||||
cd openflare-server/web
|
||||
corepack enable
|
||||
pnpm install
|
||||
pnpm build
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
```
|
||||
|
||||
Common frontend quality checks:
|
||||
Add it to the ClickHouse service `volumes` (alongside the data volume):
|
||||
|
||||
```bash
|
||||
pnpm lint
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
```yaml
|
||||
volumes:
|
||||
- ./data/clickhouse_data:/var/lib/clickhouse # or named volume
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
```
|
||||
|
||||
## 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).
|
||||
After modifying `performance.xml`, run `docker compose restart clickhouse` for it to take effect.
|
||||
|
||||
---
|
||||
|
||||
### 2. One-click Startup via Docker Compose (Integrated PostgreSQL)
|
||||
## Method 1: Docker Deployment (recommended)
|
||||
|
||||
We recommend using Docker Compose in production environments to orchestrate an independent PostgreSQL database and establish high-availability relationships.
|
||||
Docker deployment avoids configuring Go and Node.js frontend build environments locally. Choose one of the three options based on your hardware and needs:
|
||||
|
||||
Create a `docker-compose.yml` file:
|
||||
### 1. Quick Start (SQLite + Redis)
|
||||
|
||||
> **Use case**: testing/experience, lightweight single-machine deployment.
|
||||
>
|
||||
> **Features**: primary relational DB is SQLite.
|
||||
|
||||
Create a `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
container_name: openflare-server
|
||||
restart: unless-stopped
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- ./openflare-data:/data
|
||||
- ./uploads:/app/uploads
|
||||
environment:
|
||||
TZ: Asia/Shanghai
|
||||
APP_SESSION_SECRET: 'replace-with-a-long-random-string' # replace with a long random string in production
|
||||
DB_ENABLED: "false" # disables PostgreSQL, auto-enables the built-in SQLite fallback
|
||||
SQLITE_PATH: "/data/openflare.db"
|
||||
REDIS_ENABLED: "true"
|
||||
REDIS_ADDR: "redis:6379"
|
||||
depends_on:
|
||||
redis:
|
||||
condition: service_healthy
|
||||
|
||||
redis:
|
||||
image: valkey/valkey:8.0-alpine
|
||||
restart: unless-stopped
|
||||
command: ["valkey-server", "--appendonly", "yes"]
|
||||
volumes:
|
||||
- ./data/valkey:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "valkey-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Small-Traffic Business (PostgreSQL + Redis)
|
||||
|
||||
> **Use case**: production, small-to-medium traffic; PostgreSQL won't be the log-write bottleneck.
|
||||
|
||||
Create a `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
restart: unless-stopped
|
||||
env_file: .env
|
||||
environment:
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- openflare_uploads:/app/uploads
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_DB: openflare
|
||||
POSTGRES_USER: openflare
|
||||
POSTGRES_PASSWORD: replace-with-strong-password
|
||||
POSTGRES_DB: ${DB_NAME:-openflare}
|
||||
POSTGRES_USER: ${DB_USERNAME:-openflare}
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD:-replace-with-strong-password}
|
||||
volumes:
|
||||
- ./postgres-data:/var/lib/postgresql/data
|
||||
- openflare_postgres_data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U openflare -d openflare"]
|
||||
test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-openflare} -d ${DB_NAME:-openflare}"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
redis:
|
||||
image: valkey/valkey:8.0-alpine
|
||||
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
|
||||
command: ["valkey-server", "--appendonly", "yes"]
|
||||
volumes:
|
||||
- ./openflare-data:/data
|
||||
- openflare_redis_data:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "valkey-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
```
|
||||
|
||||
Start the services:
|
||||
Create a matching `.env` file for system env vars (copy and modify the root `.env.example`):
|
||||
|
||||
```bash
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
# edit .env: fill in DB, Redis, passwords, and APP_SESSION_SECRET
|
||||
|
||||
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
|
||||
### 3. Advanced (full orchestration with Jaeger tracing)
|
||||
|
||||
```bash
|
||||
go run . --port 3000 --log-dir ./logs
|
||||
> **Use case**: high traffic; needs trace performance metrics.
|
||||
>
|
||||
> **Features**: on top of the "production-recommended" bundle, stores logs with ClickHouse and uses Jaeger as the OpenTelemetry (OTel) tracing backend.
|
||||
|
||||
Create a `docker-compose.yaml`:
|
||||
|
||||
```yaml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
openflare:
|
||||
image: ghcr.io/rain-kl/openflare:latest
|
||||
restart: unless-stopped
|
||||
env_file: .env
|
||||
environment:
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
OTEL_EXPORTER_OTLP_ENDPOINT: "http://jaeger:4317"
|
||||
OTEL_EXPORTER_OTLP_INSECURE: "true"
|
||||
OTEL_SAMPLING_RATE: "1.0" # sampling rate; 1.0 samples all traces
|
||||
ports:
|
||||
- "3000:3000"
|
||||
volumes:
|
||||
- openflare_uploads:/app/uploads
|
||||
depends_on:
|
||||
postgres:
|
||||
condition: service_healthy
|
||||
redis:
|
||||
condition: service_healthy
|
||||
clickhouse:
|
||||
condition: service_healthy
|
||||
jaeger:
|
||||
condition: service_started
|
||||
|
||||
postgres:
|
||||
image: postgres:17-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
POSTGRES_DB: ${DB_NAME:-openflare}
|
||||
POSTGRES_USER: ${DB_USERNAME:-openflare}
|
||||
POSTGRES_PASSWORD: ${DB_PASSWORD:-replace-with-strong-password}
|
||||
volumes:
|
||||
- openflare_postgres_data:/var/lib/postgresql/data
|
||||
healthcheck:
|
||||
test: ["CMD-SHELL", "pg_isready -U ${DB_USERNAME:-openflare} -d ${DB_NAME:-openflare}"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
|
||||
redis:
|
||||
image: valkey/valkey:8.0-alpine
|
||||
restart: unless-stopped
|
||||
command: ["valkey-server", "--appendonly", "yes"]
|
||||
volumes:
|
||||
- openflare_redis_data:/data
|
||||
healthcheck:
|
||||
test: ["CMD", "valkey-cli", "ping"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 5s
|
||||
|
||||
jaeger:
|
||||
image: jaegertracing/jaeger:2.19.0
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ports:
|
||||
- "16686:16686" # Web UI port
|
||||
- "4317:4317" # OTLP gRPC receive port
|
||||
- "4318:4318" # OTLP HTTP receive port
|
||||
|
||||
clickhouse:
|
||||
image: clickhouse/clickhouse-server:25.3-alpine
|
||||
restart: unless-stopped
|
||||
environment:
|
||||
CLICKHOUSE_DB: ${CLICKHOUSE_NAME:-openflare}
|
||||
CLICKHOUSE_USER: ${CLICKHOUSE_USERNAME:-default}
|
||||
CLICKHOUSE_PASSWORD: ${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}
|
||||
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
|
||||
TZ: ${TZ:-Asia/Shanghai}
|
||||
ulimits:
|
||||
nofile:
|
||||
soft: 262144
|
||||
hard: 262144
|
||||
volumes:
|
||||
- openflare_clickhouse_data:/var/lib/clickhouse
|
||||
- ./config/clickhouse/performance.xml:/etc/clickhouse-server/config.d/performance.xml:ro
|
||||
healthcheck:
|
||||
test: ["CMD", "clickhouse-client", "--user", "${CLICKHOUSE_USERNAME:-default}", "--password", "${CLICKHOUSE_PASSWORD:-replace-with-clickhouse-password}", "--query", "SELECT 1"]
|
||||
interval: 10s
|
||||
timeout: 5s
|
||||
retries: 5
|
||||
start_period: 15s
|
||||
|
||||
volumes:
|
||||
openflare_uploads:
|
||||
openflare_postgres_data:
|
||||
openflare_redis_data:
|
||||
openflare_clickhouse_data:
|
||||
```
|
||||
|
||||
| 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` |
|
||||
Start and verify:
|
||||
|
||||
```bash
|
||||
mkdir -p ./config/clickhouse
|
||||
curl -fsSL -o ./config/clickhouse/performance.xml \
|
||||
https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/config/clickhouse/performance.xml
|
||||
curl -o .env.example https://raw.githubusercontent.com/Rain-kl/OpenFlare/refs/heads/main/.env.example
|
||||
cp .env.example .env
|
||||
# edit .env and make sure APP_SESSION_SECRET password is set
|
||||
|
||||
docker compose up -d
|
||||
```
|
||||
After startup, open `http://localhost:16686` to view the Jaeger monitoring UI and system span traces.
|
||||
|
||||
---
|
||||
|
||||
## First Login
|
||||
|
||||
Default credentials:
|
||||
The Server listens on port `3000` by default; open `http://localhost:3000` in a browser after startup.
|
||||
|
||||
Default admin account:
|
||||
|
||||
| Username | Password |
|
||||
| --- | --- |
|
||||
| `root` | `123456` |
|
||||
| `admin` | `12345678` |
|
||||
|
||||
Please change the default password immediately after your first login.
|
||||
> [!WARNING]
|
||||
> For your system's security, change the default password immediately in your profile settings after the first login.
|
||||
|
||||
---
|
||||
|
||||
## Distributed Deployment
|
||||
|
||||
In large production deployments, split the Server into multiple processes by responsibility:
|
||||
|
||||
```bash
|
||||
go run main.go api # API service for admin panel and node communication only
|
||||
go run main.go worker # background task Worker service only
|
||||
go run main.go scheduler # scheduled task Scheduler service only
|
||||
```
|
||||
|
||||
@@ -1,52 +1,20 @@
|
||||
# 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.
|
||||
You will learn: how to upgrade the Server and Agent, how to clean up observability data, and which verification commands to run 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.
|
||||
Before upgrading, confirm the current active version, the most recent Agent apply result, and the DB backup policy. In production, don't upgrade while a config release, a large-scale Agent reconnect, or a DB migration is 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:
|
||||
Pull the latest image and upgrade:
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs -n 100 openflare
|
||||
docker compose pull
|
||||
docker compose up
|
||||
```
|
||||
|
||||
If deployed from source, restart the Server and verify that no database migration or startup errors appear in the logs.
|
||||
For source deployments, restart the Server and confirm the logs show no DB migration or startup errors.
|
||||
|
||||
## 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.
|
||||
The Agent only caches runtime config and state files locally — no business data. To upgrade, directly pull the latest image and recreate the container. For specific deployment commands and install methods, see **[Access Agent](./agent.md)**.
|
||||
|
||||
Reference in New Issue
Block a user