feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误

refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本

按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。

验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。

docs(cordis): 记录 T1 清理结果与五个复用阻塞点

refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本

按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。

两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
  避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
  副本，待与 infra 初始化一并迁移（已登记在清理计划）。

验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。

chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染

按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。

同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。

AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。

验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。

feat(cordis): server 插件化并改由内核挂载控制面路由

新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。

路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。

已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。

feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由

server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。

验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。

docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口

feat(cordis): agent/relay/flared 落地为内核驱动插件

三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。

入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。

验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。

refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层

backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。

验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。

feat(cordis): 落地 backend/share 共享层与上游同步脚本

跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。

go build 通过，go test ./... exit 0（142 包 ok），前端零改动。

refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核

按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。

行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。

style: 修正模块路径改写导致的 import 分组排序漂移

refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare

对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。

行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。

chore(cordis): 落地改造计划与 schema/路由基线

新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。

docs(cordis): add OpenFlare Cordis 架构改造设计

明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。

backend/plugins/drivers/driver_http/cache_helper.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"sync"
+)
+
+var (
+	cacheMu  sync.RWMutex
+	cacheSvc contracts.CacheService
+)
+
+func setCacheService(s contracts.CacheService) {
+	cacheMu.Lock()
+	defer cacheMu.Unlock()
+	cacheSvc = s
+}
+
+// getCache resolves the cache service from a micro-kernel context, falling back
+// to the instance bound during plugin registration.
+func getCache(ctx context.Context) contracts.CacheService {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.CacheService](c); err == nil && s != nil {
+			return s
+		}
+	}
+	cacheMu.RLock()
+	s := cacheSvc
+	cacheMu.RUnlock()
+	return s
+}

backend/plugins/drivers/driver_http/config.go

@@ -0,0 +1,28 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+type httpAppConfig struct {
+	Addr                    string `config:"addr" env:"APP_ADDR" default:":8000"`
+	AppName                 string `config:"app_name" env:"APP_NAME" default:"Wavelet"`
+	APIPrefix               string `config:"api_prefix" env:"APP_API_PREFIX" default:"/api/v1"`
+	Env                     string `config:"env" env:"APP_ENV" default:"development"`
+	GracefulShutdownTimeout int    `config:"graceful_shutdown_timeout" env:"APP_GRACEFUL_SHUTDOWN_TIMEOUT" default:"30"`
+	SessionCookieName       string `config:"session_cookie_name" env:"APP_SESSION_COOKIE_NAME" default:"wavelet_session"`
+	SessionSecret           string `config:"session_secret" env:"APP_SESSION_SECRET" secret:"true"`
+	SessionDomain           string `config:"session_domain" env:"APP_SESSION_DOMAIN"`
+	SessionAge              int    `config:"session_age" env:"APP_SESSION_AGE" default:"86400"`
+	SessionHTTPOnly         bool   `config:"session_http_only" env:"APP_SESSION_HTTP_ONLY" default:"true"`
+	SessionSecure           bool   `config:"session_secure" env:"APP_SESSION_SECURE"`
+}
+
+type httpRedisConfig struct {
+	Enabled     bool     `config:"enabled" env:"REDIS_ENABLED" default:"false"`
+	Addrs       []string `config:"addrs" env:"REDIS_ADDR"`
+	Username    string   `config:"username" env:"REDIS_USERNAME"`
+	Password    string   `config:"password" env:"REDIS_PASSWORD" secret:"true"`
+	DB          int      `config:"db" env:"REDIS_DB"`
+	KeyPrefix   string   `config:"key_prefix" env:"REDIS_KEY_PREFIX"`
+	MinIdleConn int      `config:"min_idle_conn" env:"REDIS_MIN_IDLE_CONN"`
+}

backend/plugins/drivers/driver_http/db_helper.go

@@ -0,0 +1,39 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"context"
+	"sync"
+
+	"gorm.io/gorm"
+)
+
+var (
+	dbMu  sync.RWMutex
+	dbSvc contracts.DBService
+)
+
+func setDBService(s contracts.DBService) {
+	dbMu.Lock()
+	defer dbMu.Unlock()
+	dbSvc = s
+}
+
+func getDB(ctx context.Context) *gorm.DB {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.DBService](c); err == nil && s != nil {
+			return s.DB(ctx)
+		}
+	}
+	dbMu.RLock()
+	s := dbSvc
+	dbMu.RUnlock()
+	if s != nil {
+		return s.DB(ctx)
+	}
+	return nil
+}

