Ember Moth Hexo https://www.embermoth.blog/ All rights reserved 2026, Ember Moth 为世界上所有的美好而战! Ember Moth's Blog 2026-05-21T06:15:00.000Z Ember Moth

TL;DR — 这次迁移不是“把 import 从 gin 改成 hertz”这么简单，而是一次分层完成的渐进式重构：先抽离 transport 层，再做 Gin 兼容层，最后把热点路由和关键中间件原生化到 Hertz。中间我们甚至短暂用 Fiber 验证过 fallback 方案。最重要的收获不是“换了框架”，而是沉淀出一套对存量 Go 服务可复制的迁移方法。

一、为什么我们决定从 Gin 迁到 Hertz

gin 是一个非常成熟的框架，ppanel-server 早期能快速迭代，离不开它带来的开发效率。

迁移的原因并不是因为 Gin “不够好”，而是随着项目变大，我们开始更在意几个问题：

  1. HTTP 传输层还有没有进一步压榨性能和分配开销的空间？
  2. 热点路由能不能更直接地贴近底层请求模型，而不是永远挂在一层通用适配之上？
  3. 如果以后要继续演进网络层，中间件和 handler 能不能不要再和具体框架强耦合？
  4. 能不能在不阻塞正常开发的情况下完成迁移？

在旧实现里，HTTP 启动逻辑是标准的 Gin 形态：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
func New(svc *svc.ServiceContext) *gin.Engine {
    initialize.StartInitSystemConfig(svc)

    r := gin.Default()
    r.RemoteIPHeaders = []string{"X-Original-Forwarded-For", "X-Forwarded-For", "X-Real-IP"}

    sessionStore, err := redis.NewStore(...)
    if err != nil {
        panic(err)
    }

    r.Use(sessions.Sessions("ppanel", sessionStore))
    r.Use(middleware.TraceMiddleware(svc), middleware.LoggerMiddleware(svc), middleware.CorsMiddleware, gin.Recovery())

    handler.RegisterHandlers(r, svc)
    handler.RegisterSubscribeHandlers(r, svc)
    handler.RegisterTelegramHandlers(r, svc)
    handler.RegisterNotifyHandlers(r, svc)
    return r
}

这段代码本身没有问题，但它暴露了一个事实：

路由注册、中间件、Request/Response 语义、框架默认行为，全部绑在了 Gin 上。

这意味着一旦要迁移，就不只是“换个 router”那么简单，而是要同时面对：

  • Context 语义迁移
  • ShouldBind / ShouldBindQuery / ShouldBindUri 行为迁移
  • 中间件签名迁移
  • http.Request / http.ResponseWriter 兼容问题
  • ClientIP、Recovery、Header 写回等细节差异

所以我们一开始就没有把这次工作定义成“框架替换”，而是定义成：

一次围绕 transport 层解耦的渐进式重构。

二、迁移前先定原则：不是重写，而是渐进替换

在真正动手前，我们先定了几条硬约束。

1）业务逻辑层尽量不动

logic、svc、repository 这些层不应该感知 Gin 还是 Hertz。
变化应该尽量收敛在 transport 层和最外面的 handler 层。

2）允许新旧路由共存

我们不接受“一天之内把几百个 handler 全改成 Hertz 原生”的方案。
迁移必须允许：

  • 一部分路由继续走旧语义
  • 一部分路由已经切到原生 Hertz
  • 两者可以长期共存一段时间

3）中间件迁移要和 handler 迁移解耦

在存量项目里，中间件通常比 handler 更麻烦。

像这些逻辑都深度依赖框架上下文：

  • 鉴权
  • 设备加解密
  • Trace
  • Logger
  • CORS
  • Notify 校验

如果把中间件和 handler 绑成一个迁移批次，风险会非常高。
所以我们选择：

  • 先让老中间件继续跑
  • 再逐步把高价值中间件原生化到 Hertz

4）迁移过程必须可回退

只要迁移路径不可回退，它就一定会拖慢团队节奏。
我们需要的不是“最优雅的理论方案”，而是对线上系统最安全的工程方案。

三、迁移不是一跳完成的：我们甚至短暂经过了 Fiber

这次迁移的 commit 时间线，真实地反映了我们的思考过程：

阶段提交目标
19e61fc8重构 Gin server 初始化
2666f561增加 Fiber transport 骨架
36fc3274给 Fiber 增加 Gin fallback
4662d269用 Hertz 替换 Fiber transport
5adda20b批量把 Gin handlers 迁到 Hertz 兼容层
61c2f889把热点路由切到原生 Hertz
75e60172把关键中间件改成原生 Hertz 中间件

很多人看到这里会疑惑：

不是写 Gin 到 Hertz 的迁移吗，为什么中间会出现 Fiber？

答案很简单：

我们先验证的是“迁移策略”，不是“框架喜好”。

在早期阶段，我们更关心的是：

  • 能不能把 transport 层独立出来？
  • 能不能让新 transport 承接一部分路由？
  • 能不能让其余路由继续 fallback 到旧栈？

Fiber 在这里扮演的角色，其实更像是一个“迁移策略验证器”。
等这条路径走通后，我们再把底层 transport 实现换成真正要落地的 Hertz。

这一步的价值非常大，因为它证明了一件事：

迁移的关键，不是先选新框架，而是先证明系统允许你渐进替换。

四、第一步：先把 transport 层从业务里抽出来

我们先做的不是改 handler，而是改启动方式。

在 internal/server.go 里，我们把 HTTP 启动抽象成了一个很薄的 transportServer 接口：

1
2
3
4
type transportServer interface {
    Start()
    Shutdown(ctx context.Context) error
}

然后由 newTransportServer 决定底层到底实例化哪个实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
func newTransportServer(svc *svc.ServiceContext, addr string) transportServer {
    var tlsConfig *tls.Config
    if svc.Config.TLS.Enable {
        cert, err := tls.LoadX509KeyPair(svc.Config.TLS.CertFile, svc.Config.TLS.KeyFile)
        if err != nil {
            logger.Errorf("load tls certificate error: %s", err.Error())
            return nil
        }
        tlsConfig = &tls.Config{
            MinVersion:   tls.VersionTLS12,
            Certificates: []tls.Certificate{cert},
        }
    }
    return httpserver.New(svc, addr, tlsConfig)
}

