tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-10-02 06:56:36 +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/deployment/agent.md
+72 -89
View File
@@ -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 |