backend/plugins/drivers/driver_http/engine.go

@@ -0,0 +1,103 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"log"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-contrib/sessions/redis"
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin"
+)
+
+// BuildEngine 构建并初始化 Gin 路由引擎及全部中间件和路由
+func BuildEngine() (*gin.Engine, error) {
+	return BuildEngineWithConfig(httpAppConfig{}, httpRedisConfig{})
+}
+
+// BuildEngineWithConfig constructs the Gin engine with explicitly injected configuration.
+func BuildEngineWithConfig(appCfg httpAppConfig, redisCfg httpRedisConfig) (*gin.Engine, error) {
+	// 运行模式
+	if appCfg.Env == "production" || appCfg.Env == "prod" {
+		gin.SetMode(gin.ReleaseMode)
+	}
+
+	setAPIPrefix(appCfg.APIPrefix)
+
+	// 初始化路由
+	r := gin.New()
+	r.Use(gin.Recovery())
+	r.Use(corsMiddleware())
+
+	sessionSecret := appCfg.SessionSecret
+	if sessionSecret == "" {
+		sessionSecret = "wavelet-default-session-secret"
+	}
+
+	sessionStore := initSessionStore(sessionSecret, redisCfg)
+
+	sessionCookieName := appCfg.SessionCookieName
+	if sessionCookieName == "" {
+		sessionCookieName = "wavelet_session"
+	}
+
+	sessionAge := appCfg.SessionAge
+	if sessionAge <= 0 {
+		sessionAge = 86400
+	}
+
+	sessionStore.Options(sessions.Options{
+		Path:     "/",
+		Domain:   appCfg.SessionDomain,
+		MaxAge:   sessionAge,
+		HttpOnly: appCfg.SessionHTTPOnly,
+		Secure:   appCfg.SessionSecure,
+		SameSite: http.SameSiteLaxMode,
+	})
+
+	r.Use(sessions.Sessions(sessionCookieName, sessionStore))
+
+	appName := appCfg.AppName
+	if appName == "" {
+		appName = "Wavelet"
+	}
+
+	// 补充中间件
+	r.Use(otelgin.Middleware(appName), errorHandlerMiddleware(), loggerMiddleware())
+
+	return r, nil
+}
+
+func initSessionStore(sessionSecret string, redisCfg httpRedisConfig) sessions.Store {
+	if !redisCfg.Enabled || len(redisCfg.Addrs) == 0 {
+		return cookie.NewStore([]byte(sessionSecret))
+	}
+
+	sessionAddr := redisCfg.Addrs[0]
+	store, err := redis.NewStoreWithDB(
+		redisCfg.MinIdleConn,
+		"tcp",
+		sessionAddr,
+		redisCfg.Username,
+		redisCfg.Password,
+		strconv.Itoa(redisCfg.DB),
+		[]byte(sessionSecret),
+	)
+	if err != nil {
+		log.Printf("[driver_http] init redis session store failed, fallback to cookie store: %v\n", err)
+		return cookie.NewStore([]byte(sessionSecret))
+	}
+
+	if redisCfg.KeyPrefix != "" {
+		if err := redis.SetKeyPrefix(store, redisCfg.KeyPrefix+"session:"); err != nil {
+			log.Printf("[API] set session key prefix failed: %v\n", err)
+		}
+	}
+
+	return store
+}

backend/plugins/drivers/driver_http/frontend.go