这个改动的意义非常大：

  • Service.Start() 不再关心 Gin / Fiber / Hertz
  • 启停、重启、TLS、trace agent 生命周期仍然保持一致
  • transport 层从“嵌在业务启动里”变成了“可替换实现”

很多迁移项目失败，是因为一上来就碰路由和业务。
我们这次先做这一步，本质上是在给后面所有迁移动作打地基。

五、第二步：不要急着重写 handler，先做一个兼容层

真正让迁移速度提起来的，不是 Hertz 本身，而是我们写的 pkg/hertzx。

这个包的目标很明确：

让大部分原来依赖 Gin 语义的代码，在最小改动下先跑起来。

它没有试图完整“复刻一个 Gin”，而是只兼容项目里真正用到的那一小部分能力：

  • Context
  • HandlerFunc
  • Engine / RouterGroup
  • Wrap()
  • ShouldBind() / ShouldBindJSON() / ShouldBindQuery() / ShouldBindUri()
  • JSON() / String() / Redirect() / Header()
  • Abort() / Next()
  • http.Request / http.ResponseWriter 兼容桥接

核心入口大概长这样：

1
2
3
4
5
6
7
8
9
type HandlerFunc func(*Context)

func Wrap(handler HandlerFunc) app.HandlerFunc {
    return func(base context.Context, ctx *app.RequestContext) {
        c := NewContext(base, ctx)
        handler(c)
        c.flush()
    }
}

这里最关键的是 NewContext()。它做了两件事：

  1. 把 Hertz 的 RequestContext 包成一个我们熟悉的 *Context
  2. 构造一个兼容逻辑层的 *http.Request
1
2
3
4
5
6
7
8
9
10
11
func NewContext(base context.Context, ctx *app.RequestContext) *Context {
    c := &Context{
        base:    base,
        ctx:     ctx,
        Request: compatRequest(base, ctx),
        Writer:  newResponseWriter(ctx),
        keys:    make(map[string]interface{}),
    }
    ctx.Set(contextKey, c)
    return c
}

这层兼容的直接收益是：

  • 大量 handler 可以继续保留原来的调用形态
  • handler.RegisterHandlers(engine, svc) 这样的 generated route 注册代码几乎不用推倒重来
  • 老中间件还能继续以 func(c *hertzx.Context) 的方式运行

这让我们避免了最危险的一件事：

在路由切换的同时，重写整个 handler 语义。

六、第三步：把批量迁移的 handler 先挂到兼容层上

有了 hertzx.Engine 和 hertzx.RouterGroup 之后，大部分原来面向 Gin 的 handler 注册代码可以整体平移。

比如现在的注册方式仍然保持原来的组织结构：

1
2
3
handler.RegisterHandlers(engine, svc)
handler.RegisterTelegramHandlers(engine, svc)
handler.RegisterNotifyHandlers(engine, svc)

这里的 engine 不是 Gin 的 *gin.Engine，而是我们封装过的 *hertzx.Engine。
它对外暴露的 Group、GET、POST、Use 接口，都尽量保持了原有使用习惯。

这一步的价值不是“优雅”，而是“低风险”：

  • route 文件不需要全改
  • handler 文件不需要当天全改
  • 中间件的演进顺序可以独立安排

也正因为这样，我们才能把迁移拆成多个 commit，持续推进，而不是开一个长寿命分支大爆炸合并。

七、第四步：热点路由优先原生化到 Hertz

兼容层只是桥，不是终点。

真正对性能和协议细节最敏感的路径，最终还是要回到 Hertz 原生接口上。
所以接下来我们专门引入了 RegisterNativeHandlers()：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
func RegisterNativeHandlers(router *server.Hertz, serverCtx *svc.ServiceContext) {
    subscribePath := serverCtx.Config.Subscribe.SubscribePath
    if subscribePath == "" {
        subscribePath = "/v1/subscribe/config"
    }
    router.GET(subscribePath, SubscribeHandler(serverCtx))
    if serverCtx.Config.Subscribe.PanDomain {
        router.GET("/", PanDomainSubscribeHandler(serverCtx))
    }

    serverGroup := router.Group("/v1/server", serverHandler.ServerMiddleware(serverCtx))
    serverGroup.GET("/config", serverHandler.GetServerConfigHandler(serverCtx))
    serverGroup.POST("/online", serverHandler.PushOnlineUsersHandler(serverCtx))
    serverGroup.POST("/push", serverHandler.ServerPushUserTrafficHandler(serverCtx))
    serverGroup.POST("/status", serverHandler.ServerPushStatusHandler(serverCtx))
    serverGroup.GET("/user", serverHandler.GetServerUserListHandler(serverCtx))

    router.GET("/v2/server/:server_id", serverHandler.QueryServerProtocolConfigHandler(serverCtx))
}

我们优先迁到原生 Hertz 的，是两类接口：

1）订阅类接口

订阅路径通常访问频率高、对 header / query / body / user-agent 很敏感，而且很多时候返回的不是标准 JSON，而是配置文本。

SubscribeHandler 迁到原生 Hertz 后，可以直接从 RequestContext 构造请求对象：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
func SubscribeHandler(svcCtx *svc.ServiceContext) app.HandlerFunc {
    return func(c context.Context, ctx *app.RequestContext) {
        req := types.SubscribeRequest{
            Token:  string(ctx.GetHeader("token")),
            UA:     string(ctx.UserAgent()),
            Flag:   ctx.Query("flag"),
            Type:   ctx.Query("type"),
            Params: getQueryMap(ctx),
        }
        if req.Token == "" {
            req.Token = ctx.Query("token")
        }
        writeSubscribeResponse(c, ctx, svcCtx, req)
    }
}

这类代码用原生 Hertz 写起来更直接，也更容易看清楚请求模型到底是什么。

2）节点 / Server 上报接口

像这些路径：

  • /v1/server/config
  • /v1/server/user
  • /v1/server/online
  • /v1/server/push
  • /v1/server/status
  • /v2/server/:server_id

本身就更偏“协议接口”，请求模型清晰，错误码和 header 行为也很明确。

