[优化] 接口优化, 心跳请求返回规则摘要

docs/app-config.md

@@ -104,8 +104,7 @@ volumes:
 
 | 配置项 | 作用 | 默认值 |
 | --- | --- | --- |
-| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `30000` |
-| `AgentSyncInterval` | Agent 同步间隔（毫秒） | `30000` |
+| `AgentHeartbeatInterval` | Agent 心跳间隔（毫秒） | `10000` |
 | `NodeOfflineThreshold` | 节点离线判定阈值（毫秒） | `120000` |
 | `AgentUpdateRepo` | Agent 自更新仓库 | `Rain-kl/ATSFlare` |
 | `GlobalApiRateLimitNum` / `GlobalApiRateLimitDuration` | 全局 API 限流次数 / 时间窗口（秒） | `300` / `180` |
@@ -216,13 +215,12 @@ 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_docker_image": "openresty/openresty:alpine",
-	"heartbeat_interval": 30000,
-	"sync_interval": 30000,
-	"request_timeout": 10000
-}
+	"data_dir": "./data",
+	"openresty_container_name": "atsflare-openresty",
+	"openresty_docker_image": "openresty/openresty:alpine",
+	"heartbeat_interval": 10000,
+	"request_timeout": 10000
+}
 ```
 
 使用节点专属 Token 的示例：
@@ -239,11 +237,10 @@ go run ./cmd/agent -config ./agent.json
 	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
 	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
 	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"state_path": "./data/agent-state.json",
-	"heartbeat_interval": 30000,
-	"sync_interval": 30000,
-	"request_timeout": 10000
-}
+	"state_path": "./data/agent-state.json",
+	"heartbeat_interval": 10000,
+	"request_timeout": 10000
+}
 ```
 
 ### 2.3 Agent 配置字段
@@ -265,15 +262,14 @@ go run ./cmd/agent -config ./agent.json
 | `cert_dir` | Agent 在本机写入证书文件的目录 | 否 | 默认为 `data_dir` 下托管证书目录 | `./data/etc/nginx/certs` |
 | `openresty_cert_dir` | OpenResty 实际读取证书的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/atsflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
 | `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` |
-| `heartbeat_interval` | 心跳间隔 | 否 | `30000` 毫秒 | `30000` |
-| `sync_interval` | 配置同步间隔 | 否 | `30000` 毫秒 | `30000` |
+| `heartbeat_interval` | 心跳间隔 | 否 | `10000` 毫秒 | `10000` |
 | `request_timeout` | HTTP 请求超时时间 | 否 | `10000` 毫秒 | `10000` |
 
 说明：
 
 * `agent_token` 与 `discovery_token` 不能同时为空
-* `heartbeat_interval`、`sync_interval`、`request_timeout` 支持两种写法：
-	* 毫秒整数，例如 `30000`
+* `heartbeat_interval`、`request_timeout` 支持两种写法：
+	* 毫秒整数，例如 `10000`
 	* Go duration 字符串，例如 `"30s"`
 * `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错
 * 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式

docs/deployment.md

@@ -149,13 +149,12 @@ 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_docker_image": "openresty/openresty:alpine",
-  "heartbeat_interval": 30000,
-  "sync_interval": 30000,
-  "request_timeout": 10000
-}
+  "data_dir": "./data",
+  "openresty_container_name": "atsflare-openresty",
+  "openresty_docker_image": "openresty/openresty:alpine",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
 ```
 
 ### 3.2 全局 `discovery_token`
@@ -164,13 +163,12 @@ 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_docker_image": "openresty/openresty:alpine",
-  "heartbeat_interval": 30000,
-  "sync_interval": 30000,
-  "request_timeout": 10000
-}
+  "data_dir": "./data",
+  "openresty_container_name": "atsflare-openresty",
+  "openresty_docker_image": "openresty/openresty:alpine",
+  "heartbeat_interval": 10000,
+  "request_timeout": 10000
+}
 ```
 
 说明：
@@ -230,12 +228,12 @@ go build -o atsflare-agent ./cmd/agent
 
 ### 5.3 验证 Agent 应用
 
-预期行为：
-
-1. Agent 完成心跳与同步
-2. 自动注册模式下完成 Token 置换
-3. 拉取激活版本
-4. 写入主配置、路由配置与必要证书文件
+预期行为：
+
+1. Agent 完成心跳
+2. 自动注册模式下完成 Token 置换
+3. 心跳响应返回激活版本摘要；若版本或 checksum 不一致，则拉取激活版本
+4. 写入主配置、路由配置与必要证书文件
 5. 执行 `openresty -t`
 6. 执行 `openresty -s reload`
 7. 上报应用结果
@@ -448,7 +446,6 @@ GitHub Release 中的 Agent 二进制命名格式：
 | 参数                   | 说明                 | Agent 字段         |
 | ---------------------- | -------------------- | ------------------ |
 | AgentHeartbeatInterval | 心跳间隔（毫秒）     | heartbeat_interval |
-| AgentSyncInterval      | 同步间隔（毫秒）     | sync_interval      |
 | NodeOfflineThreshold   | 节点离线阈值（毫秒） | -                  |
 | AgentUpdateRepo        | 自动更新仓库         | update_repo        |
 

docs/design.md

@@ -127,6 +127,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 * Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相
 * 发布通过“生成完整版本并激活”完成
 * 历史版本不可变
+* Agent 常规轮询以 heartbeat 为主；heartbeat 响应返回当前激活版本的 `version` 与 `checksum` 摘要，Agent 仅在发现不一致时再拉取完整配置
 
 ---
 

docs/development-guidelines.md

@@ -220,6 +220,7 @@ Agent 必须满足：
 * 未显式配置 `node_name` 时自动获取主机名
 * 未显式配置 `node_ip` 时自动探测本机 IP
 * 周期性心跳与同步
+* 常规同步判定优先通过 heartbeat 响应中的激活版本 `version` / `checksum` 摘要完成；仅在 Agent 本地状态与摘要不一致时，再请求完整激活配置
 * 发现新版本时先备份旧文件
 * 写入新的主配置、路由配置与必要证书文件
 * 先执行 `openresty -t`