@@ -0,0 +1,92 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"io"
+	"io/fs"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+const indexFile = "index.html"
+
+// serverOwnedPrefixes are backend-owned namespaces. A miss there must keep Gin's default
+// 404 instead of silently returning the frontend shell, which would mask broken API links.
+var serverOwnedPrefixes = []string{"/api/", "/f/"}
+
+// registerFrontend mounts assets as the NoRoute fallback so client-side routes resolve.
+// It is a no-op when assets is nil, i.e. the binary was built without the embed_frontend tag.
+func registerFrontend(engine *gin.Engine, assets fs.FS) {
+	if assets == nil {
+		return
+	}
+
+	engine.NoRoute(func(c *gin.Context) {
+		if isServerOwned(c.Request.URL.Path) {
+			return
+		}
+
+		if c.Request.Method != http.MethodGet && c.Request.Method != http.MethodHead {
+			c.JSON(http.StatusMethodNotAllowed, gin.H{"error_msg": "Method not allowed"})
+			return
+		}
+
+		for _, candidate := range assetCandidates(c.Request.URL.Path) {
+			if serveAsset(c, assets, candidate) {
+				return
+			}
+		}
+	})
+}
+
+func isServerOwned(urlPath string) bool {
+	for _, prefix := range serverOwnedPrefixes {
+		if strings.HasPrefix(urlPath, prefix) {
+			return true
+		}
+	}
+	return false
+}
+
+// assetCandidates maps a request path onto the static export layout: exact file,
+// Next.js clean-URL siblings, then the single-page-app shell.
+func assetCandidates(urlPath string) []string {
+	clean := strings.TrimPrefix(path.Join("/", urlPath), "/")
+	if clean == "" || clean == "." {
+		return []string{indexFile}
+	}
+
+	candidates := []string{clean}
+	if !strings.Contains(clean, ".") {
+		candidates = append(candidates, clean+".html", path.Join(clean, indexFile))
+	}
+
+	return append(candidates, indexFile)
+}
+
+// serveAsset writes name when it exists as a regular file, reporting whether it served.
+func serveAsset(c *gin.Context, assets fs.FS, name string) bool {
+	file, err := assets.Open(name)
+	if err != nil {
+		return false
+	}
+	defer func() { _ = file.Close() }()
+
+	info, err := file.Stat()
+	if err != nil || info.IsDir() {
+		return false
+	}
+
+	seeker, ok := file.(io.ReadSeeker)
+	if !ok {
+		return false
+	}
+
+	http.ServeContent(c.Writer, c.Request, name, info.ModTime(), seeker)
+	return true
+}

backend/plugins/drivers/driver_http/frontend_disabled.go

@@ -0,0 +1,12 @@
+//go:build !embed_frontend
+
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import "io/fs"
+
+// frontendAssets returns nil: this binary was built without the embedded frontend bundle,
+// so unmatched routes keep Gin's default 404 and the frontend is served separately.
+func frontendAssets() fs.FS { return nil }

backend/plugins/drivers/driver_http/frontend_embedded.go

@@ -0,0 +1,24 @@
+//go:build embed_frontend
+
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:dist
+var frontendFS embed.FS
+
+// frontendAssets returns the exported Next.js bundle shipped inside this binary.
+func frontendAssets() fs.FS {
+	sub, err := fs.Sub(frontendFS, "dist")
+	if err != nil {
+		panic("driver_http: embedded frontend bundle unavailable: " + err.Error())
+	}
+
+	return sub
+}

backend/plugins/drivers/driver_http/middlewares.go

