tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 05:56:38 +08:00
Code Issues Packages Projects Releases Wiki Activity

[优化] 文档更新

Browse Source
This commit is contained in:
ryan
2026-03-10 17:24:51 +08:00
parent 9d4f4450ca
commit eb23826bac
5 changed files with 612 additions and 1382 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+69 -63
View File
@@ -1,63 +1,69 @@
# ATSFlare
ATSFlare 是一个面向内部使用的 Nginx 反向代理控制面 MVP。
当前版本只覆盖以下闭环：
- 管理端维护反代规则
- Server 生成并激活配置版本
- Agent 拉取激活版本并写入独立 Nginx 路由配置文件
- Agent 执行 `nginx -t` 和 `nginx -s reload`
- Server 展示节点状态和最近一次应用结果
不包含多租户、WAF、限流、Redis、对象存储、复杂缓存策略等平台化能力。
## 仓库结构
- `atsf_server`: Gin + GORM + SQLite 的控制中心，包含管理端 API、Agent API 和 Web 管理台
- `atsf_agent`: Go 单体 Agent，负责注册、心跳、同步配置、写入 Nginx 路由文件并 reload
- `docs`: 设计、开发规范、开发计划和部署联调文档
接手前请先阅读：
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)
## 当前功能状态
- Phase 1: Server 数据层与发布闭环，已完成
- Phase 2: Agent API 与节点状态，已完成
- Phase 3: Agent 本体最小闭环，已完成
- Phase 4: 管理端页面，已完成
- Phase 5: 部署与联调文档，已完成
## 快速开始
最小运行步骤见：
- [docs/deployment.md](/Users/ryan/DEV/Go/ATSFlare/docs/deployment.md)
如果只想快速验证测试：
```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
```
## 默认约束
- Server 默认使用 SQLite
- 不配置 `REDIS_CONN_STRING`
- Agent 鉴权使用 `X-Agent-Token`
- 第一版只管理独立生成的 Nginx 路由配置文件
## 后续工作
当前 MVP 已可支撑最小闭环。下一阶段优先项通常包括：
- 补充 systemd 服务示例
- 增加真实环境联调记录
- 优化前端交互和表单校验
- 增加更多 Agent 侧集成测试
<p align="right">
<a href="./README.md">中文</a> | <strong>English</strong>
</p>
[//]: # (<p align="center">)
[//]: # ( <a href="https://github.com/Rain-kl/ATSFlare"><img src="https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/atsf_server/web/public/logo.png" width="150" height="150" alt="ATSFlare logo"></a>)
[//]: # (</p>)
<div align="center">
# ATSFlare
_✨ control plane for reverse proxy management ✨_
</div>
<p align="center">
<a href="https://raw.githubusercontent.com/Rain-kl/ATSFlare/main/LICENSE">
<img src="https://img.shields.io/github/license/Rain-kl/ATSFlare?color=brightgreen" alt="license">
</a>
<a href="https://github.com/Rain-kl/ATSFlare/releases/latest">
<img src="https://img.shields.io/github/v/release/Rain-kl/ATSFlare?color=brightgreen&include_prereleases" alt="release">
</a>
<a href="https://github.com/Rain-kl/ATSFlare/releases/latest">
<img src="https://img.shields.io/github/downloads/Rain-kl/ATSFlare/total?color=brightgreen&include_prereleases" alt="release">
</a>
<a href="https://goreportcard.com/report/github.com/Rain-kl/ATSFlare">
<img src="https://goreportcard.com/badge/github.com/Rain-kl/ATSFlare" alt="GoReportCard">
</a>
</p>
[//]: # (<p align="center">)
[//]: # ( <a href="https://github.com/Rain-kl/ATSFlare/releases">Download</a>)
[//]: # ( ·)
[//]: # ( <a href="https://github.com/Rain-kl/ATSFlare/blob/main/README.en.md#deployment">Tutorial</a>)
[//]: # ( ·)
[//]: # ( <a href="https://github.com/Rain-kl/ATSFlare/issues">Feedback</a>)
[//]: # (</p>)
## 仓库结构
- `atsf_server`: Gin + GORM + SQLite 的控制中心，包含管理端 API、Agent API 和 Web 管理台
- `atsf_agent`: Go 单体 Agent，负责注册、心跳、同步配置、写入 Nginx 路由文件并 reload
- `docs`: 设计、开发规范、开发计划和部署联调文档
## 快速开始
- [docs/deployment.md](/Users/ryan/DEV/Go/ATSFlare/docs/deployment.md)
## 贡献
参与开发请先阅读：
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)
docs/deployment.md
+79 -157
View File
@@ -1,27 +1,25 @@
# ATSFlare 部署与联调说明
# ATSFlare 部署与联调说明（当前基线）
本文档用于指导在新环境手工完成 ATSFlare 当前版本的最小部署与联调。
本文档仅保留当前可用基线的最小部署方式，用于第三版开发前后的本地部署、联调与回归验证。
当前文档已同步第二版 Phase 3 的节点接入方式：
- 预创建节点：管理端创建节点后，直接生成该节点专属 `auth token`（即 `agent_token`）
- 自动发现：管理端维护一个全局 `discovery token`，多个新节点可共用该 token 自动注册
- 自动发现注册成功后，Server 会为该节点下发新的专属 `agent_token`，Agent 自动完成本地 token 置换
---
## 1. 前置条件
### Server
### 1.1 Server
- Go 1.18+
- Node.js 18+ 与 npm
- 本地可写 SQLite 文件目录
* Go 1.18+
* Node.js 18+
* 可写 SQLite 文件目录
### Agent
### 1.2 Agent
- Go 1.18+
- Agent 对目标路由文件路径有写权限
- 如果使用独立 Nginx 模式：节点已安装 `nginx`，且 Agent 运行用户可以执行 `nginx -t` 和 `nginx -s reload`
- 如果使用 Docker 模式：节点已安装 Docker，且 Agent 运行用户有权限执行 Docker 命令
* Go 1.18+
* 对 Agent 数据目录有写权限
* 若使用独立 Nginx 模式：可执行 `nginx -t` 与 `nginx -s reload`
* 若使用 Docker 模式：具备 Docker 执行权限
---
## 2. Server 启动
@@ -33,9 +31,7 @@ npm install
npm run build
```
### 2.2 启动 Server
推荐在仓库根目录执行：
### 2.2 启动服务
```bash
cd atsf_server
@@ -46,10 +42,9 @@ go run .
说明：
- 如果未设置 `SQLITE_PATH`，默认也会落到 `atsf_server/atsflare.db`
- 当前不再依赖全局 `AGENT_TOKEN` 环境变量
- 节点接入凭证改由数据库保存：节点专属 `agent_token` + 系统级 `discovery token`
- 当前默认监听端口为 `3000`
* 默认不依赖全局 `AGENT_TOKEN`
* 节点接入凭证由数据库维护：节点专属 `agent_token` + 全局 `discovery_token`
* 默认监听端口为 `3000`
### 2.3 首次登录
@@ -57,20 +52,16 @@ go run .
默认账号：
- 用户名：`root`
- 密码：`123456`
* 用户名：`root`
* 密码：`123456`
首次登录后建议立即修改密码。
---
## 3. Agent 启动
## 3. Agent 配置
### 3.1 Agent 配置文件示例
当前支持两种接入模式。
Agent 现在支持两种接入模式。
#### 方式 A：使用预创建节点的专属 auth token
在节点上创建 `agent.json`：
### 3.1 节点专属 `agent_token`
```json
{
@@ -87,7 +78,7 @@ Agent 现在支持两种接入模式。
}
```
#### 方式 B：使用全局 discovery token 自动注册
### 3.2 全局 `discovery_token`
```json
{
@@ -104,56 +95,26 @@ Agent 现在支持两种接入模式。
}
```
注意：
说明：
- 时间字段单位是纳秒，因为当前实现直接使用 Go 的 `time.Duration` JSON 反序列化
- `agent_token` 与 `discovery_token` 至少填写一个
- 当填写节点专属 `agent_token` 时，Agent 会直接以该 Token 进行心跳、拉取配置和上报
- 当 `agent_token` 为空且填写 `discovery_token` 时，Agent 会自动注册，注册成功后会把新的专属 `agent_token` 写回本地配置文件，并清空 `discovery_token`
- `node_name` 与 `node_ip` 现在可省略；未填写时会自动探测主机名和本机 IPv4 地址，手动填写则视为覆盖
- 生成资源默认统一落在 `./data`
- 如果未指定 `nginx_path`，Agent 会自动使用以下固定路径：
- `./data/etc/nginx/conf.d/atsflare_routes.conf`
- `./data/var/lib/atsflare/agent-state.json`
- 如果希望修改保存位置，可通过 `data_dir` 统一覆盖生成资源目录
- Docker 模式默认使用 `nginx_container_name` 和 `nginx_docker_image`
- `nginx_path` 仅在独立 Nginx 路径模式下使用；此时如有需要，仍可单独覆盖 `route_config_path` 和 `state_path`
* 时间字段当前仍使用纳秒整数
* `agent_token` 与 `discovery_token` 至少填写一个
* 若 `agent_token` 为空且 `discovery_token` 存在，Agent 会自动注册并写回新的专属 `agent_token`
* `node_name` 与 `node_ip` 可省略，未填写时自动探测
* 未配置 `nginx_path` 时，默认使用 Docker Nginx 容器
### 3.2 获取接入 Token
---
#### 方式 A：预创建节点
## 4. Agent 启动
1. 登录管理端
2. 打开“节点”页面
3. 点击“新增节点”
4. 创建成功后，页面会显示该节点的专属 `Auth Token`
5. 将该 token 写入对应节点的 `agent.json` 中的 `agent_token`
适用场景：
- 固定节点、固定槽位管理
- 需要明确一台机器占据哪一个节点位
#### 方式 B：全局自动发现
1. 登录管理端
2. 打开“节点”页面
3. 查看页面顶部的全局 `Discovery Token`
4. 将同一个 token 分发给多台待接入节点，写入各自 `agent.json` 中的 `discovery_token`
适用场景：
- 批量部署 Agent
- 节点数量较多，不希望逐台预生成 token
### 3.3 启动 Agent
### 4.1 直接运行
```bash
cd atsf_agent
go run ./cmd/agent -config /path/to/agent.json
```
如果需要编译二进制：
### 4.2 编译后二进制运行
```bash
cd atsf_agent
@@ -161,128 +122,89 @@ go build -o atsflare-agent ./cmd/agent
./atsflare-agent -config /path/to/agent.json
```
## 4. 最小联调步骤
---
以下步骤用于验证完整闭环。
## 5. 最小联调步骤
### 4.1 创建节点或准备 discovery token
### 5.1 准备节点接入
二选一：
#### 方案 A：预创建节点
* 在管理端预创建节点并复制专属 `agent_token`
* 在管理端查看全局 `discovery_token` 并写入节点配置
1. 登录管理端
2. 打开“节点”页面
3. 新增一个节点，例如：`edge-01`
4. 复制该节点展示的 `Auth Token`
5. 在目标机器的 `agent.json` 中填入该 `agent_token`
### 5.2 创建规则并发布
#### 方案 B：自动发现
1. 在管理端新增一条启用中的反代规则
2. 在发布前查看预览或变更摘要
3. 生成并激活新版本
1. 登录管理端
2. 打开“节点”页面
3. 复制全局 `Discovery Token`
4. 在目标机器的 `agent.json` 中填入该 `discovery_token`
### 5.3 验证 Agent 应用
### 4.2 创建规则
预期行为：
1. 登录管理端
2. 打开“规则”页面
3. 新增一条反代规则，例如：
- 域名：`demo.example.com`
- 源站：`http://127.0.0.1:8080`
- 启用：开启
1. Agent 完成心跳与同步
2. 自动注册模式下完成 Token 置换
3. 拉取激活版本
4. 写入路由配置与必要证书文件
5. 执行 `nginx -t`
6. 执行 `nginx -s reload`
7. 上报应用结果
### 4.3 发布版本
### 5.4 验证管理端状态
1. 在“规则”页面点击“发布当前规则”
2. 或在“版本”页面点击“生成新版本”
3. 确认“版本”页面出现新的激活版本
管理端应能看到：
### 4.4 验证 Agent 拉取与应用
* 节点在线状态
* 节点当前版本
* 最近一次应用结果
* 自动注册后节点已绑定专属 `agent_token`
启动 Agent 后，预期行为如下：
### 5.5 验证失败回滚
1. 如果配置的是节点专属 `agent_token`：Agent 直接进入心跳与同步流程
2. 如果配置的是全局 `discovery_token`：Agent 先自动注册，拿到新的专属 `agent_token` 并写回本地配置
3. Agent 拉取当前激活版本
4. Agent 写入 `route_config_path`
5. Agent 使用 `nginx_path` 指向的独立 Nginx，或自动准备 Docker Nginx 容器
6. Agent 启动时先校验本地路由文件 checksum 与控制面激活版本是否一致
7. Docker 模式下会重建容器，避免复用故障容器
8. Agent 执行 `nginx -t`
9. Agent 执行 `nginx -s reload`
10. Agent 上报成功结果
人为制造 `nginx -t` 失败后再次发布，预期：
### 4.5 验证管理端状态
* Agent 回滚旧配置
* 节点 `last_error` 更新
* 应用记录中出现失败记录
在管理端确认：
---
- “节点”页面中节点状态为“在线”
- 预创建节点在被实际占用前状态为“待接入”，占用后变为“在线”或“离线”
- 节点的“当前版本”与刚发布版本一致
- “应用记录”页面中存在成功记录
## 6. 常用验证命令
如果使用自动发现模式，还应确认：
- 注册成功后，Agent 本地 `agent.json` 中已写入新的 `agent_token`
- 注册成功后，本地 `discovery_token` 已被清空
### 4.6 验证失败回滚
可以手工制造一次失败，例如：
- 给节点本地 Nginx 环境制造 `nginx -t` 失败条件
- 再次发布配置
预期结果：
- Agent 写入新文件后校验失败
- Agent 恢复旧路由文件
- Server 中节点 `last_error` 更新
- “应用记录”页面出现失败记录
## 5. 常用验证命令
### Server
### 6.1 Server
```bash
cd atsf_server
GOCACHE=/tmp/atsflare-go-cache go test ./...
```
### Agent
### 6.2 Agent
```bash
cd atsf_agent
GOCACHE=/tmp/atsflare-go-cache go test ./...
```
### 前端
### 6.3 前端
```bash
cd atsf_server/web
npm run build
```
## 6. 已知限制
---
- Agent 配置中的时间字段目前使用纳秒整数，不够友好
- 尚未提供 systemd unit 文件
- 尚未提供 Docker Compose 或一键部署脚本
- Docker 模式当前默认直接重建单容器 Nginx，挂载与端口策略仍是 MVP 水平
- 前端页面已可用，但交互和校验仍是 MVP 水平
- 目前联调说明以手工步骤为主，未内置完整自动化端到端脚本
## 7. 当前已知限制
补充说明：
* 时间字段仍使用纳秒整数，不够友好
* 暂未内置 systemd unit 文件
* 暂未提供一键部署脚本
* Docker 模式仍是 MVP 级封装
* 联调以手工步骤为主
- Agent 当前已按守护进程式行为实现，心跳失败、同步失败或“当前没有激活版本”不会导致进程直接退出
- 但生产环境仍建议结合 `systemd`、Supervisor 或容器重启策略托管进程
---
## 7. 下一阶段候选项
## 8. 文档维护要求
- 提供 `systemd` 服务文件与日志轮转建议
- 增加 Agent 配置文件示例模板
- 把 `time.Duration` 配置改成更易读的字符串格式
- 为 Agent 增加退避重试与更细粒度错误恢复
- 增加真实 Nginx 环境的集成测试
当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。
docs/design.md
+199 -650
View File
@@ -1,797 +1,346 @@
# ATSFlare MVP 设计文档
# ATSFlare 设计基线（V3 准备版）
## 1. 目标
## 1. 文档目的
先做一个能用的版本，不做平台化过度设计。第一版只解决 3 件事：
本文档不再展开记录第一版、第二版的实施过程，只保留当前系统边界、稳定约束与第三版开始前必须确认的设计输入。
* 配置发布与同步
* 节点心跳检测
* Nginx 反向代理配置下发
当前结论：
系统定位是内部自用的控制面，不是面向外部租户的 CDN SaaS。
* 第一版、第二版已完成并进入归档状态
* 当前代码库的可运行能力，以本文档为唯一设计基线
* 第三版开发前，如需扩展系统边界，先更新本文档，再开始编码
---
## 2. 第一版范围（已完成）
## 2. 当前产品定位
### 已做
ATSFlare 当前仍定位为**内部自用的反向代理控制面**，不是面向外部租户的 CDN SaaS。
* Web 管理端维护反代规则
* 配置发布生成版本
* Agent 定时同步并应用配置
* Agent 控制本机 Nginx 校验与 reload
* 节点注册、心跳、在线状态展示
* 展示每个节点当前生效版本和最近一次应用结果
当前已经具备的核心能力：
### 不做（第一版）
* 反代规则管理
* 配置渲染、发布、激活与回滚
* Agent 心跳、同步、应用结果上报
* Nginx 配置写入、校验、reload 与失败回滚
* HTTPS/TLS 路由支持
* 证书托管与域名管理
* 节点预创建、节点专属 `agent_token`、全局 `discovery_token`
* 配置预览与变更摘要
当前默认工作方式：
* 所有节点消费同一份全局激活版本
* 控制面保存状态与配置，不直接 SSH 管理机器
* Agent 是节点侧唯一落地入口
---
## 3. 明确保持不做的范围
在第三版目标明确前，以下内容仍视为范围外：
* 多租户
* WAF、限流、Bot、防刷
* 灰度发布、节点分组、分批发布
* 对象存储、消息队列、Redis、Prometheus
* 复杂缓存策略管理
* 证书托管与自动签发
* Purge、中台审计、审批流
* mid-tier / 分层缓存
* 节点分组、差异化下发、灰度百分比发布
* Redis、消息队列、对象存储、Prometheus
* 复杂缓存策略、分层缓存、mid-tier
* 证书自动签发与自动续期
* 审批流、审计中台、Purge 平台化能力
* 抽象 `zone`、`origin_pool`、`policy`、`deployment` 等平台对象
第一版默认所有节点消费同一份全量配置，不做差异化下发。
如果第三版需要引入以上任一能力，必须先补设计，再进入实现。
---
## 2.5 第二版范围
## 4. 技术基线
在 MVP 闭环稳定运行的基础上，第二版聚焦以下增量能力。
### 4.1 Server
### 要做
**2.5.1 HTTPS/TLS 支持**
* `proxy_routes` 增加 HTTPS 相关字段：`enable_https`、`cert_id`、`redirect_http`
* 渲染器根据字段生成 HTTPS `server` 块（443 端口），并可选生成 HTTP → HTTPS 重定向块
* 控制面托管证书并下发到节点本地，支持手动导入与文件导入
**2.5.2 域名管理与证书托管**
* 新增 `managed_domains` 表：管理业务域名，支持精确域名与通配符域名（如 `*.example.com`）
* 新增 `tls_certificates` 表：保存证书与私钥，支持手动粘贴导入和证书文件上传导入
* 控制面新增证书管理与域名管理页面
* 在反代规则编辑时，输入域名后自动匹配可用证书（包含通配符匹配）
**2.5.3 Agent 管理与自动发现**
* 管理端支持手工创建节点、编辑节点名、删除节点
* 管理端手工创建节点时，直接为该节点生成专属 `agent_token`
* 预创建节点时，持有该 `agent_token` 的 Agent 会占据该节点位，并持续以该 Token 完成后续鉴权
* 系统同时维护一个全局 `discovery_token`，任意新节点可使用该 Token 自动接入 Server
* Agent 使用全局 `discovery_token` 首次注册成功后，Server 会为该节点生成专属 `agent_token`，Agent 本地完成 Token 置换
* Agent 默认自动探测主机名与 IP，也允许通过配置覆盖
**2.5.4 路由增强**
* `proxy_routes` 增加 `custom_headers` 字段（JSON 格式），支持每条路由追加自定义 `proxy_set_header` 指令
* 渲染器按 `custom_headers` 内容注入到对应 `server` 块
**2.5.5 配置预览与变更摘要**
* 新增"配置预览"接口：在不实际发布的情况下，返回基于当前启用规则渲染的 Nginx 配置
* 新增"变更摘要"接口：对比当前激活版本与新渲染结果，返回新增、删除、修改的域名列表
* 前端发布页接入预览与变更摘要，让管理员在点击发布前确认变化
### 仍不做（第二版）
* 多租户
* WAF、限流、Bot、防刷
* 节点分组与差异化下发
* 对象存储、消息队列、Redis、Prometheus
* 证书自动签发（ACME）
* Purge、中台审计、审批流
* mid-tier / 分层缓存
* 复杂缓存策略配置
---
## 3. 技术约束
### Server
控制中心直接基于现有 `atsf_server` 的 `ATSFlare` 工程开发：
基于 `atsf_server` 单体应用继续演进：
* Web 框架：Gin
* ORM：GORM
* 前端：沿用现有 web 管理端
* 鉴权：沿用 ATSFlare 登录体系
* 数据库：SQLite
* 管理端前端：`atsf_server/web`
* 用户鉴权：沿用现有 ATSFlare 登录体系
### 数据库
默认不以新基础设施为前提：
只使用 SQLite，不引入其他中间件：
* 不依赖 Redis
* 不依赖 MQ
* 不依赖外部对象存储
* 不配置 `SQL_DSN`，直接走项目现有 SQLite 初始化逻辑
* 不配置 `REDIS_CONN_STRING`，会退化为 cookie session
### 4.2 Agent
### Agent
Agent 使用 Go 单体程序：
基于 `atsf_agent` Go 单体程序继续演进：
* 单二进制
* systemd 管理
* 优先调用独立 Nginx，而不是依赖系统全局 Nginx
* 显式配置 `nginx_path` 时，直接调用该路径下的 Nginx
* 未配置 `nginx_path` 时，默认通过 Docker 运行独立 Nginx 容器
* 管理本机 Nginx 路由配置文件和 reload
* Agent 生成资源默认统一落在 `./data`，也允许通过单个基路径配置覆盖
* Agent 启动时会校验本地路由文件哈希与控制面激活版本是否一致
* Docker 模式启动时会重建独立 Nginx 容器，避免复用故障容器
* 节点本地执行
* 优先使用独立 Nginx
* 显式配置 `nginx_path` 时直接调用该路径
* 未配置 `nginx_path` 时默认使用 Docker Nginx 容器
* 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
### Nginx 管理边界
### 4.3 Nginx 管理边界
第一版只管理最核心的反代映射：
控制面当前只管理以下内容：
* 重点生成独立的 Nginx 路由配置文件，例如 `/etc/nginx/conf.d/atsflare_routes.conf`
* `nginx.conf`、TLS 证书、缓存细节、upstream 高级配置先保持节点本地静态配置
* Agent 可以管理独立安装路径下的 Nginx，或者独立 Docker Nginx 容器
* 反向代理路由配置
* 控制面托管证书对应的本地证书文件
也就是说，MVP 先把 Nginx 当成“可集中配置的反向代理”，不是完整网关平台。
仍不管理以下内容：
* `nginx.conf`
* upstream 高级编排
* 复杂缓存策略
* 节点级系统运维逻辑
---
## 4. 总体架构
## 5. 当前总体架构
```text
┌────────────────────────────┐
│ ATSFlare Server │
│ ATSFlare + SQLite │
│ Admin UI + Admin API │
└──────────────┬─────────────┘
│
HTTP API / Config Pull
│
┌──────────────────┴──────────────────┐
│ │
┌────────▼────────┐ ┌────────▼────────┐
│ Nginx Agent 1 │ │ Nginx Agent N │
│ heartbeat/sync │ │ heartbeat/sync │
│ nginx reload │ │ nginx reload │
└────────┬────────┘ └────────┬────────┘
│ │
┌─────▼─────┐ ┌─────▼─────┐
│ Nginx │ │ Nginx │
│ reverse │ │ reverse │
│ proxy │ │ proxy │
└─────┬─────┘ └─────┬─────┘
│ │
└──────────────► Origin ◄────────────┘
ATSFlare Server (Gin + SQLite + Web UI)
|
| HTTP API / Config Pull
v
ATSFlare Agent (heartbeat / sync / apply / report)
|
v
Local Nginx or Docker Nginx
|
v
Origin
```
设计原则只有 3 条：
设计原则保持不变：
* Server 只保存配置和节点状态，不直接 SSH 改机器
* Agent 是唯一的落地入口
* 所有发布都是“新版本生效”，不是在线修改当前文件
* Server 负责配置、版本、节点状态
* Agent 负责本地落盘、校验、reload、回滚
* 发布通过“生成新版本并激活”完成
* 历史版本不可变
---
## 5. 核心对象
## 6. 核心对象
### 5.1 proxy_routes（第一版）
### 6.1 `proxy_routes`
反代规则表，控制 `Host -> Origin` 映射。
表示一条 `domain -> origin_url` 的反向代理规则。
建议字段：
关键字段：
* `id`
* `domain`
* `origin_url`
* `enabled`
* `enable_https`
* `cert_id`
* `redirect_http`
* `custom_headers`
* `remark`
* `created_at`
* `updated_at`
约束：
* `domain` 唯一
* 一个域名只对应一个源站
* `domain` 必须唯一
* `origin_url` 必须是合法的 `http://` 或 `https://`
* 第一版一条域名只对应一个源站，不做源站池
第二版新增字段：
### 6.2 `config_versions`
* `enable_https` — 是否启用 HTTPS（bool，默认 false）
* `cert_id` — 关联托管证书 ID（nullable，未启用 HTTPS 时可为空）
* `redirect_http` — 是否将 HTTP 重定向到 HTTPS（bool，默认 false）
* `custom_headers` — 自定义 `proxy_set_header` 指令（JSON 格式，存字符串）
表示一次完整发布快照。
### 5.2 config_versions（第一版）
关键字段：
发布版本表，保存不可变快照。
建议字段：
* `id`
* `version`
* `snapshot_json`
* `rendered_config`
* `checksum`
* `is_active`
* `created_by`
* `created_at`
说明：
约束：
* `snapshot_json` 保存发布时的完整规则快照
* `rendered_config` 保存渲染后的 Nginx 路由配置
* 第一版直接存 SQLite，不单独上对象存储
* 每个版本保存完整快照与渲染结果
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
第二版沿用第一版字段，不新增分组字段。
### 6.3 `nodes`
### 5.3 nodes（第一版）
表示节点运行状态与接入凭证。
节点表，保存当前状态。
关键字段：
建议字段：
* `id`
* `node_id`
* `name`
* `ip`
* `agent_version`
* `nginx_version`
* `status`
* `current_version`
* `last_seen_at`
* `last_error`
* `created_at`
* `updated_at`
* `agent_token`
第二版沿用第一版字段，不新增分组字段。
约束：
### 5.4 apply_logs（第一版）
* 节点专属 `agent_token` 由 Server 生成并持久化
* 删除节点后，其凭证必须立即失效
* 全局 `discovery_token` 不存放在 `nodes` 表中
节点应用记录。
### 6.4 `apply_logs`
建议字段：
记录节点应用版本的结果。
关键字段：
* `id`
* `node_id`
* `version`
* `result`
* `message`
* `created_at`
### 5.5 tls_certificates（第二版新增）
### 6.5 `tls_certificates`
证书托管表，用于保存证书与私钥内容。
表示控制面托管的证书与私钥。
建议字段：
关键字段：
* `id`
* `name` — 证书名称（唯一）
* `cert_pem` — 证书 PEM 内容
* `key_pem` — 私钥 PEM 内容
* `not_before` — 证书生效时间
* `not_after` — 证书过期时间
* `name`
* `cert_pem`
* `key_pem`
* `not_before`
* `not_after`
* `remark`
* `created_at`
* `updated_at`
### 5.6 managed_domains（第二版新增）
### 6.6 `managed_domains`
域名管理表，用于维护可选域名及其默认证书关系。
表示域名资产及其默认证书关系。
建议字段：
关键字段：
* `id`
* `domain` — 域名（支持精确域名和 `*.example.com`）
* `cert_id` — 关联 `tls_certificates.id`（nullable）
* `domain`
* `cert_id`
* `enabled`
* `remark`
* `created_at`
* `updated_at`
### 5.7 nodes（第二版扩展）
节点表在第二版增加节点管理与自动发现字段。
新增字段建议：
* `agent_token` — 节点专属 Agent Token，用于节点占位与后续正式鉴权
约束：
* 管理端手工创建节点时必须直接生成 `agent_token`
* 一个节点位只对应一个 `agent_token`
* 全局 `discovery_token` 不存放在 `nodes` 表，而由系统配置统一维护
* 使用全局 `discovery_token` 自动接入的节点，应在注册成功后获得新的专属 `agent_token`
* 删除节点后，该节点关联的 Token 必须立即失效
* 支持精确域名与 `*.example.com` 通配符域名
* 证书匹配同时支持精确匹配与通配符匹配
---
## 6. 配置发布模型
## 7. 当前发布模型
第一版不做增量发布，也不做 bundle 文件仓库。
标准链路：
发布逻辑：
```text
修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
```
1. 管理员在后台修改 `proxy_routes`
2. 点击“发布”
3. Server 校验规则
4. Server 根据当前全部启用规则渲染出完整 Nginx 路由配置
5. 生成新 `config_versions` 记录
6. 将该版本标记为当前激活版本
7. Agent 下一次心跳或轮询时发现新版本并拉取
发布规则：
### 版本原则
1. 读取全部启用的 `proxy_routes`
2. 渲染完整 Nginx 配置
3. 计算 `checksum`
4. 写入 `config_versions`
5. 切换激活版本
6. Agent 在下一轮同步中发现并应用
* 一个版本就是一份完整快照
版本规则：
* 版本号格式：`YYYYMMDD-NNN`
* 版本不可变
* 节点只拉取当前激活版本
* 回滚本质上是重新激活旧版本
### 版本号建议
```text
20260309-001
20260309-002
```
### 发布校验
发布前至少做以下检查：
* `domain` 不能为空
* `origin_url` 合法
* 不允许重复域名
* 至少存在 1 条启用规则
---
## 7. Nginx 配置策略
## 8. 当前模块边界
第一版只生成独立的 Nginx 路由配置文件，这样最简单，也最容易验证。
### 8.1 `atsf_server`
### 规则映射
负责：
```conf
server {
listen 80;
server_name www.example.com;
* 管理端 UI 与 API
* Agent API
* 数据存储
* 配置渲染
* 发布与激活
* 节点状态展示
location / {
proxy_pass http://10.0.0.10:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
### 8.2 `atsf_agent`
server {
listen 80;
server_name api.example.com;
负责：
location / {
proxy_pass http://10.0.0.20:9000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### HTTPS 处理
第一版不在控制中心管理证书，第二版开始支持证书托管。
约定如下：
* 第一版：Nginx 的监听端口、证书、TLS 相关配置由节点本地预先准备
* 第二版：控制中心托管证书并在配置下发时生成对应证书文件与 HTTPS 配置引用
* 第二版：反代规则可通过 `cert_id` 绑定证书，并支持 HTTP → HTTPS 重定向
### 缓存处理
第一版不开放缓存策略配置：
* 是否开启缓存由节点静态配置决定
* 控制中心不管理 TTL、Header 改写、缓存规则
---
## 8. Server 模块设计
控制中心仍然是单体应用，不拆服务。
### 8.1 管理端模块
* 登录鉴权
* 反代规则 CRUD
* 发布版本管理
* 节点状态页面
* 应用日志查看
### 8.2 Agent API 模块
* 节点注册
* 心跳上报
* 获取当前激活版本
* 下载指定版本配置
* 首次注册与凭证置换
* 周期性心跳
* 拉取激活版本
* 写入本地路由与证书文件
* 执行 `nginx -t` / `nginx -s reload`
* 失败回滚
* 上报应用结果
### 8.3 渲染模块
### 8.3 `atsf_server/web`
职责很简单：
负责：
* 从 `proxy_routes` 读取全部启用规则
* 按固定模板拼出 Nginx 路由配置
* 计算 checksum
* 写入 `config_versions`
这层不要引入复杂 DSL，第一版直接围绕 `domain -> origin_url` 即可。
* 规则、版本、节点、应用记录页面
* 证书与域名管理页面
* 发布前预览与变更摘要展示
---
## 9. Agent 模块设计
## 9. 当前接口域
Agent 做成一个 Go 单体进程即可。
为控制文档长度，仅保留接口域，不再逐条展开历史接口清单。
### 9.1 本地职责
管理端接口当前覆盖：
* 读取本地配置
* 定时心跳
* 拉取新版本
* 覆盖 Nginx 路由配置文件
* 执行 `nginx -t` 和 `nginx -s reload`
* `proxy-routes`
* `config-versions`
* `nodes`
* `apply-logs`
* `tls-certificates`
* `managed-domains`
Agent 接口当前覆盖：
* 注册
* 心跳
* 获取激活版本
* 上报应用结果
* 保存本地最近成功版本
### 9.2 建议的本地文件
统一约束：
* `/etc/atsf-agent/config.yaml`
* `/var/lib/atsf-agent/state.json`
* `/etc/nginx/conf.d/atsflare_routes.conf`
* `/etc/nginx/conf.d/atsflare_routes.conf.bak`
### 9.3 最小工作流
```text
1. Agent 启动
2. 读取或生成 node_id
3. 上报 heartbeat
4. 获取当前激活版本元数据
5. 若版本变更，则下载 rendered_config
6. 备份旧路由配置文件
7. 写入新路由配置文件
8. 调用 `nginx -t`
9. 校验通过后执行 `nginx -s reload`
10. 记录结果并上报
11. 进入下一轮
```
### 9.4 失败处理
第一版只做最基本的容错：
* 拉取失败：继续使用本地旧配置
* 配置校验或 reload 失败：恢复备份文件并再次校验后 reload
* Server 不可用：不影响 Nginx 继续转发
* 管理端与 Agent API 均使用 JSON
* Agent API 固定放在 `/api/agent/*`
* Agent 鉴权使用 `X-Agent-Token`
---
## 10. 心跳与在线状态
## 10. 第三版设计准备要求
心跳不单独搞复杂监控系统，直接走业务表。
第三版开始编码前，至少先在本文档补齐以下内容：
### 心跳内容
1. **目标问题**：第三版要解决什么实际痛点
2. **范围边界**：明确要做与不做
3. **对象变化**：是否新增表、字段、状态流转
4. **链路影响**：是否影响发布链路、Agent 同步链路、部署方式
5. **兼容策略**：是否影响现有节点、现有版本、现有配置
6. **验收标准**：如何判断第三版完成
Agent 每次上报：
如果第三版包含以下变化，还必须同步更新其他文档：
* `node_id`
* `name`
* `ip`
* `agent_version`
* `nginx_version`
* `current_version`
* `last_apply_result`
* `timestamp`
### 状态判定
建议规则：
* 15 秒一次心跳
* 超过 45 秒未上报记为 `offline`
* 最近一次应用失败但仍有心跳，记为 `warning`
* 正常心跳且版本一致，记为 `online`
* 技术约束变化：更新 `docs/development-guidelines.md`
* 开发阶段与顺序变化：更新 `docs/development-plan.md`
* 部署方式变化：更新 `docs/deployment.md`
---
## 11. API 设计
## 11. 文档策略
### 11.1 管理端 API（第一版，已实现）
第一版、第二版的详细实施过程不再在本文档中长期保留。
* `GET /api/proxy-routes/`
* `POST /api/proxy-routes/`
* `PUT /api/proxy-routes/:id`
* `DELETE /api/proxy-routes/:id`
* `GET /api/config-versions/`
* `GET /api/config-versions/active`
* `POST /api/config-versions/publish`
* `PUT /api/config-versions/:id/activate`
* `GET /api/nodes/`
* `GET /api/apply-logs/`
后续原则：
### 11.2 Agent API（第一版，已实现）
* `POST /api/agent/nodes/register`
* `POST /api/agent/nodes/heartbeat`
* `GET /api/agent/config-versions/active`
* `POST /api/agent/apply-logs`
### 11.3 第二版新增管理端 API
* `GET /api/tls-certificates/` — 证书列表
* `POST /api/tls-certificates/` — 手动导入证书（粘贴 PEM）
* `POST /api/tls-certificates/import-file` — 证书文件导入
* `PUT /api/tls-certificates/:id` — 更新证书备注/状态
* `DELETE /api/tls-certificates/:id` — 删除证书
* `GET /api/managed-domains/` — 域名列表
* `POST /api/managed-domains/` — 创建域名并可绑定默认证书
* `PUT /api/managed-domains/:id` — 更新域名配置
* `DELETE /api/managed-domains/:id` — 删除域名
* `GET /api/tls-certificates/match?domain=` — 按输入域名返回匹配证书（支持 `*.example.com`）
* `GET /api/agent-tokens/` — Token 列表
* `POST /api/agent-tokens/` — 创建 Token
* `DELETE /api/agent-tokens/:id` — 撤销 Token
* `GET /api/config-versions/preview` — 预览当前启用规则的渲染结果（不写库）
* `GET /api/config-versions/diff` — 对比当前激活版本与待发布的变更摘要
### 11.4 鉴权方案
管理端：
* 直接沿用 ATSFlare 的登录态
Agent（第一版）：
* 预共享 Token，请求头 `X-Agent-Token`，Token 值来自环境变量
Agent（第二版）：
* Agent 正式鉴权改为查 `nodes.agent_token`
* 首次注册使用 `nodes.discovery_token`
* 不再依赖全局环境变量 Agent Token
* 后续可升级 mTLS
---
## 12. 页面设计
### 12.1 登录页
沿用 ATSFlare 现有登录。
### 12.2 反代规则页（第一版，已实现）
展示和编辑：
* 域名
* 源站地址
* 是否启用
* 备注
第二版新增字段：
* 是否启用 HTTPS
* 证书选择（自动匹配候选证书，支持通配符）
* 是否 HTTP → HTTPS 重定向
* 自定义请求头（JSON 编辑器）
### 12.3 发布版本页（第一版，已实现）
展示：
* 版本号
* 发布时间
* 发布人
* 是否当前激活
动作：
* 立即发布
* 激活旧版本
第二版新增：
* 发布前展示配置预览与变更摘要
### 12.4 节点页（第一版，已实现）
展示：
* 节点名
* IP
* 在线状态
* 当前版本
* 最后心跳时间
* 最近错误
### 12.5 应用记录页（第一版，已实现）
展示：
* 节点
* 版本
* 成功/失败
* 错误信息
* 时间
### 12.6 节点管理页（第二版增强）
展示：
* 节点名
* Node ID
* 自动发现 Token（仅待接入节点展示）
* 在线状态
* 当前版本
* 最后心跳时间
* 最近错误
动作：
* 创建节点
* 编辑节点名
* 删除节点
### 12.7 证书管理页（第二版新增）
展示：
* 证书名称
* 有效期（起止时间）
* 绑定域名数量
* 备注
动作：
* 手动导入证书（粘贴 PEM）
* 文件导入证书
* 删除证书
### 12.8 域名管理页（第二版新增）
展示：
* 域名（支持 `*.example.com`）
* 绑定证书
* 是否启用
* 备注
动作：
* 创建域名
* 绑定/更换证书
* 删除域名
---
## 13. 代码组织建议
### Server（第一版，已实现）
```text
atsf_server/
controller/
proxy_route.go
config_version.go
node.go
agent.go
model/
proxy_route.go
config_version.go
node.go
apply_log.go
router/
api-router.go
service/
proxy_route.go
config_version.go
agent.go
```
### Server（第二版新增）
```text
atsf_server/
controller/
tls_certificate.go # 证书管理
managed_domain.go # 域名管理
node.go # 节点管理
model/
tls_certificate.go # TLSCertificate 模型
managed_domain.go # ManagedDomain 模型
service/
tls_certificate.go # 证书导入与匹配逻辑
managed_domain.go # 域名管理逻辑
node.go # 节点管理与自动发现逻辑
renderer.go # 抽离渲染逻辑（HTTPS 支持扩展）
middleware/
agent-auth.go # 改为查节点专属 Token 验证
```
### Agent（第一版，已实现）
```text
atsf_agent/
cmd/agent/main.go
internal/config/config.go
internal/heartbeat/service.go
internal/sync/service.go
internal/nginx/manager.go
internal/state/state.go
internal/httpclient/client.go
internal/protocol/agent_api.go
```
### Agent（第二版）
第二版 Agent 无需新增模块，只需在现有模块内扩展：
* `sync`: 拉取包含 HTTPS 与证书引用的渲染配置并应用
* `nginx`: 写入控制面托管证书生成的本地文件并参与 `nginx -t` / reload
---
## 14. 开发顺序
### 第一版（已完成）
1. Server 建表、AutoMigrate
2. 反代规则 CRUD 与发布逻辑
3. Agent API 与节点状态表
4. Agent 同步、落盘、reload、回滚
5. 管理端页面
6. 联调和部署文档
### 第二版（当前阶段）
按以下顺序执行，前项完成后再推进下一项：
1. HTTPS/TLS 支持（ProxyRoute 扩展字段 + 渲染器 + 前端表单）
2. 域名管理与证书托管（managed_domains/tls_certificates + 证书导入 + 自动匹配）
3. Agent 管理（节点 CRUD + discovery token + 节点专属 agent token）
4. 路由增强（custom_headers 字段 + 渲染器注入 + 前端表单）
5. 配置预览与变更摘要（preview 接口 + diff 接口 + 前端发布确认弹窗）
---
## 15. 关键取舍
第一版故意做这些取舍：
* 不抽象 zone、origin pool、policy 这些平台概念
* 不做复杂发布编排，所有节点统一拉当前版本
* 不管理 Nginx 全部配置，只先管独立生成的路由配置文件
* 不引入 Redis、MQ、对象存储，先把单机 SQLite 跑起来
* 不为了“以后可能会用到”提前把系统拆复杂
只要这版能稳定完成下面这条链路，就算成功：
```text
后台改规则 -> 点击发布 -> Agent 拉到新版本 -> Nginx reload -> 节点状态可见
```
这就是当前阶段最需要的 MVP。
### 第二版取舍
* HTTPS 支持由控制面托管证书，但只支持导入，不做自动签发与自动续期
* 第二版不做节点分组，所有节点继续消费同一份激活版本
* 节点专属 Token 不做额外权限分级，第二版仅区分 discovery token 与 agent token 两种用途
* 路由自定义头不做模板变量，只支持静态 key-value，避免过早引入 DSL
* 配置预览只展示渲染结果，不实际验证 Nginx 语法，真实校验仍由 Agent 完成
第二版成功标准：
```text
HTTPS 路由可生效 + 控制面可托管证书并按域名自动匹配（含通配符）+ 节点可通过 discovery token 自动接入并完成 token 置换 + 发布前可预览变更
```
* 设计文档只保留当前有效基线
* 已完成阶段的细节以 Git 历史为准
* 新阶段开始前，先把设计输入写清楚，再进入实现
docs/development-guidelines.md
+162 -318
View File
@@ -1,190 +1,131 @@
# ATSFlare 开发规范
# ATSFlare 开发规范（V3 准备版）
## 1. 适用范围
本规范适用于 ATSFlare 第一版与第二版阶段。
本规范适用于当前代码基线以及第三版开始前后的所有开发工作。
项目第一版已完成以下能力：
当前系统状态：
* 配置发布与同步
* 节点心跳检测
* Nginx 反向代理配置下发
* 第一版、第二版功能已完成
* 当前开发重点不再是补历史阶段细节，而是稳定基线并准备第三版
* 超出 `docs/design.md` 当前边界的需求，必须先补设计，再编码
第二版在此基础上新增以下能力：
* HTTPS/TLS 路由支持
* 证书托管（手动导入与文件导入）
* 域名管理与证书自动匹配（支持 `*.example.com`）
* Agent 管理与自动发现
* 路由自定义请求头
* 配置预览与变更摘要
当前明确仍不做：
* 多租户
* WAF、限流、Bot、防刷
* 百分比灰度发布
* 节点分组与差异化下发
* Redis、MQ、对象存储、Prometheus
* 复杂缓存策略、证书自动签发、Purge、审批流
* mid-tier、分层缓存、复杂策略编排
超出以上范围的需求，必须先更新设计文档，再开始编码。
---
## 2. 技术基线
### 2.1 Server
控制中心基于现有 `atsf_server` 开发：
`atsf_server` 继续作为单体控制面：
* Web 框架：Gin
* ORM：GORM
* 数据库：SQLite
* 前端：现有 `atsf_server/web`
* 登录体系：沿用 ATSFlare 现有能力
* Gin
* GORM
* SQLite
* 现有 ATSFlare 登录体系
* 现有 `atsf_server/web` 前端
约束：
* 默认不配置 `SQL_DSN`
* 默认不配置 `REDIS_CONN_STRING`
* 不为了 MVP 引入新的基础设施依赖
* 默认不依赖 Redis
* 默认不依赖 MQ
* 默认不依赖对象存储
* 不为第三版预埋平台化基础设施
### 2.2 Agent
Agent 放在 `atsf_agent`，使用 Go 单体程序开发。
约束：
`atsf_agent` 继续作为 Go 单体程序：
* 单二进制
* systemd 运行
* 优先调用独立 Nginx，不依赖系统全局 Nginx
* 支持通过 `nginx_path` 显式指定独立 Nginx 可执行文件
* 未指定 `nginx_path` 时，默认通过 Docker 启动独立 Nginx 容器
* Agent 生成资源默认统一放在 `./data`，可通过 `data_dir` 统一覆盖
* 负责本机 Nginx 路由配置写入、校验、reload、状态上报
* 本地执行
* `nginx_path` 优先
* 无 `nginx_path` 时默认 Docker Nginx
* 生成资源默认放在 `./data`，由 `data_dir` 统一覆盖
### 2.3 Nginx 配置边界
### 2.3 前端
第一版控制面只管理独立生成的 Nginx 路由配置文件，例如 `/etc/nginx/conf.d/atsflare_routes.conf`。第二版在此基础上增加证书托管能力。
前端继续基于现有 React 管理端：
第一版以下内容不纳入控制面：
* 保持现有目录结构
* 继续复用现有 UI 与 helper 组织方式
* 不为第三版提前引入新的大型框架或状态管理方案
* `nginx.conf`
* 缓存策略
* upstream 高级配置
---
第二版约束：
## 3. 分层与目录约束
* 允许在控制面托管 TLS 证书并下发给节点
* 仅支持证书导入（手动粘贴与文件导入），不做自动签发/续期
* `nginx.conf`、缓存策略、upstream 高级配置仍保持节点本地静态配置
### 3.1 Server 分层
## 3. 仓库职责划分
* `controller/`：参数解析、调用 service、返回响应
* `service/`：业务逻辑、校验、渲染、事务编排
* `model/`：模型定义与持久化
* `router/`：路由注册
* `middleware/`：认证、鉴权、限流等横切逻辑
* `common/`：通用配置与工具
### 3.1 `atsf_server`
禁止：
负责：
* 在 `controller/` 堆积业务逻辑
* 在 `middleware/` 中写业务流程
* 为简单需求新增平台层抽象
* 管理端 UI
* 管理端 API
* Agent API
* 数据存储
* 配置渲染
* 版本发布
* 节点状态展示
### 3.2 Agent 分层
### 3.2 `atsf_agent`
保持现有模块边界：
负责：
* `config`
* `heartbeat`
* `sync`
* `nginx`
* `state`
* `httpclient`
* `protocol`
* 节点注册
* 心跳上报
* 拉取激活版本
* 写入本地 Nginx 路由配置
* 调用 `nginx -t` 和 `nginx -s reload`
* 失败回滚
* 上报应用结果
* 管理独立 Nginx 路径或 Docker Nginx 容器
要求：
### 3.3 `docs`
* 每个模块职责单一
* 外部命令调用集中封装
* 状态落盘与配置落盘保持分离
负责：
---
* 设计边界
* 开发规范
* 开发计划
* 部署与联调说明
## 4. 数据模型规范
## 4. 开发原则
所有实现都必须遵守以下原则：
* 先完成闭环，再做抽象。
* 不为了"以后可能会支持"提前引入复杂模型。
* Server 只管状态和配置，不直接 SSH 改节点。
* Agent 是唯一落地入口。
* 所有发布都是"新版本激活"，不是在线覆盖编辑。
* 第一版与第二版：所有节点默认拉同一份全量配置，不做节点分组差异化下发。
* 能用 SQLite 解决的问题，不引入额外中间件。
* 新功能优先复用现有 ATSFlare 结构，不平行造第二套框架。
## 5. 数据模型规范
第一版核心实体（已实现）：
当前有效实体：
* `proxy_routes`
* `config_versions`
* `nodes`
* `apply_logs`
* `tls_certificates`
* `managed_domains`
第二版新增实体：
通用约束：
* `tls_certificates` — 证书托管
* `managed_domains` — 域名管理与证书绑定
* 不新增平台化对象，除非第三版设计明确要求
* `proxy_routes` 仍保持一条域名对应一个 `origin_url`
* `config_versions` 必须保存完整快照与渲染结果
* 全局同时只能有一个激活版本
* 回滚通过重新激活旧版本实现
* 域名证书匹配必须同时支持精确匹配与通配符匹配
* 节点专属 `agent_token` 必须可立即失效
第二版扩展实体：
新增表或关键字段前，必须先回答两个问题：
* `nodes` — 增加 `agent_token`，用于节点占位与节点鉴权
1. 是否服务于第三版主链路？
2. 是否能在现有模型上扩展而不是平行造新模型？
约束（全版本）：
---
* 不新增 `zone`、`origin_pool`、`policy`、`deployment` 这类平台化对象
* `proxy_routes` 一条域名只对应一个 `origin_url`
* `config_versions` 必须保存完整快照和渲染后的 Nginx 路由配置
* 激活版本全局只能有一个，不引入分组维度
* 回滚通过"激活旧版本"实现，不直接修改历史记录
* 域名到证书匹配必须支持精确匹配和通配符匹配（如 `*.example.com`）
* 管理端手工创建节点时必须直接生成 `nodes.agent_token`
* 全局 `discovery_token` 由系统配置统一保存，不按节点分配
* 删除节点必须立即使该节点凭证失效
## 5. API 与鉴权规范
如需新增表，必须先证明它服务于当前迭代版本的主链路。
### 5.1 API 约定
## 6. Server 开发规范
* 管理端与 Agent API 统一使用 JSON
* 成功与失败都必须返回清晰 `message`
* 列表接口返回稳定字段
* Agent API 固定放在 `/api/agent/*`
### 6.1 分层约束
Server 代码按以下职责拆分：
* `controller/`: 参数解析、调用 service、返回 JSON
* `service/`: 业务逻辑、校验、渲染、版本切换
* `model/`: 数据表结构、查询和持久化
* `router/`: 路由注册
* `middleware/`: 认证、鉴权、限流等横切逻辑
* `common/`: 通用工具和配置
禁止行为：
* controller 直接拼接复杂业务逻辑
* controller 直接操作多个 model 形成事务链
* middleware 承担业务逻辑
* 为简单需求引入新的平台层抽象
### 6.2 API 约定
管理端和 Agent API 统一使用 JSON。
响应结构沿用现有模板风格：
统一响应结构保持现有风格：
```json
{
@@ -194,177 +135,109 @@ Server 代码按以下职责拆分：
}
```
约束：
* 成功或失败都返回清晰 `message`
* 列表接口返回稳定字段，不临时拼装结构
* 新接口命名优先使用复数资源风格
* Agent API 固定放在 `/api/agent/*`
### 6.3 鉴权规范
### 5.2 鉴权约定
管理端：
* 继续复用 ATSFlare 的登录、角色和 session 体系
* 继续复用 ATSFlare 登录、角色与 session
Agent（第一版）：
Agent：
* 预共享单 Token，来自环境变量
* 正式请求统一使用节点专属 `agent_token`
* 首次接入可使用全局 `discovery_token`
* 请求头统一使用 `X-Agent-Token`
* Agent 与管理端认证逻辑必须分开
* Agent 认证逻辑不得与用户登录态混用
Agent（第二版）：
禁止：
* 手工创建的节点直接使用节点专属 `agent_token` 接入
* 全局 `discovery_token` 仅用于批量自动发现
* 使用全局 `discovery_token` 注册成功后，下发节点专属 `agent_token`
* 后续请求统一查 `nodes.agent_token` 验证
* 不再依赖全局环境变量 Agent Token
* 将本地 Nginx 操作暴露为远程执行接口
* 在日志中打印完整 Token
注意：
---
* 不要让 Agent 接口走用户登录态
* 不要把 Nginx 命令暴露成远程管理接口
## 6. 发布与渲染规范
### 6.4 数据库规范
SQLite 是唯一默认数据库。
要求：
* 新增模型后必须在 `model.InitDB()` 中加入 `AutoMigrate`
* 不写 MySQL/PostgreSQL 特有 SQL
* 不依赖外部迁移工具作为 MVP 前提
* 时间字段统一使用 GORM 常规时间类型
### 6.5 发布与渲染规范
发布逻辑必须满足：
发布逻辑必须保持以下事实：
* 发布时读取全部启用的 `proxy_routes`
* 生成完整的 Nginx 路由配置
* 计算 checksum
* 保存快照到 `config_versions`
* 生成完整 Nginx 配置
* 计算 `checksum`
* 写入 `config_versions`
* 通过切换 `is_active` 激活版本
版本号格式固定为：
版本号格式保持：
```text
YYYYMMDD-NNN
```
例如：
限制：
```text
20260309-001
```
* 不做在线改历史版本
* 不做按节点分组的差异化版本
* 预览与 diff 是只读能力，不产生发布记录
## 7. Agent 开发规范
---
### 7.1 模块边界
## 7. Agent 行为规范
建议目录如下：
Agent 必须满足：
```text
atsf_agent/
cmd/agent/
internal/config/
internal/heartbeat/
internal/sync/
internal/nginx/
internal/state/
internal/httpclient/
```
职责要求：
* `config`: 本地配置读取
* `heartbeat`: 心跳请求和状态组装
* `sync`: 检查版本、下载配置、触发应用
* `nginx`: 封装 Nginx 校验、reload 和文件写入
* `state`: 本地成功版本和运行状态缓存
* `httpclient`: Server API 调用
### 7.2 行为规范
Agent 必须满足以下行为：
* 启动后生成或读取本地 `node_id`
* 启动后读取或生成本地 `node_id`
* 未显式配置 `node_name` 时自动获取主机名
* 未显式配置 `node_ip` 时自动获取本机 IP
* 未显式配置 `node_ip` 时自动探测本机 IP
* 周期性心跳
* 周期性检查激活版本
* 发现新版本后先备份旧文件
* 写入新路由配置文件
* 发现新版本时先备份旧文件
* 写入新路由与必要证书文件
* 先执行 `nginx -t`
* 校验通过后执行 `nginx -s reload`
* 失败时回滚备份并再次校验和 reload
* 上报最终应用结果
* 优先使用 `nginx_path`
* 未配置 `nginx_path` 时自动准备并使用 Docker Nginx 容器
* 启动时先校验本地路由文件 checksum 与控制面激活版本是否一致
* Docker 模式启动时应重建容器，而不是继续复用异常停止的旧容器
* 若本地 `agent_token` 为空且配置了 `discovery_token`，则应自动发起首次注册并完成 Token 置换
* 若本地已显式配置节点专属 `agent_token`，则无需注册，直接进入心跳与同步流程
* 成功后执行 `nginx -s reload`
* 失败时自动回滚并上报最终结果
* 本地 `agent_token` 为空且存在 `discovery_token` 时，自动注册并完成 Token 置换
### 7.3 容错规范
容错要求：
第一版最少保证：
* Server 不可用时继续使用旧配置
* 下载失败时不修改本地配置
* 本地状态文件损坏时允许重建，但不能破坏当前生效配置
* Docker 容器异常时，启动阶段应自动重建
* Server 不可用时，Nginx 继续使用旧配置
* 下载失败时，不修改本地配置
* 配置校验或 reload 失败时，自动尝试回滚
* 本地状态文件损坏时，允许重新初始化，但不能删除正在生效的 Nginx 配置
* Docker 容器异常停止时，启动阶段应自动重建容器并重新校验配置
### 7.4 外部命令规范
Agent 调用 Nginx 命令时必须：
* 明确记录执行命令和返回错误
* 设置合理超时
* 不依赖交互式输入
* 不通过 shell 拼接不可信参数
---
## 8. 前端开发规范
MVP 前端只做最小管理界面，不重做整套后台。
要求：
* 继续使用现有 React 结构和 `semantic-ui-react`
* 页面只增加 MVP 必需页面
* 不额外引入新的大型前端框架
* API 请求统一放在 `web/src/helpers/api.js` 或同类 helper 中
* 页面状态优先保持简单，不提前引入复杂全局状态管理
* 只为当前版本主链路增加页面与交互
* API 请求统一放在已有 helper 体系
* 页面状态优先保持简单
* 沿用现有组件与样式体系，不大规模重构后台 UI
第一版只需要以下页面：
如果第三版要新增页面，优先原则：
* 反代规则页
* 发布版本页
* 节点状态页
* 应用记录页
* 能复用现有页面结构就不新增一套页面框架
* 能复用已有表单模式就不自造 DSL 编辑器
## 9. 代码风格规范
---
## 9. 代码风格与日志规范
### 9.1 Go
* 保持 package 名称简短且小写
* 错误必须显式处理，不允许静默吞错
* 函数尽量只做一件事
* 输入校验放在 controller 或 service 边界
* 业务枚举值使用明确常量，不使用魔法字符串散落代码
* 仅在复杂逻辑前添加简短注释，不写废话注释
* 错误必须显式处理
* 函数尽量单一职责
* 输入校验放在边界层
* 业务枚举使用明确常量
* 不写无意义注释
### 9.2 命名
* 表名和模型名使用业务语义，不沿用模板示例语义
* 统一使用 `route`, `version`, `node`, `apply log` 这些术语
* 不混用 `client`、`edge`、`agent` 指代同一模块，统一叫 `agent`
* 统一使用 `route`、`version`、`node`、`agent`
* 不混用 `client`、`edge`、`worker` 指代 Agent
### 9.3 日志
要求记录这些关键事件：
必须覆盖关键事件：
* 发布成功/失败
* Agent 注册
@@ -373,77 +246,48 @@ MVP 前端只做最小管理界面，不重做整套后台。
* Nginx 校验或 reload 成功/失败
* 回滚触发
日志内容要可定位问题，但不要打印敏感 Token。
要求：
* 日志要足够定位问题
* 不打印敏感凭证完整值
---
## 10. 测试与验收规范
### 10.1 第一版最低测试要求（已完成）
当前基线至少要持续覆盖：
Server 至少覆盖：
* 路由校验与渲染
* 激活版本切换
* 节点在线状态判定
* 证书导入与匹配
* 自定义请求头渲染
* Agent 同步、回滚、本地状态读写
* 自动注册与 Token 置换
* 预览与 diff 的只读行为
* `origin_url` 校验
* `domain` 重复校验
* Nginx 路由配置渲染结果
* 激活版本切换逻辑
* 节点在线状态判定逻辑
第三版新增需求时：
Agent 至少覆盖：
* 先补单元测试或服务层测试
* 再补联调验证步骤
* 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试
* 版本比较逻辑
* 配置文件备份和回滚逻辑
* `nginx -t` 或 `nginx -s reload` 失败分支
* 本地状态文件读写
### 10.2 第二版新增测试要求
Server 新增覆盖：
* HTTPS server 块渲染正确性（`enable_https=true` 时生成 443 块，`redirect_http=true` 时生成重定向块）
* HTTP-only 路由渲染结果不受 HTTPS 字段影响
* 证书导入逻辑（手动导入、文件导入）和 PEM 校验逻辑
* 域名证书匹配逻辑（精确匹配与 `*.example.com` 通配符匹配）
* `custom_headers` 注入到渲染结果的正确性
* 节点创建、编辑、删除逻辑
* `discovery_token` 首次接入成功后失效
* 删除节点后 Agent 请求立即返回 401
* Agent 自动探测主机名与 IP，且允许配置覆盖
* Agent 首次注册成功后完成本地 token 置换
* 预览接口不写库
* diff 接口变更摘要计算正确性
### 10.3 联调验收标准（第一版，已完成）
1. 管理端新增反代规则并成功发布版本
2. Agent 能检测到新版本并拉取
3. Agent 成功写入 Nginx 路由配置文件
4. Agent 成功执行 `nginx -t` 和 `nginx -s reload`
5. 节点页能看到当前版本和最后心跳
6. 当 reload 失败时，Agent 能回滚到旧配置并上报失败
### 10.4 联调验收标准（第二版）
1. 创建含 HTTPS 字段的路由并发布，Nginx 能以 HTTPS 正确转发
2. 控制面可手动导入和文件导入证书，导入后可被路由选择
3. 反代规则输入域名后可自动匹配证书，且支持 `*.example.com`
4. 通过管理界面创建节点并生成 discovery token，Agent 使用 discovery token 成功接入
5. 删除节点后 Agent 请求返回 401
6. 路由配置自定义头后，渲染结果包含对应指令
7. 发布页预览展示正确渲染结果
8. 变更摘要正确列出域名变化
---
## 11. 文档维护规范
出现以下情况时必须同步更新文档：
出现以下情况必须同步更新文档：
* 产品版本范围变化（V1 → V2 → V3）
* API 发生破坏性变更
* 数据模型新增或删除
* Agent 本地文件路径变更
* 第三版范围确定或变更
* API 出现破坏性变更
* 数据模型新增、删除或关键语义变化
* Agent 本地文件结构变化
* 部署方式变化
* 新增或撤销对中间件/基础设施的依赖
* 新增基础设施依赖
优先更新：
更新顺序：
* `docs/design.md`
* `docs/development-guidelines.md`
* `docs/development-plan.md`
1. `docs/design.md`
2. `docs/development-guidelines.md`
3. `docs/development-plan.md`
4. `docs/deployment.md`
docs/development-plan.md
+103 -194
View File
@@ -1,245 +1,154 @@
# ATSFlare 开发计划
# ATSFlare 开发计划（V3 准备版）
## 1. 目标
## 1. 当前状态
当前开发目标是完成 ATSFlare 的 MVP 闭环：
当前结论：
```text
后台改规则 -> 点击发布 -> Agent 拉到新版本 -> 写入 Nginx 路由配置 -> nginx 校验并 reload -> 节点状态可见
```
* 第一版已完成并稳定闭环
* 第二版已完成并补齐 HTTPS、证书、域名、节点管理与预览能力
* 下一步进入第三版准备阶段
MVP 已于第一版完成。当前进入第二版迭代。
本文件不再展开第一版、第二版的详细实施步骤，只保留第三版启动前的计划骨架与准入条件。
## 2. 第一版里程碑（已完成）
---
### Phase 1: Server 数据层与发布闭环 ✅
## 2. 已完成能力归档
### 2.1 第一版归档
已完成：
* 规则管理
* 配置发布与激活
* Agent 心跳、同步、应用、回滚
* 节点状态与应用记录展示
### 2.2 第二版归档
已完成：
* HTTPS/TLS 路由支持
* 证书托管与导入
* 域名管理与证书自动匹配
* 节点管理、专属 `agent_token`、全局 `discovery_token`
* 路由自定义请求头
* 配置预览与变更摘要
归档原则：
* 已完成阶段的实现细节以代码和 Git 历史为准
* 后续计划文档只维护当前阶段与下一阶段
---
## 3. 第三版启动前置条件
第三版正式立项前，必须先明确以下内容：
1. 目标问题与业务价值
2. 范围边界与明确不做项
3. 涉及的核心对象与 API 变化
4. 对发布链路、Agent 链路、部署方式的影响
5. 验收标准与回归范围
未满足以上条件时，不进入第三版编码阶段。
---
## 4. 第三版建议执行骨架
在第三版范围明确后，按以下顺序推进：
### Phase A：设计冻结
交付：
* 新模型（proxy_routes、config_versions）
* AutoMigrate
* 路由 CRUD API
* 发布 API
* 激活版本 API
* 渲染 service
### Phase 2: Agent API 与节点状态 ✅
交付：
* `nodes`、`apply_logs`
* Agent Token 鉴权（全局单 Token）
* 节点在线状态计算
* 节点与应用日志查询接口
### Phase 3: Agent 本体 ✅
交付：
* 本地配置文件读取
* `node_id` 持久化
* 心跳循环
* 版本检查
* 下载配置
* 写入 Nginx 路由配置
* 配置校验、reload 与失败回滚
* 应用结果上报
### Phase 4: 管理端页面 ✅
交付：
* 反代规则页
* 版本页
* 节点页
* 应用记录页
### Phase 5: 联调与收尾 ✅
交付：
* 手工部署说明
* Agent 配置示例
* 联调验证记录
## 3. 第二版里程碑
### V2 Phase 1: HTTPS/TLS 支持 ✅
目标：
* 支持通过控制面配置 HTTPS 路由
* 渲染出包含 443 端口的 `server` 块
* 支持 HTTP → HTTPS 重定向块
* 控制面支持托管证书
交付：
* `proxy_routes` 新增字段：`enable_https`、`cert_id`、`redirect_http`
* 渲染器支持 HTTPS server 块生成
* 前端反代规则页增加 HTTPS 配置表单
* `tls_certificates` 表与模型
* 证书导入能力：手动导入（粘贴 PEM）与文件导入
* AutoMigrate 覆盖新字段
* 更新后的 `docs/design.md`
* 更新后的 `docs/development-guidelines.md`
* 明确的验收标准
完成标准：
* 创建含 HTTPS 字段的路由并发布，Agent 拉取后 Nginx 能以 HTTPS 正确转发
* HTTP 重定向配置生效
* 证书可通过控制面导入并被 HTTPS 路由引用
* 未开启 HTTPS 的路由渲染行为与第一版保持一致
* 第三版目标、范围、对象变化、兼容策略写清楚
### V2 Phase 2: 域名管理与证书自动匹配 ✅
目标：
* 控制面可管理域名并绑定证书
* 反代规则编辑时按输入域名自动匹配证书
* 支持 `*.example.com` 通配符证书匹配
### Phase B：后端主链路
交付：
* `managed_domains` 表与模型
* 域名管理 CRUD API
* 证书匹配 API（精确匹配 + 通配符匹配）
* 前端域名管理页
* 前端反代规则页接入证书自动匹配
* 数据模型变更
* API 变更
* 服务层逻辑与测试
完成标准：
* 创建域名并绑定证书后，反代规则输入域名可自动匹配证书
* 通配符证书可匹配子域名（如 `api.example.com` 匹配 `*.example.com`）
* 无匹配证书时前端给出明确提示
### V2 Phase 3: Agent 管理 ✅
目标：
* 实现对节点的增删改查
* 实现节点自动发现机制
* Server 侧主链路可独立验证
### Phase C：Agent / 前端配套
交付：
* agent-auth 中间件改造（查表验证）
* 移除全局 Token 环境变量, 节点不再通过该方式连接server
* 用户手动创建节点时，直接生成节点专属 auth token
* 引入全局自动发现 TOKEN，任意新节点持有同一个 TOKEN 即可自动连接到 SERVER
* Node CRUD API
* 前端 节点 管理页
* Agent 适配改动
* 前端页面或交互改动
* 必要的回归测试
完成标准：
* 用户启动 server 后手动在节点页添加节点，会直接生成该节点的专属 auth token，持有该 token 的节点可占据该节点位
* 用户可在管理界面查看全局 discovery token，批量部署的节点可共用该 token 自动注册到 server
* 用户可以编辑节点, 包括节点名
* 删除节点后 Agent 请求立即返回 401
* 节点配置文件不再要求填写节点名和IP地址, 节点名默认从主机名获取, IP也是自动获取. 手动指定则为覆盖
* 节点配置文件填写节点专属 `agent_token` 时，可直接上线；若 `agent_token` 为空且填写全局 discovery token，则会自动注册并完成 token 置换
* 控制面、Agent、页面链路联通
### V2 Phase 4: 路由自定义头 ✅
目标：
* 每条路由支持追加自定义 `proxy_set_header` 指令
### Phase D：联调与收尾
交付：
* `proxy_routes` 新增 `custom_headers` 字段（JSON，`[{"key":"X-My-Header","value":"foo"}]`）
* 渲染器按 `custom_headers` 在 `location /` 块中注入额外 header 指令
* 前端反代规则页增加自定义头编辑器
* 联调记录
* 部署文档更新
* 遗留问题清单
完成标准：
* 路由配置自定义头后发布，渲染结果包含对应 `proxy_set_header` 指令
* 不配置自定义头的路由渲染行为与之前保持一致
* 新能力可按部署文档落地验证
### V2 Phase 5: 配置预览与变更摘要 ✅
---
目标：
## 5. 第三版期间禁止事项
* 发布前可预览渲染结果
* 发布前可查看与当前激活版本的变更摘要
在第三版需求未明确前，不提前开始以下工作：
交付：
* 引入 Redis、MQ、对象存储等新基础设施
* 实现节点分组与差异化发布
* 实现灰度百分比发布
* 引入多租户模型
* 对现有前端进行无业务价值的大重构
* `GET /api/config-versions/preview` 接口（返回渲染后的 Nginx 配置，不写库）
* `GET /api/config-versions/diff` 接口（返回新增/删除/修改的域名列表）
* 前端发布版本页增加"预览"按钮和变更摘要展示弹窗
如果第三版确认需要以上能力，先改文档，再调整计划。
完成标准：
---
* 点击预览可查看即将生成的 Nginx 配置文本
* 变更摘要正确列出相对于当前激活版本的域名变化
* 预览和 diff 操作不产生版本记录
## 6. 第三版验收门槛模板
## 4. 第二版建议执行顺序
第三版正式验收时，至少检查：
建议严格按以下顺序开发：
* 设计文档与实现一致
* 新增 API 与数据模型有测试覆盖
* 发布链路未被破坏
* Agent 同步与回滚链路未被破坏
* 现有节点接入方式兼容或有明确迁移方案
* 部署文档已同步更新
1. HTTPS/TLS 支持（对现有渲染链路影响最小，独立可测）
2. 域名管理与证书自动匹配（与 HTTPS 强相关，尽早完成闭环）
3. Agent 管理（节点 CRUD + 自动发现 + token 置换）
4. 路由自定义头（纯增量，对现有结构影响小）
5. 配置预览与变更摘要（纯只读接口，最后补充）
---
不要先做以下内容：
## 7. 变更控制
* 节点分组与差异化下发
* 灰度百分比发布
* WAF、限流
* Redis、Prometheus
* 多租户
第三版开发中，出现以下情况必须先改文档再继续：
## 5. 第二版每阶段验收检查
* 目标问题变化
* 核心数据模型变化
* 部署方式变化
* 需要引入新的中间件或基础设施
* 需要突破当前系统边界
### V2 Phase 1 检查项
* `enable_https=true` 的路由发布后生成 443 端口 server 块
* `redirect_http=true` 的路由生成 80 → 443 重定向块
* 支持手动导入证书与文件导入证书
* 未开启 HTTPS 的路由渲染结果不受影响
* Agent 拉取后 Nginx reload 成功
### V2 Phase 2 检查项
* 可通过管理界面维护域名并绑定证书
* 反代规则输入域名后可自动匹配证书
* 通配符证书可匹配子域名（`*.example.com`）
### V2 Phase 3 检查项
* 可通过管理界面创建节点并生成节点专属 auth token
* 可查看全局 discovery token，并允许多个节点共用该 token 自动接入
* Agent 可使用全局 discovery token 自动接入并完成 agent token 置换
* 用户可编辑节点名并删除节点
* 删除节点后 Agent 请求立即失败
* Agent 在未显式配置节点名/IP 时可自动探测
### V2 Phase 4 检查项
* 路由可添加自定义头
* 渲染结果中正确包含自定义 header 指令
* 无自定义头的路由渲染结果不受影响
### V2 Phase 5 检查项
* 预览接口返回正确的 Nginx 配置文本
* diff 接口返回正确的域名变更列表
* 两个接口均不产生数据库写入
## 6. 变更控制
开发中如果出现以下情况，需要先调整计划再继续编码：
* V2 目标发生变化
* 需要引入新的中间件（Redis、MQ 等）
* 需要新增核心数据模型
* 需要把控制面扩展到 Nginx 全局配置
计划更新时，应同步修改：
同步更新清单：
* `docs/design.md`
* `docs/development-guidelines.md`
* `docs/development-plan.md`
* `docs/deployment.md`