OpenFlare/docs/plan/handover-openflare-backend-migration.md

OpenFlare 后端迁移 — AI 接手文档

状态：进行中（阶段 5 收尾）
主线：openflare-server 业务域已迁入 Wavelet/internal/apps/openflare/；管理控制台走 /api/v1/d/* + Wavelet/frontend；节点协议走 /api/v1/agent|relay|tunnel/*
关联计划：实现计划

---

1. 当前任务状态

主线任务

将 OpenFlare 控制面后端从 openflare-server 迁移至 Wavelet 框架，复用 Wavelet 用户/OAuth/Cap 等平台能力，并完成 Agent/Relay/Tunnel 协议兼容。

架构现状（2026-06-19）：原计划「阶段一 /api/* legacy 层 + 旧前端联调」已在 v1 路径切换时撤销。internal/apps/openflare/legacy/、compat/auth.go 已删除；openflare-server/web 不再能对接当前 Wavelet 后端。

开发分支

• 分支：dev
• 参考对照：旧后端 openflare-server/（待 ETL 验证后归档）

已完成（✅）

• 业务模块 T-OPTION ~ T-MISC：14 个 OpenFlare 业务包 + internal/router/v1/openflare/register_*.go
• goose 迁移 202606190001 ~ 202606190014（PostgreSQL + SQLite 双份）
• 可观测性 v1 单表：无 _00~_09 分片；heartbeat 持久化、访问日志查询、Relay/Tunnel 观测
• 后台任务：已迁入 Wavelet Asynq（async_tasks.go + 202606190013 种子）
• TLS ACME 申请/续期（lego DNS-01）
• 集成测试 4 个场景包全部通过（23 用例）
• 配置默认值：DB 名 openflare、监听 :3000、application_name=openflare-server、Redis 前缀 openflare:
• API 路径统一：控制台 /api/v1/d/*；协议 /api/v1/agent|relay|tunnel/*；Swagger 约 99 端点

进行中（阶段 5）

• [/] B5-3 旧环境数据迁移脚本 support-files/migration/（用户 + 业务表 ETL，含 10 分片观测数据合并）
• [/] B5-4 make swagger + make code-check 全绿
• [/] B5-5 全量 API 回归（对照实现计划 §12 端点表）

待处理

• 生产环境：创建并激活 config version，消除节点列表「异常」（openresty_status=unhealthy + 当前没有激活版本）
• 归档 openflare-server/ 整包（ETL 与回归通过后）

---

2. 任务队列（委派状态）

ID	板块	状态	负责目录
T-AUTH	认证/用户/OAuth/Cap	✅	Wavelet apps/user、apps/oauth、apps/cap、apps/admin（无独立 legacy 包）
T-OPTION	状态/公告/Option	✅	openflare/option/，register_option.go
T-ORIGIN	源站	✅	openflare/origin/，register_origin.go
T-APPLYLOG	应用日志	✅	openflare/apply_log/，register_apply_log.go
T-PROXY	代理规则	✅	openflare/proxy_route/，register_proxy_route.go
T-NODE	节点管理	✅	openflare/node/，register_node.go
T-WAF	WAF	✅	openflare/waf/，register_waf.go
T-TLS	TLS/证书/域名/DNS	✅	openflare/tls/，register_tls.go
T-CFGVER	配置版本	✅	openflare/config_version/，register_config_version.go
T-AGENT	Agent API + WS	✅	openflare/agent/，register_agent.go
T-PAGES	Pages 托管	✅	openflare/pages/，register_pages.go
T-RELAY	Relay + Tunnel	✅	openflare/relay/、openflare/flared/，register_relay_flared.go
T-OBS	仪表盘 + 可观测	✅	openflare/dashboard/、openflare/observability/，register_dashboard.go、register_observability.go
T-MISC	升级/GeoIP/UptimeKuma	✅	openflare/update/、openflare/geoip/、openflare/uptimekuma/，register_update.go、register_option.go

任务隔离规则

规则	说明
文件所有权	每个任务 仅修改 自己的 internal/apps/openflare/<module>/、对应 router/v1/openflare/register_<module>.go、internal/model/openflare_<module>.go、goose SQL
禁止修改	v1/user.go、v1/admin.go、model/users.go、其他任务的 register_*.go
控制台响应格式	{error_msg, data} + response.Abort*（Wavelet 标准）
协议响应格式	compat.OK/Fail（{success, message, data}），供 Agent/Relay/Tunnel 二进制使用
控制台鉴权	apiutil.AdminRequired()（Session / X-Access-Token，user.IsAdmin + token_admin）
Logic 层	logics.go 使用 context.Context，不依赖 *gin.Context
数据源	db.DB(ctx) 获取 GORM
质量门禁	完成后 go build ./... 并通过本模块测试

---

3. 核心文件与上下文

路由注册

路径	职责
Wavelet/internal/router/router.go	apiGroup → v1.RegisterV1Routes
Wavelet/internal/router/v1/v1.go	汇总 User/Admin/OpenFlare 路由
Wavelet/internal/router/v1/openflare/v1.go	RegisterV1Routes → /api/v1/d/* 控制台
Wavelet/internal/router/v1/openflare/openflare.go	RegisterRoutes → `/api/v1/agent
Wavelet/internal/router/v1/openflare/register_*.go	各资源路由挂载
Wavelet/internal/apps/openflare/*/routers.go	Handler + Swagger 注解
Wavelet/internal/apps/openflare/compat/response.go	协议层 legacy 信封（仅 Agent/Relay/Tunnel）
Wavelet/internal/apps/openflare/apiutil/	控制台 BindJSON、AdminRequired、RegisterCollection

