From 39d54c2fe4424cf549e3c26d173aa92ee127fbe8 Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Mon, 30 Mar 2026 11:13:57 +0800
Subject: [PATCH] =?UTF-8?q?[=E6=96=87=E6=A1=A3]=20=E5=8D=87=E7=BA=A7?=
 =?UTF-8?q?=E4=BB=A3=E7=90=86=E8=B7=AF=E7=94=B1=E8=A7=84=E5=88=99=E4=B8=BA?=
 =?UTF-8?q?=E7=BD=91=E7=AB=99=E9=85=8D=E7=BD=AE=EF=BC=8C=E6=94=AF=E6=8C=81?=
 =?UTF-8?q?=E5=A4=9A=E5=9F=9F=E5=90=8D=E7=BB=91=E5=AE=9A=E4=B8=8E=E5=85=B1?=
 =?UTF-8?q?=E4=BA=AB=E8=AE=BE=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/design.md                         |  10 +-
 docs/development-guidelines.md         |   6 +-
 docs/development-plan.md               |  11 +
 docs/website-configuration-redesign.md | 273 +++++++++++++++++++++++++
 4 files changed, 297 insertions(+), 3 deletions(-)
 create mode 100644 docs/website-configuration-redesign.md

diff --git a/docs/design.md b/docs/design.md
index ed106d18..56d7bccc 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -9,6 +9,7 @@ OpenFlare 是一套自托管的 OpenResty 控制面，面向单团队或单组
 当前稳定能力包括：
 
 * 反代规则管理
+* 网站级配置与多域名绑定
 * 源站管理与复用
 * 配置预览、发布、激活与回滚
 * Agent 注册、心跳、同步、应用结果上报
@@ -99,13 +100,17 @@ Origin
 
 稳定约束：
 
-* 一个域名只对应一条 `proxy_routes` 规则
+* `proxy_routes` 从“单域名规则”升级为“网站配置”聚合对象；一条记录对应一个网站，可绑定一个或多个域名，并共享一组站点级配置
+* `proxy_routes.site_name` 是网站的业务唯一标识；新建时默认取 `domains[0]`，后续允许独立维护，不随域名改动自动重写
+* `proxy_routes.domains` 至少包含一个域名，且 `domains[0]` 作为主域名；任一域名全局只能属于一个 `proxy_routes`
+* 为兼容历史数据，迁移期可保留 `proxy_routes.domain` 作为 `domains[0]` 的镜像字段，但业务读写与后续扩展必须以 `site_name` + `domains` 为准
 * `origins` 只保存源站地址、展示名与备注，不承载协议、端口、路径、权重或健康检查策略
 * `proxy_routes` 可选关联一个 `origins` 记录，用于复用源站地址；规则仍保存完整 `origin_url` 快照以参与渲染与版本快照
 * `proxy_routes` 至少包含一个上游地址；为兼容历史数据保留 `origin_url` 主上游字段，也允许在同一规则内补充多个上游做负载均衡
 * `proxy_routes` 上游统一渲染为带 keepalive 的 named `upstream`；单上游可附带 base path 或 query 并在 `proxy_pass` 中追加，多上游仍限定为纯 `scheme://host[:port]`
 * `proxy_routes.origin_host` 为可选字段，用于回源时覆盖 `Host` 请求头；未设置时默认透传访问域名
-* `proxy_routes.domain` 必须唯一
+* 网站级流量限制、反向代理、HTTPS 与缓存配置当前按站点共享，不在同一网站内做域名级差异化配置
+* 发布渲染时必须将 `proxy_routes.domains` 中的全部域名一并纳入同一站点配置，避免同站点在版本快照中被拆散
 * 所有上游地址都必须为合法 `http://` 或 `https://`
 * `config_versions` 必须保存完整快照、渲染结果与 `checksum`
 * 全局同时只能有一个激活版本
@@ -171,3 +176,4 @@ Origin
 * 产品范围或系统边界变化时更新本文档
 * 已完成阶段不再以“版本计划”形式回填
 * 新阶段开始前，先补设计，再进入实现
+* 涉及网站级规则改造的详细需求与实施顺序，见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md)
diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md
index 615726df..ef74e577 100644
--- a/docs/development-guidelines.md
+++ b/docs/development-guidelines.md
@@ -117,10 +117,14 @@
 
 * 不新增平台化对象，除非设计文档明确要求
 * `origins` 仅作为可复用源站地址目录，字段保持轻量；协议、端口、路径与查询参数继续归属具体 `proxy_routes`