@@ -0,0 +1,184 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package driver_http 提供 HTTP 路由中间件与服务启动
+package driver_http
+
+import (
+	"Wavelet/core/extpoints"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"context"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/trace"
+
+	otel_trace "Wavelet/pkg/trace"
+)
+
+var (
+	apiPrefixMu sync.RWMutex
+	apiPrefix   = "/api/v1"
+)
+
+// whitelist holds the global no-auth HTTP patterns. They are set once at
+// configuration time and matched per request, so PathWhitelist parses them up front.
+var whitelist = extpoints.NewPathWhitelist()
+
+// SetWhitelist configures global whitelist patterns for HTTP routes.
+func SetWhitelist(patterns []string) {
+	whitelist.Replace(patterns...)
+}
+
+// IsPathWhitelisted checks if the given path matches any registered whitelist pattern.
+func IsPathWhitelisted(path string) bool {
+	return whitelist.Match(path)
+}
+
+func setAPIPrefix(prefix string) {
+	if prefix == "" {
+		return
+	}
+	apiPrefixMu.Lock()
+	defer apiPrefixMu.Unlock()
+	apiPrefix = prefix
+}
+
+func getAPIPrefix() string {
+	apiPrefixMu.RLock()
+	defer apiPrefixMu.RUnlock()
+	return apiPrefix
+}
+
+func loggerMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		// 初始化 Trace
+		ctx, span := otel_trace.Start(c.Request.Context(), "LoggerMiddleware")
+		defer span.End()
+
+		// 开始计时
+		start := time.Now()
+
+		// 记录请求路径和 Query
+		path := c.Request.URL.Path
+		raw := c.Request.URL.RawQuery
+		if raw != "" {
+			path = path + "?" + raw
+		}
+
+		// 执行请求
+		c.Next()
+
+		// 停止计时
+		end := time.Now()
+		latency := end.Sub(start)
+
+		// 打印日志
+		// 排除健康检查接口
+		healthPath := getAPIPrefix() + "/health"
+		if c.Request.URL.Path != healthPath {
+			logger.InfoF(
+				ctx,
+				"[LoggerMiddleware] %s %s\nStartTime: %s\nEndTime: %s\nLatency: %d\nClientIP: %s\nResponse: %d %d",
+				c.Request.Method,
+				path,
+				start.Format(time.RFC3339),
+				end.Format(time.RFC3339),
+				latency.Milliseconds(),
+				c.ClientIP(),
+				c.Writer.Status(),
+				c.Writer.Size(),
+			)
+		}
+
+		// 设置 Span 状态
+		if c.Writer.Status() >= http.StatusBadRequest {
+			span := trace.SpanFromContext(ctx)
+			span.SetStatus(codes.Error, strconv.Itoa(c.Writer.Status()))
+		}
+	}
+}
+
+const (
+	// serverAddressConfigKey 是 admin 域声明的系统配置键（跨插件不能直接引用其常量）。
+	serverAddressConfigKey = "server_address"
+	// serverAddressCacheKey / serverAddressCacheTTL 把 CORS 允许来源的读取从每请求
+	// 一次主库查询降为每 TTL 一次，TTL 与存储驱动的系统配置缓存保持一致。
+	serverAddressCacheKey = "driver_http:cors:server_address"
+	serverAddressCacheTTL = 5 * time.Second
+)
+
+// loadServerAddress reads the configured server address straight from system configs.
+func loadServerAddress(ctx context.Context) (string, error) {
+	db := getDB(ctx)
+	if db == nil {
+		return "", nil
+	}
+	var val string
+	if err := db.Table("w_system_configs").Where("key = ?", serverAddressConfigKey).Pluck("value", &val).Error; err != nil {
+		return "", err
+	}
+	return val, nil
+}
+
+// serverAddress returns the configured server address, served from the shared
+// cache so CORS does not reach the database on every request.
+func serverAddress(ctx context.Context) (string, error) {
+	cacheSvc := getCache(ctx)
+	if cacheSvc == nil {
+		return loadServerAddress(ctx)
+	}
+
+	var val string
+	if err := cacheSvc.GetOrSet(ctx, serverAddressCacheKey, &val, serverAddressCacheTTL, func() (any, error) {
+		return loadServerAddress(ctx)
+	}); err != nil {
+		return "", err
+	}
+	return val, nil
+}
+
+func isOriginAllowed(ctx context.Context, origin string) bool {
+	val, err := serverAddress(ctx)
+	if err != nil || val == "" {
+		return false
+	}
+	allowedOrigins := strings.Split(val, ",")
+	for _, allowed := range allowedOrigins {
+		allowed = strings.TrimRight(strings.TrimSpace(allowed), "/")
+		if allowed != "" && strings.EqualFold(allowed, origin) {
+			return true
+		}
+	}
+	return false
+}
+
+func corsMiddleware() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		origin := c.Request.Header.Get("Origin")
+		if origin != "" && isOriginAllowed(c.Request.Context(), origin) {
+			c.Writer.Header().Set("Access-Control-Allow-Origin", origin)
+			c.Writer.Header().Set("Access-Control-Allow-Credentials", "true")
+			c.Writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With, X-Access-Token, X-Cap-Token")
+			c.Writer.Header().Set("Access-Control-Allow-Methods", "POST, OPTIONS, GET, PUT, DELETE, PATCH")
+		}
+
+		if c.Request.Method == "OPTIONS" {
+			c.AbortWithStatus(http.StatusNoContent)
+			return
+		}
+
+		c.Next()
+	}
+}
+
+// errorHandlerMiddleware 委托给 response.ErrorHandlerMiddleware，保持路由层单一入口。
+func errorHandlerMiddleware() gin.HandlerFunc {
+	return response.ErrorHandlerMiddleware()
+}

