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-03-15 16:04:54 +08:00
parent d68773c554
commit 32d90ba641
304 changed files with 629 additions and 969 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/app-config.md
+34 -34
View File
@@ -1,6 +1,6 @@
# ATSFlare 配置项说明
# OpenFlare 配置项说明
本文档汇总当前 ATSFlare Server 与 Agent 在启动、部署和运行时支持的参数、环境变量与配置文件字段，并说明其作用、默认值和示例。
本文档汇总当前 OpenFlare Server 与 Agent 在启动、部署和运行时支持的参数、环境变量与配置文件字段，并说明其作用、默认值和示例。
---
@@ -20,14 +20,14 @@ Server 当前支持两类启动配置：
启动示例：
```bash
cd atsf_server
cd openflare_server
go run . --port 3000 --log-dir ./logs
```
或在编译后二进制中使用：
```bash
./atsflare --port 3000 --log-dir ./logs
./openflare --port 3000 --log-dir ./logs
```
支持的命令行参数：
@@ -36,8 +36,8 @@ go run . --port 3000 --log-dir ./logs
| --- | --- | --- | --- |
| `--port` | 指定 Server 监听端口 | `3000` | `--port 3000` |
| `--log-dir` | 指定日志目录；设置后会自动创建目录并写入日志 | 空，默认输出到 stdout | `--log-dir ./logs` |
| `--version` | 输出当前版本后退出 | `false` | `./atsflare --version` |
| `--help` | 输出帮助信息后退出 | `false` | `./atsflare --help` |
| `--version` | 输出当前版本后退出 | `false` | `./openflare --version` |
| `--help` | 输出帮助信息后退出 | `false` | `./openflare --help` |
说明：
@@ -49,9 +49,9 @@ go run . --port 3000 --log-dir ./logs
源码启动示例：
```bash
cd atsf_server
cd openflare_server
export SESSION_SECRET='replace-with-random-string'
export SQLITE_PATH='./atsflare.db'
export SQLITE_PATH='./openflare.db'
export GIN_MODE='release'
export LOG_LEVEL='info'
export PORT='3000'
@@ -62,22 +62,22 @@ Docker Compose 示例：
```yaml
services:
atsflare:
image: ghcr.io/rain-kl/atsflare:latest
openflare:
image: ghcr.io/rain-kl/openflare:latest
restart: unless-stopped
ports:
- "3000:3000"
environment:
SESSION_SECRET: replace-with-random-string
SQLITE_PATH: /data/atsflare.db
SQLITE_PATH: /data/openflare.db
GIN_MODE: release
LOG_LEVEL: info
PORT: "3000"
volumes:
- atsflare-data:/data
- openflare-data:/data
volumes:
atsflare-data:
openflare-data:
```
支持的环境变量：
@@ -88,8 +88,8 @@ volumes:
| `GIN_MODE` | 指定 Gin 运行模式；仅当值为 `debug` 时启用 debug，其余情况按 release 运行 | 非 `debug` 默认按 release 运行 | `GIN_MODE=release` |
| `LOG_LEVEL` | 指定系统日志等级；支持 `debug`/`info`/`warn`/`error`（`warning` 兼容为 `warn`） | `info` | `LOG_LEVEL=warn` |
| `SESSION_SECRET` | Session 签名密钥；生产环境必须显式设置，避免重启后会话失效 | 启动时随机生成 UUID | `SESSION_SECRET=replace-with-random-string` |
| `SQLITE_PATH` | SQLite 数据库文件路径 | `atsflare.db` | `SQLITE_PATH=/data/atsflare.db` |
| `SQL_DSN` | MySQL DSN；设置后优先使用 MySQL，而不是 SQLite | 未设置时使用 SQLite | `SQL_DSN=user:pass@tcp(127.0.0.1:3306)/atsflare` |
| `SQLITE_PATH` | SQLite 数据库文件路径 | `openflare.db` | `SQLITE_PATH=/data/openflare.db` |
| `SQL_DSN` | MySQL DSN；设置后优先使用 MySQL，而不是 SQLite | 未设置时使用 SQLite | `SQL_DSN=user:pass@tcp(127.0.0.1:3306)/openflare` |
| `REDIS_CONN_STRING` | Redis 连接串；设置后启用 Redis，用于 Session/限流相关能力 | 未设置时关闭 Redis | `REDIS_CONN_STRING=redis://default:pass@127.0.0.1:6379/0` |
| `UPLOAD_PATH` | 上传文件目录 | `upload` | `UPLOAD_PATH=/data/upload` |
| `AGENT_TOKEN` | 全局 Agent Token 兼容配置；当前默认部署不依赖该变量 | 空 | `AGENT_TOKEN=legacy-shared-token` |
@@ -110,7 +110,7 @@ volumes:
| --- | --- | --- |
| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
| `NodeOfflineThreshold` | 节点离线判定阈值（毫秒） | `120000` |
| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/ATSFlare` |
| `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/OpenFlare` |
| `GeoIPProvider` | 节点/IP 归属解析方式；支持 `disabled`、`mmdb`、`ip-api`、`geojs`、`ipinfo` | `ipinfo` |
| `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口（秒） | `300` / `180` |
| `GlobalWebRateLimitNum` / `GlobalWebRateLimitDuration` | 全局 Web 限流次数 / 时间窗口（秒） | `300` / `180` |
@@ -172,7 +172,7 @@ volumes:
### 1.3 前端构建环境变量
新版管理端位于 `atsf_server/web`，构建时支持以下公开环境变量：
新版管理端位于 `openflare_server/web`，构建时支持以下公开环境变量：
| 环境变量 | 作用 | 默认值 | 示例 |
| --- | --- | --- | --- |
@@ -216,21 +216,21 @@ Agent 当前支持两类启动配置：
启动示例：
```bash
cd atsf_agent
cd openflare_agent
go run ./cmd/agent -config ./agent.json
```
或编译后二进制：
```bash
./atsflare-agent -config /path/to/agent.json
./openflare-agent -config /path/to/agent.json
```
支持的命令行参数：
| 参数 | 作用 | 默认值 | 示例 |
| --- | --- | --- | --- |
| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | `-config /etc/atsflare/agent.json` |
| `-config` | 指定 Agent 配置文件路径 | `./agent.json` | `-config /etc/openflare/agent.json` |
### 2.2 Agent 配置文件示例
@@ -241,7 +241,7 @@ go run ./cmd/agent -config ./agent.json
"server_url": "http://127.0.0.1:3000",
"discovery_token": "replace-with-global-discovery-token",
"data_dir": "./data",
"openresty_container_name": "atsflare-openresty",
"openresty_container_name": "openflare-openresty",
"openresty_docker_image": "openresty/openresty:alpine",
"openresty_observability_port": 18081,
"observability_replay_minutes": 15,
@@ -261,7 +261,7 @@ go run ./cmd/agent -config ./agent.json
"data_dir": "./data",
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
@@ -285,18 +285,18 @@ go run ./cmd/agent -config ./agent.json
| `node_name` | 节点名称 | 否 | 自动使用主机名 | `node-01` |
| `node_ip` | 节点 IP | 否 | 自动探测第一个可用 IPv4 | `192.168.1.20` |
| `openresty_path` | 本机 OpenResty 可执行文件路径；设置后按本机 OpenResty 模式运行 | 否 | 空；未设置时按 Docker OpenResty 模式处理 | `/usr/local/openresty/nginx/sbin/openresty` |
| `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `atsflare-openresty` | `atsflare-openresty` |
| `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `openflare-openresty` | `openflare-openresty` |
| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` |
| `openresty_observability_port` | Agent 注入的 OpenResty 本地观测端口；用于 heartbeat 前读取 Lua 窗口指标和 `stub_status`，默认仅监听 `127.0.0.1` | 否 | `18081` | `18081` |
| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` |
| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` |
| `main_config_path` | 第五版主配置接管时 OpenResty 主配置文件写入路径 | 第五版本机模式建议必填 | Docker 模式可使用受管默认路径；本机模式建议显式设置 | `/usr/local/openresty/nginx/conf/nginx.conf` |
| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/atsflare_routes.conf` |
| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/openflare_routes.conf` |
| `cert_dir` | Agent 在本机写入受管证书文件的目录 | 否 | 默认为 `data_dir` 下托管 certs 目录 | `./data/etc/nginx/certs` |
| `openresty_cert_dir` | OpenResty 实际读取受管证书文件的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/atsflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
| `openresty_cert_dir` | OpenResty 实际读取受管证书文件的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/openflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
| `lua_dir` | Agent 在本机写入受管 Lua 观测脚本的目录；每次启动都会覆盖释放 | 否 | 默认为 `data_dir` 下托管 lua 目录 | `./data/etc/nginx/lua` |
| `openresty_lua_dir` | OpenResty 实际读取受管 Lua 观测脚本的目录 | 否 | 本机模式默认等于 `lua_dir`；Docker 模式默认 `/etc/nginx/atsflare-lua` | `/usr/local/openresty/nginx/conf/lua` |
| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径；用于在 server 短暂离线时按时间窗口落盘待补传数据 | 否 | 默认为 `data_dir` 下托管观测缓冲文件 | `./data/var/lib/atsflare/observability-buffer.json` |
| `openresty_lua_dir` | OpenResty 实际读取受管 Lua 观测脚本的目录 | 否 | 本机模式默认等于 `lua_dir`；Docker 模式默认 `/etc/nginx/openflare-lua` | `/usr/local/openresty/nginx/conf/lua` |
| `observability_buffer_path` | Agent 本地观测补报缓冲文件路径；用于在 server 短暂离线时按时间窗口落盘待补传数据 | 否 | 默认为 `data_dir` 下托管观测缓冲文件 | `./data/var/lib/openflare/observability-buffer.json` |
| `observability_replay_minutes` | Agent 恢复心跳后允许批量补传的最近观测窗口时长（分钟） | 否 | `15` | `30` |
| `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` |
| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | `10000` |
@@ -322,23 +322,23 @@ go run ./cmd/agent -config ./agent.json
| 字段 | 默认值 |
| --- | --- |
| `main_config_path` | 第五版 Docker 模式默认可落在 `data_dir/etc/nginx/nginx.conf`；本机模式建议显式配置 |
| `route_config_path` | `data_dir/etc/nginx/conf.d/atsflare_routes.conf` |
| `route_config_path` | `data_dir/etc/nginx/conf.d/openflare_routes.conf` |
| `cert_dir` | `data_dir/etc/nginx/certs` |
| `lua_dir` | `data_dir/etc/nginx/lua` |
| `observability_buffer_path` | `data_dir/var/lib/atsflare/observability-buffer.json` |
| `state_path` | `data_dir/var/lib/atsflare/agent-state.json` |
| `observability_buffer_path` | `data_dir/var/lib/openflare/observability-buffer.json` |
| `state_path` | `data_dir/var/lib/openflare/agent-state.json` |
Docker OpenResty 模式下：
| 字段 | 默认值 |
| --- | --- |
| `openresty_cert_dir` | `/etc/nginx/atsflare-certs` |
| `openresty_lua_dir` | `/etc/nginx/atsflare-lua` |
| `openresty_cert_dir` | `/etc/nginx/openflare-certs` |
| `openresty_lua_dir` | `/etc/nginx/openflare-lua` |
补充说明：
* Agent 会在每次启动时把受管 Lua 观测脚本覆盖释放到 `lua_dir`，不再由 Server 随配置版本下发
* OpenResty 通过 `openresty_lua_dir` 读取这些本地脚本，并在每次 heartbeat 前通过 `http://127.0.0.1:<openresty_observability_port>/atsflare/observability` 读取最近窗口请求指标
* OpenResty 通过 `openresty_lua_dir` 读取这些本地脚本，并在每次 heartbeat 前通过 `http://127.0.0.1:<openresty_observability_port>/openflare/observability` 读取最近窗口请求指标
* 若 server 短暂离线，Agent 会把最近窗口观测先写入 `observability_buffer_path`，待 heartbeat 恢复后按时间窗口批量补传最近 `observability_replay_minutes` 分钟的数据
* 同一端口还会暴露仅本机可访问的 `stub_status`，用于采集 OpenResty 活动连接数
@@ -366,7 +366,7 @@ Docker OpenResty 模式下：
"agent_token": "replace-with-node-auth-token",
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
docs/deployment.md
+49 -49
View File
@@ -1,4 +1,4 @@
# ATSFlare 部署说明
# OpenFlare 部署说明
本文档仅保留当前可用基线的最小部署方式，并补充第五版（0.5.x）开发期间与 OpenResty 主配置接管相关的联调约束。
@@ -27,7 +27,7 @@
### 2.1 构建前端
```bash
cd atsf_server/web
cd openflare_server/web
corepack enable
pnpm install
pnpm build
@@ -36,7 +36,7 @@ pnpm build
说明：
* 前端使用 Next.js 静态导出模式构建
* `pnpm build` 会生成供 Go Server 托管的 `atsf_server/web/build` 目录
* `pnpm build` 会生成供 Go Server 托管的 `openflare_server/web/build` 目录
* 如需覆盖默认接口地址，可在构建前设置 `NEXT_PUBLIC_API_BASE_URL`
### 2.1.1 本地前端热更新开发
@@ -44,7 +44,7 @@ pnpm build
在本地联调时，可单独启动前端开发服务器：
```bash
cd atsf_server/web
cd openflare_server/web
corepack enable
pnpm install
pnpm dev
@@ -60,9 +60,9 @@ pnpm dev
### 2.2 启动服务
```bash
cd atsf_server
cd openflare_server
export SESSION_SECRET='replace-with-random-string'
export SQLITE_PATH='./atsflare.db'
export SQLITE_PATH='./openflare.db'
export LOG_LEVEL='info'
go run .
```
@@ -82,21 +82,21 @@ go run .
```yaml
services:
atsflare:
image: ghcr.io/rain-kl/atsflare:latest
container_name: atsflare
openflare:
image: ghcr.io/rain-kl/openflare:latest
container_name: openflare
restart: unless-stopped
ports:
- "3000:3000"
environment:
SESSION_SECRET: replace-with-random-string
SQLITE_PATH: /data/atsflare.db
SQLITE_PATH: /data/openflare.db
GIN_MODE: release
volumes:
- atsflare-data:/data
- openflare-data:/data
volumes:
atsflare-data:
openflare-data:
```
启动命令：
@@ -108,16 +108,16 @@ docker compose up -d
说明：
* `SESSION_SECRET` 必须替换为随机字符串
* SQLite 数据文件持久化到 Docker volume `atsflare-data`
* SQLite 数据文件持久化到 Docker volume `openflare-data`
* 镜像默认监听容器内 `3000` 端口
* 若要固定版本，可将 `latest` 替换为具体 tag，例如 `ghcr.io/rain-kl/atsflare:v0.3.0`
* 若要固定版本，可将 `latest` 替换为具体 tag，例如 `ghcr.io/rain-kl/openflare:v0.3.0`
版本升级说明：
* Root 用户可在管理端顶栏点击「版本」默认检查正式版 GitHub Release
* 若需尝试 preview 版本，可在同一弹窗中手动检查 preview 发布并选择是否升级
* 当前运行的是 Release 二进制且二进制目录可写时，可直接在弹窗内触发 Server 自升级
* Server 自升级会下载匹配当前平台的 `atsflare-server-*` 资产，替换当前二进制并自动重启进程
* Server 自升级会下载匹配当前平台的 `openflare-server-*` 资产，替换当前二进制并自动重启进程
* 也可在同一弹窗中手动上传 Server 二进制，服务端先检测上传文件版本，前端确认后再执行替换与重启
* 节点 Agent 默认仅跟随正式版自动更新；如需 preview 版本，可在节点详情中手动检查 preview 发布并下发更新
@@ -138,7 +138,7 @@ docker compose up -d
* Swagger UI 受管理端登录态保护，未登录不可直接访问
* 可在浏览器中查看当前 Server API 与 Agent API 定义，并直接发起调试请求
* 当 Server API 新增或变更时，需要同步更新 Swag 注解并重新生成 `atsf_server/docs`
* 当 Server API 新增或变更时，需要同步更新 Swag 注解并重新生成 `openflare_server/docs`
如需在本地重新生成 Swagger 文档，先安装 `swag`：
@@ -151,7 +151,7 @@ go install github.com/swaggo/swag/cmd/swag@latest
* Linux / macOS：`$HOME/go/bin`
* Windows：`%USERPROFILE%\go\bin`
如需在本地重新生成 Swagger 文档，可在 `atsf_server` 目录执行：
如需在本地重新生成 Swagger 文档，可在 `openflare_server` 目录执行：
```bash
swag init -g main.go -o docs
@@ -170,7 +170,7 @@ swag init -g main.go -o docs
"server_url": "http://127.0.0.1:3000",
"agent_token": "replace-with-node-auth-token",
"data_dir": "./data",
"openresty_container_name": "atsflare-openresty",
"openresty_container_name": "openflare-openresty",
"openresty_docker_image": "openresty/openresty:alpine",
"openresty_observability_port": 18081,
"observability_replay_minutes": 15,
@@ -186,7 +186,7 @@ swag init -g main.go -o docs
"server_url": "http://127.0.0.1:3000",
"discovery_token": "replace-with-global-discovery-token",
"data_dir": "./data",
"openresty_container_name": "atsflare-openresty",
"openresty_container_name": "openflare-openresty",
"openresty_docker_image": "openresty/openresty:alpine",
"openresty_observability_port": 18081,
"observability_replay_minutes": 15,
@@ -214,7 +214,7 @@ swag init -g main.go -o docs
* 本机 OpenResty 模式需要为 Agent 显式提供主配置文件写入路径
* Docker OpenResty 模式需要保证主配置、路由配置和证书目录位于同一套受管挂载路径中
* Docker OpenResty 模式会额外挂载一个仅本机可访问的 `127.0.0.1:<openresty_observability_port>` 观测端口，用于 Agent 在 heartbeat 前抓取 Lua 窗口指标
* Docker / 本机两种模式都会在 `data_dir/var/lib/atsflare/observability-buffer.json` 保留最近待补传窗口；若节点磁盘是临时盘，重启后该缓冲也会丢失
* Docker / 本机两种模式都会在 `data_dir/var/lib/openflare/observability-buffer.json` 保留最近待补传窗口；若节点磁盘是临时盘，重启后该缓冲也会丢失
* 节点现存手工维护的主配置如继续保留，必须先迁移为 Server 渲染模板的等价配置，再切换到受管模式
* 主配置切换前必须预留回滚副本，并通过一次 `openresty -t` 失败演练验证回滚
@@ -225,7 +225,7 @@ swag init -g main.go -o docs
### 4.1 直接运行
```bash
cd atsf_agent
cd openflare_agent
export LOG_LEVEL='info'
go run ./cmd/agent -config /path/to/agent.json
```
@@ -233,10 +233,10 @@ go run ./cmd/agent -config /path/to/agent.json
### 4.2 编译后二进制运行
```bash
cd atsf_agent
go build -o atsflare-agent ./cmd/agent
cd openflare_agent
go build -o openflare-agent ./cmd/agent
export LOG_LEVEL='info'
./atsflare-agent -config /path/to/agent.json
./openflare-agent -config /path/to/agent.json
```
---
@@ -277,7 +277,7 @@ export LOG_LEVEL='info'
"server_url": "http://127.0.0.1:3000",
"discovery_token": "replace-with-global-discovery-token",
"data_dir": "./data",
"openresty_container_name": "atsflare-openresty",
"openresty_container_name": "openflare-openresty",
"openresty_docker_image": "openresty/openresty:alpine",
"openresty_observability_port": 18081
}
@@ -285,24 +285,24 @@ export LOG_LEVEL='info'
验证点：
1. 首次启动后确认 `data/etc/nginx/nginx.conf`、`data/etc/nginx/conf.d/atsflare_routes.conf`、`data/etc/nginx/certs` 与 `data/etc/nginx/lua` 已由 Agent 创建
1. 首次启动后确认 `data/etc/nginx/nginx.conf`、`data/etc/nginx/conf.d/openflare_routes.conf`、`data/etc/nginx/certs` 与 `data/etc/nginx/lua` 已由 Agent 创建
2. 确认容器实际挂载了主配置、路由目录、证书目录和 Lua 目录
3. 确认宿主机本地可访问 `http://127.0.0.1:18081/atsflare/observability` 与 `http://127.0.0.1:18081/atsflare/stub_status`
3. 确认宿主机本地可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status`
3. 在管理端发布一次新版本后，确认节点 `current_version` 追平激活版本
4. 在节点详情查看“当前目标版本”与“最近应用”，确认主配置/路由配置快照和 checksum 已可见
推荐检查命令：
```bash
docker inspect atsflare-openresty
docker exec atsflare-openresty openresty -t
docker inspect openflare-openresty
docker exec openflare-openresty openresty -t
```
说明：
* `docker inspect` 重点确认主配置文件、`conf.d` 目录、证书目录和 Lua 目录都来自 Agent 受管路径
* 观测端口默认只绑定 `127.0.0.1`；若节点已有冲突，可在 `agent.json` 中调整 `openresty_observability_port`
* 若容器名使用默认值，请将上述命令中的名称替换为 `atsflare-openresty`
* 若容器名使用默认值，请将上述命令中的名称替换为 `openflare-openresty`
### 5.3.2 本机 OpenResty 模式最小验证
@@ -314,7 +314,7 @@ docker exec atsflare-openresty openresty -t
"agent_token": "replace-with-node-auth-token",
"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/openflare_routes.conf",
"cert_dir": "/usr/local/openresty/nginx/conf/certs",
"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
"lua_dir": "/usr/local/openresty/nginx/conf/lua",
@@ -327,7 +327,7 @@ docker exec atsflare-openresty openresty -t
1. 发布前先备份 `main_config_path` 与 `route_config_path`
2. 首次发布后执行 `openresty -t`，确认主配置已由 Server 模板接管且 include 指向 Agent 写入的路由文件
3. 确认本机可访问 `http://127.0.0.1:18081/atsflare/observability` 与 `http://127.0.0.1:18081/atsflare/stub_status`
3. 确认本机可访问 `http://127.0.0.1:18081/openflare/observability` 与 `http://127.0.0.1:18081/openflare/stub_status`
4. 再次发布修改后的规则或 OpenResty 参数，确认 `openresty -s reload` 成功且节点版本更新
5. 在节点详情与应用记录页确认主配置 checksum、路由配置 checksum 和支持文件数已上报
@@ -364,7 +364,7 @@ Docker OpenResty 模式：
1. 在测试节点上保留默认受管路径
2. 临时将 `openresty_docker_image` 指向一个不包含 `openresty` 运行时的错误镜像标签，或在测试环境用包装镜像让 `openresty -t` 固定失败
3. 再次发布，确认节点应用失败但 `data/etc/nginx/nginx.conf` 与 `data/etc/nginx/conf.d/atsflare_routes.conf` 已回滚为旧版本
3. 再次发布，确认节点应用失败但 `data/etc/nginx/nginx.conf` 与 `data/etc/nginx/conf.d/openflare_routes.conf` 已回滚为旧版本
4. 恢复正确镜像后重新发布，确认节点恢复健康
说明：
@@ -379,21 +379,21 @@ Docker OpenResty 模式：
### 6.1 Server
```bash
cd atsf_server
GOCACHE=/tmp/atsflare-go-cache go test ./...
cd openflare_server
GOCACHE=/tmp/openflare-go-cache go test ./...
```
### 6.2 Agent
```bash
cd atsf_agent
GOCACHE=/tmp/atsflare-go-cache go test ./...
cd openflare_agent
GOCACHE=/tmp/openflare-go-cache go test ./...
```
### 6.3 前端
```bash
cd atsf_server/web
cd openflare_server/web
pnpm build
```
@@ -406,7 +406,7 @@ pnpm build
Docker 镜像发布使用 [.github/workflows/docker-image.yml](.github/workflows/docker-image.yml)：
* 仅构建 `atsf_server` 服务端镜像
* 仅构建 `openflare_server` 服务端镜像
* 发布到 GitHub Container Registry（`ghcr.io/<owner>/<repo>:<tag>`）
* 单个工作流通过分架构原生构建再合并 manifest 的方式产出 `linux/amd64` 与 `linux/arm64` 多架构镜像，避免 `arm64` 长时间模拟编译
@@ -419,7 +419,7 @@ Docker 镜像发布使用 [.github/workflows/docker-image.yml](.github/workflows
在目标机器上运行：
```bash
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
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
```
@@ -431,23 +431,23 @@ curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/insta
| `--server-url` | Server 地址（必填） | - |
| `--discovery-token` | 全局 Discovery Token | - |
| `--agent-token` | 节点专属 Token | - |
| `--install-dir` | 安装目录 | `/opt/atsflare-agent` |
| `--repo` | GitHub Release 仓库 | `Rain-kl/ATSFlare` |
| `--install-dir` | 安装目录 | `/opt/openflare-agent` |
| `--repo` | GitHub Release 仓库 | `Rain-kl/OpenFlare` |
| `--no-service` | 不创建 systemd 服务 | - |
安装脚本会：
1. 从 GitHub Releases 下载最新 Agent 二进制（`atsflare-agent-{os}-{arch}`）
2. 若检测到已存在安装目录，会先停止运行中的 `atsflare-agent` 服务并删除整个安装目录
1. 从 GitHub Releases 下载最新 Agent 二进制（`openflare-agent-{os}-{arch}`）
2. 若检测到已存在安装目录，会先停止运行中的 `openflare-agent` 服务并删除整个安装目录
3. 先下载到临时文件，再写入全新的安装目录，避免覆盖运行中进程导致写入失败
4. 生成 `agent.json` 配置文件
5. 创建 systemd 服务 `atsflare-agent.service`
5. 创建 systemd 服务 `openflare-agent.service`
6. 启动并启用自启
说明：
* 脚本可重复执行，用于重装或升级到最新 Release
* 若检测到已运行的 `atsflare-agent` systemd 服务，会先停止服务、清空安装目录，再重新安装
* 若检测到已运行的 `openflare-agent` systemd 服务，会先停止服务、清空安装目录，再重新安装
* 重装会删除旧的 `agent.json`、本地状态、缓存数据和旧二进制，因此节点会按新的 Token 或 Discovery Token 重新接入
### 7.2 管理端生成部署命令
@@ -471,9 +471,9 @@ Agent 自动更新默认为关闭。
GitHub Release 中的 Agent 二进制命名格式：
* `atsflare-agent-linux-amd64`
* `atsflare-agent-linux-arm64`
* `atsflare-agent-darwin-arm64`
* `openflare-agent-linux-amd64`
* `openflare-agent-linux-arm64`
* `openflare-agent-darwin-arm64`
---
docs/design.md
+15 -15
View File
@@ -1,13 +1,13 @@
# ATSFlare 设计基线
# OpenFlare 设计基线
## 1. 文档目的
本文档只保留 ATSFlare 当前有效的产品边界、系统结构与稳定约束。
本文档只保留 OpenFlare 当前有效的产品边界、系统结构与稳定约束。
当前状态：
* 第一版、第二版、第三版均已完成
* 前端改造已完成，`atsf_server/web` 新版工程已成为正式基线
* 前端改造已完成，`openflare_server/web` 新版工程已成为正式基线
* 第五版（0.5.x）已完成，OpenResty 反代、缓存性能优化与主配置接管已落地
* 第六版（0.6.x）已立项，目标聚焦节点流量数据采集、访问分析与数据看板升级
* 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计
@@ -16,7 +16,7 @@
## 2. 产品定位
ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
OpenFlare 当前定位为内部自用的反向代理控制面，不面向外部租户提供 CDN SaaS 能力。
当前核心能力：
@@ -70,7 +70,7 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
* 主配置文件由 Server 统一生成并由 Agent 受控落地，不开放节点侧手改后再回传合并
* 性能优化参数统一在 Server 配置，不支持按节点分叉不同性能模板
* 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备
* 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 ATSFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染
* 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 OpenFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染
第六版边界补充：
@@ -93,18 +93,18 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
### 4.1 Server
`atsf_server` 继续作为单体控制面：
`openflare_server` 继续作为单体控制面：
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
* 托管 `atsf_server/web` 静态构建产物
* 现有 OpenFlare 登录体系
* 托管 `openflare_server/web` 静态构建产物
* 托管 OpenResty 主配置模板、性能参数与缓存参数
### 4.2 Agent
`atsf_agent` 继续作为 Go 单体程序：
`openflare_agent` 继续作为 Go 单体程序：
* 单二进制
* 节点本地执行
@@ -115,7 +115,7 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
### 4.3 Frontend
`atsf_server/web` 作为正式管理端前端基线：
`openflare_server/web` 作为正式管理端前端基线：
* Next.js App Router
* React 19
@@ -128,11 +128,11 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
## 5. 总体架构
```text
ATSFlare Server (Gin + SQLite + Web UI)
OpenFlare Server (Gin + SQLite + Web UI)
|
| HTTP API / Config Pull
v
ATSFlare Agent (register / heartbeat / sync / apply / update)
OpenFlare Agent (register / heartbeat / sync / apply / update)
|
v
Local OpenResty or Docker OpenResty
@@ -239,7 +239,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
## 8. 模块边界
### 8.1 `atsf_server`
### 8.1 `openflare_server`
负责：
@@ -252,7 +252,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
* 发布与激活
* 节点状态与设置管理
### 8.2 `atsf_agent`
### 8.2 `openflare_agent`
负责：
@@ -266,7 +266,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
* 自我更新
* 应用结果上报
### 8.3 `atsf_server/web`
### 8.3 `openflare_server/web`
负责：
docs/development-guidelines.md
+8 -8
View File
@@ -1,4 +1,4 @@
# ATSFlare 开发规范
# OpenFlare 开发规范
## 1. 适用范围
@@ -8,7 +8,7 @@
* 第一版、第二版、第三版已完成
* `docs/design.md` 是当前系统边界的唯一设计基线
* `atsf_server/web` 新版前端已完成迁移并成为正式基线
* `openflare_server/web` 新版前端已完成迁移并成为正式基线
* 第五版（0.5.x）已完成
* 第六版（0.6.x）以节点流量数据采集、访问分析与看板升级为主线
@@ -20,13 +20,13 @@
### 2.1 Server
`atsf_server` 继续作为单体控制面：
`openflare_server` 继续作为单体控制面：
* Go 1.24+
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
* 现有 OpenFlare 登录体系
约束：
@@ -36,7 +36,7 @@
### 2.2 Agent
`atsf_agent` 继续作为 Go 单体程序：
`openflare_agent` 继续作为 Go 单体程序：
* Go 1.23+
* 单二进制
@@ -47,7 +47,7 @@
### 2.3 Frontend
新版前端基线以当前 `atsf_server/web` 实现为准：
新版前端基线以当前 `openflare_server/web` 实现为准：
* Next.js 15 App Router
* React 19
@@ -186,7 +186,7 @@
管理端：
* 继续复用 ATSFlare 登录、角色与 session
* 继续复用 OpenFlare 登录、角色与 session
Agent：
@@ -375,4 +375,4 @@ Agent 必须满足：
* Server 提供 Swagger UI 入口：`/swagger/index.html`
* Swagger UI 仅对已登录的管理端用户开放
* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `atsf_server/docs`
* 新增或修改 API 时，必须同步更新 Swag 注解并重新生成 `openflare_server/docs`
docs/development-plan.md
+2 -2
View File
@@ -1,4 +1,4 @@
# ATSFlare 开发计划
# OpenFlare 开发计划
## 1. 当前状态
@@ -69,7 +69,7 @@
* 首屏新增世界地图看板，用于展示全部节点分布与在线状态
* 调整总览信息结构，不再以单一“四卡摘要”作为主布局
* 增加趋势、分布、Top 榜单、容量风险和异常信号展示
* 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 ATSFlare 当前系统健康与流量状态
* 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 OpenFlare 当前系统健康与流量状态
4. 节点详情页改造
* 第一行重构为三块核心卡片：系统信息、实时资源占用、网络流量监控
docs/frontend-development-guidelines.md
+2 -2
View File
@@ -1,8 +1,8 @@
# ATSFlare 前端开发规范
# OpenFlare 前端开发规范
## 1. 适用范围
本文档约束 `atsf_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
本文档约束 `openflare_server/web` 新版前端的工程结构、请求层、组件设计、样式体系、状态管理与测试方式。
当前状态：
docs/frontend-revamp-plan.md
+4 -4
View File
@@ -1,8 +1,8 @@
# ATSFlare 前端改造说明
# OpenFlare 前端改造说明
## 1. 当前状态
前端改造已完成，`atsf_server/web` 的 Next.js 新版工程已经成为正式管理端基线。
前端改造已完成，`openflare_server/web` 的 Next.js 新版工程已经成为正式管理端基线。
当前结论：
@@ -14,7 +14,7 @@
## 2. 当前前端基线
新版管理端位于 `atsf_server/web`，当前基线为：
新版管理端位于 `openflare_server/web`，当前基线为：
* Next.js 15 App Router
* React 19
@@ -28,7 +28,7 @@
工程与运行方式：
* `next build` 后生成静态导出产物
* 构建后通过现有流程交由 `atsf_server` 托管
* 构建后通过现有流程交由 `openflare_server` 托管
* 登录态继续兼容现有 Session/Cookie 体系
---
docs/improve_plan.md
+2 -2
View File
@@ -1,4 +1,4 @@
# ATSFlare 整理维护期改进计划
# OpenFlare 整理维护期改进计划
## 1. 背景
@@ -20,7 +20,7 @@
### 2.1 总目标
在不扩大产品边界的前提下，把 ATSFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。
在不扩大产品边界的前提下，把 OpenFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。
### 2.2 具体目标