# ATSFlare MVP 设计文档 ## 1. 目标 先做一个能用的版本，不做平台化过度设计。第一版只解决 3 件事： * 配置发布与同步 * 节点心跳检测 * Nginx 反向代理配置下发 系统定位是内部自用的控制面，不是面向外部租户的 CDN SaaS。 --- ## 2. 第一版范围（已完成） ### 已做 * Web 管理端维护反代规则 * 配置发布生成版本 * Agent 定时同步并应用配置 * Agent 控制本机 Nginx 校验与 reload * 节点注册、心跳、在线状态展示 * 展示每个节点当前生效版本和最近一次应用结果 ### 不做（第一版） * 多租户 * WAF、限流、Bot、防刷 * 灰度发布、节点分组、分批发布 * 对象存储、消息队列、Redis、Prometheus * 复杂缓存策略管理 * 证书托管与自动签发 * Purge、中台审计、审批流 * mid-tier / 分层缓存 第一版默认所有节点消费同一份全量配置，不做差异化下发。 --- ## 2.5 第二版范围 在 MVP 闭环稳定运行的基础上，第二版聚焦以下增量能力。 ### 要做 **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` 的 `gin-template` 工程开发： * Web 框架：Gin * ORM：GORM * 前端：沿用现有 web 管理端 * 鉴权：沿用 gin-template 登录体系 ### 数据库 只使用 SQLite，不引入其他中间件： * 不配置 `SQL_DSN`，直接走项目现有 SQLite 初始化逻辑 * 不配置 `REDIS_CONN_STRING`，会退化为 cookie session ### Agent Agent 使用 Go 单体程序： * 单二进制 * systemd 管理 * 优先调用独立 Nginx，而不是依赖系统全局 Nginx * 显式配置 `nginx_path` 时，直接调用该路径下的 Nginx * 未配置 `nginx_path` 时，默认通过 Docker 运行独立 Nginx 容器 * 管理本机 Nginx 路由配置文件和 reload * Agent 生成资源默认统一落在 `./data`，也允许通过单个基路径配置覆盖 * Agent 启动时会校验本地路由文件哈希与控制面激活版本是否一致 * Docker 模式启动时会重建独立 Nginx 容器，避免复用故障容器 ### Nginx 管理边界 第一版只管理最核心的反代映射： * 重点生成独立的 Nginx 路由配置文件，例如 `/etc/nginx/conf.d/atsflare_routes.conf` * `nginx.conf`、TLS 证书、缓存细节、upstream 高级配置先保持节点本地静态配置 * Agent 可以管理独立安装路径下的 Nginx，或者独立 Docker Nginx 容器 也就是说，MVP 先把 Nginx 当成“可集中配置的反向代理”，不是完整网关平台。 --- ## 4. 总体架构 ```text ┌────────────────────────────┐ │ ATSFlare Server │ │ gin-template + 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 ◄────────────┘ ``` 设计原则只有 3 条： * Server 只保存配置和节点状态，不直接 SSH 改机器 * Agent 是唯一的落地入口 * 所有发布都是“新版本生效”，不是在线修改当前文件 --- ## 5. 核心对象 ### 5.1 proxy_routes（第一版） 反代规则表，控制 `Host -> Origin` 映射。 建议字段： * `id` * `domain` * `origin_url` * `enabled` * `remark` * `created_at` * `updated_at` 约束： * `domain` 唯一 * `origin_url` 必须是合法的 `http://` 或 `https://` * 第一版一条域名只对应一个源站，不做源站池 第二版新增字段： * `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，不单独上对象存储 第二版沿用第一版字段，不新增分组字段。 ### 5.3 nodes（第一版） 节点表，保存当前状态。 建议字段： * `id` * `node_id` * `name` * `ip` * `agent_version` * `nginx_version` * `status` * `current_version` * `last_seen_at` * `last_error` * `created_at` * `updated_at` 第二版沿用第一版字段，不新增分组字段。 ### 5.4 apply_logs（第一版） 节点应用记录。 建议字段： * `id` * `node_id` * `version` * `result` * `message` * `created_at` ### 5.5 tls_certificates（第二版新增） 证书托管表，用于保存证书与私钥内容。 建议字段： * `id` * `name` — 证书名称（唯一） * `cert_pem` — 证书 PEM 内容 * `key_pem` — 私钥 PEM 内容 * `not_before` — 证书生效时间 * `not_after` — 证书过期时间 * `remark` * `created_at` * `updated_at` ### 5.6 managed_domains（第二版新增） 域名管理表，用于维护可选域名及其默认证书关系。 建议字段： * `id` * `domain` — 域名（支持精确域名和 `*.example.com`） * `cert_id` — 关联 `tls_certificates.id`（nullable） * `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 必须立即失效 --- ## 6. 配置发布模型 第一版不做增量发布，也不做 bundle 文件仓库。 发布逻辑： 1. 管理员在后台修改 `proxy_routes` 2. 点击“发布” 3. Server 校验规则 4. Server 根据当前全部启用规则渲染出完整 Nginx 路由配置 5. 生成新 `config_versions` 记录 6. 将该版本标记为当前激活版本 7. Agent 下一次心跳或轮询时发现新版本并拉取 ### 版本原则 * 一个版本就是一份完整快照 * 版本不可变 * 节点只拉取当前激活版本 * 回滚本质上是重新激活旧版本 ### 版本号建议 ```text 20260309-001 20260309-002 ``` ### 发布校验 发布前至少做以下检查： * `domain` 不能为空 * `origin_url` 合法 * 不允许重复域名 * 至少存在 1 条启用规则 --- ## 7. Nginx 配置策略 第一版只生成独立的 Nginx 路由配置文件，这样最简单，也最容易验证。 ### 规则映射 ```conf server { listen 80; server_name www.example.com; 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; } } 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 模块 * 节点注册 * 心跳上报 * 获取当前激活版本 * 下载指定版本配置 * 上报应用结果 ### 8.3 渲染模块 职责很简单： * 从 `proxy_routes` 读取全部启用规则 * 按固定模板拼出 Nginx 路由配置 * 计算 checksum * 写入 `config_versions` 这层不要引入复杂 DSL，第一版直接围绕 `domain -> origin_url` 即可。 --- ## 9. Agent 模块设计 Agent 做成一个 Go 单体进程即可。 ### 9.1 本地职责 * 读取本地配置 * 定时心跳 * 拉取新版本 * 覆盖 Nginx 路由配置文件 * 执行 `nginx -t` 和 `nginx -s reload` * 上报应用结果 * 保存本地最近成功版本 ### 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 继续转发 --- ## 10. 心跳与在线状态 心跳不单独搞复杂监控系统，直接走业务表。 ### 心跳内容 Agent 每次上报： * `node_id` * `name` * `ip` * `agent_version` * `nginx_version` * `current_version` * `last_apply_result` * `timestamp` ### 状态判定 建议规则： * 15 秒一次心跳 * 超过 45 秒未上报记为 `offline` * 最近一次应用失败但仍有心跳，记为 `warning` * 正常心跳且版本一致，记为 `online` --- ## 11. API 设计 ### 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 鉴权方案 管理端： * 直接沿用 gin-template 的登录态 Agent（第一版）： * 预共享 Token，请求头 `X-Agent-Token`，Token 值来自环境变量 Agent（第二版）： * Agent 正式鉴权改为查 `nodes.agent_token` * 首次注册使用 `nodes.discovery_token` * 不再依赖全局环境变量 Agent Token * 后续可升级 mTLS --- ## 12. 页面设计 ### 12.1 登录页 沿用 gin-template 现有登录。 ### 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 置换 + 发布前可预览变更 ```