-* `proxy_routes` 维持一条域名对应一条规则；规则内允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`
+* `proxy_routes` 以“网站配置”作为聚合边界，必须包含唯一 `site_name` 与非空 `domains` 列表；数据库内部 `id` 可继续作为技术主键，但不能替代 `site_name` 的业务唯一性
+* `proxy_routes.domains` 中的每个域名都必须全局唯一；列表第一项视为主域名，创建时若未显式填写 `site_name`，则默认使用主域名
+* `proxy_routes` 继续允许保存一个或多个上游地址用于负载均衡，但不引入独立 `origin_pool`
+* 迁移期如保留遗留 `domain` 字段，只能作为 `domains[0]` 的兼容镜像；新代码不得继续以该字段作为唯一业务输入
 * `proxy_routes` 如关联 `origins`，必须同时保存可直接渲染的 `origin_url`；源站地址变更时，由 service 负责同步更新引用该源站的规则快照
 * `proxy_routes` 的上游统一使用 named `upstream` + keepalive；单上游如带 base path 或 query，应在 `proxy_pass` 上补回 URI，多上游仅允许纯 `scheme://host[:port]`
 * `proxy_routes.origin_host` 为可选字段，仅用于覆盖回源 `Host` 请求头，不引入新的平台化对象
+* 流量限制、反向代理、HTTPS 与缓存配置当前都归属站点级 `proxy_routes`，同一网站内不拆分域名级差异配置
 * `config_versions` 必须保存完整快照与渲染结果
 * 全局同时只能有一个激活版本
 * 回滚通过重新激活旧版本实现
diff --git a/docs/development-plan.md b/docs/development-plan.md
index f10fe92f..f8d74b41 100644
--- a/docs/development-plan.md
+++ b/docs/development-plan.md
@@ -48,3 +48,14 @@
 * 部署与配置变动：更新 `README.md`、`docs/deployment.md`、`docs/app-config.md`
 
 如果未来出现明确的新阶段目标，再单独新增专项计划文档；不要把已完成的历史计划继续堆回本文件。
