tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-30 22:26:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(i18n): 同步 24 篇旧英文文档与中文最新内容

Browse Source 
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
2026-08-16 23:27:18 +08:00
parent 454542c1d0
commit e7b8fb2f99
24 changed files with 1985 additions and 2361 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/reference/cli.md
+67 -49
View File
@@ -1,111 +1,129 @@
# CLI Commands
# Commands & Scripts
You will learn: Common commands for starting, building, testing, installing, and uninstalling the OpenFlare Server, Admin Frontend, Agent, Swagger, and Documentation site.
You will learn: common start, build, test, install, and uninstall commands for the OpenFlare Server, admin frontend, Agent, Relay, OpenFlared, Swagger, and the docs site.
> All commands run at the **repo root** unless noted otherwise.
## Server
Start from source:
Source startup:
```bash
cd openflare-server
export SESSION_SECRET='replace-with-random-string'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
go run .
cp config.example.yaml config.yaml
go run main.go all
```
Specify listening port and logging directory:
Split processes:
```bash
go run . --port 3000 --log-dir ./logs
go run main.go api # HTTP API only
go run main.go worker # Asynq Worker only
go run main.go scheduler # scheduled tasks only
```
Run tests:
Build the binary:
```bash
make build-backend
# output: bin/openflare-server
```
Tests:
```bash
cd openflare-server
GOCACHE=/tmp/openflare-go-cache go test ./...
```
## Frontend
Development:
Quality gate:
```bash
cd openflare-server/web
make code-check
```
Auto-format backend Go source (organize imports) and frontend source:
```bash
make format
```
This command uses `goimports` to organize backend Go imports and the repo-pinned Prettier version to format `frontend/` source; build artifacts, dependencies, public static assets, and lock files are ignored.
## Frontend
Dev:
```bash
cd frontend
pnpm install
pnpm dev
```
Build static assets:
Build the embedded artifact (hosted by the Go Server):
```bash
cd openflare-server/web
pnpm build
cd frontend
pnpm build:embed
# or at repo root: make build-embedded
```
Linting and testing checks:
Checks:
```bash
cd openflare-server/web
cd frontend
pnpm lint
pnpm typecheck
pnpm test
pnpm tsc --noEmit --jsx preserve
pnpm check:i18n
```
## Agent
Run from source:
Source run:
```bash
cd openflare-agent
go run ./cmd/agent -config /path/to/agent.json
```
Compile:
Build:
```bash
cd openflare-agent
go build -o openflare-agent ./cmd/agent
make build-agent
# or: go build -o bin/openflare-agent ./cmd/agent
```
Run tests:
Tests:
```bash
cd openflare-agent
GOCACHE=/tmp/openflare-go-cache go test ./...
GOCACHE=/tmp/openflare-go-cache go test ./internal/apps/agent/...
```
## Relay (Server-side)
## Relay
Run from source:
Source run:
```bash
cd openflare-relay
go run ./cmd -config /path/to/relay.json
go run ./cmd/relay -config /path/to/relay.json
```
Compile:
Build:
```bash
cd openflare-relay
go build -o openflare-relay ./cmd
make build-relay
# or: go build -o bin/openflare-relay ./cmd/relay
```
## OpenFlared (Client-side)
## OpenFlared (Tunnel client)
Run from source:
Source run:
```bash
cd openflared
go run ./cmd -config /path/to/flared.json
go run ./cmd/flared -config /path/to/flared.json
```
Compile:
Build:
```bash
cd openflared
go build -o openflared ./cmd
make build-flared
# or: go build -o bin/flared ./cmd/flared
```
## Install Agent
@@ -124,14 +142,14 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
## Swagger
Regenerate Swagger documentation:
Regenerate the Swagger docs:
```bash
go install github.com/swaggo/swag/cmd/swag@v1.16.4
cd openflare-server
swag init -g main.go -o docs
make swagger
```
Access: `http://localhost:3000/api/swagger/index.html` (default `api_prefix` `/api`; only mounted in non-production)
## Docs
Local preview:
docs/en/reference/configuration.md
+365 -328
View File
@@ -1,370 +1,407 @@
# Configuration Options
# Configuration
You will learn: What configuration sources are supported by OpenFlare Server, frontend builds, and Agents; what the default configuration values are; and how to configure common deployment combinations.
You will learn: which config sources OpenFlare Server, frontend build, Agent, Relay, and OpenFlared support, what config fields and env vars exist, and their defaults and behavior.
This document aggregates the currently supported configuration options for OpenFlare Server and Agent in version `1.0.0`, keeping only running parameters that are currently active.
This document summarizes all configuration items supported by the current OpenFlare version.
## Configuration Sources
---
The Server supports three types of configuration sources:
## Config Sources
1. CLI arguments.
2. Environment variables.
3. Runtime configurations in the database `options` table.
### 1. Server Config Sources
- **Config file**: reads `config.yaml` in the same directory at startup by default (overridable via the `CONFIG_PATH` env var).
- **Env vars**: every field in the config file can be overridden by an `UPPER_SNAKE_CASE` env var (env vars take precedence over `config.yaml`).
- **System runtime config**: stored in the `w_system_configs` table in the relational DB. These can be hot-updated and take effect dynamically via the admin UI or system API.
The Agent supports:
### 2. Agent / Relay / OpenFlared Config Sources
- **CLI args**: `-config` specifies the config file (JSON format).
- **Config file**: e.g. `agent.json`, `relay.json`, `flared.json`.
- **Override env vars**: specific env vars can override connection addresses and Token credentials in the config file.
1. The `-config` CLI argument.
2. The `agent.json` configuration file.
3. A small set of environment variables for overriding logs and settings.
---
The Relay (Server-side) supports:
## Config File Locations
1. The `-config` CLI argument.
2. The `relay.json` configuration file.
3. Persistent environment variables for overriding runtime flags.
The Client (Intranet Client) supports:
1. The `-config` CLI argument.
2. The `flared.json` configuration file.
3. Startup overrides and logging environment variables.
## Configuration File Locations
| Component | Default Location | Description |
| Component | Default Location | Notes |
| --- | --- | --- |
| Server SQLite | `openflare.db` | Can be customized via `SQLITE_PATH` |
| Agent Config | `./agent.json` | Can be specified via `-config` |
| One-Click Agent | `/opt/openflare-agent/agent.json` | Generated by the installation script by default |
| Agent Data Dir | `data` in the config folder | Can be customized via `data_dir` |
| Relay Config | `./relay.json` | Can be specified via `-config` |
| One-Click Relay | `/opt/openflare-relay/relay.json` | Generated by the installation script by default |
| Client Config | `./flared.json` | Can be specified via `-config` |
| One-Click Client | `/opt/openflared/flared.json` | Generated by the installation script by default |
| Server config file | `./config.yaml` | overridable via `CONFIG_PATH` |
| Server SQLite DB | `openflare.db` | overridable via `database.sqlite_path` / `SQLITE_PATH` |
| Agent config file | `./agent.json` | overridable via `-config` |
| One-click install Agent config | `/opt/openflare-agent/agent.json` | default path generated by the install script |
| Agent data dir | `data` next to the config file | overridable via `data_dir` |
| Relay config file | `./relay.json` | overridable via `-config` |
| One-click install Relay config | `/opt/openflare-relay/relay.json` | default path generated by the install script |
| Client config file | `./flared.json` | overridable via `-config` |
| One-click install Client config | `/opt/openflared/flared.json` | default path generated by the install script |
## Server CLI Arguments
---
## Server CLI Args
```bash
cd openflare-server
go run . --port 3000 --log-dir ./logs
# specify a config file when starting the Server
CONFIG_PATH=/path/to/custom-config.yaml ./openflare-server all
```
| Argument | Description | Default Value |
| --- | --- | --- |
| `--port` | Port the Server listens on | `3000` |
| `--log-dir` | Directory to output logs | Empty (stdout) |
| `--version` | Outputs current version and exits | `false` |
| `--help` | Outputs help information and exits | `false` |
Supported sub-service commands (fused/single-process mode):
- `all`: starts all services in one process (API + Worker + Scheduler, default).
- `api`: starts only the API service for the admin panel and node communication.
- `worker`: starts only the background-task Worker service.
- `scheduler`: starts only the scheduled-task Scheduler service.
## Server Environment Variables
---
| Environment Variable | Description | Default Value |
| --- | --- | --- |
| `PORT` | Port the Server listens on | `3000` |
| `GIN_MODE` | Gin framework running mode | Defaults to release unless `debug` |
| `LOG_LEVEL` | Logging level | `info` |
| `SESSION_SECRET` | Session signing key | Randomly generated on startup |
| `SQLITE_PATH` | SQLite database file path | `openflare.db` |
| `DSN` | PostgreSQL DSN (takes precedence over SQLite) | Empty |
| `SQL_DSN` | Legacy PostgreSQL DSN (lower priority than `DSN`) | Empty |
| `REDIS_CONN_STRING` | Redis connection string | Empty |
| `AGENT_TOKEN` | Legacy global Agent Token | Empty |
## Server Env Vars vs Config File
Notes:
All Server core base config is defined in `config.yaml`, and every field supports env-var overrides (env vars take precedence over the YAML file).
* If both `DSN` and `SQL_DSN` exist, `DSN` is prioritized.
* If either `DSN` or `SQL_DSN` coexist with `SQLITE_PATH`, PostgreSQL is prioritized.
* If the target PostgreSQL database is empty and a local SQLite file exists at `SQLITE_PATH`, the Server automatically migrates SQLite data table-by-table on startup.
* `SESSION_SECRET` must be explicitly configured in production.
* If `REDIS_CONN_STRING` is unconfigured, co-located features fall back to in-memory implementations.
## Runtime Options
The following options are maintained in the admin settings page and support hot reloading:
| Parameter | Description | Default Value |
| --- | --- | --- |
| `AgentHeartbeatInterval` | Heartbeat interval for Agents (ms) | `10000` |
| `AgentWebsocketUpgradeEnabled` | Toggles WebSocket upgrades after successful HTTP heartbeat | `true` |
| `NodeOfflineThreshold` | Threshold duration to mark a node offline (ms) | `120000` |
| `AgentUpdateRepo` | GitHub repository for Agent self-updates | `Rain-kl/OpenFlare` |
| `GeoIPProvider` | Geolocation resolution provider | `ipinfo` |
| `DatabaseAutoCleanupEnabled` | Toggles daily automatic cleanup of observability logs | `false` |
| `DatabaseAutoCleanupRetentionDays` | Data retention duration in days, minimum 1 day | `30` |
| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | Global API rate limit count / window | `300` / `180` |
| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | Global Web rate limit count / window | `300` / `180` |
| `CriticalRateLimitNum` / `CriticalRateLimitDuration` | Sensitive API rate limit count / window | `100` / `1200` |
Notes:
* When `DatabaseAutoCleanupEnabled` is enabled, the Server deletes `node_access_logs`, `node_metric_snapshots`, and `node_request_reports` daily at 3:00 AM.
* `DatabaseAutoCleanupRetentionDays` must be greater than or equal to 1.
* Leaving retention days blank during a manual trigger in the console deletes all historic logs instantly.
* The GitHub Release in `AgentUpdateRepo` must contain a matching `.sha256` checksum file for every Agent binary (e.g., `openflare-agent-linux-amd64.sha256`); the Agent validates this checksum before replacing the local executable.
* Third-party logins no longer use `GitHubOAuthEnabled`, `GitHubClientId`, and `GitHubClientSecret` as main configuration entrypoints; these legacy options are used only for migrating default GitHub credentials during upgrades.
* The legacy WeChat login options are kept for backward compatibility, but the option page no longer edits them.
* Legacy Cloudflare Turnstile options and validation logic are retained and will work normally.
## OpenResty Parameters
OpenResty performance and caching parameters are managed in the `options` table, including:
* `OpenRestyWorkerProcesses`
* `OpenRestyWorkerConnections`
* `OpenRestyWorkerRlimitNofile`
* `OpenRestyKeepaliveTimeout`
* `OpenRestyProxyConnectTimeout`
* `OpenRestyProxySendTimeout`
* `OpenRestyProxyReadTimeout`
* `OpenRestyProxyBufferingEnabled`
* `OpenRestyGzipEnabled`
* `OpenRestyCacheEnabled`
* `OpenRestyCachePath`
* `OpenRestyCacheMaxSize`
These parameters must be validated, saved, and rendered structurally.
Constraints:
* The console no longer exposes `resolver` settings.
* Upstreams are rendered uniformly as named `upstream` blocks with keepalive enabled.
* Single upstreams carrying a base path or query have their URI correctly appended in `proxy_pass`.
* Multi-upstreams must be pure `scheme://host[:port]` using the same protocol within a single rule.
* `OpenRestyCacheEnabled` enables cache infrastructure and global defaults; the actual caching matching policies (by URL, suffix, or path) are configured per `proxy_routes`.
* The default cache key is `$scheme$host$request_uri`.
* Default `keepalive_timeout` is `20` seconds; default `proxy_connect_timeout` is `3` seconds.
* The default event model is `epoll` with `multi_accept` enabled.
* HTTPS listeners use the independent `http2 on;` directive to avoid deprecation warnings for `listen ... http2` in newer Nginx/OpenResty versions.
## Frontend Build Environment Variables
| Environment Variable | Description | Default Value |
| --- | --- | --- |
| `NEXT_PUBLIC_API_BASE_URL` | Base path for frontend API calls | `/api` |
| `NEXT_PUBLIC_APP_VERSION` | Application version shown in the UI | `dev` |
| `NEXT_DEV_BACKEND_URL` | Target backend proxied by the local dev server | `http://127.0.0.1:3000` |
## Agent Environment Variables
| Environment Variable | Description | Default Value |
| --- | --- | --- |
| `LOG_LEVEL` | Logging level for the Agent | `info` |
| `OPENFLARE_SERVER_URL` | Server URL; overrides `agent.json` | Empty |
| `OPENFLARE_AGENT_TOKEN` | Node-specific Token; overrides `agent.json` | Empty |
| `OPENFLARE_DISCOVERY_TOKEN` | Auto-registration Token; overrides `agent.json` | Empty |
| `OPENFLARE_NODE_NAME` | Node name; overrides `agent.json` | Empty |
| `OPENFLARE_NODE_IP` | Node IP; overrides `agent.json` | Empty |
| `OPENFLARE_DATA_DIR` | Agent data directory; overrides `agent.json` | Empty |
| `OPENFLARE_OPENRESTY_PATH` | Path to OpenResty binary; overrides `agent.json` | Empty |
| `OPENFLARE_HEARTBEAT_INTERVAL` | Heartbeat interval; overrides `agent.json` | Empty |
| `OPENFLARE_REQUEST_TIMEOUT` | Request timeout; overrides `agent.json` | Empty |
| `OPENFLARE_OPENRESTY_OBSERVABILITY_PORT` | Local observability port; overrides `agent.json` | Empty |
| `OPENFLARE_MMDB_PATH` | WAF GeoIP mmdb path; overrides `agent.json` | Empty |
| `OPENFLARE_MMDB_UPDATE_INTERVAL` | GeoIP mmdb update interval; overrides `agent.json` | Empty |
| `OPENFLARE_MMDB_DOWNLOAD_URL` | GeoIP mmdb download link; overrides `agent.json` | Empty |
## Agent CLI Arguments
| Argument | Description | Default Value |
| --- | --- | --- |
| `-config` | Path to the Agent configuration file | `./agent.json` |
## Agent Configurations Fields
| Field | Description | Required | Default Value / Behavior |
### 1. App Basic Config (`app:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `server_url` | Control plane URL | Yes | None |
| `agent_token` | Node-specific access Token | Mutually exclusive with discovery_token | Empty |
| `discovery_token` | Global auto-registration Token | Mutually exclusive with agent_token | Empty |
| `node_name` | Node name | No | Hostname |
| `node_ip` | Node IP | No | Auto-detect, resolves outbound public IP via realip.cc first, falls back to local adapters |
| `openresty_path` | Path to the OpenResty binary | No | `"openresty"` |
| `openresty_observability_port` | Observability port for health checks | No | `18081` |
| `data_dir` | Agent data directory | No | `data` in the config folder |
| `main_config_path` | Write path for Nginx main configuration | No | `data_dir/etc/nginx/nginx.conf` |
| `route_config_path` | Write path for route configurations | No | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
| `access_log_path` | Write path for OpenResty access logs | No | `data_dir/var/log/openflare/access.log` |
| `cert_dir` | Write directory for SSL certificates | No | `data_dir/etc/nginx/certs` |
| `openresty_cert_dir` | Read directory for certificates in Nginx | No | Same as `cert_dir` |
| `lua_dir` | Write directory for Lua scripts and assets | No | `data_dir/etc/nginx/lua` |
| `openresty_lua_dir` | Read directory for Lua scripts in Nginx | No | Same as `lua_dir` |
| `runtime_config_dir` | Write directory for Agent runtime configs | No | `data_dir/etc/openflare` |
| `mmdb_path` | WAF GeoIP database file path | No | `data_dir/etc/openflare/GeoLite2-Country.mmdb` |
| `mmdb_update_interval` | WAF GeoIP database check interval | No | `86400000` milliseconds |
| `mmdb_download_url` | WAF GeoIP database download URL | No | Built-in GeoLite2 Country URL |
| `observability_buffer_path` | Buffer path for retry metrics logs | No | `data_dir/var/lib/openflare/observability-buffer.json` |
| `observability_replay_minutes` | Lookback window for metric retries | No | `15` |
| `state_path` | Path to store local state JSON file | No | `data_dir/var/lib/openflare/agent-state.json` |
| `heartbeat_interval` | Heartbeat polling interval | No | `10000` milliseconds |
| `request_timeout` | HTTP request timeout duration | No | `10000` milliseconds |
| `app.app_name` | `APP_NAME` | application identifier name | `openflare` |
| `app.env` | `APP_ENV` | runtime env (`development` / `testing` / `production`) | `production` |
| `app.addr` | `APP_ADDR` | service listen address and port | `:3000` |
| `app.node_id` | `APP_NODE_ID` | Snowflake node ID (0-1023); must be unique in multi-instance deploys | `1` |
| `app.api_prefix` | `APP_API_PREFIX` | route prefix for admin panel and API | `/api` |
| `app.graceful_shutdown_timeout` | `APP_GRACEFUL_SHUTDOWN_TIMEOUT` | graceful shutdown wait timeout (seconds) | `30` |
| `app.session_cookie_name` | `APP_SESSION_COOKIE_NAME` | session cookie name | `openflare_session_id` |
| `app.session_secret` | `APP_SESSION_SECRET` | session signature secret; **must be a random long string in production** | none (random) |
| `app.session_domain` | `APP_SESSION_DOMAIN` | shared-session cookie scope domain | empty |
| `app.session_age` | `APP_SESSION_AGE` | browser session lifetime (seconds) | `86400` (24h) |
| `app.session_http_only` | `APP_SESSION_HTTP_ONLY` | enable the cookie's HttpOnly attribute | `false` |
| `app.session_secure` | `APP_SESSION_SECURE` | enable the cookie's Secure attribute (HTTPS) | `false` |
Notes:
* `agent_token` and `discovery_token` cannot both be empty.
* `heartbeat_interval` and `request_timeout` support integer milliseconds or Go duration strings.
* If `AgentWebsocketUpgradeEnabled` is enabled on the Server, the Agent upgrades the HTTP heartbeat to WebSocket; it automatically falls back to HTTP heartbeats if it fails or disconnects.
* If `openresty_path` is left blank, the Agent calls `openresty` on the host.
* Periodic health checks query `http://127.0.0.1:<openresty_observability_port>/openflare/stub_status` instead of executing `openresty -t`; validation prior to reloads, starts, or rollbacks still runs `openresty -t -c <main_config_path>`.
* The Agent initializes and periodically updates `mmdb_path` to support GeoIP region checks; failures to update write warnings and do not disrupt configuration synchronizations.
* The Agent boots normally if `agent.json` is missing but environment variables (`OPENFLARE_SERVER_URL` and a Token) are available; environment variables override JSON settings.
* If `node_ip` is left blank, the Agent resolves its outbound IP via `https://realip.cc` first, which is suitable for Docker/NAT networks.
* If the Agent registers a private `node_ip`, the Server prioritizes saving the public TCP connection IP, preventing NAT adapters from registering internal IPs.
* Enabling "Lock Node IP" in the console retains the manual IP; subsequent Agent registration or heartbeats do not overwrite it.
## Relay Environment Variables
| Environment Variable | Description | Default Value |
| --- | --- | --- |
| `LOG_LEVEL` | Logging level for the Relay | `info` |
| `OPENFLARE_SERVER_URL` | Server URL; overrides `relay.json` | Empty |
| `OPENFLARE_AGENT_TOKEN` | Node-specific Token; overrides `relay.json` | Empty |
| `OPENFLARE_DISCOVERY_TOKEN` | Auto-registration Token; overrides `relay.json` | Empty |
| `OPENFLARE_NODE_NAME` | Node name; overrides `relay.json` | Empty |
| `OPENFLARE_NODE_IP` | Node IP; overrides `relay.json` | Empty |
| `OPENFLARE_DATA_DIR` | Relay data directory; overrides `relay.json` | Empty |
| `OPENFLARE_FRPS_PATH` | frps binary path; overrides `relay.json` | Empty |
## Relay CLI Arguments
| Argument | Description | Default Value |
| --- | --- | --- |
| `-config` | Path to the Relay configuration file | `./relay.json` |
## Relay Configuration Fields
| Field | Description | Required | Default Value / Behavior |
### 2. Relational DB Config (`database:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `server_url` | Control plane URL | Yes | None |
| `agent_token` | Node-specific access Token | Mutually exclusive with discovery_token | Empty |
| `discovery_token` | Global auto-registration Token | Mutually exclusive with agent_token | Empty |
| `node_name` | Node name | No | Hostname |
| `node_ip` | Relay listening IP for tunnel traffic | No | Auto-detect, prioritizes outbound public IP |
| `frps_path` | Path to the `frps` binary | No | `frps` (system PATH) |
| `data_dir` | Relay runtime data directory | No | `data` in the config folder |
| `state_path` | Path to store local state JSON file | No | `data_dir/relay-state.json` |
| `heartbeat_interval` | Heartbeat polling interval | No | `10000` milliseconds, supports Go duration strings |
| `request_timeout` | HTTP request timeout duration | No | `10000` milliseconds, supports Go duration strings |
| `database.enabled` | `DB_ENABLED` | enable PostgreSQL; `false` falls back to SQLite | `true` |
| `database.sqlite_path` | `SQLITE_PATH` | SQLite DB file path when PostgreSQL disabled | `openflare.db` |
| `database.host` | `DB_HOST` | PostgreSQL host | `127.0.0.1` |
| `database.port` | `DB_PORT` | PostgreSQL port | `5432` |
| `database.username` | `DB_USERNAME` | PostgreSQL username | `openflare` |
| `database.password` | `DB_PASSWORD` | PostgreSQL password | `replace-with-strong-password` |
| `database.database` | `DB_NAME` | PostgreSQL database name | `openflare` |
| `database.ssl_mode` | `DB_SSL_MODE` | PostgreSQL SSL mode | `disable` |
| `database.time_zone` | `DB_TIMEZONE` | DB session timezone | `UTC` |
| `database.log_level` | `DB_LOG_LEVEL` | GORM SQL log level (`info` / `warn` / `error` / `silent`) | `info` |
| `database.max_idle_conn` | `DB_MAX_IDLE_CONN` | connection pool max idle | `16` |
| `database.max_open_conn` | `DB_MAX_OPEN_CONN` | connection pool max open | `128` |
## OpenFlared (Client) Environment Variables
| Environment Variable | Description | Default Value |
| --- | --- | --- |
| `LOG_LEVEL` | Logging level for the client | `info` |
| `OPENFLARE_SERVER_URL` | Server URL; overrides `flared.json` | Empty |
| `OPENFLARE_TUNNEL_TOKEN` | Tunnel access Token; overrides `flared.json` | Empty |
| `OPENFLARE_DATA_DIR` | Client data directory; overrides `flared.json` | Empty |
| `OPENFLARE_FRPC_PATH` | frpc binary path; overrides `flared.json` | Empty |
## OpenFlared (Client) CLI Arguments
| Argument | Description | Default Value |
| --- | --- | --- |
| `-config` | Path to the client configuration file | `./flared.json` |
## OpenFlared (Client) Configuration Fields
| Field | Description | Required | Default Value / Behavior |
### 3. Redis Config (`redis:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `server_url` | Control plane URL | Yes | None |
| `tunnel_token` | Tunnel dedicated access Token | Yes | None |
| `frpc_path` | Path to the `frpc` binary | No | `frpc` (system PATH) |
| `data_dir` | Client runtime data directory | No | `data` in the config folder |
| `state_path` | Path to store local state JSON file | No | `data_dir/flared-state.json` |
| `heartbeat_interval` | Heartbeat polling interval | No | `10000` milliseconds, supports Go duration strings |
| `sync_interval` | Configuration sync interval | No | `30000` milliseconds, supports Go duration strings |
| `request_timeout` | HTTP request timeout duration | No | `10000` milliseconds, supports Go duration strings |
| `redis.enabled` | `REDIS_ENABLED` | enable Redis. **The async queue and sync depend on it; must be on** | `true` |
| `redis.addrs` | `REDIS_ADDR` | Redis single/cluster address array (env var sets a single address) | `["127.0.0.1:6379"]` |
| `redis.username` | `REDIS_USERNAME` | Redis username (if any) | empty |
| `redis.password` | `REDIS_PASSWORD` | Redis password | empty |
| `redis.db` | `REDIS_DB` | Redis logical DB number | `0` |
| `redis.key_prefix` | `REDIS_KEY_PREFIX` | system key prefix in Redis | `openflare:` |
| `redis.pool_size` | `REDIS_POOL_SIZE` | Redis connection pool size | `100` |
| `redis.maint_notifications` | `REDIS_MAINT_NOTIFICATIONS` | enable Redis maintenance-notifications negotiation at startup; keep off when compatibility is unclear; restart needed after change | `false` |
## Common Configuration Combos
### 4. ClickHouse Config (`clickhouse:`)
### Production Server + PostgreSQL
> **Note**: these are OpenFlare **client** connection params. For ClickHouse **server** small-host tuning: curl `performance.xml` to `./config/clickhouse/`, then mount it as a single file at the container's `config.d/performance.xml` — see [Start the Server](../deployment/server.md).
```bash
export SESSION_SECRET='replace-with-a-long-random-string'
export DSN='postgres://openflare:replace-with-strong-password@postgres:5432/openflare?sslmode=disable'
export GIN_MODE='release'
export LOG_LEVEL='info'
```
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `clickhouse.enabled` | `CLICKHOUSE_ENABLED` | enable ClickHouse. **Node metrics and access logs are written here at scale**. Off by default: missing config or `false` disables it and the primary DB handles logs/metrics; explicit `true` or setting `CLICKHOUSE_HOST` enables it | `false` |
| `clickhouse.hosts` | `CLICKHOUSE_HOST` | ClickHouse cluster address array (env var sets a single address) | `["127.0.0.1:9000"]` |
| `clickhouse.username` | `CLICKHOUSE_USERNAME` | ClickHouse username | `default` |
| `clickhouse.password` | `CLICKHOUSE_PASSWORD` | ClickHouse password | `replace-with-clickhouse-password` |
| `clickhouse.database` | `CLICKHOUSE_NAME` | ClickHouse database name | `openflare` |
| `clickhouse.max_idle_conn` | - | client idle connections (low by default for small hosts) | `8` |
| `clickhouse.max_open_conn` | - | client max open connections | `16` |
| `clickhouse.conn_max_lifetime` | - | connection max lifetime (seconds) | `3600` |
| `clickhouse.dial_timeout` | - | dial timeout (seconds) | `5` |
| `clickhouse.block_buffer_size` | - | native-protocol block buffer rows | `32` |
### Local Server + SQLite
### 5. System Log Config (`log:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `log.level` | `LOG_LEVEL` | global log level (`debug` / `info` / `warn` / `error` / `fatal`) | `info` |
| `log.format` | `LOG_FORMAT` | log format (`console` readable / `json` structured) | `console` |
| `log.output` | `LOG_OUTPUT` | log output (`stdout` / `file`) | `stdout` |
| `log.file_path` | - | log file path when output is file | `./logs/app.log` |
| `log.max_size` | - | max single log file size (MB); auto-rotates beyond | `100` |
| `log.max_age` | - | max days to keep rotated log files | `30` |
```bash
export SESSION_SECRET='dev-session-secret'
export SQLITE_PATH='./openflare-dev.db'
export LOG_LEVEL='debug'
go run .
```
### 6. Async Task Worker Queue Config (`worker:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `worker.concurrency` | `WORKER_CONCURRENCY` | max concurrent tasks consumed by the background Worker | `20` |
| `worker.strict_priority`| `WORKER_STRICT_PRIORITY` | strictly assign consumer threads by queue priority (else weighted round-robin) | `false` |
### Agent + Default OpenResty
### 7. Tracing OpenTelemetry Config (`otel:`)
| YAML path | Override env var | Description | Default |
| --- | --- | --- | --- |
| `otel.sampling_rate` | `OTEL_SAMPLING_RATE` | global OTel sampling rate. `0.0` no sampling, `1.0` full tracing | `0.0` |
| `otel.tracer_name` | `OTEL_TRACER_NAME` | global OTel tracer instance name | `github.com/Rain-kl/OpenFlare` |
```json
{
"server_url": "http://your-server:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "/opt/openflare-agent/data",
"openresty_path": "openresty",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
---
### Agent + Customized OpenResty Paths
## Runtime System Config (SystemConfig)
```json
{
"server_url": "http://your-server: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
}
```
These items are stored in the `w_system_configs` table. Changes actively notify Redis cache invalidation for dynamic hot-update; admins manage them via the admin UI.
### Relay (Server-side) Default Configuration
### 1. Base & Business Runtime Config
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `site_name` | `string` | admin platform display name | `OpenFlare` |
| `server_address` | `string` | public access address of the admin console, used to assemble OAuth callbacks and download links | empty |
| `password_login_enabled` | `bool` | allow admin login with normal username/password | `true` |
| `registration_enabled` | `bool` | allow self-service new-user registration (off by default; root invites or distributes) | `false` |
| `password_register_enabled` | `bool` | allow direct email/password registration on the frontend | `false` |
| `oidc_login_enabled` | `bool` | enable OIDC (SSO) third-party passwordless login | `true` |
| `max_api_keys_per_user` | `int` | max API keys (API Tokens) per admin user | `5` |
| `login_session_ttl_hours` | `int` | user session lifetime in the browser cookie (hours). 0 = clear on browser close | `0` |
| `upload_allowed_extensions` | `string` | allowed upload file extensions (comma-separated; empty = unlimited) | `jpg,png,webp` |
| `file_access_whitelist` | `json` | file business types allowed for public download/access without login (JSON array) | `["avatar"]` |
| `disk_cache_max_size_mb` | `int` | platform local disk cache max storage (MB) | `100` |
| `disk_cache_ttl_minutes` | `int` | local disk cache object default TTL (minutes) | `60` |
| `disk_cache_lru_enabled` | `bool` | use LRU eviction when local disk cache space is low | `true` |
| `update_upstream_repository` | `string` | GitHub repo for self-update detection | `Rain-kl/OpenFlare` |
| `storage_config` | `json` | object-storage structured config (JSON): local disk and AWS S3-compatible storage | local-storage mode |
| `relay_frps_web_ui_enabled` | `bool` | enable the embedded frps traffic-monitoring Web UI on relay nodes | `false` |
| `relay_frps_web_ui_port` | `int` | host port the relay frps monitoring panel listens on | `17500` |
| `search_engine_indexing_enabled` | `bool` | allow search engines to crawl/index the site | `false` |
| `menu_display_config` | `string` | menu display structured config (JSON string, format `{url: enabled}`) | `{}` |
| `pages_max_package_size_mb` | `int` | Pages deployment package upload size cap (MiB, range 1–2048) | `100` |
| `pages_max_history_count` | `int` | max historical deployments kept per Pages project (0 = unlimited) | `20` |
`relay.json`:
### 2. Human Verification (PoW Captcha)
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `cap_login_enabled` | `bool` | require local PoW anti-brute-force human verification on the login page | `false` |
| `cap_auto_solve` | `bool` | auto-start background PoW computation on page load (no manual click) | `true` |
| `cap_challenge_count` | `int` | number of PoW challenges required. More = longer compute (recommended 1–5) | `1` |
| `cap_challenge_difficulty`| `int`| PoW hash prefix-match difficulty per challenge. Recommended 3-5 | `4` |
| `cap_challenge_size` | `int` | challenge salt length | `32` |
| `cap_challenge_ttl_seconds`| `int`| max valid time to submit the computed challenge (seconds); auto-invalidates on timeout | `600` |
| `cap_token_ttl_seconds` | `int` | validity of the login credential after solving (seconds); must log in within the window | `1200` |
```json
{
"server_url": "http://your-server:3000",
"agent_token": "replace-with-relay-auth-token",
"frps_path": "frps",
"data_dir": "/opt/openflare-relay/data",
"heartbeat_interval": 10000,
"request_timeout": 10000
}
```
### 3. SMTP Email Config
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `smtp_host` | `string` | SMTP server address | empty |
| `smtp_port` | `int` | SMTP port (usually 465 SSL or 587 STARTTLS) | `465` |
| `smtp_username` | `string` | SMTP account email | empty |
| `smtp_password` | `string` | SMTP account auth password/cert key (encrypted on save, never echoed) | empty |
| `email_login_verification_enabled` | `bool` | send a one-time 6-digit code for second-factor auth on email login | `false` |
| `email_register_verification_enabled` | `bool` | force email verification with a registration code for self-service registration | `false` |
### OpenFlared (Client-side) Default Configuration
### 4. Node & Agent Ops Runtime
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `agent_discovery_token` | `string` | global discovery Token for one-click first-time node registration | none (auto-generated on first visit) |
| `agent_heartbeat_interval`| `int` | standard heartbeat interval dispatched to all Agents (ms) | `3000` (3s) |
| `agent_websocket_upgrade_enabled` | `bool` | allow Agents to upgrade to a persistent WebSocket connection after HTTP heartbeat handshake | `true` |
| `node_offline_threshold` | `int` | no-response threshold (ms) after which a node is marked offline in the admin panel | `60000` (60s) |
| `agent_update_repo` | `string` | Release repo source for Agent self-binary updates | `Rain-kl/OpenFlare` |
| `geoip_provider` | `string` | GeoIP provider, e.g. `maxmind`, for WAF geo analysis | `ipinfo` |
`flared.json`:
### 5. Uptime Kuma Monitoring Sync
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `uptime_kuma_enabled` | `bool` | auto-sync generated Uptime Kuma HTTP monitors after config release/activation | `false` |
| `uptime_kuma_url` | `string` | Uptime Kuma instance access URL (with port and path) | empty |
| `uptime_kuma_username` | `string` | Uptime Kuma admin username for sync API auth | empty |
| `uptime_kuma_password` | `string` | Uptime Kuma login password (encrypted on save, never echoed) | empty |
| `uptime_kuma_monitor_scope`| `string` | route scope for auto-generated monitors (`all` sites or `selected`) | `all` |
| `uptime_kuma_selected_sites`| `string` | selected proxied-site Site Name list to monitor (comma-separated) | empty |
| `uptime_kuma_sync_interval`| `int` | differential scan/calibration sync frequency to the Uptime Kuma instance (minutes) | `5` |
| `uptime_kuma_interval` | `int` | HTTP GET probe period of generated monitors (seconds) | `60` |
| `uptime_kuma_retry` | `int` | max reconnect retries after probe connection failures | `0` |
| `uptime_kuma_retry_interval`| `int` | pause between failed reconnect retries (seconds) | `60` |
| `uptime_kuma_timeout` | `int` | timeout for an HTTP GET monitor request (seconds) | `48` |
```json
{
"server_url": "http://your-server:3000",
"tunnel_token": "replace-with-tunnel-token",
"frpc_path": "frpc",
"data_dir": "/opt/openflared/data",
"heartbeat_interval": 10000,
"sync_interval": 30000,
"request_timeout": 10000
}
```
### 6. OpenResty Core Main Config & Rendering Options
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `openresty_default_server_return_status` | `int` | status code returned for requests hitting no matching route by default | `421` |
| `openresty_worker_processes` | `string` | nginx `worker_processes`; fixed integer or `auto` | `auto` |
| `openresty_worker_connections` | `int` | nginx `worker_connections` per-process max connections | `4096` |
| `openresty_worker_rlimit_nofile` | `int` | nginx `worker_rlimit_nofile` max open file descriptors | `65535` |
| `openresty_events_use` | `string` | event polling engine (e.g. `epoll` preferred on Linux) | `epoll` |
| `openresty_events_multi_accept_enabled` | `bool` | accept all pending connection handshakes in one batch | `true` |
| `openresty_keepalive_timeout` | `int` | nginx `keepalive_timeout` (seconds) | `20` |
| `openresty_keepalive_requests` | `int` | max requests per reused TCP connection | `1000` |
| `openresty_client_header_timeout` | `int` | read timeout for the client Request Header (seconds) | `15` |
| `openresty_client_body_timeout` | `int` | read timeout for the client Request Body (seconds) | `15` |
| `openresty_client_max_body_size` | `string` | max client request Body size, with a unit like `10m`/`50m` | `64m` |
| `openresty_large_client_header_buffers` | `string` | buffers for oversized request headers (e.g. `4 16k`) | `4 16k` |
| `openresty_send_timeout` | `int` | max interval for sending Response data to the client (seconds) | `30` |
| `openresty_resolvers` | `string` | DNS resolver addresses/params for dynamic name resolution on nodes | empty |
| `openresty_proxy_connect_timeout` | `int` | TCP handshake timeout to the origin (seconds) | `3` |
| `openresty_proxy_send_timeout` | `int` | max interval for writing request data to the origin (seconds) | `60` |
| `openresty_proxy_read_timeout` | `int` | max wait for origin response data (seconds) | `60` |
| `openresty_websocket_enabled` | `bool` | auto-load WebSocket-supporting globals and headers in the HTTP section | `true` |
| `openresty_http3_enabled` | `bool` | render HTTP/3 QUIC dual-stack listen capability in generated nginx listens | `true` |
| `openresty_proxy_request_buffering_enabled`| `bool` | fully buffer the client Request Body before forwarding to the origin | `false` |
| `openresty_proxy_buffering_enabled` | `bool` | buffer large origin Response data before forwarding to the user | `true` |
| `openresty_proxy_buffers` | `string` | nginx proxy response buffer count/size (e.g. `16 16k`) | `16 16k` |
| `openresty_proxy_buffer_size` | `string` | buffer for origin Response Header | `8k` |
| `openresty_proxy_busy_buffers_size` | `string` | Busy-state buffer cap when response stream is oversized | `64k` |
| `openresty_gzip_enabled` | `bool` | enable gzip real-time compression on eligible content | `true` |
| `openresty_gzip_min_length` | `int` | file size threshold for gzip; below it, skip to save CPU | `1024` (1KB) |
| `openresty_gzip_comp_level` | `int` | gzip level 1-9; higher = more compression, more CPU | `5` |
| `openresty_cache_enabled` | `bool` | initialize the proxy cache region (Proxy Cache Path) in global config | `false` |
| `openresty_cache_path` | `string` | proxy cache temp physical dir on the node | `__OPENFLARE_PROXY_CACHE_PATH__` |
| `openresty_cache_levels` | `string` | proxy cache directory tree level layout | `1:2` |
| `openresty_cache_inactive` | `string` | time after which an unaccessed cache file is invalidated from disk | `30m` |
| `openresty_cache_max_size` | `string` | max disk quota for the proxy cache region on a node | `1g` |
| `openresty_cache_key_template` | `string` | default proxy cache key template | `$scheme$host$request_uri` |
| `openresty_cache_lock_enabled` | `bool` | queue/lock origin connections on high-concurrency cache misses for the same expired resource | `true` |
| `openresty_cache_lock_timeout` | `string` | max queue wait for the proxy cache lock | `5s` |
| `openresty_cache_use_stale` | `string` | serve stale cache on specific origin errors (500/502/504 etc.) | `error timeout updating http_500 http_502 http_503 http_504` |
| `openresty_default_limit_conn_per_server` | `int` | default concurrent-connection cap per server when a site has no config; `0` = off | `0` |
| `openresty_default_limit_conn_per_ip` | `int` | default per-IP concurrent cap when a site has no config; `0` = off | `0` |
| `openresty_default_limit_rate` | `string` | default per-request bandwidth when a site has no config (e.g. `512k`); empty = off | empty |
| `openresty_default_limit_req_per_ip` | `string` | default per-IP request rate limit when a site has no config (e.g. `10r/s`, `100r/m`); empty = off | empty |
| `openresty_main_config_template` | `string` | fully rewrite the OpenResty nginx.conf skeleton template | empty (built-in default skeleton) |
## Maintenance Rules
### 7. Origin Error Page
This document must be updated in sync when any of the following change:
Global origin error page config; written into the config version snapshot and distributed to edge Agents on release/rollback. Only affects **reverse proxy** routes; Pages static routes are unaffected. Admin entry:「Website Management → Error Page」. Design: [Origin Error Page Design](../design/origin-error-page.md).
* Server CLI arguments.
* Server environment variables.
* Agent CLI arguments and configuration parameters.
* Relay CLI arguments and configuration parameters.
* Client CLI arguments and configuration parameters.
* Default values, scopes, or examples of any configuration items.
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `origin_error_page_enabled` | `bool` | enable the global origin error page. When on, matching status codes from origin/gateway are replaced by custom/default HTML with the **HTTP status kept**; when off, no directives are generated and pass-through resumes. Requires a config release to take effect | `true` |
| `origin_error_page_get_only` | `bool` | only apply to **GET** requests. When on, only matching GET error statuses return the custom error page; POST/PUT and other methods **pass through the origin response** (original status and body unchanged) | `false` |
| `origin_error_page_status_codes` | `json` | status code tag JSON array triggering the error page. Supports single codes (e.g. `522`) and closed ranges (e.g. `500-599`); single codes and range endpoints must be in **400–599**, with `lo ≤ hi`. The expanded result must not be empty when enabled | `["500-599"]` |
| `origin_error_page_html` | `string` | custom error page HTML. Empty uses the built-in OpenFlare default template (minimal white); supports `{{status}}` (matches the HTTP status) and `{{host}}` (request Host). Max **256 KiB** (bytes). Don't embed untrusted third-party scripts | empty |
---
### 8. Log Database
Runtime config after log-store decoupling: the log primary DB is managed by the「Switch Log Database」task (internal/protected keys, forbidden for manual admin edits); access-log retention days are set per storage DB in business config; performance metrics (CPU/memory/disk/network) decay fast and use a shared short retention independent of the access-log retention config.
| Key | Type | Description | Default |
| --- | --- | --- | --- |
| `log_database` | `string` | current log primary DB (`postgres` / `sqlite` / `clickhouse`). **Internal protected key**: only written by the「Switch Log Database」migration task; admins can't create/modify manually | follows the primary DB (`postgres` when PostgreSQL enabled, else `sqlite`; `clickhouse` preferred when ClickHouse enabled) |
| `log_db_migration` | `string` | log migration freeze marker (`migrating` or empty). **Internal protected key**: only the migration task writes it; while set, log writes return 503「log DB migrating, not writable」 | empty |
| `log_retention_days_postgres` | `int` | access-log retention days in the PostgreSQL log DB (expired logs deleted by the daily garbage-collection task) | `30` |
| `log_retention_days_sqlite` | `int` | access-log retention days in the SQLite log DB | `30` |
| `log_retention_days_clickhouse` | `int` | access-log retention days in the ClickHouse log DB | `30` |
| `metric_retention_days` | `int` | performance metric (CPU/memory/disk/network) retention days; shared short retention across the three DBs (independent of access-log retention) | `3` |
---
## Frontend Build Env Vars
| Env var | Purpose | Default |
| --- | --- | --- |
| `WAVELET_BACKEND_URL` | backend address for server-side rendering and dev proxy | `http://localhost:3000` |
| `NEXT_PUBLIC_WAVELET_BACKEND_URL` | backend address for browser API requests; empty = same-origin | empty |
| `NEXT_PUBLIC_APP_VERSION` | displayed frontend version | `dev` |
---
## Agent Env Vars
| Env var | Purpose | Default |
| --- | --- | --- |
| `LOG_LEVEL` | Agent log level | `info` |
| `OPENFLARE_SERVER_URL` | control-plane address, overrides `agent.json` | empty |
| `OPENFLARE_AGENT_TOKEN` | node-specific auth Token, overrides `agent.json` | empty |
| `OPENFLARE_DISCOVERY_TOKEN` | first-time auto-registration Token, overrides `agent.json` | empty |
| `OPENFLARE_NODE_NAME` | node name, overrides `agent.json` | empty |
| `OPENFLARE_NODE_IP` | node IP, overrides `agent.json` | empty |
| `OPENFLARE_DATA_DIR` | Agent data dir, overrides `agent.json` | empty |
| `OPENFLARE_OPENRESTY_PATH` | OpenResty binary path, overrides `agent.json` | empty |
| `OPENFLARE_PAGES_DIR` | Pages static deployment dir, overrides `agent.json` | empty |
| `OPENFLARE_HEARTBEAT_INTERVAL` | heartbeat interval, overrides `agent.json` | empty |
| `OPENFLARE_REQUEST_TIMEOUT` | request timeout, overrides `agent.json` | empty |
| `OPENFLARE_OPENRESTY_OBSERVABILITY_PORT` | local observability port, overrides `agent.json` | empty |
| `OPENFLARE_MMDB_PATH` | WAF GeoIP mmdb path, overrides `agent.json` | empty |
| `OPENFLARE_MMDB_UPDATE_INTERVAL` | WAF GeoIP mmdb update interval, overrides `agent.json` | empty |
| `OPENFLARE_MMDB_DOWNLOAD_URL` | WAF GeoIP mmdb download URL, overrides `agent.json` | empty |
| `OPENFLARE_CITY_MMDB_PATH` | WAF City MMDB path, overrides `agent.json` | empty |
| `OPENFLARE_CITY_MMDB_DOWNLOAD_URL` | WAF City MMDB download URL, overrides `agent.json` | empty |
---
## Agent CLI Args and Config Fields
### CLI Args
- `-config`: Agent config file path, default `./agent.json`.
### Config File Fields (agent.json)
| Field | Purpose | Required | Default/Behavior |
| --- | --- | --- | --- |
| `server_url` | control-plane address | yes | none |
| `agent_token` | node-specific auth Token | one of two with `discovery_token` | empty |
| `discovery_token` | global Token for first-time auto-registration | one of two with `agent_token` | empty |
| `node_name` | node name | no | hostname automatically |
| `node_ip` | node IP | no | auto-detected, prefers the public egress IP; falls back to local NIC detection on failure |
| `openresty_path` | OpenResty binary path | no | `openresty` |
| `openresty_observability_port` | local observability & OpenResty health-check port | no | `18081` |
| `data_dir` | Agent data dir | no | `data` next to the config file |
| `main_config_path` | OpenResty main config write path | no | `data_dir/etc/nginx/nginx.conf` |
| `route_config_path` | route config write path | no | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
| `access_log_path` | OpenResty access log path | no | `data_dir/var/log/openflare/access.log` |
| `cert_dir` | certificate write dir | no | `data_dir/etc/nginx/certs` |
| `openresty_cert_dir` | certificate dir read by the OpenResty config | no | same as `cert_dir` |
| `lua_dir` | Lua scripts & static assets write dir | no | `data_dir/etc/nginx/lua` |
| `openresty_lua_dir` | Lua dir read by the OpenResty config | no | same as `lua_dir` |
| `runtime_config_dir` | Agent runtime config write dir, e.g. `pow_config.json` | no | `data_dir/etc/openflare` |
| `pages_dir` | Pages deployment package extraction & current deploy dir | no | `data_dir/var/lib/openflare/pages` |
| `mmdb_path` | WAF GeoIP mmdb file path | no | `data_dir/etc/openflare/GeoLite2-Country.mmdb` |
| `city_mmdb_path` | WAF City MMDB file path | no | `data_dir/etc/openflare/GeoLite2-City.mmdb` |
| `mmdb_update_interval` | WAF GeoIP mmdb update interval | no | `86400000` ms (24h) |
| `mmdb_download_url` | WAF GeoIP mmdb periodic update URL | no | GeoLite2 Country update URL; first download when the disk file is missing (Docker images COPY default-path files) |
| `city_mmdb_download_url` | WAF City MMDB periodic update URL | no | GeoLite2 City update URL; first download when the disk file is missing (Docker images COPY default-path files) |
| `observability_buffer_path` | observability backfill buffer file path | no | `data_dir/var/lib/openflare/observability-buffer.json` |
| `observability_replay_minutes` | auto-backfill recent observability window (minutes) | no | `60` |
| `state_path` | Agent local state file path | no | `data_dir/var/lib/openflare/agent-state.json` |
| `heartbeat_interval` | heartbeat interval | no | `3000` ms |
| `request_timeout` | HTTP request timeout | no | `10000` ms |
---
## Relay Env Vars and Config Fields
### Env Vars
- `LOG_LEVEL`: Relay log level, default `info`.
- Supports `OPENFLARE_SERVER_URL`, `OPENFLARE_AGENT_TOKEN`, `OPENFLARE_DISCOVERY_TOKEN`, `OPENFLARE_NODE_NAME`, `OPENFLARE_NODE_IP`, `OPENFLARE_DATA_DIR`, `OPENFLARE_FRPS_PATH` overrides.
### CLI Args
- `-config`: Relay config file path, default `./relay.json`.
### Config File Fields (relay.json)
| Field | Purpose | Required | Default/Behavior |
| --- | --- | --- | --- |
| `server_url` | control-plane address | yes | none |
| `agent_token` | relay node-specific auth Token | one of two with `discovery_token` | empty |
| `discovery_token` | global Token for first-time auto-registration | one of two with `agent_token` | empty |
| `node_name` | node name | no | hostname automatically |
| `node_ip` | relay node IP for receiving tunnel traffic | no | auto-detected, prefers the public egress IP; falls back to NIC detection on failure |
| `frps_path` | frps binary path | no | `frps` (found on system PATH) |
| `data_dir` | Relay runtime data dir | no | `data` next to the config file |
| `state_path` | Relay local state file path | no | `data_dir/relay-state.json` |
| `heartbeat_interval` | heartbeat interval | no | `10000` ms |
| `request_timeout` | HTTP request timeout | no | `10000` ms |
---
## OpenFlared (Client) Env Vars and Config Fields
### Env Vars
- `LOG_LEVEL`: Client log level, default `info`.
- Supports `OPENFLARE_SERVER_URL`, `OPENFLARE_TUNNEL_TOKEN`, `OPENFLARE_DATA_DIR`, `OPENFLARE_FRPC_PATH` overrides.
### CLI Args
- `-config`: Client config file path, default `./flared.json`.
### Config File Fields (flared.json)
| Field | Purpose | Required | Default/Behavior |
| --- | --- | --- | --- |
| `server_url` | control-plane address | yes | none |
| `tunnel_token` | tunnel-specific auth Token | yes | none |
| `frpc_path` | frpc binary path | no | `frpc` (found on system PATH) |
| `data_dir` | Client runtime data dir | no | `data` next to the config file |
| `state_path` | Client local state file path | no | `data_dir/flared-state.json` |
| `heartbeat_interval` | heartbeat interval | no | `10000` ms |
| `sync_interval` | config pull/sync interval | no | `30000` ms |
| `request_timeout` | HTTP request timeout | no | `10000` ms |
docs/en/reference/index.md
+6 -8
View File
@@ -1,13 +1,11 @@
# Reference Manuals
# Reference
You will learn: Which information belongs to stable reference manuals, and where to look up configurations, commands, APIs, and repository structures.
You will learn: which information counts as stable reference material, and where to look up config, commands, API, and repository structure.
This section collects stable information at the runtime, API, and repository layers, suitable for rapid lookup during deployment, integration, and troubleshooting.
This section consolidates stable runtime, interface, and repository-level information for quick reference during deployment, integration, and troubleshooting.
| Page | Content |
| --- | --- |
| [Configuration Options](./configuration.md) | Server environment variables, CLI arguments, runtime Options, and Agent configuration parameters |
| [CLI Commands](./cli.md) | Common CLI commands for starting, building, testing, installing, and uninstalling |
| [API Conventions](./api.md) | Response structures, authentication, and routing paths for Admin and Agent APIs |
| [Repository Structure](../design/repository.md) | Scope of responsibilities and folder layering of the Server, Agent, Relay, and Client |
| [Deployment & Upgrade](../deployment/) | Server and Agent deployment, configuration, and upgrade guides (dedicated section) |
| [Configuration](./configuration.md) | Server env vars, CLI args, runtime Options, and Agent config fields |
| [Commands & Scripts](./cli.md) | common start, build, test, install, and uninstall commands |
| [Repository Structure](../design/index.md#repository-structure) | monorepo directory responsibilities and layering (`main.go`, `cmd/`, `internal/apps/`, `frontend/`, etc.) |