From 65817ac9b68bfca5cc6e33343e0eab73a1cad530 Mon Sep 17 00:00:00 2001 From: ryan Date: Mon, 9 Mar 2026 23:30:50 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=E9=83=A8=E7=BD=B2=E4=B8=8E?= =?UTF-8?q?=E8=81=94=E8=B0=83=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E5=8C=85=E5=90=AB=E5=89=8D=E7=BD=AE=E6=9D=A1=E4=BB=B6=E3=80=81?= =?UTF-8?q?=E5=90=AF=E5=8A=A8=E6=AD=A5=E9=AA=A4=E5=92=8C=E9=AA=8C=E8=AF=81?= =?UTF-8?q?=E6=B5=81=E7=A8=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 133 +++++++++++-------------------- docs/deployment.md | 193 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 239 insertions(+), 87 deletions(-) create mode 100644 docs/deployment.md diff --git a/README.md b/README.md index 84eecede..92014503 100644 --- a/README.md +++ b/README.md @@ -1,104 +1,63 @@ -

- 中文 | English -

+# ATSFlare -

- gin-template logo -

+ATSFlare 是一个面向内部使用的 Nginx 反向代理控制面 MVP。 -
+当前版本只覆盖以下闭环： -# Gin 项目模板 +- 管理端维护反代规则 +- Server 生成并激活配置版本 +- Agent 拉取激活版本并写入独立 Nginx 路由配置文件 +- Agent 执行 `nginx -t` 和 `nginx -s reload` +- Server 展示节点状态和最近一次应用结果 -_✨ 用于 Gin & React 项目的模板 ✨_ +不包含多租户、WAF、限流、Redis、对象存储、复杂缓存策略等平台化能力。 -
+## 仓库结构 -

- - license - - - release - - - docker pull - - - release - - - GoReportCard - -

+- `atsf_server`: Gin + GORM + SQLite 的控制中心，包含管理端 API、Agent API 和 Web 管理台 +- `atsf_agent`: Go 单体 Agent，负责注册、心跳、同步配置、写入 Nginx 路由文件并 reload +- `docs`: 设计、开发规范、开发计划和部署联调文档 -

- 程序下载 - · - 部署教程 - · - 意见反馈 - · - 在线演示 -