我们把公共解析逻辑也顺手抽了出来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
func ServerMiddleware(svcCtx *svc.ServiceContext) app.HandlerFunc {
    return func(c context.Context, ctx *app.RequestContext) {
        key, ok := ctx.GetQuery("secret_key")
        if ok && key == svcCtx.Config.Node.NodeSecret {
            ctx.Next(c)
            return
        }
        ctx.String(consts.StatusForbidden, "Forbidden")
        ctx.Abort()
    }
}

func serverCommonRequest(ctx *app.RequestContext) (types.ServerCommon, error) {
    var serverID int64
    if rawServerID := ctx.Query("server_id"); rawServerID != "" {
        id, err := strconv.ParseInt(rawServerID, 10, 64)
        if err != nil {
            return types.ServerCommon{}, err
        }
        serverID = id
    }
    return types.ServerCommon{
        Protocol:  ctx.Query("protocol"),
        ServerId:  serverID,
        SecretKey: ctx.Query("secret_key"),
    }, nil
}

这一步有两个非常直接的收益：

  • 减少 compat 层的额外跳转开销
  • 让协议细节变得明确，不再埋在一层通用适配里

八、第五步：中间件原生化，兼容层只留给真正需要的地方

最后一层优化，是中间件。

在最终形态里，HTTP server 的核心初始化已经直接挂载原生 Hertz 中间件：

1
2
3
4
5
6
7
8
9
10
func newServer(svc *svc.ServiceContext, opts []config.Option) *Server {
    engine := hertzx.Default(opts...)
    engine.Hertz().Use(middleware.TraceMiddleware(svc), middleware.LoggerMiddleware(svc), middleware.CorsMiddleware)

    handler.RegisterNativeHandlers(engine.Hertz(), svc)
    handler.RegisterHandlers(engine, svc)
    handler.RegisterTelegramHandlers(engine, svc)
    handler.RegisterNotifyHandlers(engine, svc)
    return &Server{h: engine.Hertz()}
}

这里有一个非常重要的策略选择：

不是所有中间件都要在同一天原生化。

我们优先原生化的是：

  • TraceMiddleware
  • LoggerMiddleware
  • CorsMiddleware

原因很简单：

  • 它们是全局中间件
  • 会作用到每一个请求
  • 原生化收益最大
  • 行为最值得统一到 Hertz 模型里

例如 TraceMiddleware 直接使用 app.RequestContext 采集 OpenTelemetry 所需字段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
func TraceMiddleware(_ *svc.ServiceContext) app.HandlerFunc {
    return func(c context.Context, ctx *app.RequestContext) {
        tracer := trace.TracerFromContext(c)
        spanName := ctx.FullPath()
        method := string(ctx.Method())

        c, span := tracer.Start(
            c,
            fmt.Sprintf("%s %s", method, spanName),
            oteltrace.WithSpanKind(oteltrace.SpanKindServer),
        )
        defer span.End()

        requestId := trace.TraceIDFromContext(c)
        ctx.Header(trace.RequestIdKey, requestId)
        ctx.Next(c)
    }
}

LoggerMiddleware 也同样直接从 Hertz 的 request/response 结构里取信息，并对节点 telemetry 路径做了专门裁剪，避免把大 body 全量打进日志。

而像 AuthMiddleware、DeviceMiddleware 这类更依赖历史 Context 语义的中间件，则继续先挂在 compat 层上。这样迁移风险最低。

这也是我们这次迁移中反复验证的一条经验：

迁移顺序应该由“风险”和“收益”共同决定，而不是按文件顺序决定。

九、迁移中最值得记录的几个坑

如果只写“迁移完成、效果很好”，这篇文章就没价值了。

真正有价值的部分，恰恰是那些在存量系统里一定会踩到的坑。

坑 1：兼容的不是 API，而是语义

ShouldBind() 看起来只是一个函数名兼容，但真正麻烦的是：

  • query 从哪里取
  • body 什么时候被读掉
  • form / json / uri 的优先级是什么
  • 下游看到的是 Hertz request，还是兼容出来的 *http.Request

在 hertzx.Context 里，我们最终做的是一层“项目足够用”的绑定适配：

1
2
3
4
5
6
7
8
9
10
11
12
func (c *Context) ShouldBind(obj interface{}) error {
    if isJSONRequest(c.Request) {
        return c.ShouldBindJSON(obj)
    }
    if err := bindValues(obj, c.Request.URL.Query()); err != nil {
        return err
    }
    if len(c.ctx.Request.Body()) == 0 {
        return nil
    }
    return c.ctx.Bind(obj)
}

注意这里不是“1:1 复刻 Gin”，而是针对项目当前真实用法做兼容。
这点非常关键。

坑 2：请求被改写后，要同步回 Hertz 本体

设备加解密中间件是这次迁移里最典型的案例。

它会在请求进入业务前解密 query/body，然后把解密后的内容重新塞回请求对象。
如果你只改了兼容出来的 *http.Request，但没有同步回 Hertz 原生 request，那么后面的 binder 和 native handler 看到的仍然是旧数据。

所以我们专门补了两个同步函数：

1
2
hertzx.SyncRequestURI(c)
hertzx.SyncRequestBody(c)

这类问题在迁移前很难凭空想到，只有在“兼容层 + 原生层并存”的阶段才会暴露出来。

坑 3：Client IP 语义不是默认一致的

旧 Gin 初始化里我们显式配置过：

1
r.RemoteIPHeaders = []string{"X-Original-Forwarded-For", "X-Forwarded-For", "X-Real-IP"}

而 Hertz 默认关注的是 X-Forwarded-For 和 X-Real-IP。
如果你的反向代理链路里用到了 X-Original-Forwarded-For，迁移后一定要重新检查 ClientIP() 的语义，否则日志、风控、审计链路都可能出现偏差。

这个问题很隐蔽，因为本地调试通常看不出来，只有挂到真实代理链路上才会暴露。

坑 4：最容易出问题的是 Header 写回

兼容层里最危险的一类 bug，通常不是业务逻辑 bug，而是协议层 bug。

比如：

  • Header 重复追加
  • Location 重复
  • ETag 行为异常
  • 自定义 header 被覆盖或多写

