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/pkg/util/client_errs.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+const (
+	errCreateHTTPRequestFailed = "创建HTTP请求失败: %w"
+	errHTTPRequestFailed       = "请求%s接口失败: %w"
+	errInvalidCustomValue      = "invalid value: %v"
+)

backend/pkg/util/crypto.go

@@ -0,0 +1,159 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package util provides generic utility functions.
+package util
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"crypto/ed25519"
+	"crypto/rand"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+)
+
+const (
+	aesKeyLength = 32
+
+	errInvalidSignKey         = "invalid sign key: %w"
+	errSignKeyLengthInvalid   = "sign key must be 32 bytes (64 hex characters)"
+	errCreateCipherFailed     = "failed to create cipher: %w"
+	errCreateGCMFailed        = "failed to create GCM: %w"
+	errGenerateNonceFailed    = "failed to generate nonce: %w"
+	errDecodeCiphertextFailed = "failed to decode ciphertext: %w"
+	errCiphertextTooShort     = "ciphertext too short"
+	errDecryptFailed          = "failed to decrypt: %w"
+)
+
+// Encrypt 使用 SignKey 加密字符串数据
+// signKey: 64 字符 hex 编码的密钥（对应 32 字节，用于 AES-256）
+// plaintext: 要加密的明文字符串
+// return: base64 编码的密文
+func Encrypt(signKey, plaintext string) (string, error) {
+	return encryptBytes(signKey, []byte(plaintext))
+}
+
+// Decrypt 使用 SignKey 解密字符串数据
+// signKey: 64 字符 hex 编码的密钥（对应 32 字节，用于 AES-256）
+// ciphertext: base64 编码的密文
+// return: 解密后的明文字符串
+func Decrypt(signKey, ciphertext string) (string, error) {
+	plaintext, err := decryptBytes(signKey, ciphertext)
+	if err != nil {
+		return "", err
+	}
+	return string(plaintext), nil
+}
+
+// encryptBytes 加密函数，处理字节数据
+func encryptBytes(signKey string, plaintext []byte) (string, error) {
+	// 将 hex 编码的密钥转换为字节
+	key, err := hex.DecodeString(signKey)
+	if err != nil {
+		return "", fmt.Errorf(errInvalidSignKey, err)
+	}
+	if len(key) != aesKeyLength {
+		return "", errors.New(errSignKeyLengthInvalid)
+	}
+
+	// 创建 AES cipher
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return "", fmt.Errorf(errCreateCipherFailed, err)
+	}
+
+	// 使用 GCM 模式（Galois/Counter Mode）
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return "", fmt.Errorf(errCreateGCMFailed, err)
+	}
+
+	// 生成随机 nonce
+	nonce := make([]byte, gcm.NonceSize())
+	if _, err := io.ReadFull(rand.Reader, nonce); err != nil {
+		return "", fmt.Errorf(errGenerateNonceFailed, err)
+	}
+
+	// 加密数据
+	ciphertext := gcm.Seal(nonce, nonce, plaintext, nil)
+
+	// 返回 base64 编码的密文
+	return Base64Encode(ciphertext), nil
+}
+
+// decryptBytes 解密函数，处理字节数据
+func decryptBytes(signKey, ciphertext string) ([]byte, error) {
+	// 将 hex 编码的密钥转换为字节
+	key, err := hex.DecodeString(signKey)
+	if err != nil {
+		return nil, fmt.Errorf(errInvalidSignKey, err)
+	}
+	if len(key) != aesKeyLength {
+		return nil, errors.New(errSignKeyLengthInvalid)
+	}
+
+	// 解码 base64 密文
+	data, err := Base64Decode(ciphertext)
+	if err != nil {
+		return nil, fmt.Errorf(errDecodeCiphertextFailed, err)
+	}
+
+	// 创建 AES cipher
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, fmt.Errorf(errCreateCipherFailed, err)
+	}
+
+	// 使用 GCM 模式
+	gcm, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, fmt.Errorf(errCreateGCMFailed, err)
+	}
+
+	// 提取 nonce
+	nonceSize := gcm.NonceSize()
+	if len(data) < nonceSize {
+		return nil, errors.New(errCiphertextTooShort)
+	}
+
+	nonce, ciphertextBytes := data[:nonceSize], data[nonceSize:]
+
+	// 解密数据
+	plaintext, err := gcm.Open(nil, nonce, ciphertextBytes, nil)
+	if err != nil {
+		return nil, fmt.Errorf(errDecryptFailed, err)
+	}
+
+	return plaintext, nil
+}
+
+// Base64Encode Base64编码
+func Base64Encode(data []byte) string {
+	return base64.StdEncoding.EncodeToString(data)
+}
+
+// Base64Decode Base64解码
+func Base64Decode(encoded string) ([]byte, error) {
+	return base64.StdEncoding.DecodeString(encoded)
+}
+
+// Ed25519Verify 验证 Ed25519 签名
+// publicKey: 32 字节的公钥（已解码的二进制格式）
+// message: 待验证的原始消息
+// signature: 64 字节的签名（已解码的二进制格式）
+// return: 签名是否有效
+func Ed25519Verify(publicKey, message, signature []byte) bool {
+	if len(publicKey) != ed25519.PublicKeySize {
+		return false
+	}
+
+	if len(signature) != ed25519.SignatureSize {
+		return false
+	}
+
+	return ed25519.Verify(publicKey, message, signature)
+}