+接手前请先阅读： -## 功能 -+ [x] 内置用户管理 -+ [x] 内置文件管理 -+ [x] [GitHub 开放授权](https://github.com/settings/applications/new) -+ [x] 微信公众号授权（需要 [wechat-server](https://github.com/songquanpeng/wechat-server)） -+ [x] 邮箱验证以及通过邮件进行密码重置 -+ [x] 请求频率限制 -+ [x] 静态文件缓存 -+ [x] 移动端适配 -+ [x] 基于令牌的鉴权 -+ [x] 使用 GitHub Actions 自动打包可执行文件与 Docker 镜像 -+ [x] Cloudflare Turnstile 用户校验 +1. [docs/design.md](/Users/ryan/DEV/Go/ATSFlare/docs/design.md) +2. [docs/development-guidelines.md](/Users/ryan/DEV/Go/ATSFlare/docs/development-guidelines.md) +3. [docs/development-plan.md](/Users/ryan/DEV/Go/ATSFlare/docs/development-plan.md) -## 部署 -### 基于 Docker 进行部署 -执行：`docker run --name gin-template -d --restart always -p 3000:3000 -v /home/ubuntu/data/gin-template:/data justsong/gin-template` +## 当前功能状态 -数据将会保存在宿主机的 `/home/ubuntu/data/gin-template` 目录。 +- Phase 1: Server 数据层与发布闭环，已完成 +- Phase 2: Agent API 与节点状态，已完成 +- Phase 3: Agent 本体最小闭环，已完成 +- Phase 4: 管理端页面，已完成 +- Phase 5: 部署与联调文档，已完成 -### 手动部署 -1. 从 [GitHub Releases](https://github.com/songquanpeng/gin-template/releases/latest) 下载可执行文件或者从源码编译： - ```shell - git clone https://github.com/songquanpeng/gin-template.git - cd gin-template/web - npm install - npm run build - cd .. - go mod download - go build -ldflags "-s -w" -o gin-template - ```` -2. 运行： - ```shell - chmod u+x gin-template - ./gin-template --port 3000 --log-dir ./logs - ``` -3. 访问 [http://localhost:3000/](http://localhost:3000/) 并登录。初始账号用户名为 `root`，密码为 `123456`。 +## 快速开始 -更加详细的部署教程[参见此处](https://iamazing.cn/page/how-to-deploy-a-website)。 +最小运行步骤见： -## 配置 -系统本身开箱即用。 +- [docs/deployment.md](/Users/ryan/DEV/Go/ATSFlare/docs/deployment.md) -你可以通过设置环境变量或者命令行参数进行配置。 +如果只想快速验证测试： -等到系统启动后，使用 `root` 用户登录系统并做进一步的配置。 +```bash +cd atsf_server && GOCACHE=/tmp/atsflare-go-cache go test ./... +cd atsf_agent && GOCACHE=/tmp/atsflare-go-cache go test ./... +cd atsf_server/web && npm run build +``` -### 环境变量 -1. `REDIS_CONN_STRING`：设置之后将使用 Redis 作为请求频率限制的存储，而非使用内存存储。 - + 例子：`REDIS_CONN_STRING=redis://default:redispw@localhost:49153` -2. `SESSION_SECRET`：设置之后将使用固定的会话密钥，这样系统重新启动后已登录用户的 cookie 将依旧有效。 - + 例子：`SESSION_SECRET=random_string` -3. `SQL_DSN`：设置之后将使用指定数据库而非 SQLite。 - + 例子：`SQL_DSN=root:123456@tcp(localhost:3306)/gin-template` +## 默认约束 -### 命令行参数 -1. `--port `: 指定服务器监听的端口号，默认为 `3000`。 - + 例子：`--port 3000` -2. `--log-dir `: 指定日志文件夹，如果没有设置，日志将不会被保存。 - + 例子：`--log-dir ./logs` -3. `--version`: 打印系统版本号并退出。 \ No newline at end of file +- Server 默认使用 SQLite +- 不配置 `REDIS_CONN_STRING` +- Agent 鉴权使用 `X-Agent-Token` +- 第一版只管理独立生成的 Nginx 路由配置文件 + +## 后续工作 + +当前 MVP 已可支撑最小闭环。下一阶段优先项通常包括： + +- 补充 systemd 服务示例 +- 增加真实环境联调记录 +- 优化前端交互和表单校验 +- 增加更多 Agent 侧集成测试 diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 00000000..e92fb24c --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,193 @@ +# ATSFlare 部署与联调说明 + +本文档对应 Phase 5，用于指导在新环境手工完成 ATSFlare MVP 的最小部署与联调。 + +## 1. 前置条件 + +### Server + +- Go 1.18+ +- Node.js 18+ 与 npm +- 本地可写 SQLite 文件目录 + +### Agent + +- Go 1.18+ +- 节点已安装 `nginx` +- Agent 对目标路由文件路径有写权限 +- Agent 运行用户可以执行 `nginx -t` 和 `nginx -s reload` + +## 2. Server 启动 + +### 2.1 构建前端 + +```bash +cd atsf_server/web +npm install +npm run build +``` + +### 2.2 启动 Server + +推荐在仓库根目录执行： + +```bash +cd atsf_server +export SESSION_SECRET='replace-with-random-string' +export SQLITE_PATH='./gin-template.db' +export AGENT_TOKEN='replace-with-shared-agent-token' +go run . +``` + +说明： + +- 如果未设置 `SQLITE_PATH`，默认也会落到 `atsf_server/gin-template.db` +- 如果未设置 `AGENT_TOKEN`，Agent API 会拒绝访问 +- 当前默认监听端口为 `3000` + +### 2.3 首次登录 + +访问 `http://localhost:3000` + +默认账号： + +- 用户名：`root` +- 密码：`123456` + +首次登录后建议立即修改密码。 + +## 3. Agent 启动 + +### 3.1 Agent 配置文件示例 + +在节点上创建 `agent.json`： + +```json +{ + "server_url": "http://127.0.0.1:3000", + "agent_token": "replace-with-shared-agent-token", + "node_name": "edge-01", + "node_ip": "10.0.0.8", + "agent_version": "0.1.0", + "nginx_version": "1.25.5", + "route_config_path": "/etc/nginx/conf.d/atsflare_routes.conf", + "state_path": "/var/lib/atsflare/agent-state.json", + "nginx_binary": "nginx", + "heartbeat_interval": 30000000000, + "sync_interval": 30000000000, + "request_timeout": 10000000000 +} +``` + +注意： + +- 时间字段单位是纳秒，因为当前实现直接使用 Go 的 `time.Duration` JSON 反序列化 +- `agent_token` 必须与 Server 侧 `AGENT_TOKEN` 完全一致 +- `route_config_path` 只应指向 ATSFlare 独立管理的路由文件 + +### 3.2 启动 Agent + +```bash +cd atsf_agent +go run ./cmd/agent -config /path/to/agent.json +``` + +如果需要编译二进制： + +```bash +cd atsf_agent +go build -o atsflare-agent ./cmd/agent +./atsflare-agent -config /path/to/agent.json +``` + +## 4. 最小联调步骤 + +以下步骤用于验证完整闭环。 + +### 4.1 创建规则 + +1. 登录管理端 +2. 打开“规则”页面 +3. 新增一条反代规则，例如： + - 域名：`demo.example.com` + - 源站：`http://127.0.0.1:8080` + - 启用：开启 + +### 4.2 发布版本 + +1. 在“规则”页面点击“发布当前规则” +2. 或在“版本”页面点击“生成新版本” +3. 确认“版本”页面出现新的激活版本 + +### 4.3 验证 Agent 拉取与应用 + +启动 Agent 后，预期行为如下： + +1. Agent 首次注册节点 +2. Agent 拉取当前激活版本 +3. Agent 写入 `route_config_path` +4. Agent 执行 `nginx -t` +5. Agent 执行 `nginx -s reload` +6. Agent 上报成功结果 + +### 4.4 验证管理端状态 + +在管理端确认： + +- “节点”页面中节点状态为“在线” +- 节点的“当前版本”与刚发布版本一致 +- “应用记录”页面中存在成功记录 + +### 4.5 验证失败回滚 + +可以手工制造一次失败，例如： + +- 给节点本地 Nginx 环境制造 `nginx -t` 失败条件 +- 再次发布配置 + +预期结果： + +- Agent 写入新文件后校验失败 +- Agent 恢复旧路由文件 +- Server 中节点 `last_error` 更新 +- “应用记录”页面出现失败记录 + +## 5. 常用验证命令 + +### Server + +```bash +cd atsf_server +GOCACHE=/tmp/atsflare-go-cache go test ./... +``` + +### Agent + +```bash +cd atsf_agent +GOCACHE=/tmp/atsflare-go-cache go test ./... +``` + +### 前端 + +```bash +cd atsf_server/web +npm run build +``` + +## 6. 已知限制 + +- Agent 配置中的时间字段目前使用纳秒整数，不够友好 +- Agent 运行器当前任一心跳或同步失败会直接退出，需要结合进程管理器拉起 +- 尚未提供 systemd unit 文件 +- 尚未提供 Docker Compose 或一键部署脚本 +- 前端页面已可用，但交互和校验仍是 MVP 水平 +- 目前联调说明以手工步骤为主，未内置完整自动化端到端脚本 + +## 7. 下一阶段候选项 + +- 提供 `systemd` 服务文件与日志轮转建议 +- 增加 Agent 配置文件示例模板 +- 把 `time.Duration` 配置改成更易读的字符串格式 +- 为 Agent 增加退避重试与更细粒度错误恢复 +- 增加真实 Nginx 环境的集成测试