原因通常是：

  • 一部分 header 写到了兼容 ResponseWriter
  • 一部分 header 又直接写到了 Hertz 原生 response
  • 最后 flush 时如果再统一回写一次，而且是 Add 而不是 Set，就可能把同一个 header 重复追加

这类问题在普通“返回 200 就算通过”的测试里很难暴露，
但在 redirect、subscription-userinfo、ETag 这类协议头上会非常明显。

这也是我对兼容层最大的一个体会：

兼容层的复杂度不在于“能不能跑”，而在于“协议语义会不会悄悄漂移”。

十、迁移完成后，我们怎么验证它是安全的

很多迁移项目的问题是：

  • 编译过了
  • 几个页面点通了
  • 就默认迁移成功

但 HTTP 框架迁移真正容易出问题的，是那些“肉眼不一定看得出来”的协议细节。

所以这次我们专门补了 transport 层测试。

例如 internal/transport/httpserver/server_test.go 里就覆盖了这些场景：

1
2
3
4
5
6
7
8
9
10
func TestServerSecretMiddlewareBlocksMigratedPost(t *testing.T) {
    app := newTestServer("secret")
    status, body := performNativeRequest(app, http.MethodPost, "/v1/server/online?secret_key=wrong")
    if status != http.StatusForbidden {
        t.Fatalf("expected status %d, got %d", http.StatusForbidden, status)
    }
    if body != "Forbidden" {
        t.Fatalf("expected forbidden body, got %q", body)
    }
}

以及：

  • server_id 非法时返回 400
  • secret key 错误时返回 401/403
  • CORS 预检请求要能绕过 server secret 校验
1
2
3
4
5
6
7
8
9
10
11
12
13
func TestCorsPreflightBypassesServerSecretMiddleware(t *testing.T) {
    app := newTestServer("secret")

    ctx := app.Engine().NewContext()
    ctx.Request.SetRequestURI("/v1/server/online")
    ctx.Request.Header.SetMethod(http.MethodOptions)
    ctx.Request.Header.Set("Origin", "https://example.com")
    app.Engine().ServeHTTP(context.Background(), ctx)

    if status := ctx.Response.StatusCode(); status != http.StatusNoContent {
        t.Fatalf("expected status %d, got %d", http.StatusNoContent, status)
    }
}

除了测试，我们还加了 benchmark 和 CI workflow：

  • scripts/perf/bench.sh
  • .github/workflows/performance.yml

benchmark 直接跑 ./internal/transport/httpserver：

1
2
3
4
go test ./internal/transport/httpserver \
  -run '^$' \
  -bench '^BenchmarkHTTPServer' \
  -benchmem

这样迁移就不再只是“感觉上更快”，而是有持续可比较的数据基线。

十一、这次迁移里最有价值的，不是换成了 Hertz

如果只从结果看，这次迁移确实是“Gin -> Hertz”。

但如果从工程角度看，真正有价值的东西其实是下面这几条：

1）先抽 transport，再换引擎

没有这一层抽象，后面的所有迁移都会互相缠绕。

2）兼容层不是终点，是桥梁

hertzx 的意义不是永远存在，而是让我们能安全跨过去。

3）热点路径优先原生化

真正值得原生化的，不是“最容易改的路由”，而是：

  • 请求量高
  • 协议敏感
  • compat 成本高
  • 性能收益明显

4）中间件可以独立演进

没必要把 handler 和 middleware 绑在一个迁移批次里。

5）协议级测试比页面回归更重要

HTTP 框架迁移最可怕的往往不是业务错误，而是 header、status、body、redirect 语义漂移。

十二、如果让我再重来一次，我会更早做这三件事

1）更早补协议一致性测试

尤其是这些：

  • redirect
  • custom header
  • CORS preflight
  • ETag / 304
  • Client IP

这些测试写得越早，后面的兼容层越不容易悄悄长歪。

2）更早明确 compat 层边界

哪些 API 兼容，哪些不兼容，最好一开始就说清楚。
不然 compat 层会不断“长功能”，最后变成另一个小框架。

3）更早把高频路径切到原生 Hertz

compat 层非常适合兜底，但它不适合永久承载热点流量。

结语

这次迁移让我最大的一个感受是：

存量系统的框架迁移，核心问题从来不是“新框架香不香”，而是“我们有没有能力把变化控制在正确的边界里”。

从 Gin 迁到 Hertz，本质上不是一次“技术栈翻新”，而是一次面向长期演进能力的重构。

它让我们把 transport、handler、中间件、协议语义重新梳理了一遍；
也让我们以后再做网络层优化时，不需要再从一团耦合代码里硬拆。

如果你面对的也是一个已经在线上跑了很久的 Go 服务，我会非常建议你记住一句话：

不要试图一口气迁完所有东西。先让系统支持渐进迁移，然后再一点点替换。

这是这次 Gin -> Hertz 迁移里，我们验证过最有效的路线。

]]> https://www.embermoth.blog/2026/05/21/ppanel-gin-to-hertz-migration/ 2026-05-21T06:15:00.000Z

TL;DR — 这次迁移不是“把 import 从 gin 改成 hertz”这么简单，而是一次分层完成的渐进式重构：先抽离 transport 层，再做 Gin 兼容层，最后把热点路由和关键中间件原生化到 Hertz。中间我们甚至短暂用 Fiber 验证过 fallback 方案。最重要的收获不是“换了框架”，而是沉淀出一套对存量 Go 服务可复制的迁移方法。

]]> 从 Gin 迁移到 Hertz：一次渐进式重构实战 2026-05-21T06:15:00.000Z Ember Moth

TL;DR — 为已有项目新增第二种数据库支持，工作量远大于”加个驱动依赖”。
本文记录 ppanel-server 从 MySQL-only 到同时支持 MySQL + PostgreSQL 的完整改造：重构配置抽象层、拆分两套迁移 DDL、修复 model 层 20+ 个 MySQL 专属写法、顺带优化搜索索引。
涉及 2 个 PR、6 次提交、约 40 个文件改动。最有价值的发现是：引入异构数据库测试，意外暴露了一个 MySQL 下潜伏了半年的隐性 bug。

