feat: add metricsServer for health checks, metrics and pprof (#5578)

Add a separate HTTP listener for observability, configured through
metricsServer in both frps and frpc. It serves /healthz and, when
pprofEnable is set, the pprof handlers except /debug/pprof/cmdline. It
never serves the dashboard, static assets or the admin API, and it does
not touch the global assets filesystem.

frps also serves /metrics on this listener with both runtime and business
metrics, enabled by metricsServer.port alone. The in-memory collector
still starts only with the dashboard, and the Prometheus collector starts
either with metricsServer or with enablePrometheus plus webServer, so a
configuration that collected nothing before still collects nothing.

The /healthz, /metrics and pprof endpoints on webServer, and
enablePrometheus, keep working but are deprecated and log a hint at
startup. frpc does not serve /metrics yet.

client/metrics_server_test.go

@@ -0,0 +1,91 @@
+// Copyright 2026 The frp Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package client
+
+import (
+	"context"
+	"net"
+	"net/http"
+	"path/filepath"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/fatedier/frp/pkg/config/source"
+	v1 "github.com/fatedier/frp/pkg/config/v1"
+)
+
+func TestNewServiceReleasesWebServerOnMetricsServerFailure(t *testing.T) {
+	for _, mode := range []string{"port conflict", "invalid TLS certificate"} {
+		t.Run(mode, func(t *testing.T) {
+			ln, err := net.Listen("tcp", "127.0.0.1:0")
+			require.NoError(t, err)
+			defer ln.Close()
+			cfg := &v1.ClientCommonConfig{
+				WebServer:     v1.WebServerConfig{Port: getFreeTCPPort(t)},
+				MetricsServer: v1.MetricsServerConfig{Port: ln.Addr().(*net.TCPAddr).Port},
+			}
+			if mode == "invalid TLS certificate" {
+				cfg.MetricsServer.TLS = &v1.TLSConfig{
+					CertFile: filepath.Join(t.TempDir(), "missing.crt"), KeyFile: "missing.key",
+				}
+				require.NoError(t, ln.Close())
+			}
+			svr, err := NewService(ServiceOptions{
+				Common: cfg, ConfigSourceAggregator: source.NewAggregator(source.NewConfigSource()),
+			})
+			if svr != nil {
+				svr.Close()
+			}
+			require.Error(t, err)
+			require.Nil(t, svr)
+			assertLifecycleAdminPort(t, net.JoinHostPort(cfg.WebServer.Addr, strconv.Itoa(cfg.WebServer.Port)), true)
+			if mode == "invalid TLS certificate" {
+				assertLifecycleAdminPort(t, ln.Addr().String(), true)
+			}
+		})
+	}
+}
+
+func TestServiceMetricsServerLifecycle(t *testing.T) {
+	svr, err := NewService(ServiceOptions{
+		Common: &v1.ClientCommonConfig{
+			LoginFailExit: new(false), MetricsServer: v1.MetricsServerConfig{Port: getFreeTCPPort(t)},
+		},
+		ConfigSourceAggregator: source.NewAggregator(source.NewConfigSource()),
+		ConnectorCreator: func(context.Context, *v1.ClientCommonConfig) Connector {
+			return &failingConnector{err: net.ErrClosed}
+		},
+	})
+	require.NoError(t, err)
+	require.Nil(t, svr.webServer)
+	address := svr.metricsServer.Address()
+	done := make(chan struct{})
+	go func() { _ = svr.Run(context.Background()); close(done) }()
+	defer func() {
+		svr.Close()
+		waitLifecycleSignal(t, done)
+		assertLifecycleAdminPort(t, address, true)
+	}()
+	client := &http.Client{Timeout: 3 * time.Second}
+	for path, status := range map[string]int{"/healthz": http.StatusOK, "/metrics": http.StatusNotFound} {
+		resp, err := client.Get("http://" + address + path)
+		require.NoError(t, err)
+		require.Equal(t, status, resp.StatusCode)
+		require.NoError(t, resp.Body.Close())
+	}
+}

client/service.go

@@ -123,7 +123,8 @@ type Service struct {
 	auth *auth.ClientAuth
 
 	// web server for admin UI and apis
-	webServer *httppkg.Server
+	webServer     *httppkg.Server
+	metricsServer *httppkg.Server
 
 	vnetController *vnet.Controller
 
@@ -188,8 +189,8 @@ func NewService(options ServiceOptions) (*Service, error) {
 	proxyCfgs = config.CompleteProxyConfigurers(proxyCfgs)
 	visitorCfgs = config.CompleteVisitorConfigurers(visitorCfgs)
 
-	// Create the web server after all fallible steps so its listener is not
-	// leaked when an earlier error causes NewService to return.
+	// Create HTTP servers after all other fallible steps, rolling back the web
+	// listener if the metrics server cannot be created.
 	var webServer *httppkg.Server
 	if options.Common.WebServer.Port > 0 {
 		ws, err := httppkg.NewServer(options.Common.WebServer)
@@ -198,11 +199,19 @@ func NewService(options ServiceOptions) (*Service, error) {
 		}
 		webServer = ws
 	}
+	metricsServer, err := httppkg.NewMetricsServer(options.Common.MetricsServer, nil)
+	if err != nil {
+		if webServer != nil {
+			_ = webServer.Close()
+		}
+		return nil, err
+	}
 
 	s := &Service{
 		ctx:              context.Background(),
 		auth:             authRuntime,
 		webServer:        webServer,
+		metricsServer:    metricsServer,
 		common:           options.Common,
 		reloadCommon:     options.Common,
 		configFilePath:   options.ConfigFilePath,
@@ -263,6 +272,12 @@ func (svr *Service) Run(ctx context.Context) error {
 	}
 
 	if svr.webServer != nil {
+		if svr.common.WebServer.PprofEnable {
+			log.Warnf("webServer pprof endpoints are deprecated; use metricsServer.pprofEnable instead")
+		}
+		if svr.common.MetricsServer.Port == 0 {
+			log.Infof("webServer /healthz is deprecated; health probes can migrate to metricsServer.port")
+		}
 		webServer := svr.webServer
 		go func() {
 			log.Infof("admin server listen on %s", webServer.Address())
@@ -272,6 +287,16 @@ func (svr *Service) Run(ctx context.Context) error {
 		}()
 	}
 
+	if svr.metricsServer != nil {
+		metricsServer := svr.metricsServer
+		go func() {
+			log.Infof("metrics server listen on %s", metricsServer.Address())
+			if err := metricsServer.Run(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+				log.Warnf("metrics server exit with error: %v", err)
+			}
+		}()
+	}
+
 	// first login to frps
 	svr.loopLoginUntilSuccess(10*time.Second, lo.FromPtr(svr.common.LoginFailExit))
 	if svr.ctl == nil {
@@ -497,6 +522,10 @@ func (svr *Service) stop() {
 		svr.webServer.Close()
 		svr.webServer = nil
 	}
+	if svr.metricsServer != nil {
+		svr.metricsServer.Close()
+		svr.metricsServer = nil
+	}
 	if svr.vnetController != nil {
 		_ = svr.vnetController.Stop()
 		svr.vnetController = nil