+
+## 6. 当前专项计划
+
+已确认需要推进“网站级规则与配置界面改造”专项，详细需求、实施顺序与验收标准见 [docs/website-configuration-redesign.md](./website-configuration-redesign.md)。
+
+本专项的执行顺序固定为：
+
+1. 先完成数据模型与配置渲染兼容方案
+2. 再调整接口、校验与版本 diff 语义
+3. 然后改造规则列表与网站配置子页面
+4. 最后补齐迁移、回归测试与文档联动
diff --git a/docs/website-configuration-redesign.md b/docs/website-configuration-redesign.md
new file mode 100644
index 00000000..1a16283e
--- /dev/null
+++ b/docs/website-configuration-redesign.md
@@ -0,0 +1,273 @@
+# 网站配置改造需求与开发计划
+
+## 1. 背景
+
+当前规则模块以“一个域名对应一条规则”为中心，已经支持单域名绑定一个或多个上游，但无法表达“多个域名共享同一套站点配置”的场景。
+
+现阶段已经出现以下真实需求：
+
+* 多个域名指向同一站点，并共享反向代理、HTTPS、缓存等设置
+* 后续希望围绕“网站”继续叠加更多功能，而不是持续在规则列表中堆积字段
+* 现有抽屉式编辑界面已经不适合承载更复杂的配置结构
+
+因此，本轮改造将 `proxy_routes` 从“单域名规则”升级为“网站配置”视角，并引入独立的配置子页面。
+
+## 2. 目标
+
+本轮改造的目标如下：
+
+* 支持一个网站绑定多个域名
+* 支持一个网站绑定一个或多个上游
+* 引入 `site_name` 作为网站业务唯一标识
+* 将原列表页的“编辑”操作替换为“配置”，进入独立子页面管理
+* 将网站配置拆分为更清晰的功能分区，为后续扩展预留结构
+
+## 3. 本轮范围
+
+本轮仅覆盖以下站点级配置能力：
+
+* 域名设置
+* 流量限制
+* 反向代理
+* HTTPS
+* 缓存
+
+## 4. 核心模型要求
+
+### 4.1 网站标识
+
+* `site_name` 为网站业务唯一标识
+* 新建网站时，若用户未输入 `site_name`，默认取域名列表第一项
+* `site_name` 在首次生成后允许独立编辑，不随域名变更自动同步，避免影响引用、跳转和审计
+* 数据库内部主键可以继续使用现有数值 `id`，但业务层必须校验 `site_name` 唯一性
+
+### 4.2 域名列表
+
+* 网站的域名字段改为 `domains` 列表
+* `domains` 至少包含一个有效域名
+* `domains[0]` 视为主域名，用于列表摘要、默认展示和兼容历史逻辑
+* 同一网站内域名不能重复
+* 任一域名在全局只能属于一个网站
+* 域名列表需要支持新增、删除和调整顺序
+
+### 4.3 历史兼容
+
+* 存量单域名数据迁移后应自动转换为：
+  `site_name = domain`
+  `domains = [domain]`
+* 若迁移期保留旧 `domain` 字段，该字段仅作为 `domains[0]` 的兼容镜像，不再作为主要业务输入
+* 版本渲染、差异预览、接口返回和前端展示都应逐步以 `site_name + domains` 为准
+
+## 5. 功能需求
+
+### 5.1 列表页改造
+
+规则列表改造为“网站列表”视图，要求如下：
+
+* 保留当前列表页入口，但展示对象改为网站
+* 原“编辑”按钮替换为“配置”按钮
+* 点击“配置”进入网站配置子页面
+* 列表项至少展示：
+  `site_name`
+  主域名
+  域名数量
+  上游摘要
+  HTTPS/缓存/启用状态摘要
+* 删除、发布等现有高风险操作仍保留明确确认
+
+### 5.2 网站配置子页面
+
+网站配置采用左右布局：
+
+* 左侧为菜单栏，用于切换配置分区
+* 右侧为当前分区的设置面板
+* 默认进入“域名设置”分区
+* 建议基于 App Router 子路由或稳定的 tab 路由参数实现，保证可直接访问和刷新恢复
+
+建议左侧菜单项固定为：
+
+1. 域名设置
+2. 流量限制
+3. 反向代理
+4. HTTPS
+5. 缓存
+
+为降低跨分区校验干扰，每个分区应支持独立保存与反馈；若采用统一保存，也必须提供未保存修改提示。
+
+### 5.3 域名设置
+
+域名设置分区负责维护网站身份与域名列表，要求如下：
+
+* 可编辑 `site_name`
+* 可维护 `domains` 列表
+* 可新增、删除、排序域名
+* 明确提示第一项为主域名
+* 保存前校验：
+  `site_name` 非空且唯一
+  `domains` 非空
+  每个域名格式合法
+  域名在当前站点内不重复
+  域名在全局不与其他网站冲突
+
+### 5.4 流量限制
+
+流量限制分区用于配置站点级限流，第一期要求覆盖以下字段：
+
+* `limit_conn perserver`
+* `limit_conn perip`
+* `limit_rate`
+
+要求如下：
+
+* 采用结构化字段存储，不允许直接录入原始 Nginx 片段
+* `limit_conn perserver` 与 `limit_conn perip` 为整数；空值或 `0` 视为未启用
+* `limit_rate` 采用人类可读格式录入，例如 `512k`、`1m`
+* 保存前进行格式校验，并在页面中提供示例说明
+* 配置发布后渲染为对应的 OpenResty/Nginx 指令
+
+### 5.5 反向代理
+
+反向代理分区负责维护网站回源配置，要求如下：
+
+* 支持一个或多个上游
+* 至少保留一个上游
+* 支持维护回源主机名 `origin_host`
+* 继续兼容当前单上游带 path/query、多上游做负载均衡的模式
+* 若复用 `origins` 目录，只作为地址候选来源，不改变网站配置为主的编辑模型
+
+建议继续保留当前兼容约束：
+
+* 单上游可附带 path/query
+* 多上游模式下，上游项保持 `scheme://host[:port]` 形式
+* 同一网站的多个上游在多上游模式下维持统一协议，降低渲染复杂度
+
+### 5.6 HTTPS
+
+HTTPS 分区负责维护站点级 TLS 行为，要求如下：
+
+* 支持开启或关闭 HTTPS
+* 支持选择证书
+* 支持保留现有 `HTTP -> HTTPS` 跳转能力
+* 当 HTTPS 开启时必须明确证书来源
+* 应校验证书是否覆盖当前网站的全部域名；若无法覆盖，应阻止保存或给出不可忽略的错误提示
+
+### 5.7 缓存
+
+缓存分区负责维护站点级缓存策略，要求如下：
+
+* 支持开启或关闭缓存
+* 支持多种缓存策略
+* 第一阶段至少兼容当前已存在的策略：
+  `url`
+  `suffix`
+  `path_prefix`
+  `path_exact`
+* 缓存规则继续采用结构化配置，不直接暴露原始 Nginx 片段
+* 保持当前安全绕过逻辑，不因界面改造改变默认缓存边界
+
+## 6. 接口与渲染要求
+
+* 列表接口需要返回 `site_name`、`domains`、主域名、状态摘要等字段
+* 详情接口需要按分区所需字段返回完整站点配置
+* 更新接口需要支持按分区或按网站整体更新，但服务端必须统一做跨字段校验
+* 配置 diff 不再只关注单个域名变更，还要能识别：
+  网站新增/删除
+  域名列表变更
+  站点级配置变更
+* 发布渲染时，同一网站的全部域名必须落入同一份站点配置上下文中
+
+## 7. 前端实现要求
+
+* 列表页负责导航与摘要，不再承载完整编辑表单
+* 网站配置子页面中的每个分区表单继续遵循 `React Hook Form + Zod`
+* API 请求统一收敛在 `lib/api/`
+* 站点级数据查询与缓存继续使用 TanStack Query
+* 左侧菜单切换时需要明确处理未保存状态，避免无提示丢失修改
+* 页面至少覆盖加载态、空态、错误态和保存成功反馈
+
+## 8. 数据迁移要求
+
+实施前必须准备显式数据库迁移与校验逻辑，至少包含：
+
+1. 新增 `site_name` 与 `domains` 存储结构
+2. 将旧数据从单域名回填到站点结构
+3. 为 `site_name` 建立唯一约束
+4. 为域名唯一性建立可校验约束
+5. 对迁移结果做一致性校验
+
+迁移失败时，启动流程必须中止，不允许带半迁移状态继续运行。
+
+## 9. 开发计划
+
+### 阶段一：模型与渲染改造
+
+目标：
+
+* 定义网站级 `proxy_routes` 数据结构
+* 完成存量数据迁移
+* 调整配置渲染与发布链路，支持多域名同站点输出
+
+交付物：
+
+* 数据库迁移
+* model/service 调整
+* 配置渲染兼容实现
+* 迁移与渲染测试
+
+### 阶段二：接口与校验改造
+
+目标：
+
+* 更新列表、详情、创建、更新接口的数据结构
+* 引入 `site_name`、`domains`、流量限制等字段校验
+* 调整版本 diff 与发布预览语义
+
+交付物：
+
+* API 契约更新
+* 服务端参数校验与错误消息
+* diff/preview 适配
+* 接口回归测试
+
+### 阶段三：前端网站列表与配置子页面
+
+目标：
+
+* 将规则列表切换为网站列表
+* 用“配置”按钮替代“编辑”按钮
+* 落地左右布局的网站配置子页面与五个分区
+
+交付物：
+
+* 列表页 UI 改造
+* 子页面路由与布局
+* 域名设置、流量限制、反向代理、HTTPS、缓存五个分区
+* 前端交互与表单测试
+
+### 阶段四：联调、发布验证与文档收口
+
+目标：
+
+* 验证从创建网站到发布配置的全链路
+* 验证 Agent 拉取、应用与回滚不受影响
+* 收口文档与测试
+
+交付物：
+
+* 联调记录
+* 发布/回滚回归验证
+* 文档同步更新
+
+## 10. 验收标准
+
+满足以下条件后，本专项可视为完成：
+
+* 可以创建一个网站，并绑定多个域名
+* 一个网站可以绑定单个或多个上游
+* `site_name` 唯一，且创建时默认取第一个域名
+* 原列表页已用“配置”按钮替代“编辑”按钮
+* 网站配置子页面已经采用左侧菜单、右侧设置的布局
+* 五个分区均可独立完成基本配置与保存
+* 发布后的渲染结果可正确覆盖同一网站的全部域名
+* Agent 同步、应用、回滚链路不被破坏
+* 迁移、接口、渲染与前端关键路径均有对应测试或等效回归验证