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

[新增] 更新文档

Browse Source
This commit is contained in:
ryan
2026-05-28 22:56:39 +08:00
parent 5a0821274b
commit c856faca50
17 changed files with 171 additions and 98 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/guide/agent.md
+13 -3
View File
@@ -34,8 +34,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
"server_url": "http://127.0.0.1:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "./data",
"openresty_container_name": "openflare-openresty",
"openresty_docker_image": "openresty/openresty:alpine",
"openresty_path": "openresty",
"openresty_observability_port": 18081,
"observability_replay_minutes": 15,
"heartbeat_interval": 10000,
@@ -43,7 +42,18 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
}
```
Without `openresty_path`, Agent uses Docker OpenResty by default.
Without `openresty_path`, Agent runs `openresty` by default.
## Docker
```bash
docker run -d --name openflare-agent --restart unless-stopped \
-p 80:80 -p 443:443 -p 127.0.0.1:18081:18081 \
-v openflare-agent-data:/data \
-e OPENFLARE_SERVER_URL=http://your-server:3000 \
-e OPENFLARE_AGENT_TOKEN=YOUR_AGENT_TOKEN \
ghcr.io/rain-kl/openflare-agent:latest
```
## Run from Source
docs/en/guide/deployment.md
+8 -6
View File
@@ -2,7 +2,7 @@
You will learn the recommended OpenFlare deployment model, Server and Agent requirements, source startup workflow, integration steps, upgrade paths, and uninstall entry points.
For production, use PostgreSQL for the Server database and set `SESSION_SECRET` explicitly. Agent nodes use Docker OpenResty by default; local OpenResty mode requires `openresty_path` and write paths.
For production, use PostgreSQL for the Server database and set `SESSION_SECRET` explicitly. Agent controls OpenResty through the OpenResty binary; Docker deployments run the Agent image that already includes OpenResty.
## Topology
@@ -17,7 +17,7 @@ OpenFlare Server :3000
OpenFlare Agent
|
v
Local OpenResty or Docker OpenResty
OpenResty binary
|
v
Origin service
@@ -40,8 +40,8 @@ Agent:
| --- | --- |
| OS | Install script supports Linux and macOS. systemd service is created only on Linux + systemd. |
| Architecture | `amd64` or `arm64` |
| Docker | Required by the default Docker OpenResty mode |
| Local OpenResty | Required only when `openresty_path` is configured |
| OpenResty | Required for local Agent installs |
| Docker | Required only when running the Agent Docker image |
| Network | Agent node must reach the Server URL |
[Needs confirmation: recommended production CPU, memory, and disk size]
@@ -154,6 +154,7 @@ Supported options:
| `--discovery-token` | First-registration token, mutually exclusive with `--agent-token` |
| `--agent-token` | Node-specific token, mutually exclusive with `--discovery-token` |
| `--install-dir` | Install directory, default `/opt/openflare-agent` |
| `--openresty-path` | OpenResty binary path, auto-detected when omitted |
| `--repo` | GitHub repository for Agent downloads, default `Rain-kl/OpenFlare` |
| `--no-service` | Do not create a systemd service |
@@ -190,12 +191,13 @@ Minimal `agent.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
}
```
When `openresty_path` is not configured, Agent uses Docker OpenResty.
When `openresty_path` is not configured, Agent runs `openresty`.
## Minimal Integration Flow
@@ -227,7 +229,7 @@ Uninstall Agent:
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
```
The uninstall script stops Agent, removes the systemd service and install directory, and attempts to remove the Docker OpenResty container/image when Docker mode is detected. Local `openresty_path` mode does not remove the local OpenResty installation.
The uninstall script stops Agent and removes the systemd service and install directory. It does not remove the local OpenResty installation.
## Validation Commands
docs/en/guide/development.md
+4 -3
View File
@@ -21,7 +21,8 @@ This page is for contributors. Product boundaries, data model constraints, API c
| Go | `1.25+` |
| Node.js | `18+` |
| pnpm | Use `corepack enable` to follow the project-declared version |
| Docker | Needed for the default Docker OpenResty Agent mode and local integration |
| Docker | Needed for Server containers, local integration, and the Agent Docker image |
| OpenResty | Needed when running Agent locally |
| PostgreSQL | Optional. The Server uses SQLite when PostgreSQL is not configured. |
## Install Frontend Dependencies
@@ -106,7 +107,7 @@ export LOG_LEVEL='debug'
go run ./cmd/agent -config ./agent.json
```
When `openresty_path` is not configured, the Agent uses Docker OpenResty. To debug local OpenResty, set `openresty_path`, `main_config_path`, `route_config_path`, `cert_dir`, and `lua_dir`.
When `openresty_path` is not configured, the Agent runs `openresty`. For debugging, set `openresty_path`, `main_config_path`, `route_config_path`, `access_log_path`, `cert_dir`, `lua_dir`, and `runtime_config_dir` as needed.
## Tests
@@ -172,7 +173,7 @@ go build -o openflare-agent ./cmd/agent
| Agent logs | `LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json` |
| Swagger | `http://localhost:3000/swagger/index.html` |
| Frontend API proxy | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev` |
| Docker OpenResty container | `docker ps --filter name=openflare-openresty` |
| OpenResty config test | `openresty -t -c ./data/etc/nginx/nginx.conf` |
## Change Acceptance
docs/en/guide/quick-start.md
+4 -6
View File
@@ -10,13 +10,14 @@ The minimal OpenFlare setup contains:
| Agent | Runs on proxy nodes, pulls configuration, writes OpenResty files, validates, and reloads |
| OpenResty | Receives traffic and proxies requests to origins |
By default, the Agent uses Docker OpenResty when `openresty_path` is not configured. Prepare Docker on Agent nodes for this quick start.
Agent controls OpenResty through the OpenResty binary. Local installs need an `openresty` executable on the node; Docker installs can run the Agent image that already includes OpenResty.
## Requirements
| Item | Requirement |
| --- | --- |
| Docker / Docker Compose | Used to start Server and PostgreSQL, and used by the default Agent Docker OpenResty mode |
| Docker / Docker Compose | Used to start Server and PostgreSQL; also used if you run the Agent Docker image |
| OpenResty | Required for local Agent installs unless `--openresty-path` points to a custom binary |
| Reachable ports | Server listens on `3000` by default. Agent nodes must reach the Server URL. |
| Browser | Used to open the management UI |
@@ -128,7 +129,7 @@ The script defaults to:
| Install directory | `/opt/openflare-agent` |
| Config file | `/opt/openflare-agent/agent.json` |
| systemd service | `openflare-agent.service` |
| OpenResty mode | Docker OpenResty when `openresty_path` is not configured |
| OpenResty path | Auto-detects `openresty` unless `--openresty-path` is provided |
Check status:
@@ -166,11 +167,8 @@ On the Agent node:
```bash
journalctl -u openflare-agent -n 100 --no-pager
docker ps --filter name=openflare-openresty
```
If Docker OpenResty is used, the default container name is `openflare-openresty`.
## Common Failures
| Symptom | What to Check |
docs/en/guide/troubleshooting.md
+7 -8
View File
@@ -153,22 +153,21 @@ Common causes:
| Invalid upstream URL | Every upstream must be `http://` or `https://` |
| Invalid multi-upstream format | Multiple upstreams must be plain `scheme://host[:port]` |
| Missing certificate or wrong path | Check domain certificate binding and Agent certificate directory permissions |
| Port conflict | Check local or Docker `80` and `443` usage |
| Port conflict | Check local `80` and `443` usage |
Docker OpenResty mode:
OpenResty config test:
```bash
docker ps --filter name=openflare-openresty
docker logs --tail 100 openflare-openresty
openresty -t -c /path/to/openflare/data/etc/nginx/nginx.conf
```
Local OpenResty mode:
OpenResty runtime:
```bash
/usr/local/openresty/nginx/sbin/nginx -t
ps aux | grep openresty
```
Use the actual path from `openresty_path` in `agent.json`.
Use the actual `openresty_path` and `main_config_path` from `agent.json`.
## HTTPS Does Not Work
@@ -187,7 +186,7 @@ Domains without a bound certificate are not automatically added to HTTPS configu
## No Access Analytics
1. Confirm the node applied a configuration that includes observability Lua assets.
2. Confirm Docker OpenResty or local OpenResty is running.
2. Confirm OpenResty is running.
3. Check Agent logs for collection or replay failures.
4. Check whether `openresty_observability_port` is occupied. The default is `18081`.
5. Confirm Server cleanup policy did not remove data for that time window.