OpenFlare/docs/website-configuration-redesign.md

网站配置改造需求与开发计划

1. 背景

当前规则模块以“一个域名对应一条规则”为中心，已经支持单域名绑定一个或多个上游，但无法表达“多个域名共享同一套站点配置”的场景。

现阶段已经出现以下真实需求：

• 多个域名指向同一站点，并共享反向代理、缓存等设置，同时允许按域名分别绑定 HTTPS 证书
• 后续希望围绕“网站”继续叠加更多功能，而不是持续在规则列表中堆积字段
• 现有抽屉式编辑界面已经不适合承载更复杂的配置结构

因此，本轮改造将 proxy_routes 从“单域名规则”升级为“网站配置”视角，并引入独立的配置子页面。

2. 目标

本轮改造的目标如下：

• 支持一个网站绑定多个域名
• 支持一个网站绑定一个或多个上游
• 引入 site_name 作为网站业务唯一标识
• 将原列表页的“编辑”操作替换为“配置”，进入独立子页面管理
• 将网站配置拆分为更清晰的功能分区，为后续扩展预留结构

3. 本轮范围

本轮仅覆盖以下站点级配置能力：

• 域名设置
• 流量限制
• 反向代理
• 缓存

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. 缓存

为降低跨分区校验干扰，每个分区应支持独立保存与反馈；若采用统一保存，也必须提供未保存修改提示。

5.3 域名设置

域名设置分区负责维护网站身份与域名列表，要求如下：

• 可编辑 site_name
• 可维护 domains 列表
• 可新增、删除、排序域名
• 明确提示第一项为主域名
• 每个域名可单独选择一张证书，形成与 domains 平行的 domain_cert_ids
• 若某个域名未选择证书，则该域名不启用 HTTPS
• HTTP -> HTTPS 跳转逻辑与域名证书绑定放在同一分区维护
• 保存前校验： 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 缓存

缓存分区负责维护站点级缓存策略，要求如下：

• 支持开启或关闭缓存
• 支持多种缓存策略
• 第一阶段至少兼容当前已存在的策略： url suffix path_prefix path_exact
• 缓存规则继续采用结构化配置，不直接暴露原始 Nginx 片段
• 保持当前安全绕过逻辑，不因界面改造改变默认缓存边界

6. 接口与渲染要求

• 列表接口需要返回 site_name、domains、主域名、状态摘要等字段
• 详情接口需要按分区所需字段返回完整站点配置
• 更新接口需要支持按分区或按网站整体更新，但服务端必须统一做跨字段校验
• 配置 diff 不再只关注单个域名变更，还要能识别： 网站新增/删除 域名列表变更 站点级配置变更
• 发布渲染时，同一网站的全部域名必须落入同一份站点配置上下文中
• 同一网站内，带证书的域名需按证书分组生成 HTTPS server；未配置证书的域名只保留 HTTP

7. 前端实现要求

• 列表页负责导航与摘要，不再承载完整编辑表单
• 网站配置子页面中的每个分区表单继续遵循 React Hook Form + Zod
• API 请求统一收敛在 lib/api/
• 站点级数据查询与缓存继续使用 TanStack Query
• 左侧菜单切换时需要明确处理未保存状态，避免无提示丢失修改
• 页面至少覆盖加载态、空态、错误态和保存成功反馈

8. 数据迁移要求

实施前必须准备显式数据库迁移与校验逻辑，至少包含：

1. 新增 site_name、domains 与 domain_cert_ids 存储结构
2. 将旧数据从单域名回填到站点结构，并补齐逐域名证书映射
3. 为 site_name 建立唯一约束
4. 为域名唯一性建立可校验约束
5. 对迁移结果做一致性校验

迁移失败时，启动流程必须中止，不允许带半迁移状态继续运行。

9. 开发计划

阶段一：模型与渲染改造

目标：

• 定义网站级 proxy_routes 数据结构
• 完成存量数据迁移
• 调整配置渲染与发布链路，支持多域名同站点输出

交付物：

• 数据库迁移
• model/service 调整
• 配置渲染兼容实现
• 迁移与渲染测试

阶段二：接口与校验改造

目标：

• 更新列表、详情、创建、更新接口的数据结构
• 引入 site_name、domains、流量限制等字段校验
• 调整版本 diff 与发布预览语义

交付物：

• API 契约更新
• 服务端参数校验与错误消息
• diff/preview 适配
• 接口回归测试

阶段三：前端网站列表与配置子页面

目标：

• 将规则列表切换为网站列表
• 用“配置”按钮替代“编辑”按钮
• 落地左右布局的网站配置子页面与五个分区

交付物：

• 列表页 UI 改造
• 子页面路由与布局
• 域名设置、流量限制、反向代理、缓存四个分区
• 前端交互与表单测试

阶段四：联调、发布验证与文档收口

目标：

• 验证从创建网站到发布配置的全链路
• 验证 Agent 拉取、应用与回滚不受影响
• 收口文档与测试

交付物：

• 联调记录
• 发布/回滚回归验证
• 文档同步更新

10. 验收标准

满足以下条件后，本专项可视为完成：

• 可以创建一个网站，并绑定多个域名
• 一个网站可以绑定单个或多个上游
• site_name 唯一，且创建时默认取第一个域名
• 原列表页已用“配置”按钮替代“编辑”按钮
• 网站配置子页面已经采用左侧菜单、右侧设置的布局
• 五个分区均可独立完成基本配置与保存
• 发布后的渲染结果可正确覆盖同一网站的全部域名，并只为已绑定证书的域名生成 HTTPS 配置
• Agent 同步、应用、回滚链路不被破坏
• 迁移、接口、渲染与前端关键路径均有对应测试或等效回归验证