backend/pkg/util/custom_types.go

@@ -0,0 +1,28 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package util provides framework-agnostic helper types and HTTP utilities.
+package util
+
+import (
+	"database/sql/driver"
+	"encoding/json"
+	"fmt"
+)
+
+// StringArray custom type for handling JSON arrays
+type StringArray []string
+
+// Scan 实现 sql.Scanner 接口，从数据库读取 JSON 数组
+func (sa *StringArray) Scan(value interface{}) error {
+	bytesValue, ok := value.([]byte)
+	if !ok {
+		return fmt.Errorf(errInvalidCustomValue, value)
+	}
+	return json.Unmarshal(bytesValue, sa)
+}
+
+// Value 实现 driver.Valuer 接口，将 JSON 数组序列化为数据库存储值
+func (sa StringArray) Value() (driver.Value, error) {
+	return json.Marshal(sa)
+}

backend/pkg/util/format.go

@@ -0,0 +1,70 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package util provides shared formatting and string helper functions.
+package util
+
+import (
+	"fmt"
+	"strconv"
+)
+
+const (
+	secondsPerYear   = 31104000 // 360 days
+	secondsPerMonth  = 2592000  // 30 days
+	secondsPerDay    = 86400
+	secondsPerHour   = 3600
+	secondsPerMinute = 60
+)
+
+const (
+	sizeKB = 1024
+	sizeMB = sizeKB * 1024
+	sizeGB = sizeMB * 1024
+)
+
+// Bytes2Size converts a byte count to a human-readable string with unit (B, KB, MB, GB).
+func Bytes2Size(num int64) string {
+	var numStr string
+	unit := "B"
+	switch {
+	case num/int64(sizeGB) >= 1:
+		numStr = fmt.Sprintf("%.2f", float64(num)/float64(sizeGB))
+		unit = "GB"
+	case num/int64(sizeMB) >= 1:
+		numStr = strconv.Itoa(int(float64(num) / float64(sizeMB)))
+		unit = "MB"
+	case num/int64(sizeKB) >= 1:
+		numStr = strconv.Itoa(int(float64(num) / float64(sizeKB)))
+		unit = "KB"
+	default:
+		numStr = strconv.FormatInt(num, 10)
+	}
+	return numStr + " " + unit
+}
+
+// Seconds2Time converts a number of seconds to a human-readable Chinese duration string.
+func Seconds2Time(num int) (time string) {
+	if num/secondsPerYear > 0 {
+		time += strconv.Itoa(num/secondsPerYear) + " 年 "
+		num %= secondsPerYear
+	}
+	if num/secondsPerMonth > 0 {
+		time += strconv.Itoa(num/secondsPerMonth) + " 个月 "
+		num %= secondsPerMonth
+	}
+	if num/secondsPerDay > 0 {
+		time += strconv.Itoa(num/secondsPerDay) + " 天 "
+		num %= secondsPerDay
+	}
+	if num/secondsPerHour > 0 {
+		time += strconv.Itoa(num/secondsPerHour) + " 小时 "
+		num %= secondsPerHour
+	}
+	if num/secondsPerMinute > 0 {
+		time += strconv.Itoa(num/secondsPerMinute) + " 分钟 "
+		num %= secondsPerMinute
+	}
+	time += strconv.Itoa(num) + " 秒"
+	return
+}

