mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 14:06:36 +08:00
feat: add OperationSetting component and integrate into settings page
- Introduced OperationSetting component for managing agent configurations. - Updated settings page to include a new tab for operation settings. - Implemented functionality to fetch and update agent parameters such as heartbeat interval, sync interval, and auto-update settings. docs: enhance deployment documentation for agent installation - Added detailed instructions for agent installation using a script. - Included examples for using discovery and agent tokens. - Updated sections on global discovery tokens and agent auto-update features. docs: revise design and development guidelines for V3 - Updated design document to reflect the current state and goals for V3. - Clarified development guidelines to focus on operational experience improvements. ci: add GitHub Actions workflow for agent releases - Created a new workflow to automate the release of agent binaries on GitHub. - Configured the workflow to build binaries for multiple platforms and publish them as releases. feat: implement self-update mechanism for agent - Added updater module to handle checking for and applying updates from GitHub releases. - Implemented logic to restart the agent after a successful update. chore: create install script for agent deployment - Developed a bash script to facilitate the installation of the ATSFlare agent. - The script supports automatic configuration and systemd service creation.
This commit is contained in:
ryan
+101
-39
@@ -63,43 +63,43 @@ go run .
|
||||
|
||||
### 3.1 节点专属 `agent_token`
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "./data",
|
||||
"nginx_container_name": "atsflare-nginx",
|
||||
"nginx_docker_image": "nginx:stable-alpine",
|
||||
"heartbeat_interval": 30000,
|
||||
"sync_interval": 30000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"agent_token": "replace-with-node-auth-token",
|
||||
"data_dir": "./data",
|
||||
"nginx_container_name": "atsflare-nginx",
|
||||
"nginx_docker_image": "nginx:stable-alpine",
|
||||
"heartbeat_interval": 30000,
|
||||
"sync_interval": 30000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 全局 `discovery_token`
|
||||
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"discovery_token": "replace-with-global-discovery-token",
|
||||
"data_dir": "./data",
|
||||
"nginx_container_name": "atsflare-nginx",
|
||||
"nginx_docker_image": "nginx:stable-alpine",
|
||||
"heartbeat_interval": 30000,
|
||||
"sync_interval": 30000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* `agent_version` 由 Agent 代码内常量提供，升级时同步修改代码
|
||||
* `nginx_version` 由 Agent 启动时执行命令自动探测
|
||||
* 时间字段使用毫秒整数
|
||||
* `agent_token` 与 `discovery_token` 至少填写一个
|
||||
* 若 `agent_token` 为空且 `discovery_token` 存在，Agent 会自动注册并写回新的专属 `agent_token`
|
||||
* `node_name` 与 `node_ip` 可省略，未填写时自动探测
|
||||
* 未配置 `nginx_path` 时，默认使用 Docker Nginx 容器
|
||||
```json
|
||||
{
|
||||
"server_url": "http://127.0.0.1:3000",
|
||||
"discovery_token": "replace-with-global-discovery-token",
|
||||
"data_dir": "./data",
|
||||
"nginx_container_name": "atsflare-nginx",
|
||||
"nginx_docker_image": "nginx:stable-alpine",
|
||||
"heartbeat_interval": 30000,
|
||||
"sync_interval": 30000,
|
||||
"request_timeout": 10000
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
* `agent_version` 由 Agent 代码内常量提供，升级时同步修改代码
|
||||
* `nginx_version` 由 Agent 启动时执行命令自动探测
|
||||
* 时间字段使用毫秒整数
|
||||
* `agent_token` 与 `discovery_token` 至少填写一个
|
||||
* 若 `agent_token` 为空且 `discovery_token` 存在，Agent 会自动注册并写回新的专属 `agent_token`
|
||||
* `node_name` 与 `node_ip` 可省略，未填写时自动探测
|
||||
* 未配置 `nginx_path` 时，默认使用 Docker Nginx 容器
|
||||
|
||||
---
|
||||
|
||||
@@ -193,12 +193,74 @@ npm run build
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前已知限制
|
||||
## 7. Agent 一键部署（V3）
|
||||
|
||||
* 暂未内置 systemd unit 文件
|
||||
* 暂未提供一键部署脚本
|
||||
* Docker 模式仍是 MVP 级封装
|
||||
* 联调以手工步骤为主
|
||||
### 7.1 curl 安装
|
||||
|
||||
在目标机器上运行：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--discovery-token YOUR_DISCOVERY_TOKEN
|
||||
```
|
||||
|
||||
支持参数：
|
||||
|
||||
| 参数 | 说明 | 默认值 |
|
||||
| ------------------- | -------------------- | --------------------- |
|
||||
| `--server-url` | Server 地址（必填） | - |
|
||||
| `--discovery-token` | 全局 Discovery Token | - |
|
||||
| `--agent-token` | 节点专属 Token | - |
|
||||
| `--install-dir` | 安装目录 | `/opt/atsflare-agent` |
|
||||
| `--repo` | GitHub Release 仓库 | `Rain-kl/ATSFlare` |
|
||||
| `--no-service` | 不创建 systemd 服务 | - |
|
||||
|
||||
安装脚本会：
|
||||
|
||||
1. 从 GitHub Releases 下载最新 Agent 二进制（`atsflare-agent-{os}-{arch}`）
|
||||
2. 生成 `agent.json` 配置文件
|
||||
3. 创建 systemd 服务 `atsflare-agent.service`
|
||||
4. 启动并启用自启
|
||||
|
||||
### 7.2 管理端生成部署命令
|
||||
|
||||
在管理端 **系统设置 → 运维设置** 中查看已生成的一键部署命令，直接复制到目标节点执行。
|
||||
|
||||
### 7.3 Agent 自动更新
|
||||
|
||||
在管理端 **运维设置** 中启用「Agent 自动更新」后，Agent 会在每次心跳周期检查 GitHub Releases，发现新版本时自动下载并重启。
|
||||
|
||||
---
|
||||
|
||||
## 8. Agent 二进制命名规则
|
||||
|
||||
GitHub Release 中的 Agent 二进制命名格式：
|
||||
|
||||
* `atsflare-agent-linux-amd64`
|
||||
* `atsflare-agent-linux-arm64`
|
||||
* `atsflare-agent-darwin-arm64`
|
||||
|
||||
---
|
||||
|
||||
## 9. 运维设置热更新（V3）
|
||||
|
||||
以下参数可通过管理端 **运维设置** 修改，修改后通过心跳响应下发到 Agent，无需重启：
|
||||
|
||||
| 参数 | 说明 | Agent 字段 |
|
||||
| ---------------------- | -------------------- | ------------------ |
|
||||
| AgentHeartbeatInterval | 心跳间隔（毫秒） | heartbeat_interval |
|
||||
| AgentSyncInterval | 同步间隔（毫秒） | sync_interval |
|
||||
| NodeOfflineThreshold | 节点离线阈值（毫秒） | - |
|
||||
| AgentAutoUpdate | 是否启用自动更新 | auto_update |
|
||||
| AgentUpdateRepo | 自动更新仓库 | update_repo |
|
||||
|
||||
---
|
||||
|
||||
## 10. 当前已知限制
|
||||
|
||||
* Docker 模式仍是 MVP 级封装
|
||||
* 联调以手工步骤为主
|
||||
|
||||
---
|
||||
|
||||
|
||||
+142
-3
@@ -1,14 +1,14 @@
|
||||
# ATSFlare 设计基线（V3 准备版）
|
||||
# ATSFlare 设计基线（V3）
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
本文档不再展开记录第一版、第二版的实施过程，只保留当前系统边界、稳定约束与第三版开始前必须确认的设计输入。
|
||||
本文档保留当前系统边界、稳定约束与第三版的设计输入。
|
||||
|
||||
当前结论：
|
||||
|
||||
* 第一版、第二版已完成并进入归档状态
|
||||
* 第三版进入实施阶段
|
||||
* 当前代码库的可运行能力，以本文档为唯一设计基线
|
||||
* 第三版开发前，如需扩展系统边界，先更新本文档，再开始编码
|
||||
|
||||
---
|
||||
|
||||
@@ -324,3 +324,142 @@ Agent 接口当前覆盖：
|
||||
* 设计文档只保留当前有效基线
|
||||
* 已完成阶段的细节以 Git 历史为准
|
||||
* 新阶段开始前，先把设计输入写清楚，再进入实现
|
||||
|
||||
---
|
||||
|
||||
## 11. 第三版设计输入
|
||||
|
||||
### 11.1 目标定位
|
||||
|
||||
第三版聚焦**运维体验优化**，不扩展系统功能边界，只提升已有能力的可操作性与可维护性。
|
||||
|
||||
### 11.2 启动设置热更新
|
||||
|
||||
当前状态：
|
||||
|
||||
* `SESSION_SECRET`、`SQLITE_PATH`、`PORT` 等启动参数通过环境变量注入
|
||||
* 变更需要重启 Server 进程
|
||||
|
||||
第三版变更：
|
||||
|
||||
* 将可热更新的运行时设置迁入 Option 表，通过设置页面管理
|
||||
* 以下设置在前端运维设置面板中可配置：
|
||||
* `AgentHeartbeatInterval`：Agent 心跳上报间隔（毫秒），默认 30000
|
||||
* `AgentSyncInterval`：Agent 配置同步间隔（毫秒），默认 30000
|
||||
* `NodeOfflineThreshold`：节点离线判定阈值（毫秒），默认 120000
|
||||
* `AgentAutoUpdate`：是否允许 Agent 自动更新（`true`/`false`），默认 `false`
|
||||
* `AgentUpdateRepo`：Agent 自动更新 GitHub 仓库地址，默认 `Rain-kl/ATSFlare`
|
||||
* 环境变量类设置（`SESSION_SECRET`、`SQLITE_PATH`、`PORT`）不迁移，保留原有方式
|
||||
* 前端在设置页面新增「运维设置」Tab
|
||||
|
||||
### 11.3 Server 下发 Agent 设置
|
||||
|
||||
当前状态：
|
||||
|
||||
* Agent 心跳请求只是单向上报，Server 不返回业务数据
|
||||
* Agent 的心跳间隔、同步间隔只在本地 `agent.json` 配置
|
||||
|
||||
第三版变更：
|
||||
|
||||
* 心跳响应新增 `agent_settings` 字段，包含 Server 端可控的运行时参数：
|
||||
* `heartbeat_interval`（毫秒）
|
||||
* `sync_interval`（毫秒）
|
||||
* `auto_update`（布尔值）
|
||||
* `update_repo`（GitHub 仓库名）
|
||||
* Agent 收到心跳响应后，动态调整本地定时器间隔
|
||||
* 当 Server 未返回 `agent_settings` 或字段为空时，Agent 保持本地值不变
|
||||
* Agent 不持久化 Server 下发的间隔值，重启后以本地 `agent.json` 为准，再由下次心跳覆盖
|
||||
|
||||
### 11.4 Agent 自我更新
|
||||
|
||||
当前状态：
|
||||
|
||||
* Agent 版本固定，更新需要运维手动替换二进制文件
|
||||
|
||||
第三版变更：
|
||||
|
||||
* Agent 在收到 `auto_update=true` 时：
|
||||
* 通过 GitHub Releases API 查询 `update_repo` 的最新 Release
|
||||
* 比较本地 `agent_version` 与远端 tag
|
||||
* 若存在更新，下载对应平台的二进制文件
|
||||
* 替换自身二进制并重启
|
||||
* 更新检查频率：每轮心跳周期结束后检查一次，不独立起定时器
|
||||
* 更新过程中不中断当前同步任务
|
||||
* 更新失败不影响正常心跳与同步
|
||||
* Agent 二进制文件命名约定：`atsflare-agent-{os}-{arch}`
|
||||
|
||||
### 11.5 Agent 一键部署
|
||||
|
||||
当前状态：
|
||||
|
||||
* Agent 需要手动编译或复制二进制并创建配置文件
|
||||
|
||||
第三版变更：
|
||||
|
||||
* 提供 `install-agent.sh` 脚本，支持以下方式部署：
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/scripts/install-agent.sh | bash -s -- \
|
||||
--server-url http://your-server:3000 \
|
||||
--discovery-token your-token
|
||||
```
|
||||
* 脚本行为：
|
||||
* 检测平台架构（linux/amd64、linux/arm64）
|
||||
* 从 GitHub Releases 下载最新 Agent 二进制
|
||||
* 创建安装目录（默认 `/opt/atsflare-agent`）
|
||||
* 生成基础 `agent.json` 配置
|
||||
* 创建 systemd service 文件（可选）
|
||||
* 启动 Agent
|
||||
|
||||
### 11.6 GitHub Actions 内测发布
|
||||
|
||||
当前状态：
|
||||
|
||||
* 现有工作流只构建 Server 二进制和 Docker 镜像
|
||||
* Agent 二进制不在 CI 中构建
|
||||
* Alpha 标签在部分工作流中被排除
|
||||
|
||||
第三版变更：
|
||||
|
||||
* 新增 `agent-release.yml` 工作流：
|
||||
* 触发条件：推送任意 tag（包括 alpha）
|
||||
* 构建 Agent 二进制：`linux/amd64`、`linux/arm64`、`darwin/arm64`
|
||||
* 产物命名：`atsflare-agent-{os}-{arch}`
|
||||
* 上传至 GitHub Release
|
||||
* 修改现有工作流：
|
||||
* 统一 `linux-release.yml` 为同时构建 Server + Agent 二进制
|
||||
* Alpha 标签的发布标记为 prerelease
|
||||
* 安装脚本与自我更新共用同一 Release 产物
|
||||
|
||||
### 11.7 前端运维体验优化
|
||||
|
||||
当前状态：
|
||||
|
||||
* 时间字段使用纳秒整数，不够友好
|
||||
* 设置页面未包含运维类设置
|
||||
|
||||
第三版变更：
|
||||
|
||||
* 设置页面新增「运维设置」Tab，包含：
|
||||
* Agent 心跳间隔
|
||||
* Agent 同步间隔
|
||||
* 节点离线阈值
|
||||
* Agent 自动更新开关
|
||||
* Agent 更新仓库
|
||||
* 全局 Discovery Token 展示与重新生成
|
||||
* Agent 一键部署命令展示（根据当前 ServerAddress 和 DiscoveryToken 动态生成 curl 命令）
|
||||
* 节点列表页优化：
|
||||
* 时间显示改为友好的相对时间格式
|
||||
* 节点状态使用颜色标识
|
||||
|
||||
---
|
||||
|
||||
## 12. 第三版不做的范围
|
||||
|
||||
以下内容不在第三版范围内：
|
||||
|
||||
* 多租户
|
||||
* WAF、限流、Bot
|
||||
* 节点分组、差异化下发
|
||||
* 证书自动签发与续期
|
||||
* Agent 配置文件加密
|
||||
* Server 远程执行 Agent 命令
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
# ATSFlare 开发规范（V3 准备版）
|
||||
# ATSFlare 开发规范（V3）
|
||||
|
||||
## 1. 适用范围
|
||||
|
||||
本规范适用于当前代码基线以及第三版开始前后的所有开发工作。
|
||||
本规范适用于当前代码基线以及第三版的所有开发工作。
|
||||
|
||||
当前系统状态：
|
||||
|
||||
* 第一版、第二版功能已完成
|
||||
* 当前开发重点不再是补历史阶段细节，而是稳定基线并准备第三版
|
||||
* 第三版聚焦运维体验优化
|
||||
* 超出 `docs/design.md` 当前边界的需求，必须先补设计，再编码
|
||||
|
||||
---
|
||||
@@ -202,6 +202,14 @@ Agent 必须满足：
|
||||
* 本地状态文件损坏时允许重建，但不能破坏当前生效配置
|
||||
* Docker 容器异常时，启动阶段应自动重建
|
||||
|
||||
V3 新增行为：
|
||||
|
||||
* 心跳响应包含 `agent_settings` 时，动态调整定时器间隔
|
||||
* `auto_update=true` 时在每次心跳后检查 GitHub Releases 更新
|
||||
* 自我更新失败不影响心跳与同步
|
||||
* Server 下发的间隔值不持久化到 `agent.json`，重启后以本地为准
|
||||
* Agent 新增 `internal/updater` 模块处理自我更新逻辑
|
||||
|
||||
---
|
||||
|
||||
## 8. 前端开发规范
|
||||
|
||||
+118
-4
@@ -1,4 +1,4 @@
|
||||
# ATSFlare 开发计划（V3 准备版）
|
||||
# ATSFlare 开发计划（V3）
|
||||
|
||||
## 1. 当前状态
|
||||
|
||||
@@ -6,9 +6,9 @@
|
||||
|
||||
* 第一版已完成并稳定闭环
|
||||
* 第二版已完成并补齐 HTTPS、证书、域名、节点管理与预览能力
|
||||
* 下一步进入第三版准备阶段
|
||||
* 第三版进入实施阶段，聚焦运维体验优化
|
||||
|
||||
本文件不再展开第一版、第二版的详细实施步骤，只保留第三版启动前的计划骨架与准入条件。
|
||||
本文件不再展开第一版、第二版的详细实施步骤，只保留第三版实施计划与验收标准。
|
||||
|
||||
---
|
||||
|
||||
@@ -37,4 +37,118 @@
|
||||
归档原则：
|
||||
|
||||
* 已完成阶段的实现细节以代码和 Git 历史为准
|
||||
* 后续计划文档只维护当前阶段与下一阶段
|
||||
* 后续计划文档只维护当前阶段与下一阶段
|
||||
|
||||
---
|
||||
|
||||
## 3. 第三版实施计划
|
||||
|
||||
### 3.1 阶段一：Server 运维设置热更新
|
||||
|
||||
目标：将可热更新的运维相关设置迁入 Option 表，前端提供设置面板。
|
||||
|
||||
实施步骤：
|
||||
|
||||
1. 在 `common/constants.go` 新增运维设置变量：
|
||||
* `AgentHeartbeatInterval`（默认 30000ms）
|
||||
* `AgentSyncInterval`（默认 30000ms）
|
||||
* `NodeOfflineThreshold`（默认 120000ms）
|
||||
* `AgentAutoUpdate`（默认 false）
|
||||
* `AgentUpdateRepo`（默认 `Rain-kl/ATSFlare`）
|
||||
2. 在 `model/option.go` 的 `InitOptionMap()` 注册新选项
|
||||
3. 在 `model/option.go` 的 `updateOptionMap()` 增加对新选项的同步
|
||||
4. 修改 `service/agent.go` 中 `computeNodeStatus()` 使用动态 `NodeOfflineThreshold`
|
||||
5. 前端设置页新增「运维设置」Tab
|
||||
|
||||
验收标准：
|
||||
|
||||
* 运维设置在设置页面可查看和修改
|
||||
* 修改后立即生效，无需重启 Server
|
||||
* `NodeOfflineThreshold` 变更后节点状态判定使用新阈值
|
||||
|
||||
### 3.2 阶段二：Server 下发 Agent 设置 + Agent 接收
|
||||
|
||||
目标：心跳响应携带 `agent_settings`，Agent 动态调整运行参数。
|
||||
|
||||
实施步骤：
|
||||
|
||||
1. Server 端：
|
||||
* 修改 `service/agent.go` 的 `HeartbeatNode()` 返回 `AgentSettings`
|
||||
* 新增 `AgentSettings` 结构体
|
||||
* 修改 `controller/agent.go` 心跳接口返回 `agent_settings`
|
||||
2. Agent 端：
|
||||
* 修改 `protocol/agent_api.go` 新增 `HeartbeatResponse` 和 `AgentSettings`
|
||||
* 修改 `httpclient/client.go` 解析心跳响应
|
||||
* 修改 `heartbeat/service.go` 返回 `HeartbeatResponse`
|
||||
* 修改 `agent/runner.go` 根据响应动态调整 `heartbeatTicker` 和 `syncTicker`
|
||||
|
||||
验收标准：
|
||||
|
||||
* Server 心跳响应 JSON 中包含 `agent_settings`
|
||||
* Agent 收到新间隔后在下一个周期生效
|
||||
* Agent 重启后恢复 `agent.json` 配置，再由心跳覆盖
|
||||
* Server 未配置时 Agent 保持本地值不变
|
||||
|
||||
### 3.3 阶段三：Agent 自我更新
|
||||
|
||||
目标：Agent 支持从 GitHub Releases 自动更新。
|
||||
|
||||
实施步骤：
|
||||
|
||||
1. Agent 新增 `internal/updater` 模块：
|
||||
* GitHub Releases API 查询最新版本
|
||||
* 版本比较（语义化版本）
|
||||
* 下载对应平台二进制
|
||||
* 替换自身并重启（exec syscall）
|
||||
2. 在 `runner.go` 心跳循环中集成更新检查
|
||||
3. 更新触发条件：`auto_update=true` 且存在新版本
|
||||
|
||||
验收标准：
|
||||
|
||||
* Agent 能正确检测新版本
|
||||
* 能下载并替换自身二进制
|
||||
* 更新后自动重启并恢复心跳
|
||||
* 更新失败不影响正常运行
|
||||
|
||||
### 3.4 阶段四：GitHub Actions 完善与 Agent 一键部署
|
||||
|
||||
目标：CI 支持 Agent 构建发布，提供 curl 一键安装。
|
||||
|
||||
实施步骤：
|
||||
|
||||
1. 新增 `.github/workflows/agent-release.yml`
|
||||
2. 修改现有工作流支持 alpha/prerelease
|
||||
3. 创建 `scripts/install-agent.sh` 安装脚本
|
||||
4. 前端运维设置面板展示动态 curl 部署命令
|
||||
|
||||
验收标准：
|
||||
|
||||
* 推送 tag 后 Agent 二进制出现在 GitHub Release
|
||||
* Alpha tag 标记为 prerelease
|
||||
* curl 命令可在干净 Linux 机器上完成 Agent 部署
|
||||
* 前端正确展示拼接后的 curl 命令
|
||||
|
||||
### 3.5 阶段五：前端体验优化
|
||||
|
||||
目标：优化管理端操作体验。
|
||||
|
||||
实施步骤：
|
||||
|
||||
1. 节点列表时间显示改为友好格式
|
||||
2. 节点状态颜色标识
|
||||
3. Discovery Token 在运维设置面板中可查看和重新生成
|
||||
4. Agent 部署命令一键复制
|
||||
|
||||
验收标准：
|
||||
|
||||
* 时间显示为友好的相对时间（如「2 分钟前」）
|
||||
* 节点状态有颜色区分：在线（绿色）、离线（红色）、待接入（黄色）
|
||||
* curl 部署命令支持一键复制
|
||||
|
||||
---
|
||||
|
||||
## 4. 阶段执行原则
|
||||
|
||||
* 每个阶段完成后验证验收标准，再进入下一阶段
|
||||
* 阶段间的代码不相互依赖时可并行
|
||||
* 每个阶段完成后运行全量测试
|
||||
Reference in New Issue
Block a user