backend/plugins/drivers/driver_http/middlewares_test.go

@@ -0,0 +1,245 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package driver_http
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/testhelper"
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+)
+
+type mockDBService struct {
+	db *gorm.DB
+}
+
+func (m *mockDBService) GORM() *gorm.DB {
+	return m.db
+}
+
+func (m *mockDBService) DB(ctx context.Context) *gorm.DB {
+	return m.db.WithContext(ctx)
+}
+
+func (m *mockDBService) Named(_ string) *gorm.DB {
+	return m.db
+}
+
+func TestCORSMiddleware(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	setDBService(&mockDBService{db: dbConn})
+	defer func() {
+		setDBService(nil)
+		cleanup()
+	}()
+
+	gin.SetMode(gin.TestMode)
+
+	clearConfigCache := func() {}
+
+	t.Run("missing server_address configuration returns no CORS headers", func(t *testing.T) {
+		clearConfigCache()
+		if err := dbConn.Table("w_system_configs").Where("key = ?", "server_address").Update("value", "").Error; err != nil {
+			t.Fatalf("failed to update config: %v", err)
+		}
+
+		r := gin.New()
+		r.Use(corsMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		req.Header.Set("Origin", "http://attacker.com")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Header().Get("Access-Control-Allow-Origin") != "" {
+			t.Errorf("expected no Access-Control-Allow-Origin, got %s", w.Header().Get("Access-Control-Allow-Origin"))
+		}
+	})
+
+	t.Run("configured server_address allows exact origin match", func(t *testing.T) {
+		if err := dbConn.Table("w_system_configs").Where("key = ?", "server_address").Update("value", "http://trusted.com").Error; err != nil {
+			t.Fatalf("failed to update config: %v", err)
+		}
+
+		r := gin.New()
+		r.Use(corsMiddleware())
+		r.GET("/test", func(c *gin.Context) {
+			c.String(http.StatusOK, "ok")
+		})
+
+		// Trusted origin
+		req, _ := http.NewRequest(http.MethodGet, "/test", nil)
+		req.Header.Set("Origin", "http://trusted.com")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Header().Get("Access-Control-Allow-Origin") != "http://trusted.com" {
+			t.Errorf("expected Access-Control-Allow-Origin http://trusted.com, got %s", w.Header().Get("Access-Control-Allow-Origin"))
+		}
+		if w.Header().Get("Access-Control-Allow-Credentials") != "true" {
+			t.Errorf("expected Access-Control-Allow-Credentials true, got %s", w.Header().Get("Access-Control-Allow-Credentials"))
+		}
+
+		// Untrusted origin
+		req, _ = http.NewRequest(http.MethodGet, "/test", nil)
+		req.Header.Set("Origin", "http://attacker.com")
+		w = httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Header().Get("Access-Control-Allow-Origin") != "" {
+			t.Errorf("expected no Access-Control-Allow-Origin for attacker, got %s", w.Header().Get("Access-Control-Allow-Origin"))
+		}
+	})
+
+	t.Run("preflight OPTIONS request responds with 204", func(t *testing.T) {
+		if err := dbConn.Table("w_system_configs").Where("key = ?", "server_address").Update("value", "http://trusted.com").Error; err != nil {
+			t.Fatalf("failed to update config: %v", err)
+		}
+
+		r := gin.New()
+		r.Use(corsMiddleware())
+
+		req, _ := http.NewRequest(http.MethodOptions, "/test", nil)
+		req.Header.Set("Origin", "http://trusted.com")
+		w := httptest.NewRecorder()
+		r.ServeHTTP(w, req)
+
+		if w.Code != http.StatusNoContent {
+			t.Errorf("expected status 204, got %d", w.Code)
+		}
+		if w.Header().Get("Access-Control-Allow-Methods") == "" {
+			t.Error("expected Access-Control-Allow-Methods header")
+		}
+	})
+}
+
+// memoryCache 是一个可工作的内存缓存，用于统计 loader（即数据库查询）实际执行次数。
+type memoryCache struct {
+	values map[string]string
+	loads  int
+}
+
+func (c *memoryCache) Get(_ context.Context, key string, target any) error {
+	v, ok := c.values[key]
+	if !ok {
+		return contracts.ErrCacheMiss
+	}
+	dst, ok := target.(*string)
+	if !ok {
+		return contracts.ErrCacheMiss
+	}
+	*dst = v
+	return nil
+}
+
+func (c *memoryCache) Set(_ context.Context, key string, value any, _ time.Duration) error {
+	v, ok := value.(string)
+	if !ok {
+		return nil
+	}
+	c.values[key] = v
+	return nil
+}
+
+func (c *memoryCache) Delete(_ context.Context, key string) error {
+	delete(c.values, key)
+	return nil
+}
+
+func (c *memoryCache) GetOrSet(_ context.Context, key string, target any, _ time.Duration, loader func() (any, error)) error {
+	if err := c.Get(context.Background(), key, target); err == nil {
+		return nil
+	}
+	raw, err := loader()
+	if err != nil {
+		return err
+	}
+	c.loads++
+	v, ok := raw.(string)
+	if !ok {
+		return nil
+	}
+	c.values[key] = v
+	if dst, ok := target.(*string); ok {
+		*dst = v
+	}
+	return nil
+}
+
+func (c *memoryCache) Invalidate(ctx context.Context, key string) error {
+	return c.Delete(ctx, key)
+}
+
+// TestCORSAllowedOriginReadsConfigOncePerCacheWindow 回归：CORS 的来源校验不得在
+// 每个请求上都查询主库，缓存有效期内 loader 只应执行一次。
+func TestCORSAllowedOriginReadsConfigOncePerCacheWindow(t *testing.T) {
+	dbConn, _, cleanup := testhelper.SetupTestEnvironment(t)
+	setDBService(&mockDBService{db: dbConn})
+	cache := &memoryCache{values: map[string]string{}}
+	setCacheService(cache)
+	defer func() {
+		setCacheService(nil)
+		setDBService(nil)
+		cleanup()
+	}()
+
+	ctx := context.Background()
+	const origin = "http://localhost:8000" // testhelper 预置的 server_address
+	for range 3 {
+		if !isOriginAllowed(ctx, origin) {
+			t.Fatalf("origin %q should be allowed", origin)
+		}
+	}
+
+	if cache.loads != 1 {
+		t.Errorf("expected 1 config load across 3 requests, got %d", cache.loads)
+	}
+}
+
+func TestBuildEngineWithCookieFallback(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	appCfg := httpAppConfig{
+		SessionSecret:     "test-secret",
+		SessionCookieName: "wavelet_session",
+		SessionAge:        3600,
+	}
+	redisCfg := httpRedisConfig{
+		Enabled: false,
+	}
+
+	engine, err := BuildEngineWithConfig(appCfg, redisCfg)
+	if err != nil {
+		t.Fatalf("expected nil error with cookie fallback, got: %v", err)
+	}
+
+	engine.GET("/set-session", func(c *gin.Context) {
+		sess := sessions.Default(c)
+		sess.Set("test_user_id", uint64(12345))
+		_ = sess.Save()
+		c.String(http.StatusOK, "ok")
+	})
+
+	req, _ := http.NewRequest(http.MethodGet, "/set-session", nil)
+	w := httptest.NewRecorder()
+	engine.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK, got %d", w.Code)
+	}
+
+	setCookie := w.Header().Get("Set-Cookie")
+	if setCookie == "" {
+		t.Fatal("expected Set-Cookie header in response, got none")
+	}
+}

