mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 05:56:38 +08:00
docs(zone): add migration and release verification guide
补充 Zone 域名迁移操作指南（备份、migrate-zones、预览等价性、发布与回滚）， 更新设计文档阶段说明、指南导航与 Unreleased 变更日志。
This commit is contained in:
ryan
@@ -25,10 +25,18 @@ sidebar: false
|
||||
|
||||
- 新增第一阶段 Zone 与正规化 Zone 域名数据库表及路由绑定模型，为后续以稳定 ID 管理网站与域名关联提供基础。
|
||||
- 新增 Zone 管理 API 与显式历史域名导入命令，使用公共后缀列表验证注册根域和域名归属。
|
||||
- 管理端网站入口改为 Zone 列表与 `/websites/:zoneId` 详情（概览 / 域名 / 路由 / 证书 / 设置），反代路由通过 Zone 域名选择器绑定。
|
||||
- 新增 Zone 域名迁移指南（`docs/guide/zone-domain-migration.md`），覆盖备份、`wavelet migrate-zones`、预览等价性与回滚步骤。
|
||||
|
||||
### 修改
|
||||
|
||||
- 配置快照、OpenResty 渲染、Tunnel 与 Uptime Kuma 监控改为从 Zone 域名绑定读取域名和证书，移除对反代路由旧域名/证书字段的运行时回退。
|
||||
- 反代路由 API 以 `zone_domain_ids` / `zone_domains` 为唯一域名与证书关联来源，不再接受或返回路由内嵌域名/证书字段。
|
||||
- 第二阶段迁移删除 `of_managed_domains` 及 `of_proxy_routes` 上的 `domain` / `domains` / `cert_id` / `cert_ids` / `domain_cert_ids` 冗余列。
|
||||
|
||||
### 移除
|
||||
|
||||
- 移除托管域名（managed-domains）管理 API 与前端 `WebsiteService`；请改用 Zone / Zone 域名 API。
|
||||
|
||||
### 修复
|
||||
|
||||
|
||||
@@ -73,6 +73,7 @@ function sidebarGuide(): DefaultTheme.SidebarItem[] {
|
||||
{ text: '概览', link: '' },
|
||||
{ text: '快速开始', link: 'quick-start' },
|
||||
{ text: 'TLS 证书与自动续期', link: 'certificates' },
|
||||
{ text: 'Zone 域名迁移', link: 'zone-domain-migration' },
|
||||
{ text: '新建反代配置', link: 'proxy-config' },
|
||||
{ text: 'Pages 静态托管使用', link: 'pages-usage' },
|
||||
{ text: '内网穿透与隧道使用', link: 'tunnel-usage' },
|
||||
|
||||
@@ -81,15 +81,22 @@ WAF、Pages、上游与发布版本仍属于 `proxy_routes`。Zone 概览只聚
|
||||
|
||||
## 数据迁移
|
||||
|
||||
本次改造分两个发布阶段，以免 SQL 用错误的“末两段域名”规则处理多级公共后缀。
|
||||
本次改造分两个发布阶段，以免 SQL 用错误的“末两段域名”规则处理多级公共后缀。操作细则见 [Zone 域名迁移与发布验收](../guide/zone-domain-migration.md)。
|
||||
|
||||
1. 使用 PostgreSQL 与 SQLite 同版本 Goose DDL 创建新表、索引；保留旧表和路由冗余列。
|
||||
2. 通过可显式执行、可重复运行的 Go 数据迁移使用 `publicsuffix.EffectiveTLDPlusOne`：从既有路由域名及 `managed_domains` 创建 Zone 和 Zone 域名，按旧 `domain_cert_ids` 的位置迁移证书到 `zone_domains.cert_id`；旧记录仅在没有路由时生成未绑定 Zone 域名。迁移报告必须列出无法解析或存在冲突的记录并中止，不静默丢弃。
|
||||
3. 新代码切换到 Zone 模型、完成配置编译与 UI 验证后，再在独立 Goose 迁移中删除 `of_managed_domains` 和旧冗余列。
|
||||
1. **第一阶段 DDL**：PostgreSQL 与 SQLite 同版本 Goose 创建 `of_zones` / `of_zone_domains`；暂时保留 `of_managed_domains` 与路由冗余列。
|
||||
2. **数据导入**：`wavelet migrate-zones` 使用 `publicsuffix.EffectiveTLDPlusOne`，从既有路由域名及（无路由域名时的）`managed_domains` 创建 Zone / Zone 域名，按旧 `domain_cert_ids` 位置写入 `zone_domains.cert_id`。冲突时整单回滚并输出报告，禁止在有冲突时发布。
|
||||
3. **代码切换**：控制面 API、配置快照、渲染、前端均以 Zone 域名为唯一来源；路由写入仅使用 `zone_domain_ids`。
|
||||
4. **第二阶段清理**：独立 Goose 迁移 `202607130001_drop_legacy_route_domain_columns` 删除 `of_managed_domains` 与 `of_proxy_routes` 的 `domain` / `domains` / `cert_id` / `cert_ids` / `domain_cert_ids`。Down 仅恢复开发库空结构，不回填历史数据。
|
||||
|
||||
### 运行时模型边界
|
||||
|
||||
* 持久化：域名与证书只存在于 `of_zone_domains`；`of_proxy_routes` 仅保存路由策略（上游、缓存、限流、WAF 绑定键等）。
|
||||
* 渲染：配置快照在内存中组装临时 `Domains` / `DomainCertIDs` 供 OpenResty 渲染，不写回数据库。
|
||||
* 导入命令：第二阶段后若旧列/旧表已不存在则跳过对应源，对已导入 Zone 域名保持幂等。
|
||||
|
||||
## 验证
|
||||
|
||||
* 单元测试：Public Suffix List 分组、FQDN / 通配符拒绝、跨 Zone 路由、证书 SAN 覆盖、删除保护及迁移幂等性。
|
||||
* 单元测试：Public Suffix List 分组、FQDN / 通配符拒绝、跨 Zone 路由、证书 SAN 覆盖、删除保护及迁移幂等性；清理后断言旧列/旧表不存在。
|
||||
* 集成测试：Zone、Zone 域名与路由 API 的成功与失败响应；现有路由迁移后生成相同 OpenResty 域名与证书配置。
|
||||
* 前端测试：Zone 列表、ID 路由、详情加载 / 错误 / 空状态、域名选择器与 API 负载。
|
||||
* 手动验证：迁移前后比较激活配置快照中的 `server_name` 和证书路径，发布后使用根域及各子域请求验证路由。
|
||||
|
||||
+9
-8
@@ -11,14 +11,15 @@ OpenFlare 是一套自托管的 OpenResty 控制面。它把反向代理网站
|
||||
1. [快速开始](./quick-start.md)：用 Docker Compose 启动 Server，登录管理端，并接入第一个 Agent。
|
||||
2. [发布第一份配置](./first-site.md)：快速新建一条最基础的 HTTP 反代站点规则，并验证节点生效状态。
|
||||
3. [新建反代配置](./proxy-config.md)：一步一步了解如何从证书导入与申请开始，配置 HTTPS 加密与上游源站管理。
|
||||
4. [Pages 静态托管使用](./pages-usage.md)：了解静态项目 ZIP 上传限制、SPA Fallback、以及内置 API 反向代理配置。
|
||||
5. [内网穿透与隧道使用](./tunnel-usage.md)：部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。
|
||||
6. [WAF 安全防护使用](./waf-usage.md)：配置 WAF 规则组，掌握 IP 黑白名单、自动/订阅 IP 组、地域限制与 PoW CC 防护。
|
||||
7. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
|
||||
8. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。
|
||||
9. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。
|
||||
10. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
|
||||
11. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。
|
||||
4. [Zone 域名迁移](./zone-domain-migration.md)：从旧托管域名/路由内嵌域名升级到 Zone 模型，含备份、导入、预览与回滚。
|
||||
5. [Pages 静态托管使用](./pages-usage.md)：了解静态项目 ZIP 上传限制、SPA Fallback、以及内置 API 反向代理配置。
|
||||
6. [内网穿透与隧道使用](./tunnel-usage.md)：部署 Relay 与 Client，实现安全、无公网 IP 反向穿透。
|
||||
7. [WAF 安全防护使用](./waf-usage.md)：配置 WAF 规则组，掌握 IP 黑白名单、自动/订阅 IP 组、地域限制与 PoW CC 防护。
|
||||
8. [WAF 自动 IP 组语法](./waf-ip-group-expr.md)：编写自动 IP 组 Expr 规则，了解关键字含义和预设规则。
|
||||
9. [Uptime Kuma 监控同步](./uptime-kuma.md)：配置并使用 Uptime Kuma 自动差分同步和监控范围控制。
|
||||
10. [SSO 登录配置](./sso.md)：配置 GitHub 或 OIDC 实现第三方单点登录 (SSO) 接入。
|
||||
11. [故障排查](./troubleshooting.md)：按症状排查登录、数据库、节点同步、OpenResty 应用和前端构建问题。
|
||||
12. [引用与致谢](./credits.md)：查看系统依赖的优秀开源项目与社区致谢清单。
|
||||
|
||||
## 按角色查找
|
||||
|
||||
|
||||
@@ -0,0 +1,98 @@
|
||||
# Zone 域名迁移与发布验收
|
||||
|
||||
从旧版 `managed_domains` / 反代路由内嵌域名列迁移到 Zone + Zone 域名模型时，按本指南操作。**导入报告存在冲突时禁止继续发布。**
|
||||
|
||||
## 前置条件
|
||||
|
||||
* 已备份 PostgreSQL / SQLite 数据库与当前激活配置版本（可导出管理端「配置版本」中的激活快照）。
|
||||
* Server 二进制已升级到包含 `of_zones` / `of_zone_domains` 表迁移的版本。
|
||||
* 维护窗口内可暂停非必要配置发布。
|
||||
|
||||
## 1. 备份
|
||||
|
||||
```bash
|
||||
# PostgreSQL 示例
|
||||
pg_dump "$DATABASE_URL" > openflare-pre-zone-$(date +%Y%m%d).sql
|
||||
|
||||
# 或复制备份卷 / 快照；SQLite 则直接复制 data 目录中的库文件
|
||||
```
|
||||
|
||||
在管理端确认当前**激活版本号**并记下 checksum，便于回滚对比。
|
||||
|
||||
## 2. 执行历史导入
|
||||
|
||||
```bash
|
||||
# 二进制名称为 wavelet（或你的部署包中的同名入口）
|
||||
wavelet migrate-zones
|
||||
```
|
||||
|
||||
命令会：
|
||||
|
||||
1. 先跑 goose 迁移（确保 Zone 表存在）。
|
||||
2. 以事务从旧路由域名（及无路由域名时的 `of_managed_domains`）导入 Zone / Zone 域名。
|
||||
3. 使用公共后缀列表解析注册根域；冲突时整单回滚并输出报告。
|
||||
|
||||
**成功标志：** 进程退出码 0，且日志/标准输出无「冲突」列表。
|
||||
|
||||
**失败时：** 阅读冲突项（无法解析的根域、通配符 FQDN、全局域名冲突、证书不存在等），修复源数据后重新执行。`migrate-zones` 幂等：已导入的域名会跳过，不会重复创建。
|
||||
|
||||
**有冲突时不要发布配置、不要执行第二阶段删列迁移。**
|
||||
|
||||
## 3. 导入后检查
|
||||
|
||||
1. 打开管理端 **网站** `/websites`：确认 Zone 根域与域名计数合理。
|
||||
2. 进入各 Zone 详情：域名、证书绑定、关联路由 ID 是否正确。
|
||||
3. 打开 **反代路由**：域名区应展示 Zone 域名绑定，而不是手写域名。
|
||||
|
||||
## 4. 配置预览与快照等价性
|
||||
|
||||
在升级前若已导出激活快照，导入后：
|
||||
|
||||
1. 在管理端打开配置差异 / 预览（或调用配置 diff / preview API）。
|
||||
2. **逐路由**核对：
|
||||
* 明确 `server_name` 集合（全部 FQDN）
|
||||
* 证书支持文件路径 / 证书 ID 与域名对应关系
|
||||
* WAF 绑定的 Route ID（`site_name` 与路由 ID 不变）
|
||||
* Pages 项目引用
|
||||
3. **允许**旧快照 JSON 中路由上的冗余 `domain` / `domains` / `cert_ids` 字段消失。
|
||||
4. **不允许**数据面语义变化（域名集合、证书覆盖、上游、WAF、Pages 绑定）。
|
||||
|
||||
不一致时：停止发布，修正 Zone 域名/证书绑定后重新预览。
|
||||
|
||||
## 5. 发布与回滚
|
||||
|
||||
1. 预览通过后，在管理端执行**配置发布**，记录新版本号。
|
||||
2. 用根域与各子域发起 HTTP(S) 请求，确认节点应用成功。
|
||||
3. **回滚：** 在配置版本中重新激活导入前的版本；节点会拉取旧快照。数据库侧若需回退，使用升级前备份恢复（第二阶段删列后 Down 迁移不回填业务数据）。
|
||||
|
||||
## 6. 第二阶段：删除旧表与冗余列
|
||||
|
||||
仅在以下条件全部满足后执行：
|
||||
|
||||
* `migrate-zones` 无冲突
|
||||
* 至少完成一次预览对比与发布（及必要时的回滚演练）
|
||||
* 运维确认不再依赖 `of_managed_domains` 与 `of_proxy_routes` 上的 `domain` / `domains` / `cert_*` 列
|
||||
|
||||
然后升级到包含 `202607130001_drop_legacy_route_domain_columns` 的版本并启动 Server（自动 goose）。该迁移将：
|
||||
|
||||
* 删除 `of_proxy_routes` 的 `domain`、`domains`、`cert_id`、`cert_ids`、`domain_cert_ids`
|
||||
* 删除表 `of_managed_domains`
|
||||
|
||||
**不可逆业务数据：** Down 仅在开发库重建空结构，不恢复历史域名行。
|
||||
|
||||
## 7. 命令速查
|
||||
|
||||
| 步骤 | 命令 / 操作 |
|
||||
| --- | --- |
|
||||
| 备份 | `pg_dump` / 复制 SQLite 文件 |
|
||||
| 导入 | `wavelet migrate-zones` |
|
||||
| 预览 | 管理端配置差异 / Preview API |
|
||||
| 发布 | 管理端发布激活版本 |
|
||||
| 回滚配置 | 管理端激活旧版本 |
|
||||
| 回滚库 | 恢复备份（勿依赖 Down 填数） |
|
||||
|
||||
## 相关文档
|
||||
|
||||
* [Zone 与域名资源设计](../design/zone-design.md)
|
||||
* [新建反代配置](./proxy-config.md)
|
||||
* [发布第一份配置](./first-site.md)
|
||||
Reference in New Issue
Block a user