一、故事的起点

事情始于社群里一条不算特别紧迫的请求——“能支持 PostgreSQL 吗？”

这不是第一次有人提了。ppanel-server 的社群中，PostgreSQL 支持的呼声断断续续出现了好几次。有人在用托管 PostgreSQL（Supabase、Neon、RDS for PostgreSQL），有人的服务器上已经跑着 PostgreSQL 实例，不想为 ppanel 再单独维护一套 MySQL。这些声音一直挂着，没人真的动手做。

我其实一直知道这件事早晚要面对。所以某天我下定决心后，先做了一件事——走进代码，看看如果要加 PostgreSQL，到底要动多少东西。

结果比我预想的要深得多。

配置结构体直接叫 MySQL，初始化向导的路由叫 /init/mysql/test，迁移 SQL 全是 MySQL 方言，model 层散落着 FIND_IN_SET 和各种 MySQL 专属写法。不是一两个地方的问题——是整个数据层被 MySQL 渗透透了。

最麻烦的地方在于：很多 MySQL 专属写法是隐形的。FIND_IN_SET 可以用 grep 搜出来，但隐式类型转换、保留字裸写、MySQL 独有的 SQL 方言散落在 GORM 的查询字符串里，静态分析根本抓不全。这意味着即使我把抽象层和迁移层改好了，PostgreSQL 能不能真正跑起来，只有跑起来才知道。

我决定认真做一次，不打补丁。不是”加个 driver import 再修几个报错”，而是从架构层面让 ppanel-server 真正支持两种数据库。

后来的故事证明，这个判断是对的——这项工作最终拆成了两个 PR：#130 负责基础设施（抽象层、配置层、迁移层），#133 专门修 model 层在 PostgreSQL 下的兼容性问题。

二、摸清现状：MySQL 假设渗透到了哪里

动手之前，我先做了一次全面的代码审计。MySQL 的假设一共渗透了四个层面。

配置层

config.Config 里一个 MySQL orm.Config 字段，整个程序读配置、存配置、校验配置都直接操作它：

1
2
3
4
5
if startConfigPath != "etc/ppanel.yaml" && c.MySQL.Addr == "" {
    return true
}
// ...
c.MySQL = *cfg

如果要支持第二种数据库，”加一个 PostgreSQL 字段”是最直接的做法，但也是最难维护的——调用方代码里会到处出现 if db == MySQL { ... } else { ... }。必须抽象出一个驱动无关的接口。

初始化流程

首次部署的 Web 向导里，handleInitConfig 直接拼 MySQL 格式的 DSN（user:pass@tcp(host:port)/db），硬编码调用 gorm.Open(mysql.Open(dsn)) 来测试连通性。路由 /init/mysql/test 则直接用了 gorm.Open 的 MySQL dialector。整个流程没有任何切换数据库的入口。

ORM 连接层

orm 包里只有一个 ConnectMysql 函数，import 的是 gorm.io/driver/mysql。

迁移文件

所有 SQL 文件平铺在 initialize/migrate/database/ 下。CREATE TABLE 用的是 AUTO_INCREMENT、TINYINT(1)、ENGINE=InnoDB。PostgreSQL 拿到这些文件一条都跑不通。

model 层

这是最复杂的部分。MySQL 专属写法散落在十几个文件里，有的是显式的——FIND_IN_SET、DATE_FORMAT——有的是隐式的：保留字裸写、数值类型的文本匹配、隐式类型转换。静态搜索只能抓到前一类，后一类只有等跑 PostgreSQL 时才会炸出来。

三、设计驱动抽象层

啃下这块骨头之前，先定目标：调用方代码不应该知道底层是哪个数据库，所有驱动差异收敛到 orm 包内部。

3.1 驱动标识与规范化

定义常量，和 NormalizeDriver 函数处理用户输入的各种别名：

1
2
3
4
5
6
7
8
9
10
11
12
13
const (
    DriverMySQL    = "mysql"
    DriverPostgres = "postgres"
)

func NormalizeDriver(driver string) string {
    switch strings.ToLower(strings.TrimSpace(driver)) {
    case "postgres", "postgresql", "pg":
        return DriverPostgres
    default:
        return DriverMySQL
    }
}

默认值是 MySQL，所有现有配置文件零改动。

3.2 统一配置结构体

orm.Config 增加 Driver 字段，其他字段在两个驱动间复用：

1
2
3
4
5
6
7
8
9
10
11
type Config struct {
    Driver        string
    Addr          string
    Username      string
    Password      string
    Dbname        string
    Config        string // DSN 附加参数
    MaxIdleConns  int
    MaxOpenConns  int
    SlowThreshold int
}

然后在 orm.Mysql 上挂两个方法，把 DSN 格式差异藏起来：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
func (m Mysql) Driver() string {
    return NormalizeDriver(m.Config.Driver)
}

func (m Mysql) MigrationDsn() string {
    if m.Driver() == DriverPostgres {
        return fmt.Sprintf("postgres://%s:%s@%s/%s?%s",
            m.Config.Username, m.Config.Password,
            m.Config.Addr, m.Config.Dbname, m.Config.Config)
    }
    return fmt.Sprintf("%s:%s@tcp(%s)/%s?%s",
        m.Config.Username, m.Config.Password,
        m.Config.Addr, m.Config.Dbname, m.Config.Config)
}

3.3 ConnectDatabase：统一连接入口

1
2
3
4
5
6
7
8
func ConnectDatabase(m Mysql) (*gorm.DB, error) {
    switch m.Driver() {
    case DriverPostgres:
        return connectPostgres(m)
    default:
        return connectMySQL(m)
    }
}

新增的依赖：

1
2
gorm.io/driver/postgres v1.6.0
github.com/jackc/pgx/v5 v5.6.0

注意 gorm.io/driver/postgres 底层用的是 pgx/v5，而不是老的 lib/pq。两者对 GORM 的上层接口无差异，但 pgx 性能更好、对连接池的控制更细。

四、改造配置层和初始化流程

4.1 config.Config 的接口化

MySQL 字段不能直接改名——现有 YAML 配置文件反序列化靠字段名匹配，改名就是破坏性变更。所以保留原字段，新增方法做兼容层：

