添加部署与联调说明文档，包含前置条件、启动步骤和验证流程

2026-09-30 06:16:37 +08:00 · 2026-03-09 23:30:50 +08:00
parent 6a9d56e045
commit 65817ac9b6
2 changed files with 239 additions and 87 deletions
@@ -1,104 +1,63 @@
-<p align="right">
-   <strong>中文</strong> | <a href="./README.en.md">English</a>
-</p>
+# ATSFlare

-<p align="center">
-  <a href="https://github.com/songquanpeng/gin-template"><img src="https://raw.githubusercontent.com/songquanpeng/gin-template/main/web/public/logo.png" width="150" height="150" alt="gin-template logo"></a>
-</p>
+ATSFlare 是一个面向内部使用的 Nginx 反向代理控制面 MVP。

-<div align="center">
+当前版本只覆盖以下闭环：

-# Gin 项目模板
+- 管理端维护反代规则
+- Server 生成并激活配置版本
+- Agent 拉取激活版本并写入独立 Nginx 路由配置文件
+- Agent 执行 `nginx -t` 和 `nginx -s reload`
+- Server 展示节点状态和最近一次应用结果

-_✨ 用于 Gin & React 项目的模板 ✨_
+不包含多租户、WAF、限流、Redis、对象存储、复杂缓存策略等平台化能力。

-</div>
+## 仓库结构

-<p align="center">
-  <a href="https://raw.githubusercontent.com/songquanpeng/gin-template/main/LICENSE">
-    <img src="https://img.shields.io/github/license/songquanpeng/gin-template?color=brightgreen" alt="license">
-  </a>
-  <a href="https://github.com/songquanpeng/gin-template/releases/latest">
-    <img src="https://img.shields.io/github/v/release/songquanpeng/gin-template?color=brightgreen&include_prereleases" alt="release">
-  </a>
-  <a href="https://hub.docker.com/repository/docker/justsong/gin-template">
-    <img src="https://img.shields.io/docker/pulls/justsong/gin-template?color=brightgreen" alt="docker pull">
-  </a>
-  <a href="https://github.com/songquanpeng/gin-template/releases/latest">
-    <img src="https://img.shields.io/github/downloads/songquanpeng/gin-template/total?color=brightgreen&include_prereleases" alt="release">
-  </a>
-  <a href="https://goreportcard.com/report/github.com/songquanpeng/gin-template">
-    <img src="https://goreportcard.com/badge/github.com/songquanpeng/gin-template" alt="GoReportCard">
-  </a>
-</p>
+- `atsf_server`: Gin + GORM + SQLite 的控制中心，包含管理端 API、Agent API 和 Web 管理台
+- `atsf_agent`: Go 单体 Agent，负责注册、心跳、同步配置、写入 Nginx 路由文件并 reload
+- `docs`: 设计、开发规范、开发计划和部署联调文档

-<p align="center">
-  <a href="https://github.com/songquanpeng/gin-template/releases">程序下载</a>
-  ·
-  <a href="https://github.com/songquanpeng/gin-template#部署">部署教程</a>
-  ·
-  <a href="https://github.com/songquanpeng/gin-template/issues">意见反馈</a>
-  ·
-  <a href="https://gin-template.vercel.app/">在线演示</a>
-</p>
+接手前请先阅读：

-## 功能
-+ [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 <port_number>`: 指定服务器监听的端口号，默认为 `3000`。
-   + 例子：`--port 3000`
-2. `--log-dir <log_dir>`: 指定日志文件夹，如果没有设置，日志将不会被保存。
-   + 例子：`--log-dir ./logs`
-3. `--version`: 打印系统版本号并退出。
+- Server 默认使用 SQLite
+- 不配置 `REDIS_CONN_STRING`
+- Agent 鉴权使用 `X-Agent-Token`
+- 第一版只管理独立生成的 Nginx 路由配置文件
+
+## 后续工作
+
+当前 MVP 已可支撑最小闭环。下一阶段优先项通常包括：
+
+- 补充 systemd 服务示例
+- 增加真实环境联调记录
+- 优化前端交互和表单校验
+- 增加更多 Agent 侧集成测试
@@ -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 环境的集成测试