mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
[新增] 更新文档
This commit is contained in:
ryan
@@ -93,7 +93,7 @@ docker compose up -d
|
||||
|
||||
### 2. 安装 Agent
|
||||
|
||||
**注意:** 安装agent前需确保存已经安装了Docker, 虽然支持裸Openresty,但未得到充分验证,可能存在未知问题.
|
||||
安装 Agent 前请先在节点上安装 OpenResty，或改用内置 OpenResty 的 Agent Docker 镜像。
|
||||
|
||||
使用 `discovery_token` 接入：
|
||||
|
||||
@@ -111,7 +111,18 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
--agent-token YOUR_AGENT_TOKEN
|
||||
```
|
||||
|
||||
安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，并可重复执行以重装或升级 Agent。
|
||||
安装脚本默认写入 `/opt/openflare-agent`，创建 `openflare-agent.service`，自动查找 `openresty`，并可重复执行以重装或升级 Agent。
|
||||
|
||||
Docker 部署可直接运行 Agent 镜像：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 3. 卸载 Agent
|
||||
|
||||
@@ -121,10 +132,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
卸载脚本会先停止并移除 `openflare-agent.service`、删除整个 `/opt/openflare-agent` 目录，然后根据卸载前保存的 `agent.json` 判断 OpenResty 安装方式：
|
||||
|
||||
* Docker 模式：删除对应 OpenResty 容器，并尝试移除镜像
|
||||
* 本机 `openresty_path` 模式：不改动本机 OpenResty，只提示用户手动卸载
|
||||
卸载脚本会先停止并移除 `openflare-agent.service`、删除整个 `/opt/openflare-agent` 目录，不会删除本机 OpenResty。
|
||||
|
||||
### 4. 发布第一份配置
|
||||
|
||||
|
||||
@@ -52,8 +52,8 @@ Agent：
|
||||
|
||||
* 单二进制
|
||||
* 节点本地执行
|
||||
* `openresty_path` 优先
|
||||
* 无 `openresty_path` 时默认 Docker OpenResty
|
||||
* 通过 `openresty_path` 或默认 `openresty` 控制 OpenResty 二进制
|
||||
* Docker 部署使用内置 OpenResty 的 Agent 镜像，不由 Agent 再控制独立 OpenResty 容器
|
||||
|
||||
Frontend：
|
||||
|
||||
@@ -236,7 +236,7 @@ Agent 必须满足：
|
||||
* 常规同步优先依据 heartbeat 返回的版本摘要判断。
|
||||
* 发现新版本时先备份旧文件。
|
||||
* 写入主配置、路由配置与必要证书文件。
|
||||
* 写入新配置后以运行态恢复为目标执行激活，Docker 模式优先重建容器并确认容器保持运行。
|
||||
* 写入新配置后执行 `openresty -t -c <main_config_path>`，再 reload；reload 发现运行时未启动时允许直接启动 OpenResty。
|
||||
* 新配置激活失败时必须先尝试用目标配置恢复运行，再回滚到旧配置并重新拉起 OpenResty。
|
||||
* 回滚后 OpenResty 恢复正常时上报警告；回滚后仍无法恢复运行时上报失败。
|
||||
* 某个目标 `version + checksum` 一旦应用失败并回退，Agent 必须在本地状态中阻断该目标的重复应用。
|
||||
|
||||
@@ -55,7 +55,7 @@ Agent 发现新版本后会：
|
||||
2. 备份旧文件。
|
||||
3. 写入主配置、路由配置、证书与必要 Lua 资源。
|
||||
4. 执行 OpenResty 配置校验。
|
||||
5. reload 或重建 Docker OpenResty。
|
||||
5. reload；如果运行时未启动，则尝试用当前配置启动 OpenResty。
|
||||
6. 上报成功、警告或失败。
|
||||
|
||||
如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。
|
||||
|
||||
@@ -10,7 +10,7 @@ OpenFlare Server (Gin + SQLite/PostgreSQL + Web UI)
|
||||
OpenFlare Agent (register / heartbeat / sync / apply / update)
|
||||
|
|
||||
v
|
||||
Local OpenResty or Docker OpenResty
|
||||
OpenResty binary
|
||||
|
|
||||
v
|
||||
Origin
|
||||
@@ -24,7 +24,7 @@ It owns the admin UI and API, Agent API, configuration rendering, version publis
|
||||
|
||||
## Agent
|
||||
|
||||
`openflare_agent` is a single Go binary that runs locally on each node. It prefers `openresty_path` when configured and uses Docker OpenResty by default otherwise.
|
||||
`openflare_agent` is a single Go binary that runs on each node. It controls OpenResty through `openresty_path`, or `openresty` by default. Docker deployments use an Agent image that already includes OpenResty and follows the same binary-control flow.
|
||||
|
||||
It handles registration, heartbeat, sync, file writes, `openresty -t`, reload, rollback, self-update, and lightweight collection.
|
||||
|
||||
|
||||
+13
-3
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -60,12 +60,14 @@ Agent supports the `-config` CLI flag, an `agent.json` file, and the `LOG_LEVEL`
|
||||
| `discovery_token` | Global token for first registration | one of `agent_token` / `discovery_token` | empty |
|
||||
| `node_name` | Node name | no | host name |
|
||||
| `node_ip` | Node IP | no | auto-detected |
|
||||
| `openresty_path` | Local OpenResty path | no | empty; Docker mode |
|
||||
| `openresty_container_name` | Docker container name | no | `openflare-openresty` |
|
||||
| `openresty_docker_image` | Docker image | no | `openresty/openresty:alpine` |
|
||||
| `openresty_path` | OpenResty binary path | no | `openresty` |
|
||||
| `openresty_container_name` | Deprecated Docker-control field, read for compatibility only | no | empty |
|
||||
| `openresty_docker_image` | Deprecated Docker-control field, read for compatibility only | no | empty |
|
||||
| `openresty_observability_port` | Local observability port | no | `18081` |
|
||||
| `docker_binary` | Docker binary name or path | no | `docker` |
|
||||
| `docker_binary` | Deprecated Docker-control field, read for compatibility only | no | empty |
|
||||
| `data_dir` | Agent data directory | no | `data` under config directory |
|
||||
| `access_log_path` | OpenResty access log path | no | `data_dir/var/log/openflare/access.log` |
|
||||
| `runtime_config_dir` | Runtime config directory, including `pow_config.json` | no | `data_dir/etc/openflare` |
|
||||
| `heartbeat_interval` | Heartbeat interval | no | `10000` ms |
|
||||
| `request_timeout` | HTTP timeout | no | `10000` ms |
|
||||
|
||||
|
||||
+27
-12
@@ -43,6 +43,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
| `--discovery-token` | 首次自动注册 Token |
|
||||
| `--agent-token` | 节点专属 Token |
|
||||
| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
|
||||
| `--openresty-path` | OpenResty 二进制路径，未传时自动查找 `openresty` |
|
||||
| `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
|
||||
| `--no-service` | 不创建 systemd 服务 |
|
||||
|
||||
@@ -54,15 +55,14 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
/opt/openflare-agent/agent.json
|
||||
```
|
||||
|
||||
Docker OpenResty 模式示例：
|
||||
本地配置示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"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,
|
||||
@@ -70,24 +70,39 @@ Docker OpenResty 模式示例：
|
||||
}
|
||||
```
|
||||
|
||||
本机 OpenResty 模式示例：
|
||||
自定义 OpenResty 路径示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "/var/lib/openflare-agent",
|
||||
"openresty_path": "/usr/local/openresty/nginx/sbin/nginx",
|
||||
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
|
||||
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
|
||||
"cert_dir": "/usr/local/openresty/nginx/conf/openflare-certs",
|
||||
"lua_dir": "/usr/local/openresty/nginx/conf/openflare-lua",
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
如果不配置 `openresty_path`，Agent 默认使用 Docker OpenResty。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
|
||||
如果不配置 `openresty_path`，Agent 默认调用 `openresty`。完整字段见 [配置项参考](../reference/configuration.md#agent-配置字段)。
|
||||
|
||||
## Docker 运行
|
||||
|
||||
Docker 部署时直接运行内置 OpenResty 的 Agent 镜像：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 启动与验证
|
||||
|
||||
@@ -144,7 +159,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
|
||||
| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
|
||||
| `--service-name` | systemd 服务名，默认 `openflare-agent` |
|
||||
|
||||
卸载脚本会先读取卸载前的 `agent.json` 判断 OpenResty 模式。Docker 模式会尝试删除对应容器和镜像；本机 `openresty_path` 模式不会删除本机 OpenResty。
|
||||
卸载脚本只移除 Agent 服务、进程和安装目录，不会删除本机 OpenResty。
|
||||
|
||||
## 常见问题
|
||||
|
||||
@@ -152,5 +167,5 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/unin
|
||||
| --- | --- |
|
||||
| `agent_token 和 discovery_token 不能同时为空` | 检查 `agent.json` 至少配置了一个 Token |
|
||||
| 节点一直离线 | 在 Agent 节点执行 `curl -I http://your-server:3000`，确认 Server 地址可达 |
|
||||
| Docker OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，并确认当前用户有 Docker 执行权限 |
|
||||
| OpenResty 没有启动 | 查看 `journalctl -u openflare-agent`，确认 `openresty_path` 可执行且 80/443 端口未被占用 |
|
||||
| 发布后重复失败 | Agent 会阻断同一 `version + checksum` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
你会学到：OpenFlare 的推荐部署方式、Server 与 Agent 的运行要求、源码启动方式、联调步骤、升级与卸载入口。
|
||||
|
||||
生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 节点默认使用 Docker OpenResty；如果要使用本机 OpenResty，需要额外配置 `openresty_path` 和写入目录。
|
||||
生产环境建议使用 PostgreSQL 作为 Server 数据库，并为 Server 显式配置 `SESSION_SECRET`。Agent 统一通过 OpenResty 二进制控制运行时；Docker 部署请直接使用内置 OpenResty 的 Agent 镜像。
|
||||
|
||||
## 部署拓扑
|
||||
|
||||
@@ -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：
|
||||
| --- | --- |
|
||||
| 系统 | 安装脚本支持 Linux 和 macOS；systemd 服务仅在 Linux + systemd 环境创建 |
|
||||
| 架构 | `amd64` 或 `arm64` |
|
||||
| Docker | 默认 Docker OpenResty 模式需要 |
|
||||
| 本机 OpenResty | 仅在显式配置 `openresty_path` 时需要 |
|
||||
| OpenResty | 本地部署需要可执行 `openresty`，或通过 `--openresty-path` 指定路径 |
|
||||
| Docker | 仅 Docker 部署 Agent 镜像时需要 |
|
||||
| 网络 | Agent 节点必须能访问 Server 地址 |
|
||||
|
||||
[需要确认：生产环境推荐的最低 CPU、内存与磁盘容量]
|
||||
@@ -154,6 +154,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
| `--discovery-token` | 首次自动注册 Token，与 `--agent-token` 二选一 |
|
||||
| `--agent-token` | 节点专属 Token，与 `--discovery-token` 二选一 |
|
||||
| `--install-dir` | 安装目录，默认 `/opt/openflare-agent` |
|
||||
| `--openresty-path` | OpenResty 二进制路径，未传时自动查找 `openresty` |
|
||||
| `--repo` | 下载 Agent 的 GitHub 仓库，默认 `Rain-kl/OpenFlare` |
|
||||
| `--no-service` | 不创建 systemd 服务 |
|
||||
|
||||
@@ -164,6 +165,31 @@ systemctl status openflare-agent
|
||||
journalctl -u openflare-agent -f
|
||||
```
|
||||
|
||||
## Docker 运行 Agent
|
||||
|
||||
Docker 部署时直接运行 Agent 镜像。该镜像基于 OpenResty 镜像制作，内置 Agent 控制器与 OpenResty 二进制。
|
||||
|
||||
挂载配置文件：
|
||||
|
||||
```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 \
|
||||
-v ./agent.json:/etc/openflare/agent.json:ro \
|
||||
ghcr.io/rain-kl/openflare-agent:latest
|
||||
```
|
||||
|
||||
使用环境变量：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
## 手动运行 Agent
|
||||
|
||||
源码运行：
|
||||
@@ -190,12 +216,13 @@ export LOG_LEVEL='info'
|
||||
"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
|
||||
}
|
||||
```
|
||||
|
||||
未配置 `openresty_path` 时，Agent 会使用 Docker OpenResty。
|
||||
未配置 `openresty_path` 时，Agent 默认调用 `openresty`。
|
||||
|
||||
## 最小联调步骤
|
||||
|
||||
@@ -227,7 +254,7 @@ Agent：
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/uninstall-agent.sh | bash
|
||||
```
|
||||
|
||||
卸载脚本会停止 Agent、删除 systemd 服务和安装目录；如果检测到 Docker OpenResty 模式，会尝试移除对应容器和镜像。本机 `openresty_path` 模式不会删除本机 OpenResty。
|
||||
卸载脚本会停止 Agent、删除 systemd 服务和安装目录，不会删除本机 OpenResty。
|
||||
|
||||
## 常用验证命令
|
||||
|
||||
|
||||
@@ -21,7 +21,8 @@
|
||||
| Go | `1.25+` |
|
||||
| Node.js | `18+` |
|
||||
| pnpm | 推荐通过 `corepack enable` 使用项目声明版本 |
|
||||
| Docker | Agent 默认 Docker OpenResty 模式和本地联调需要 |
|
||||
| Docker | Server 容器、本地联调和 Agent Docker 镜像需要 |
|
||||
| OpenResty | 本地运行 Agent 时需要可执行 `openresty` |
|
||||
| PostgreSQL | 可选；未配置时 Server 使用 SQLite |
|
||||
|
||||
## 初始化前端依赖
|
||||
@@ -106,7 +107,7 @@ export LOG_LEVEL='debug'
|
||||
go run ./cmd/agent -config ./agent.json
|
||||
```
|
||||
|
||||
未配置 `openresty_path` 时，Agent 会使用 Docker OpenResty。调试本机 OpenResty 时，显式配置 `openresty_path`、`main_config_path`、`route_config_path`、`cert_dir` 和 `lua_dir`。
|
||||
未配置 `openresty_path` 时，Agent 默认调用 `openresty`。调试时可显式配置 `openresty_path`、`main_config_path`、`route_config_path`、`access_log_path`、`cert_dir`、`lua_dir` 和 `runtime_config_dir`。
|
||||
|
||||
## 测试
|
||||
|
||||
@@ -172,7 +173,7 @@ go build -o openflare-agent ./cmd/agent
|
||||
| Agent 日志 | `LOG_LEVEL=debug go run ./cmd/agent -config ./agent.json` |
|
||||
| Swagger | `http://localhost:3000/swagger/index.html` |
|
||||
| 前端 API 代理 | `NEXT_DEV_BACKEND_URL=http://127.0.0.1:3000 pnpm dev` |
|
||||
| Docker OpenResty 容器 | `docker ps --filter name=openflare-openresty` |
|
||||
| OpenResty 配置校验 | `openresty -t -c ./data/etc/nginx/nginx.conf` |
|
||||
|
||||
## 代码风格与变更准入
|
||||
|
||||
|
||||
@@ -10,13 +10,14 @@ OpenFlare 的最小运行单元包含：
|
||||
| Agent | 运行在代理节点上，拉取配置、写入 OpenResty、执行校验与 reload |
|
||||
| OpenResty | 实际接收流量并反向代理到源站 |
|
||||
|
||||
默认情况下，Agent 未配置 `openresty_path` 时会使用 Docker OpenResty。因此快速开始建议在 Agent 节点准备 Docker。
|
||||
Agent 统一通过 OpenResty 二进制控制运行时。本地部署需要节点上已有 `openresty` 可执行文件；Docker 部署可直接运行内置 OpenResty 的 Agent 镜像。
|
||||
|
||||
## 环境要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL，也用于 Agent 默认的 Docker OpenResty 模式 |
|
||||
| Docker / Docker Compose | 用于启动 Server 和 PostgreSQL；如果采用 Docker Agent 镜像，也用于运行 Agent |
|
||||
| OpenResty | 本地安装 Agent 时需要可执行 `openresty`，或在安装脚本中指定路径 |
|
||||
| 可访问端口 | Server 默认监听 `3000`，Agent 节点需要能访问 Server 地址 |
|
||||
| 浏览器 | 用于访问管理端 |
|
||||
|
||||
@@ -128,7 +129,7 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/OpenFlare/main/scripts/inst
|
||||
| 安装目录 | `/opt/openflare-agent` |
|
||||
| 配置文件 | `/opt/openflare-agent/agent.json` |
|
||||
| systemd 服务 | `openflare-agent.service` |
|
||||
| OpenResty 模式 | 未配置 `openresty_path` 时使用 Docker OpenResty |
|
||||
| OpenResty 路径 | 未指定时自动查找 `openresty` |
|
||||
|
||||
确认 Agent 服务状态：
|
||||
|
||||
@@ -166,11 +167,8 @@ journalctl -u openflare-agent -f
|
||||
|
||||
```bash
|
||||
journalctl -u openflare-agent -n 100 --no-pager
|
||||
docker ps --filter name=openflare-openresty
|
||||
```
|
||||
|
||||
如果使用 Docker OpenResty，默认容器名是 `openflare-openresty`。
|
||||
|
||||
## 常见失败原因
|
||||
|
||||
| 现象 | 排查方向 |
|
||||
|
||||
@@ -153,22 +153,21 @@ journalctl -u openflare-agent -f
|
||||
| 上游地址不合法 | 确认所有上游都是 `http://` 或 `https://` |
|
||||
| 多上游格式不符合约束 | 多上游必须是纯 `scheme://host[:port]` |
|
||||
| 证书缺失或路径错误 | 检查域名是否绑定证书，以及 Agent 证书目录是否可写 |
|
||||
| 端口被占用 | 检查本机或 Docker 容器的 `80`、`443` 端口 |
|
||||
| 端口被占用 | 检查本机 `80`、`443` 端口 |
|
||||
|
||||
Docker OpenResty 模式：
|
||||
OpenResty 配置校验：
|
||||
|
||||
```bash
|
||||
docker ps --filter name=openflare-openresty
|
||||
docker logs --tail 100 openflare-openresty
|
||||
openresty -t -c /path/to/openflare/data/etc/nginx/nginx.conf
|
||||
```
|
||||
|
||||
本机 OpenResty 模式：
|
||||
OpenResty 运行状态：
|
||||
|
||||
```bash
|
||||
/usr/local/openresty/nginx/sbin/nginx -t
|
||||
ps aux | grep openresty
|
||||
```
|
||||
|
||||
实际路径以 `agent.json` 中的 `openresty_path` 为准。
|
||||
实际二进制路径和主配置路径以 `agent.json` 中的 `openresty_path` 与 `main_config_path` 为准。
|
||||
|
||||
## HTTPS 不生效
|
||||
|
||||
@@ -187,7 +186,7 @@ curl -Iv https://your-domain
|
||||
## 访问分析没有数据
|
||||
|
||||
1. 确认节点已经成功应用包含观测 Lua 资源的配置。
|
||||
2. 确认 Docker OpenResty 容器或本机 OpenResty 正在运行。
|
||||
2. 确认 OpenResty 正在运行。
|
||||
3. 查看 Agent 日志是否有观测采集或补报失败信息。
|
||||
4. 检查 `openresty_observability_port` 是否被占用，默认是 `18081`。
|
||||
5. 确认 Server 侧没有因数据库清理策略删除对应时间窗口数据。
|
||||
|
||||
@@ -136,6 +136,16 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
|
||||
| 环境变量 | 作用 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `LOG_LEVEL` | Agent 日志等级 | `info` |
|
||||
| `OPENFLARE_SERVER_URL` | 控制面地址，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_AGENT_TOKEN` | 节点专属认证 Token，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_DISCOVERY_TOKEN` | 首次自动注册 Token，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_NODE_NAME` | 节点名称，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_NODE_IP` | 节点 IP，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_DATA_DIR` | Agent 数据目录，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_OPENRESTY_PATH` | OpenResty 二进制路径，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_HEARTBEAT_INTERVAL` | 心跳间隔，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_REQUEST_TIMEOUT` | 请求超时，可覆盖 `agent.json` | 空 |
|
||||
| `OPENFLARE_OPENRESTY_OBSERVABILITY_PORT` | 本地观测端口，可覆盖 `agent.json` | 空 |
|
||||
|
||||
## Agent 命令行参数
|
||||
|
||||
@@ -152,18 +162,20 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
|
||||
| `discovery_token` | 首次自动注册使用的全局 Token | 与 `agent_token` 二选一 | 空 |
|
||||
| `node_name` | 节点名称 | 否 | 自动使用主机名 |
|
||||
| `node_ip` | 节点 IP | 否 | 自动探测，优先选择公网 IPv4；仅无公网地址时退回可用内网地址 |
|
||||
| `openresty_path` | 本机 OpenResty 路径 | 否 | 空，未设置时走 Docker 模式 |
|
||||
| `openresty_container_name` | Docker 模式下的容器名 | 否 | `openflare-openresty` |
|
||||
| `openresty_docker_image` | Docker 模式下的镜像 | 否 | `openresty/openresty:alpine` |
|
||||
| `openresty_path` | OpenResty 二进制路径 | 否 | `openresty` |
|
||||
| `openresty_container_name` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
|
||||
| `openresty_docker_image` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
|
||||
| `openresty_observability_port` | 本地观测端口 | 否 | `18081` |
|
||||
| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` |
|
||||
| `docker_binary` | 旧 Docker 控制字段，仅兼容读取 | 否 | 空 |
|
||||
| `data_dir` | Agent 数据目录 | 否 | 配置文件所在目录下的 `data` |
|
||||
| `main_config_path` | OpenResty 主配置写入路径 | 否 | 本机模式建议显式配置 |
|
||||
| `main_config_path` | OpenResty 主配置写入路径 | 否 | `data_dir/etc/nginx/nginx.conf` |
|
||||
| `route_config_path` | 路由配置写入路径 | 否 | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
|
||||
| `cert_dir` | 本机证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
|
||||
| `openresty_cert_dir` | OpenResty 读取证书目录 | 否 | 随运行模式变化 |
|
||||
| `lua_dir` | 本机 Lua 脚本写入目录 | 否 | `data_dir/etc/nginx/lua` |
|
||||
| `openresty_lua_dir` | OpenResty 读取 Lua 目录 | 否 | 随运行模式变化 |
|
||||
| `access_log_path` | OpenResty 访问日志路径 | 否 | `data_dir/var/log/openflare/access.log` |
|
||||
| `cert_dir` | 证书写入目录 | 否 | `data_dir/etc/nginx/certs` |
|
||||
| `openresty_cert_dir` | OpenResty 配置中读取证书的目录 | 否 | 同 `cert_dir` |
|
||||
| `lua_dir` | Lua 脚本与静态资源写入目录 | 否 | `data_dir/etc/nginx/lua` |
|
||||
| `openresty_lua_dir` | OpenResty 配置中读取 Lua 的目录 | 否 | 同 `lua_dir` |
|
||||
| `runtime_config_dir` | Agent 运行时配置写入目录，如 `pow_config.json` | 否 | `data_dir/etc/openflare` |
|
||||
| `observability_buffer_path` | 观测补报缓冲文件路径 | 否 | `data_dir/var/lib/openflare/observability-buffer.json` |
|
||||
| `observability_replay_minutes` | 自动补传最近观测窗口分钟数 | 否 | `15` |
|
||||
| `state_path` | Agent 本地状态文件路径 | 否 | `data_dir/var/lib/openflare/agent-state.json` |
|
||||
@@ -174,9 +186,9 @@ OpenResty 性能参数与缓存参数继续统一保存在 `Option` 表。当前
|
||||
|
||||
* `agent_token` 与 `discovery_token` 不能同时为空。
|
||||
* `heartbeat_interval` 与 `request_timeout` 支持毫秒整数或 Go duration 字符串。
|
||||
* 未配置 `openresty_path` 时默认使用 Docker OpenResty 模式。
|
||||
* 未配置 `openresty_path` 时默认调用 `openresty`。
|
||||
* 如果 `agent.json` 不存在，但 `OPENFLARE_SERVER_URL` 与 Token 等环境变量足够，Agent 可以直接启动；两者同时存在时环境变量优先。
|
||||
* Agent 自动探测到私网 `node_ip` 时，Server 会在注册/心跳阶段优先保留 Agent 直连来源的公网地址，避免 NAT/多网卡场景误登记内网网卡地址。
|
||||
* [需要确认：安装脚本当前生成的 `sync_interval` 是否仍应保留；当前 Agent 配置结构未使用该字段。]
|
||||
|
||||
## 常见配置组合
|
||||
|
||||
@@ -198,32 +210,33 @@ export LOG_LEVEL='debug'
|
||||
go run .
|
||||
```
|
||||
|
||||
### Agent + Docker OpenResty
|
||||
### Agent + 默认 OpenResty
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://your-server:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "/opt/openflare-agent/data",
|
||||
"openresty_container_name": "openflare-openresty",
|
||||
"openresty_docker_image": "openresty/openresty:alpine",
|
||||
"openresty_path": "openresty",
|
||||
"heartbeat_interval": 10000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
### Agent + 本机 OpenResty
|
||||
### Agent + 自定义 OpenResty 路径
|
||||
|
||||
```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/nginx",
|
||||
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
|
||||
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
|
||||
"cert_dir": "/usr/local/openresty/nginx/conf/openflare-certs",
|
||||
"lua_dir": "/usr/local/openresty/nginx/conf/openflare-lua",
|
||||
"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
|
||||
}
|
||||
|
||||
@@ -29,7 +29,7 @@
|
||||
| `config` | 配置读取与默认值 |
|
||||
| `heartbeat` | 心跳与版本摘要判断 |
|
||||
| `sync` | 配置拉取与应用编排 |
|
||||
| `nginx` / `openresty` | OpenResty 文件写入、校验、reload 与 Docker 模式管理 |
|
||||
| `nginx` / `openresty` | OpenResty 文件写入、校验、reload、启动与回滚 |
|
||||
| `state` | 本地状态与观测补报缓冲 |
|
||||
| `httpclient` | Server 通信 |
|
||||
| `protocol` | Agent API 协议类型 |
|
||||
|
||||
Reference in New Issue
Block a user