1
2
3
4
5
6
7
8
9
10
func (c *Config) DatabaseConfig() orm.Config {
    if c.Database.Driver != "" {
        return c.Database
    }
    return c.MySQL  // 回退到老字段
}

func (c *Config) SetDatabaseConfig(cfg orm.Config) {
    c.Database = cfg
}

配置写回 YAML 时也统一走 Database 字段：

1
2
3
4
newConfig := config.File{
    // ...
    Database: c.DatabaseConfig(), // 原来是 MySQL: c.MySQL
}

这样三件事同时成立：

  • 新部署：配置文件里出现 Database.Driver: postgres
  • 老用户升级：MySQL 字段自动回退，行为不变
  • 老用户升级后重写配置：自动迁移到新格式

4.2 初始化向导的改造

handleInitConfig 的请求体里新增 databaseDriver 字段，对接 buildDatabaseConfig：

1
2
3
4
5
dbConfig, err := buildDatabaseConfig(
    request.DatabaseDriver,
    request.MysqlHost, request.MysqlPort,
    request.MysqlDatabase, request.MysqlUser, request.MysqlPassword,
)

buildDatabaseConfig 集中做三件事：规范化驱动名、验证合法性、注入各驱动的默认 DSN 参数（PostgreSQL 默认 sslmode=disable&TimeZone=Asia/Shanghai）。

迁移的调用从：

1
migrate.Migrate(dsn).Up()

改成：

1
migrate.Migrate(dbClient.Driver(), dbClient.MigrationDsn()).Up()

同时新增 /init/database/test 路由，老的 /init/mysql/test 内部转发到新函数：

1
2
3
func HandleMySQLTest(c *gin.Context) {
    HandleDatabaseTest(c) // 向前兼容
}

五、迁移文件：从一套 DDL 到两套

这是最枯燥但不能省的工作。所有迁移文件平铺在 database/ 下的局面不能再继续了——两种数据库的 DDL 语法差异，混在一个目录里迟早要出事。

新的目录结构：

1
2
3
4
5
6
7
8
9
initialize/migrate/database/
├── mysql/
│   ├── 00001_init_schema.up.sql
│   ├── 00002_init_basic_data.up.sql
│   └── ...
└── postgres/
    ├── 00001_init_schema.up.sql
    ├── 00002_init_basic_data.up.sql
    └── ...

以第一版建 users 表为例，差异其实比想象中多：

MySQL 版本：