backend/pkg/util/format_test.go

@@ -0,0 +1,52 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"testing"
+)
+
+func TestBytes2Size(t *testing.T) {
+	tests := []struct {
+		input    int64
+		expected string
+	}{
+		{0, "0 B"},
+		{500, "500 B"},
+		{1023, "1023 B"},
+		{1024, "1 KB"},
+		{2048, "2 KB"},
+		{1024 * 1024, "1 MB"},
+		{1024 * 1024 * 1024, "1.00 GB"},
+		{1024 * 1024 * 1024 * 2, "2.00 GB"},
+	}
+
+	for _, tt := range tests {
+		result := Bytes2Size(tt.input)
+		if result != tt.expected {
+			t.Errorf("Bytes2Size(%d) = %q, expected %q", tt.input, result, tt.expected)
+		}
+	}
+}
+
+func TestSeconds2Time(t *testing.T) {
+	tests := []struct {
+		input    int
+		expected string
+	}{
+		{0, "0 秒"},
+		{30, "30 秒"},
+		{60, "1 分钟 0 秒"},
+		{125, "2 分钟 5 秒"},
+		{3600, "1 小时 0 秒"},
+		{86400, "1 天 0 秒"},
+	}
+
+	for _, tt := range tests {
+		result := Seconds2Time(tt.input)
+		if result != tt.expected {
+			t.Errorf("Seconds2Time(%d) = %q, expected %q", tt.input, result, tt.expected)
+		}
+	}
+}

backend/pkg/util/goroutine.go

@@ -0,0 +1,31 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"log/slog"
+	"runtime"
+	"runtime/debug"
+)
+
+// Go runs fn in a new goroutine and recovers panics, so a background task
+// cannot crash the whole process. The panic is logged together with the
+// util.Go call site. Use it for every fire-and-forget / long-lived
+// background goroutine; HTTP handlers are already covered by gin.Recovery.
+func Go(fn func()) {
+	pc, file, line, _ := runtime.Caller(1)
+	go func() {
+		defer func() {
+			if r := recover(); r != nil {
+				slog.Error("panic recovered in background goroutine",
+					"caller", runtime.FuncForPC(pc).Name(),
+					"file", file,
+					"line", line,
+					"panic", r,
+					"stack", string(debug.Stack()))
+			}
+		}()
+		fn()
+	}()
+}

backend/pkg/util/goroutine_test.go

@@ -0,0 +1,38 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"sync"
+	"testing"
+)
+
+func TestGoRecoversPanic(t *testing.T) {
+	var wg sync.WaitGroup
+	wg.Add(1)
+
+	// Go should swallow the panic without crashing the test process
+	Go(func() {
+		defer wg.Done()
+		panic("boom")
+	})
+
+	wg.Wait()
+}
+
+func TestGoRunsNormally(t *testing.T) {
+	var wg sync.WaitGroup
+	wg.Add(1)
+	ran := false
+
+	Go(func() {
+		defer wg.Done()
+		ran = true
+	})
+
+	wg.Wait()
+	if !ran {
+		t.Fatal("expected fn to run")
+	}
+}