backend/plugins/drivers/driver_http/plugin.go

@@ -0,0 +1,309 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package driver_http provides the Gin HTTP web server driver plugin for Cordis.
+package driver_http
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/util"
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	defaultAddr              = ":8080"
+	defaultReadHeaderTimeout = 10 * time.Second
+	defaultShutdownTimeout   = 5 * time.Second
+)
+
+// Option configures the HTTP driver plugin.
+type Option func(*Plugin)
+
+// WithAddr sets the TCP address for the HTTP server to listen on.
+func WithAddr(addr string) Option {
+	return func(p *Plugin) {
+		p.addr = addr
+	}
+}
+
+// WithEngine sets a pre-configured Gin engine for the HTTP server.
+func WithEngine(engine *gin.Engine) Option {
+	return func(p *Plugin) {
+		p.engine = engine
+	}
+}
+
+// WithReadHeaderTimeout sets the ReadHeaderTimeout for http.Server.
+func WithReadHeaderTimeout(d time.Duration) Option {
+	return func(p *Plugin) {
+		p.readHeaderTimeout = d
+	}
+}
+
+// WithShutdownTimeout sets the fallback timeout for graceful server shutdown.
+func WithShutdownTimeout(d time.Duration) Option {
+	return func(p *Plugin) {
+		p.shutdownTimeout = d
+	}
+}
+
+// Plugin implements core.Plugin and core.Driver for Gin HTTP Web Server.
+type Plugin struct {
+	mu                sync.RWMutex
+	addr              string
+	engine            *gin.Engine
+	server            *http.Server
+	listener          net.Listener
+	running           bool
+	readHeaderTimeout time.Duration
+	shutdownTimeout   time.Duration
+	coreCtx           *core.Context
+}
+
+// New creates a new Gin HTTP server driver plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{
+		addr:              defaultAddr,
+		readHeaderTimeout: defaultReadHeaderTimeout,
+		shutdownTimeout:   defaultShutdownTimeout,
+	}
+
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+
+	return p
+}
+
+// Name returns the unique plugin identifier.
+func (p *Plugin) Name() string {
+	return "driver_http"
+}
+
+// DeclareConfig declares configuration bindings for driver_http.
+func (p *Plugin) DeclareConfig() []core.ConfigBinding {
+	return []core.ConfigBinding{
+		{Prefix: "app", Target: &httpAppConfig{}},
+		{Prefix: "redis", Target: &httpRedisConfig{}},
+	}
+}
+
+// Apply mounts the HTTP driver plugin into the micro-kernel Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	var appCfg httpAppConfig
+	if err := ctx.Config().Bind("app", &appCfg); err != nil {
+		return err
+	}
+	var redisCfg httpRedisConfig
+	_ = ctx.Config().Bind("redis", &redisCfg)
+
+	p.mu.Lock()
+	p.coreCtx = ctx
+	if p.addr == defaultAddr && appCfg.Addr != "" {
+		p.addr = appCfg.Addr
+	}
+	if appCfg.GracefulShutdownTimeout > 0 {
+		p.shutdownTimeout = time.Duration(appCfg.GracefulShutdownTimeout) * time.Second
+	}
+	p.mu.Unlock()
+
+	// Bind DBService from Context
+	if db, err := core.Inject[contracts.DBService](ctx); err == nil && db != nil {
+		setDBService(db)
+	} else {
+		core.When[contracts.DBService](ctx, func(db contracts.DBService) {
+			setDBService(db)
+		})
+	}
+	ctx.OnDispose(func() error {
+		setDBService(nil)
+		return nil
+	})
+
+	// Bind CacheService from Context
+	if cache, err := core.Inject[contracts.CacheService](ctx); err == nil && cache != nil {
+		setCacheService(cache)
+	} else {
+		core.When[contracts.CacheService](ctx, func(cache contracts.CacheService) {
+			setCacheService(cache)
+		})
+	}
+	ctx.OnDispose(func() error {
+		setCacheService(nil)
+		return nil
+	})
+
+	ctx.OnDispose(func() error {
+		shutdownCtx, cancel := context.WithTimeout(context.Background(), p.shutdownTimeout)
+		defer cancel()
+		return p.Stop(shutdownCtx)
+	})
+
+	return ctx.RegisterDriver(p)
+}
+
+// Type returns DriverTypeHTTP.
+func (p *Plugin) Type() core.DriverType {
+	return core.DriverTypeHTTP
+}
+
+// Start boots the Gin HTTP server, binds routes collected from ctx.Router(), and starts listening.
+func (p *Plugin) Start(ctx context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if p.running {
+		return nil
+	}
+
+	if p.engine == nil {
+		var appCfg httpAppConfig
+		var redisCfg httpRedisConfig
+		if p.coreCtx != nil {
+			_ = p.coreCtx.Config().Bind("app", &appCfg)
+			_ = p.coreCtx.Config().Bind("redis", &redisCfg)
+		}
+		var err error
+		p.engine, err = BuildEngineWithConfig(appCfg, redisCfg)
+		if err != nil {
+			p.engine, _ = BuildEngine()
+		}
+	}
+
+	// Mount routes collected in Context RouterExtension
+	if p.coreCtx != nil && p.coreCtx.Router() != nil {
+		SetWhitelist(p.coreCtx.Router().Whitelist())
+		for _, rd := range p.coreCtx.Router().Routes() {
+			allHandlers := make([]gin.HandlerFunc, 0, len(rd.Middlewares)+len(rd.Handlers))
+
+			for _, m := range rd.Middlewares {
+				gh, err := toGinHandler(m)
+				if err != nil {
+					return fmt.Errorf("driver_http: invalid middleware for route %s %s: %w", rd.Method, rd.Path, err)
+				}
+				allHandlers = append(allHandlers, gh)
+			}
+
+			for _, h := range rd.Handlers {
+				gh, err := toGinHandler(h)
+				if err != nil {
+					return fmt.Errorf("driver_http: invalid handler for route %s %s: %w", rd.Method, rd.Path, err)
+				}
+				allHandlers = append(allHandlers, gh)
+			}
+
+			p.engine.Handle(rd.Method, rd.Path, allHandlers...)
+		}
+	}
+
+	registerFrontend(p.engine, frontendAssets())
+
+	p.server = &http.Server{
+		Addr:              p.addr,
+		Handler:           p.engine,
+		ReadHeaderTimeout: p.readHeaderTimeout,
+	}
+
+	lc := &net.ListenConfig{}
+	listener, err := lc.Listen(ctx, "tcp", p.addr)
+	if err != nil {
+		return fmt.Errorf("driver_http: listen on %s failed: %w", p.addr, err)
+	}
+
+	p.listener = listener
+	p.addr = listener.Addr().String()
+	p.running = true
+
+	srv := p.server
+	util.Go(func() {
+		if serveErr := srv.Serve(listener); serveErr != nil && !errors.Is(serveErr, http.ErrServerClosed) {
+			_ = serveErr
+		}
+	})
+
+	return nil
+}
+
+// Stop gracefully stops the HTTP server.
+//
+//nolint:contextcheck
+func (p *Plugin) Stop(ctx context.Context) error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+
+	if !p.running {
+		return nil
+	}
+
+	p.running = false
+
+	var err error
+	if p.server != nil {
+		if ctx == nil {
+			var cancel context.CancelFunc
+			ctx, cancel = context.WithTimeout(context.Background(), p.shutdownTimeout)
+			defer cancel()
+		}
+		err = p.server.Shutdown(ctx)
+	}
+
+	if p.listener != nil {
+		_ = p.listener.Close()
+		p.listener = nil
+	}
+
+	return err
+}
+
+// Addr returns the current listening address (or configured address if not yet started).
+func (p *Plugin) Addr() string {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.addr
+}
+
+// Engine returns the underlying Gin engine.
+func (p *Plugin) Engine() *gin.Engine {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.engine
+}
+
+// IsRunning returns whether the HTTP server is currently running.
+func (p *Plugin) IsRunning() bool {
+	p.mu.RLock()
+	defer p.mu.RUnlock()
+	return p.running
+}
+
+func toGinHandler(h any) (gin.HandlerFunc, error) {
+	if h == nil {
+		return nil, errors.New("nil handler")
+	}
+
+	switch fn := h.(type) {
+	case gin.HandlerFunc:
+		return fn, nil
+	case func(*gin.Context):
+		return gin.HandlerFunc(fn), nil
+	case http.HandlerFunc:
+		return gin.WrapF(fn), nil
+	case func(http.ResponseWriter, *http.Request):
+		return gin.WrapF(fn), nil
+	case http.Handler:
+		return gin.WrapH(fn), nil
+	default:
+		return nil, fmt.Errorf("unsupported handler type: %T", h)
+	}
+}