后台任务（Asynq）

任务名	说明
openflare:database_auto_cleanup	可观测数据自动清理（受 Option 开关控制）
openflare:waf_ip_group_sync	WAF IP 组周期同步
openflare:uptime_kuma_sync	UptimeKuma 同步
openflare:ssl_renew	ACME 证书自动续期

启动链路：wavelet api / wavelet all → bootstrap.Init → Asynq worker/scheduler 执行；任务定义见 async_tasks.go，调度种子见 202606190013。

数据库迁移

版本	内容
202606190001	of_options
202606190002	of_origins
202606190003	of_apply_logs
202606190004	of_proxy_routes
202606190005	of_nodes
202606190006	of_waf_*
202606190007	of_tls_*
202606190008	of_config_versions
202606190009	of_pages_*
202606190010	可观测性单表
202606190011	of_node_access_logs 复合索引
202606190012	of_node_obs_frpc
202606190013	OpenFlare Asynq 调度种子
202606190014	Pages upload_id 字段

路径：Wavelet/internal/db/migrator/goose/postgres/ 与 sqlite/ 各一份。

近期修复要点（2026-06-19）

问题	根因	修复/处理
Agent 已连接但节点显示「异常」	无激活 config version	运维：发布并激活配置版本
节点详情无错误日志	可观测性表未迁移	202606190010 + agent/observability.go
WAF IP 组未下发	Agent sync 未实装	agent/waf_ip_group.go、waf/ip_group_sync.go
Pages 包下载 404	Agent 路由缺失	pages/logics.go、agent/routers.go
访问日志查询空	单表查询层缺失	model/openflare_access_log.go、202606190011
Relay/Tunnel 观测缺失	heartbeat 未持久化	relay/observability.go、flared/observability.go、202606190012

依赖修复

replace github.com/rain-kl/openflare => ../ 会引入根 go.mod 的 gomodule/redigo v2.0.0+incompatible，与 gin-contrib/sessions/redistore 不兼容。已在 Wavelet/go.mod 添加 exclude 并锁定 redigo v1.9.3。

---

4. 集成测试

测试包	场景	结果
integration/auth_option_test.go	Access Token 鉴权、option 权限、热重载	✅ 5/5
integration/core_chain_test.go	源站→规则→发布→节点→apply-log	✅ 6/6
integration/security_test.go	WAF/TLS/域名/DNS	✅ 7/7
integration/agent_protocol_test.go	Agent/Relay/Tunnel 协议	✅ 5/5

cd Wavelet
go test ./internal/apps/openflare/... -count=1
go build ./...

---

5. 本地启动（Wavelet 后端）

配置

复制 Wavelet/config.example.yaml → config.yaml，关键项：

app:
  app_name: "openflare"
  addr: ":3000"
database:
  enabled: true
  database: "openflare"
  application_name: "openflare-server"
redis:
  key_prefix: "openflare:"

启动命令

cd Wavelet
go run . all    # 开发：API + Worker + Scheduler
go run . api    # 生产：API 进程
go run . worker
go run . scheduler

当前联调方式

• 管理控制台：Wavelet/frontend（pnpm dev 或 embed 构建产物），Session 鉴权，API 前缀 /api/v1/d/*
• 节点二进制：连接 /api/v1/agent/*、/api/v1/relay/*、/api/v1/tunnel/*（legacy {success,message,data} 信封）
• 旧前端 openflare-server/web：已无法对接当前后端（无 /api/* 控制台路由、无 OpenFlare-Token 桥接）

---

6. 待决策与遗留问题

项	说明	当前处理
观测数据 10 分片 → 单表	旧生产环境有 node_*_XX 分片表	v1 单表；B5-3 ETL 脚本待建
微信登录	Wavelet 无内置	旧 /api/oauth/wechat* 未保留；评估废弃或补 v1 适配
三级角色 Root(100)	旧 RootAuth	简化为 is_admin + Access Token token_admin
节点「异常」展示	连接正常但无激活版本	属预期行为；需运维发布配置
make code-check	全仓库静态检查	阶段 5 待跑通

---

7. 下一步行动指南

1. 确认环境：cd Wavelet && go build ./... && go test ./internal/apps/openflare/... -count=1
2. 跑质量门禁：make code-check
3. 实现 B5-3：Wavelet/support-files/migration/ ETL 脚本
4. API 回归：对照实现计划 §12 端点表逐项验证
5. 联调验证：Wavelet/frontend 登录 → 创建规则 → 发布并激活 config version → Agent 心跳 → 检查节点状态

---

8. 参考文档

文档	用途
实现计划	模块清单、§12 端点对照
前端迁移计划	UI 迁移与验收
Wavelet/AGENTS.md	框架 Guardrails
旧后端源码（对照用）	openflare-server/internal/
Changelog	docs/changelog/index.md [Unreleased]