backend/pkg/util/http_clients.go

@@ -0,0 +1,66 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"Wavelet/pkg/httppool"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"time"
+)
+
+// IsLocalhost 检查 URL 是否为 localhost
+func IsLocalhost(urlStr string) bool {
+	u, err := url.Parse(urlStr)
+	if err != nil {
+		return false
+	}
+	hostname := u.Hostname()
+	return hostname == "localhost" || hostname == "127.0.0.1" || hostname == "::1"
+}
+
+// HTTP 客户端配置常量
+const (
+	httpClientTimeout       = 10 // HTTP 客户端超时时间（秒）
+	httpMaxIdleConns        = 100
+	httpMaxIdleConnsPerHost = 20
+	httpIdleConnTimeout     = 60 // 空闲连接超时（秒）
+)
+
+// 配置HTTP客户端 使用 otelhttp 自动注入 trace span
+var httpClient = &http.Client{
+	Timeout:   httpClientTimeout * time.Second,
+	Transport: httppool.DefaultTransport(),
+}
+
+// SetHTTPClient 替换全局 HTTP 客户端实例
+func SetHTTPClient(c *http.Client) {
+	httpClient = c
+}
+
+// Request 发送 HTTP 请求，支持自定义 Headers 和 Cookies
+func Request(ctx context.Context, method, url string, body io.Reader, headers, cookies map[string]string) (*http.Response, error) {
+	req, err := http.NewRequestWithContext(ctx, method, url, body)
+	if err != nil {
+		return nil, fmt.Errorf(errCreateHTTPRequestFailed, err)
+	}
+
+	for key, value := range cookies {
+		req.AddCookie(&http.Cookie{Name: key, Value: value}) //nolint:gosec // client-side cookies do not require server attributes (Secure/HttpOnly)
+	}
+
+	for key, value := range headers {
+		req.Header.Set(key, value)
+	}
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf(errHTTPRequestFailed, url, err)
+	}
+
+	return resp, nil
+}

backend/pkg/util/like.go