1
2
3
4
5
6
7
8
9
10
11
12
CREATE TABLE `users` (
    `id`          BIGINT       NOT NULL AUTO_INCREMENT,
    `email`       VARCHAR(255) NOT NULL,
    `password`    VARCHAR(255) NOT NULL,
    `balance`     DECIMAL(10,2) DEFAULT 0.00,
    `status`      TINYINT(1)   DEFAULT 1,
    `is_admin`    TINYINT(1)   DEFAULT 0,
    `created_at`  DATETIME     DEFAULT CURRENT_TIMESTAMP,
    `updated_at`  DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    INDEX `idx_users_email` (`email`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

PostgreSQL 版本：

1
2
3
4
5
6
7
8
9
10
11
12
CREATE TABLE users (
    id          BIGSERIAL    NOT NULL,
    email       VARCHAR(255) NOT NULL,
    password    VARCHAR(255) NOT NULL,
    balance     DECIMAL(10,2) DEFAULT 0.00,
    status      SMALLINT     DEFAULT 1,
    is_admin    BOOLEAN      DEFAULT FALSE,
    created_at  TIMESTAMP    DEFAULT NOW(),
    updated_at  TIMESTAMP    DEFAULT NOW(),
    PRIMARY KEY (id)
);
CREATE INDEX idx_users_email ON users(email);

几个核心差异：

场景MySQLPostgreSQL
自增主键BIGINT AUTO_INCREMENTBIGSERIAL
布尔值TINYINT(1) + 0/1BOOLEAN + TRUE/FALSE
时间戳默认值CURRENT_TIMESTAMPNOW()
更新时戳ON UPDATE CURRENT_TIMESTAMP需 trigger
引擎指定ENGINE=InnoDB无需
字符集CHARSET utf8mb4库级别

我用 golang-migrate 这个框架，它支持按子目录区分数据库驱动，只需要在调用时传入正确的 database 参数：

1
2
3
4
// mysql
migrate.Migrate("mysql", "user:pass@tcp(localhost:3306)/ppanel?...").Up()
// postgres
migrate.Migrate("postgres", "postgres://user:pass@localhost:5432/ppanel?...").Up()

框架自动定位到对应目录的 migration 文件。工作量集中在翻译 DDL 上——全量迁移文件大约 20 组，逐条翻译、逐条确认功能等价。

六、跑起来之后：model 层挖坑记

PR #130 合并之后，我长舒了一口气。抽象层、配置层、迁移层都过了，理论上 PostgreSQL 应该能跑起来了。

然后搭了一个 PostgreSQL 实例，启动服务，开始逐个调用接口。

日志里刷出来十几行错误。

有些是预料之中的——FIND_IN_SET、保留字——改了就行。有些则完全出乎意料，比如一个 MySQL 下潜伏了半年的 bug 因为 PostgreSQL 的严格类型检查而炸了出来。

以下按修复顺序，摘几个代表性的问题讲讲。

6.1 FIND_IN_SET

项目里多处用逗号分隔的字段存关联 ID：

1
node.group_ids = "1,3,7"

原来的查询：

1
db.Where("FIND_IN_SET(?, group_ids)", groupID)

FIND_IN_SET 是 MySQL 专有函数，在 PostgreSQL 下报错 function does not exist。

修复：在 orm 包里增加 CommaSeparatedContains，对两种数据库生成不同 SQL：

1
2
3
4
5
6
7
8
9
10
11
12
func CommaSeparatedContains(column string, value interface{}) clause.Expr {
    if currentDriver == DriverPostgres {
        return clause.Expr{
            SQL:  fmt.Sprintf("? = ANY(string_to_array(%s, ','))", column),
            Vars: []interface{}{fmt.Sprintf("%v", value)},
        }
    }
    return clause.Expr{
        SQL:  fmt.Sprintf("FIND_IN_SET(?, %s)", column),
        Vars: []interface{}{value},
    }
}

调用方只需写：

1
db.Where(orm.CommaSeparatedContains("group_ids", groupID))

这种模式后来被反复使用——不是所有问题都能靠一个 helper 解决，但这种”生成驱动相关的 SQL 片段，暴露统一接口”的模式，贯穿了整个改造。

6.2 数值字段的文本 LIKE

ticket.port 是 INT 类型，但后台搜索框中用户可能输入”端口号片段”来筛选。原来的代码做字符串 LIKE 匹配。MySQL 会隐式做类型转换，所有行都能正常返回。PostgreSQL 直接报类型错误。

这种场景没有特别优雅的解法。我加了一层驱动判断：

1
2
3
4
5
if orm.CurrentDriver() == orm.DriverPostgres {
    db = db.Where("port::TEXT LIKE ?", "%"+keyword+"%")
} else {
    db = db.Where("CAST(port AS CHAR) LIKE ?", "%"+keyword+"%")
}

不优雅，但稳妥。理想的方案是把这类场景收敛到 helper 里，但 port 的模糊搜索只出现在后台管理页面的全能搜索框里，调用点很少，就先以最小改动保证正确性。

6.3 Node BeforeUpdate 中的错误 Model 引用

这是整轮改造中价值最大的发现。

Node 的 BeforeUpdate hook 里有一段排序校验逻辑：

1
2
3
4
5
func (n *Node) BeforeUpdate(tx *gorm.DB) error {
    var existing Server // 错误！应该是 Node
    tx.Where("id = ?", n.ID).First(&existing)
    // ... 用 existing.Sort 做校验
}

Server 和 Node 恰好在结构上有点像（都有 ID、Sort 字段），MySQL 下 GORM 虽然表名走了 servers 表，但查询结果恰好包含这些字段，校验逻辑阴差阳错地通过了。这个 bug 一直静默存在了半年之久。

但在 PostgreSQL 下，这条 SQL 走了 servers 表并返回了错误的数据，排序校验逻辑在不正确的数据上运行，导致后续的状态更新调用产生 500。沿着错误栈一层层追下去，最终定位到 BeforeUpdate 的这个位置时，我盯着屏幕愣了几秒——“这也行？”

修复只是一行文本变化：

1
var existing Node // 修正

但这件事让我意识到：异构数据库的价值不仅是适配更多用户，它还扮演了”额外的编译器”的角色——在更好的类型系统、更严格的语法约束下，它发现了常规测试从未触达的 bug。

一个项目中同时跑两种数据库，它们的差异点本身就是一套隐性测试。

6.4 保留字裸写

PostgreSQL 对 SQL 保留字比 MySQL 严格得多。最典型的是 system 表的 key 列：

1
db.Where("key = ?", k)

MySQL 下虽然 key 是保留字，但 DML 中 MySQL 会隐式加反引号。PostgreSQL 直接报语法错误。show 字段同理，分别出现在 subscribe、announcement、document 三个表里。

修复：不用手写字符串，改用 GORM 的 clause.Eq，它会自动对列名做安全引号处理：

1
2
3
4
5
6
7
// internal/model/system/scope.go
func WhereCategoryKey(category, key string) []clause.Interface {
    return []clause.Interface{
        clause.Eq{Column: "category", Value: category},
        clause.Eq{Column: "key", Value: key},
    }
}

调用方从：

1
db.Where("key = ?", k).Where("category = ?", cat)

变成：

1
db.Where(system.WhereCategoryKey(cat, k))

安全、驱动无关。

改动波及了大约 10 个文件——凡是涉及 system 表 key 的 updateXxxConfigLogic.go 都要改。每个文件一两行，但必须全部过一遍，不能遗漏。

6.5 查询函数的隐式副作用

这是一个设计问题，不是 SQL 兼容性问题。但在 PostgreSQL 的严格事务隔离下，它从”不优雅”变成了一个真实的 bug。

FindUsersSubscribeBySubscribeId —— 函数名语义是”查找”——但函数体里实际还有写操作：

1
2
3
4
5
6
7
8
9
10
11
12
func FindUsersSubscribeBySubscribeId(id uint) ([]*UserSubscribe, error) {
    var list []*UserSubscribe
    db.Where("subscribe_id = ?", id).Find(&list)

    // ⚠️ 顺手激活待激活的订阅
    for _, item := range list {
        if item.Status == StatusPending {
            db.Model(item).Update("status", StatusActive)
        }
    }
    return list, nil
}

调用方按函数名做信任判断，以为它只读不做写入。在 PostgreSQL 的事务隔离下，这种模式更容易造成并发写冲突。

拆分成两个职责清晰的函数：

1
2
3
4
5
6
7
8
9
10
11
func FindUsersSubscribeBySubscribeId(id uint) ([]*UserSubscribe, error) {
    var list []*UserSubscribe
    db.Where("subscribe_id = ?", id).Find(&list)
    return list, nil
}

func ActivatePendingSubscribesBySubscribeId(id uint) error {
    return db.Model(&UserSubscribe{}).
        Where("subscribe_id = ? AND status = ?", id, StatusPending).
        Update("status", StatusActive).Error
}

函数名就是语义协议，调用方按名称做信任判断。这段经历让我在 review 中养成了一个习惯：看到一个叫 Find*、Get*、Query* 的函数，多看一眼它的函数体里有没有 Update、Insert、Delete。

七、搜索性能：顺带修了一轮索引

在改兼容性的过程中，我注意到搜索查询里大量使用 %keyword% 写法。这种写法两端都加通配符，B-Tree 索引完全用不上，一定是全表扫描。既然已经在改数据层了，顺手优化这块。

7.1 搜索 Helper

1
2
3
4
5
6
7
8
9
10
11
12
13
14
func PrefixLike(keyword string) string {
    return EscapeLike(keyword) + "%"
}

func ContainsLike(keyword string) string {
    return "%" + EscapeLike(keyword) + "%"
}

func EscapeLike(keyword string) string {
    keyword = strings.ReplaceAll(keyword, "\\", "\\\\")
    keyword = strings.ReplaceAll(keyword, "%", "\\%")
    keyword = strings.ReplaceAll(keyword, "_", "\\_")
    return keyword
}

EscapeLike 之前的搜索代码里完全没有，用户输入包含 % 或 _ 时搜索语义会被静默篡改。

搜索策略调整：email、用户名等”用户通常从头输入”的字段改用 PrefixLike，可以命中 B-Tree 索引；节点备注、套餐名称等必须支持任意位置匹配的保留 ContainsLike。

7.2 搜索索引迁移

MySQL 版本加普通 B-Tree 索引，不做特殊处理。

PostgreSQL 版本引入 pg_trgm extension 和 GIN 索引来加速包含匹配：

1
2
3
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_nodes_remark_trgm
    ON nodes USING gin(remark gin_trgm_ops);

pg_trgm 把字符串按三个字符一组切分，用 GIN 索引存储。几十万行以上的表，这个索引能把 LIKE '%keyword%' 从秒级降到毫秒级。

部署注意事项：CREATE EXTENSION 需要超级用户权限，托管 PostgreSQL 需要在控制台手动启用或请 DBA 协助。我在 PR 描述里特意标注了这一点。

八、向后兼容：让已有 MySQL 用户无感升级

整个改造过程中，我心里一直挂着一条红线：已有 MySQL 用户什么都不用改，二进制替换重启即可。

保障机制：

  1. config.Config 保留 MySQL 字段。Database.Driver 为空时自动回退读 MySQL。
  2. NormalizeDriver("") 默认返回 "mysql"。
  3. 路由 /init/mysql/test 保留，内部转发给新函数。
  4. 迁移文件只迁移目录，内容不改。

新配置格式示例：

1
2
3
4
5
6
7
Database:
  Driver: postgres
  Addr: localhost:5432
  Username: postgres
  Password: password
  Dbname: ppanel
  Config: sslmode=disable&TimeZone=Asia/Shanghai

也可以只写：

1
2
3
4
5
Database:
  Addr: localhost:3306
  Username: root
  Password: password
  Dbname: ppanel

Driver 留空则默认为 MySQL。

九、技术取舍：一个没有重命名的命名

细心的读者可能注意到：在整篇文章里，承载 PostgreSQL 逻辑的 Go 类型仍然叫 orm.Mysql。

1
type Mysql struct { Config }  // 同时也处理 Postgres 连接

为什么不重命名为 orm.DBConfig 或 orm.Driver？这是一个真实的遗留设计债务。

做这个改造时，orm.Mysql 被引用在几十个文件里——作为函数参数类型、结构体字面量初始化、方法接收者。改名意味着全量搜索替换，增加 reviewer 的心智负担，而且没有任何行为收益。在当时”最小改动原则”的约束下，我选择保留命名。

这是一个 tradeoff：新增 PostgreSQL 支持已经改变了 40 个文件，再叠一个全量重命名，PR diff 会膨胀到根本没法 review。改命名应该是一个独立的、纯重构的 PR——从效果上看，早晚会做。但适配本身不必须等它。

这和学习接口的一个道理：先让它 work，再让它 clean。

十、回顾

两个 PR，六次提交，约四十个文件改动：

PR提交内容
#130ee53e6ePostgreSQL 驱动支持，配置抽象，迁移拆分
#130dad79ddCI 发布流程调整
#133064cc96model 层 PostgreSQL 兼容性修复
#1331ec853e拆分订阅查询和激活逻辑
#133b4629b8搜索查询优化和索引迁移
#1337b074e2MySQL 保留字修复

几条值得记录的教训：

1. 驱动抽象要尽早做。 如果一开始 orm 层就是 ConnectDatabase(driver, config) 的形态，后来加驱动只是加一个 case 的工作量。等到代码里散落了上百处 mysql.Open 的调用，就很难优雅了。

2. GORM 不能屏蔽所有 SQL 差异。 FIND_IN_SET、保留字、数值类型转换这些问题，GORM 的 standardized API 覆盖不到。写 model 层时要有跨数据库意识，预期之外的 SQL 字符不该出现在 db.Where() 的字符串里。

3. 函数名就是语义协议。 Find* 里写 Update 是程序员的信任违约。被 PostgreSQL 逼着修了这个问题后，我现在 code review 里多了一条默认检查。

4. 异构数据库测试的价值超过适配本身。 这是整件事里最意外的收获。引入 PostgreSQL 不仅让项目支持了更多用户，它还像一个”额外的编译器”一样，用更严格的类型检查暴露了一个 MySQL 下潜伏半年的 bug。选择支持多种数据库，不仅仅是扩大用户面——它在替你运行一条额外的、价值极高的测试套件。

5. 迁移 SQL 早分早省事。 两套 DDL 语法差异放到一个目录里，不管理论上多小心，迟早混淆。目录结构是最简单的强制约束。

6. 向后兼容不是可选项，是硬条件。 已经有用户在生产环境跑着你的软件，你的改进不能让他们升级后亮红灯。保留路由、保留字段、设定合理的默认值——这些不会出现在 feature 列表里，但比你写的新功能更重要。

最后：如果你在考虑为一个 MySQL-only 的项目加 PostgreSQL 支持，我的建议就是 做，并且做彻底。因为你会发现，真正难的不是加 PostgreSQL，而是揭开 MySQL 留给你的一切便利假设。

]]> https://www.embermoth.blog/2026/05/19/ppanel-postgresql-support/ 2026-05-19T09:23:00.000Z

TL;DR — 为已有项目新增第二种数据库支持，工作量远大于”加个驱动依赖”。
本文记录 ppanel-server 从 MySQL-only 到同时支持 MySQL + PostgreSQL 的完整改造：重构配置抽象层、拆分两套迁移 DDL、修复 model 层 20+ 个 MySQL 专属写法、顺带优化搜索索引。
涉及 2 个 PR、6 次提交、约 40 个文件改动。最有价值的发现是：引入异构数据库测试，意外暴露了一个 MySQL 下潜伏了半年的隐性 bug。

]]> 从MySQL Only到PostgreSQL+MySQL：一次从驱动抽象到 SQL 兼容的完整改造 2026-05-19T09:23:00.000Z