tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 14:06: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/guide/agent.md
+27 -12
View File
@@ -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` 的重复应用；需要修正配置后重新发布，或激活旧版本回滚 |
docs/guide/deployment.md
+33 -6
View File
@@ -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。
## 常用验证命令
docs/guide/development.md
+4 -3
View File
@@ -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` |
## 代码风格与变更准入
docs/guide/quick-start.md
+4 -6
View File
@@ -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`。
## 常见失败原因
| 现象 | 排查方向 |
docs/guide/troubleshooting.md
+7 -8
View File
@@ -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 侧没有因数据库清理策略删除对应时间窗口数据。