@@ -0,0 +1,16 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "strings"
+
+var likeEscaper = strings.NewReplacer(`\`, `\\`, `%`, `\%`, `_`, `\_`)
+
+// EscapeLike escapes SQL LIKE metacharacters (\, %, _) so a user-supplied
+// value matches literally in LIKE patterns. Pair it with an explicit
+// `ESCAPE '\'` clause where the dialect has no backslash default (SQLite);
+// PostgreSQL and ClickHouse treat backslash as the default LIKE escape.
+func EscapeLike(value string) string {
+	return likeEscaper.Replace(value)
+}

backend/pkg/util/like_test.go

@@ -0,0 +1,22 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "testing"
+
+func TestEscapeLike(t *testing.T) {
+	cases := map[string]string{
+		"":            "",
+		"/my_page":    `/my\_page`,
+		"100%":        `100\%`,
+		`a\b`:         `a\\b`,
+		`%_\`:         `\%\_\\`,
+		"normal/path": "normal/path",
+	}
+	for input, want := range cases {
+		if got := EscapeLike(input); got != want {
+			t.Errorf("EscapeLike(%q) = %q, want %q", input, got, want)
+		}
+	}
+}

backend/pkg/util/network.go

@@ -0,0 +1,45 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"log/slog"
+	"net"
+)
+
+// GetIP returns the first private IPv4 address found on the local network interfaces.
+func GetIP() (ip string) {
+	ips, err := net.InterfaceAddrs()
+	if err != nil {
+		slog.Error("get interface addresses failed", "error", err)
+		return ip
+	}
+
+	for _, a := range ips {
+		if candidate, ok := privateIPv4FromAddr(a); ok {
+			return candidate
+		}
+	}
+	return
+}
+
+func privateIPv4FromAddr(addr net.Addr) (string, bool) {
+	ipNet, ok := addr.(*net.IPNet)
+	if !ok || ipNet.IP.IsLoopback() || ipNet.IP.To4() == nil {
+		return "", false
+	}
+	ip := ipNet.IP.String()
+	if isPrivateIPv4(ip) {
+		return ip, true
+	}
+	return "", false
+}
+
+func isPrivateIPv4(ip string) bool {
+	parsedIP := net.ParseIP(ip)
+	if parsedIP == nil {
+		return false
+	}
+	return parsedIP.IsPrivate()
+}

backend/pkg/util/network_test.go

@@ -0,0 +1,36 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"testing"
+)
+
+func TestIsPrivateIPv4(t *testing.T) {
+	tests := []struct {
+		ip       string
+		expected bool
+	}{
+		{"127.0.0.1", false}, // Loopback is not in RFC 1918 private range
+		{"10.0.0.1", true},
+		{"172.16.0.1", true},
+		{"192.168.1.1", true},
+		{"8.8.8.8", false},
+		{"invalid-ip", false},
+	}
+
+	for _, tt := range tests {
+		result := isPrivateIPv4(tt.ip)
+		if result != tt.expected {
+			t.Errorf("isPrivateIPv4(%q) = %v, expected %v", tt.ip, result, tt.expected)
+		}
+	}
+}
+
+func TestGetIP(t *testing.T) {
+	ip := GetIP()
+	// GetIP should return empty if no private IPv4 address is configured, or a valid IP.
+	// We just ensure it doesn't panic.
+	t.Logf("GetIP returned: %q", ip)
+}

backend/pkg/util/password.go

@@ -0,0 +1,50 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"sync"
+
+	"golang.org/x/crypto/bcrypt"
+)
+
+// HashPassword 使用 bcrypt 对密码进行哈希处理
+func HashPassword(password string) (string, error) {
+	hash, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
+	if err != nil {
+		return "", err
+	}
+	return string(hash), nil
+}
+
+var (
+	dummyPasswordHashOnce sync.Once
+	dummyPasswordHash     string
+)
+
+func dummyHash() string {
+	dummyPasswordHashOnce.Do(func() {
+		hash, err := bcrypt.GenerateFromPassword([]byte("x"), bcrypt.DefaultCost)
+		if err != nil {
+			return
+		}
+		dummyPasswordHash = string(hash)
+	})
+	return dummyPasswordHash
+}
+
+// CheckPasswordHash 比较 bcrypt 哈希值与明文密码是否匹配
+func CheckPasswordHash(hash, password string) bool {
+	return bcrypt.CompareHashAndPassword([]byte(hash), []byte(password)) == nil
+}
+
+// DummyCheckPassword runs a bcrypt compare against a dummy hash so missing-user
+// login failures take a similar amount of time as a real password miss.
+func DummyCheckPassword(password string) {
+	hash := dummyHash()
+	if hash == "" {
+		return
+	}
+	_ = CheckPasswordHash(hash, password)
+}

backend/pkg/util/password_test.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "testing"
+
+func TestDummyCheckPasswordDoesNotPanic(t *testing.T) {
+	DummyCheckPassword("any-password")
+}
+
+func TestCheckPasswordHashRoundTrip(t *testing.T) {
+	hash, err := HashPassword("secret-pass")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !CheckPasswordHash(hash, "secret-pass") {
+		t.Fatal("expected matching password to succeed")
+	}
+	if CheckPasswordHash(hash, "other-pass") {
+		t.Fatal("expected mismatched password to fail")
+	}
+}

backend/pkg/util/slice.go

@@ -0,0 +1,79 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"sort"
+	"strings"
+	"time"
+)
+
+// Unique returns a new slice containing only the unique elements of the input slice,
+// preserving their original order.
+func Unique[T comparable](slice []T) []T {
+	if slice == nil {
+		return nil
+	}
+	seen := make(map[T]struct{})
+	result := make([]T, 0)
+	for _, item := range slice {
+		if _, ok := seen[item]; ok {
+			continue
+		}
+		seen[item] = struct{}{}
+		result = append(result, item)
+	}
+	return result
+}
+
+// UniqueAndCleanStringSlice trims spaces, removes empty elements, and returns only the unique elements
+// of the input string slice. It preserves order and returns nil if the resulting slice is empty.
+func UniqueAndCleanStringSlice(slice []string) []string {
+	if slice == nil {
+		return nil
+	}
+	seen := make(map[string]struct{})
+	result := make([]string, 0)
+	for _, item := range slice {
+		trimmed := strings.TrimSpace(item)
+		if trimmed == "" {
+			continue
+		}
+		if _, ok := seen[trimmed]; ok {
+			continue
+		}
+		seen[trimmed] = struct{}{}
+		result = append(result, trimmed)
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+// IdentifiableTimeRecord represents a database record that has a unique ID and a primary timestamp field.
+type IdentifiableTimeRecord interface {
+	GetID() uint
+	GetTime() time.Time
+}
+
+// SortAndLimitRecords sorts a slice of IdentifiableTimeRecord descendingly by their timestamp (and ID as a tie-breaker),
+// and limits the slice to the specified size if limit > 0.
+func SortAndLimitRecords[T IdentifiableTimeRecord](rows []T, limit int) []T {
+	if len(rows) == 0 {
+		return rows
+	}
+	sort.Slice(rows, func(i, j int) bool {
+		ti := rows[i].GetTime()
+		tj := rows[j].GetTime()
+		if ti.Equal(tj) {
+			return rows[i].GetID() > rows[j].GetID()
+		}
+		return ti.After(tj)
+	})
+	if limit > 0 && len(rows) > limit {
+		rows = rows[:limit]
+	}
+	return rows
+}

backend/pkg/util/string.go

@@ -0,0 +1,15 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "strings"
+
+// TrimStringFields trims leading and trailing spaces from all provided string pointers.
+func TrimStringFields(fields ...*string) {
+	for _, f := range fields {
+		if f != nil {
+			*f = strings.TrimSpace(*f)
+		}
+	}
+}

backend/pkg/util/strings.go

@@ -0,0 +1,34 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "strings"
+
+// emailPartsCount 邮箱地址由 @ 分割为两部分
+const (
+	emailPartsCount    = 2
+	emailLocalMinChars = 2 // 邮箱 local 部分掩码显示的最小字符数
+)
+
+// DerefString 安全地解引用字符串指针，nil 返回空字符串
+func DerefString(s *string) string {
+	if s == nil {
+		return ""
+	}
+	return *s
+}
+
+// MaskEmail 安全脱敏用户的邮箱地址（例如 us***@example.com）
+func MaskEmail(email string) string {
+	parts := strings.Split(email, "@")
+	if len(parts) != emailPartsCount {
+		return email
+	}
+	local := parts[0]
+	domain := parts[1]
+	if len(local) <= emailLocalMinChars {
+		return "**@" + domain
+	}
+	return local[:2] + "***" + local[len(local)-1:] + "@" + domain
+}

backend/pkg/util/uuid.go

@@ -0,0 +1,28 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+
+	"github.com/google/uuid"
+)
+
+// uniqueIDBytes 生成唯一 ID 所需的随机字节长度
+const uniqueIDBytes = 32
+
+// GenerateUniqueIDSimple 生成 64 位唯一标识符
+func GenerateUniqueIDSimple() string {
+	randomBytes := make([]byte, uniqueIDBytes)
+	if _, err := io.ReadFull(rand.Reader, randomBytes); err != nil {
+		// 如果随机数生成失败，使用 UUID 作为后备
+		uuidBytes := []byte(uuid.NewString())
+		hash := sha256.Sum256(uuidBytes)
+		copy(randomBytes, hash[:])
+	}
+	return hex.EncodeToString(randomBytes)
+}

backend/pkg/util/value.go

@@ -0,0 +1,22 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"fmt"
+	"strconv"
+)
+
+// Interface2String converts a string, int, or float64 value to its string representation.
+func Interface2String(inter any) string {
+	switch v := inter.(type) {
+	case string:
+		return v
+	case int:
+		return strconv.Itoa(v)
+	case float64:
+		return fmt.Sprintf("%f", v)
+	}
+	return "Not Implemented"
+}

backend/pkg/util/version.go

@@ -0,0 +1,129 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import (
+	"strconv"
+	"strings"
+)
+
+const gitDescribeMinIdentifiers = 2
+
+// VersionInfo holds the parsed components of a semantic version string.
+type VersionInfo struct {
+	Valid               bool
+	IsDev               bool
+	Numbers             []int
+	Prerelease          []string
+	GitDescribeDistance int
+	GitDescribeTail     []string
+}
+
+// ParseVersionInfo parses a version string into a structured VersionInfo.
+func ParseVersionInfo(version string) VersionInfo {
+	normalized := strings.TrimSpace(strings.TrimPrefix(version, "v"))
+	if normalized == "" || normalized == "dev" {
+		return VersionInfo{IsDev: strings.EqualFold(normalized, "dev")}
+	}
+	base := normalized
+	prerelease := ""
+	if separator := strings.IndexRune(normalized, '-'); separator >= 0 {
+		base = normalized[:separator]
+		prerelease = normalized[separator+1:]
+	}
+
+	segments := strings.Split(base, ".")
+	parts := make([]int, 0, len(segments))
+	for _, segment := range segments {
+		segment = strings.TrimSpace(segment)
+		if segment == "" {
+			parts = append(parts, 0)
+			continue
+		}
+
+		numeric := strings.Builder{}
+		for _, r := range segment {
+			if r < '0' || r > '9' {
+				break
+			}
+			numeric.WriteRune(r)
+		}
+		if numeric.Len() == 0 {
+			parts = append(parts, 0)
+			continue
+		}
+		value, err := strconv.Atoi(numeric.String())
+		if err != nil {
+			return VersionInfo{}
+		}
+		parts = append(parts, value)
+	}
+	info := VersionInfo{Valid: len(parts) > 0, Numbers: parts}
+	if prerelease != "" {
+		identifiers := splitPrereleaseIdentifiers(prerelease)
+		if distance, tail, ok := parseGitDescribeIdentifiers(identifiers); ok {
+			info.GitDescribeDistance = distance
+			info.GitDescribeTail = tail
+		} else {
+			info.Prerelease = identifiers
+		}
+	}
+	return info
+}
+
+func parseGitDescribeIdentifiers(identifiers []string) (int, []string, bool) {
+	if len(identifiers) < gitDescribeMinIdentifiers {
+		return 0, nil, false
+	}
+	distance, err := strconv.Atoi(strings.TrimSpace(identifiers[0]))
+	if err != nil || distance <= 0 {
+		return 0, nil, false
+	}
+	commitToken := strings.TrimSpace(identifiers[1])
+	if commitToken == "" || !strings.HasPrefix(strings.ToLower(commitToken), "g") {
+		return 0, nil, false
+	}
+	return distance, identifiers[1:], true
+}
+
+func splitPrereleaseIdentifiers(value string) []string {
+	parts := strings.FieldsFunc(strings.TrimSpace(value), func(r rune) bool {
+		return r == '.' || r == '-'
+	})
+	filtered := make([]string, 0, len(parts))
+	for _, part := range parts {
+		part = strings.TrimSpace(part)
+		if part != "" {
+			filtered = append(filtered, part)
+		}
+	}
+	return filtered
+}
+
+// CompareVersions compares two version strings.
+// Returns -1 if left < right, 1 if left > right, and 0 if they are equal.
+func CompareVersions(local, remote string) int {
+	left := ParseVersionInfo(local)
+	right := ParseVersionInfo(remote)
+	if left.IsDev {
+		if right.Valid {
+			return -1
+		}
+		return 0
+	}
+	if !left.Valid || !right.Valid {
+		return 0
+	}
+
+	if result := compareVersionNumbers(left, right); result != 0 {
+		return result
+	}
+	if result := compareGitDescribeDistance(left, right); result != 0 {
+		return result
+	}
+	if left.GitDescribeDistance > 0 || right.GitDescribeDistance > 0 {
+		return compareGitDescribeTails(left, right)
+	}
+	return comparePrereleaseIdentifiers(left, right)
+}

backend/pkg/util/version_compare.go

@@ -0,0 +1,108 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package util
+
+import "strconv"
+
+func compareVersionNumbers(left, right VersionInfo) int {
+	maxLen := max(len(right.Numbers), len(left.Numbers))
+	for index := range maxLen {
+		leftValue := 0
+		rightValue := 0
+		if index < len(left.Numbers) {
+			leftValue = left.Numbers[index]
+		}
+		if index < len(right.Numbers) {
+			rightValue = right.Numbers[index]
+		}
+		if leftValue < rightValue {
+			return -1
+		}
+		if leftValue > rightValue {
+			return 1
+		}
+	}
+	return 0
+}
+
+func compareGitDescribeDistance(left, right VersionInfo) int {
+	if left.GitDescribeDistance == right.GitDescribeDistance {
+		return 0
+	}
+	if left.GitDescribeDistance < right.GitDescribeDistance {
+		return -1
+	}
+	return 1
+}
+
+func compareGitDescribeTails(left, right VersionInfo) int {
+	maxLen := max(len(right.GitDescribeTail), len(left.GitDescribeTail))
+	for index := range maxLen {
+		if index >= len(left.GitDescribeTail) {
+			return -1
+		}
+		if index >= len(right.GitDescribeTail) {
+			return 1
+		}
+		if left.GitDescribeTail[index] < right.GitDescribeTail[index] {
+			return -1
+		}
+		if left.GitDescribeTail[index] > right.GitDescribeTail[index] {
+			return 1
+		}
+	}
+	return 0
+}
+
+func comparePrereleaseIdentifiers(left, right VersionInfo) int {
+	if len(left.Prerelease) == 0 && len(right.Prerelease) == 0 {
+		return 0
+	}
+	if len(left.Prerelease) == 0 {
+		return 1
+	}
+	if len(right.Prerelease) == 0 {
+		return -1
+	}
+
+	maxLen := max(len(right.Prerelease), len(left.Prerelease))
+	for index := range maxLen {
+		if index >= len(left.Prerelease) {
+			return -1
+		}
+		if index >= len(right.Prerelease) {
+			return 1
+		}
+		if result := comparePrereleasePart(left.Prerelease[index], right.Prerelease[index]); result != 0 {
+			return result
+		}
+	}
+	return 0
+}
+
+func comparePrereleasePart(leftPart, rightPart string) int {
+	leftNumber, leftErr := strconv.Atoi(leftPart)
+	rightNumber, rightErr := strconv.Atoi(rightPart)
+	switch {
+	case leftErr == nil && rightErr == nil:
+		if leftNumber < rightNumber {
+			return -1
+		}
+		if leftNumber > rightNumber {
+			return 1
+		}
+	case leftErr == nil:
+		return -1
+	case rightErr == nil:
+		return 1
+	default:
+		if leftPart < rightPart {
+			return -1
+		}
+		if leftPart > rightPart {
+			return 1
+		}
+	}
+	return 0
+}