feat(usage): added UI for metrics and metrics persistence

.gitignore

@@ -15,6 +15,7 @@ pgstore/*
 gitstore/*
 objectstore/*
 static/*
+metrics.json
 
 # Authentication data
 auths/*

Dockerfile

@@ -23,9 +23,12 @@ RUN mkdir /CLIProxyAPI
 COPY --from=builder ./app/CLIProxyAPI /CLIProxyAPI/CLIProxyAPI
 
 COPY config.example.yaml /CLIProxyAPI/config.example.yaml
+COPY ui /CLIProxyAPI/ui
 
 WORKDIR /CLIProxyAPI
 
+ENV IN_DOCKER=true
+
 EXPOSE 8317
 
 ENV TZ=Asia/Shanghai

cmd/server/main.go

@@ -378,6 +378,21 @@ func main() {
 		}
 	}
 	usage.SetStatisticsEnabled(cfg.UsageStatisticsEnabled)
+
+	metricsFile := cfg.MetricsFile
+	if metricsFile == "" {
+		metricsFile = "metrics.json"
+	}
+
+	loopDelay := cfg.LoopDelay
+	if loopDelay == 0 {
+		loopDelay = 10 * time.Minute
+	}
+
+	// Load last saved metrics from file and start periodic save
+	usage.LoadMetricsFromFile(metricsFile)
+	usage.StartPeriodicSaving(metricsFile, loopDelay, cfg.CrashOnError)
+
 	coreauth.SetQuotaCooldownDisabled(cfg.DisableCooling)
 
 	if err = logging.ConfigureLogOutput(cfg.LoggingToFile); err != nil {

config.example.yaml

@@ -85,3 +85,18 @@ ws-auth: false
 #    models: # The models supported by the provider.
 #      - name: "moonshotai/kimi-k2:free" # The actual model name.
 #        alias: "kimi-k2" # The alias used in the API.
+
+# --- Metrics Persistence ---
+#
+# File path for storing metrics periodically.
+# If commented out or empty, defaults to "metrics.json" in the project root.
+# metrics-file: "metrics.json"
+#
+# How often to save metrics to the file.
+# If commented out or empty, defaults to 10m (10 minutes).
+# loop-delay: 10m
+#
+# If true, the application will crash if it fails to save metrics.
+# If false, it will print an error to stderr and continue.
+# Defaults to false.
+# crash-on-error: false

internal/api/handlers/metrics/handler.go

@@ -0,0 +1,152 @@
+// Package metrics provides handlers for the metrics endpoints.
+package metrics
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"sort"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/usage"
+)
+
+// Handler holds the dependencies for the metrics handlers.
+type Handler struct {
+	Stats *usage.RequestStatistics
+}
+
+// NewHandler creates a new metrics handler.
+func NewHandler(stats *usage.RequestStatistics) *Handler {
+	return &Handler{Stats: stats}
+}
+
+// MetricsResponse is the top-level struct for the metrics endpoint response.
+type MetricsResponse struct {
+	Totals     TotalsMetrics      `json:"totals"`
+	ByModel    []ModelMetrics     `json:"by_model"`
+	Timeseries []TimeseriesBucket `json:"timeseries"`
+}
+
+// TotalsMetrics holds the aggregated totals for the queried period.
+type TotalsMetrics struct {
+	Tokens   int64 `json:"tokens"`
+	Requests int64 `json:"requests"`
+}
+
+// ModelMetrics holds the aggregated metrics for a specific model.
+type ModelMetrics struct {
+	Model    string `json:"model"`
+	Tokens   int64  `json:"tokens"`
+	Requests int64  `json:"requests"`
+}
+
+// TimeseriesBucket holds the aggregated metrics for a specific time bucket.
+type TimeseriesBucket struct {
+	BucketStart string `json:"bucket_start"` // ISO 8601 format
+	Tokens      int64  `json:"tokens"`
+	Requests    int64  `json:"requests"`
+}
+
+// GetMetrics is the handler for the /_qs/metrics endpoint.
+func (h *Handler) GetMetrics(c *gin.Context) {
+	fromStr := c.Query("from")
+	toStr := c.Query("to")
+	modelFilter := c.Query("model")
+
+	var fromTime, toTime time.Time
+	var err error
+
+	// Default to last 24 hours if no time range is given
+	if fromStr == "" && toStr == "" {
+		toTime = time.Now()
+		fromTime = toTime.Add(-24 * time.Hour)
+	} else {
+		if fromStr != "" {
+			fromTime, err = time.Parse(time.RFC3339, fromStr)
+			if err != nil {
+				c.JSON(http.StatusBadRequest, gin.H{"error": "invalid 'from' timestamp format"})
+				return
+			}
+		}
+		if toStr != "" {
+			toTime, err = time.Parse(time.RFC3339, toStr)
+			if err != nil {
+				c.JSON(http.StatusBadRequest, gin.H{"error": "invalid 'to' timestamp format"})
+				return
+			}
+		}
+	}
+
+	snapshot := h.Stats.Snapshot()
+
+	modelMetricsMap := make(map[string]*ModelMetrics)
+	timeseriesMap := make(map[time.Time]*TimeseriesBucket)
+	var totalTokens int64
+	var totalRequests int64
+
+	for _, apiSnapshot := range snapshot.APIs {
+		for modelName, modelSnapshot := range apiSnapshot.Models {
+			if modelFilter != "" && modelFilter != modelName {
+				continue
+			}
+
+			for _, detail := range modelSnapshot.Details {
+				if !fromTime.IsZero() && detail.Timestamp.Before(fromTime) {
+					continue
+				}
+				if !toTime.IsZero() && detail.Timestamp.After(toTime) {
+					continue
+				}
+
+				totalRequests++
+				totalTokens += detail.Tokens.TotalTokens
+
+				if _, ok := modelMetricsMap[modelName]; !ok {
+					modelMetricsMap[modelName] = &ModelMetrics{Model: modelName}
+				}
+				modelMetricsMap[modelName].Requests++
+				modelMetricsMap[modelName].Tokens += detail.Tokens.TotalTokens
+
+				bucket := detail.Timestamp.Truncate(time.Hour)
+				if _, ok := timeseriesMap[bucket]; !ok {
+					timeseriesMap[bucket] = &TimeseriesBucket{BucketStart: bucket.Format(time.RFC3339)}
+				}
+				timeseriesMap[bucket].Requests++
+				timeseriesMap[bucket].Tokens += detail.Tokens.TotalTokens
+			}
+		}
+	}
+
+	resp := MetricsResponse{
+		Totals: TotalsMetrics{
+			Tokens:   totalTokens,
+			Requests: totalRequests,
+		},
+		ByModel:    make([]ModelMetrics, 0, len(modelMetricsMap)),
+		Timeseries: make([]TimeseriesBucket, 0, len(timeseriesMap)),
+	}
+
+	for _, mm := range modelMetricsMap {
+		resp.ByModel = append(resp.ByModel, *mm)
+	}
+
+	sort.Slice(resp.ByModel, func(i, j int) bool {
+		return resp.ByModel[i].Model < resp.ByModel[j].Model
+	})
+
+	for _, tb := range timeseriesMap {
+		resp.Timeseries = append(resp.Timeseries, *tb)
+	}
+
+	sort.Slice(resp.Timeseries, func(i, j int) bool {
+		return resp.Timeseries[i].BucketStart < resp.Timeseries[j].BucketStart
+	})
+
+	if jsonData, err := json.MarshalIndent(resp, "", "  "); err == nil {
+		fmt.Println(string(jsonData))
+	}
+
+	c.JSON(http.StatusOK, resp)
+}

internal/api/middleware/request_logging.go

@@ -80,6 +80,9 @@ func captureRequestInfo(c *gin.Context) (*RequestInfo, error) {
 		headers[key] = values
 	}
 
+	delete(headers, "Authorization")
+	delete(headers, "Cookie")
+
 	// Capture request body
 	var body []byte
 	if c.Request.Body != nil {

internal/api/server.go

@@ -20,6 +20,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/access"
 	managementHandlers "github.com/router-for-me/CLIProxyAPI/v6/internal/api/handlers/management"
+	metrics "github.com/router-for-me/CLIProxyAPI/v6/internal/api/handlers/metrics"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/api/middleware"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/logging"
@@ -148,6 +149,9 @@ type Server struct {
 	// management handler
 	mgmt *managementHandlers.Handler
 
+	// metrics handler
+	metricsHandler *metrics.Handler
+
 	// managementRoutesRegistered tracks whether the management routes have been attached to the engine.
 	managementRoutesRegistered atomic.Bool
 	// managementRoutesEnabled controls whether management endpoints serve real handlers.
@@ -249,6 +253,7 @@ func NewServer(cfg *config.Config, authManager *auth.Manager, accessManager *sdk
 	auth.SetQuotaCooldownDisabled(cfg.DisableCooling)
 	// Initialize management handler
 	s.mgmt = managementHandlers.NewHandler(cfg, configFilePath, authManager)
+	s.metricsHandler = metrics.NewHandler(usage.GetRequestStatistics())
 	if optionState.localPassword != "" {
 		s.mgmt.SetLocalPassword(optionState.localPassword)
 	}
@@ -277,8 +282,13 @@ func NewServer(cfg *config.Config, authManager *auth.Manager, accessManager *sdk
 	}
 
 	// Create HTTP server
+	bindAddr := "localhost"
+	if os.Getenv("IN_DOCKER") == "true" {
+		bindAddr = "0.0.0.0"
+	}
+
 	s.server = &http.Server{
-		Addr:    fmt.Sprintf(":%d", cfg.Port),
+		Addr:    fmt.Sprintf("%s:%d", bindAddr, cfg.Port),
 		Handler: engine,
 	}
 
@@ -324,9 +334,21 @@ func (s *Server) setupRoutes() {
 				"POST /v1/chat/completions",
 				"POST /v1/completions",
 				"GET /v1/models",
+				"GET /_qs/health",
+				"GET /_qs/metrics",
 			},
 		})
 	})
+
+	qs := s.engine.Group("/_qs")
+	{
+		qs.GET("/health", func(c *gin.Context) {
+			c.JSON(http.StatusOK, gin.H{"ok": true})
+		})
+		qs.GET("/metrics", s.metricsHandler.GetMetrics)
+		qs.GET("/metrics/ui", s.serveMetricsUI)
+	}
+
 	s.engine.POST("/v1internal:method", geminiCLIHandlers.CLIHandler)
 
 	// OAuth callback endpoints (reuse main server port)
@@ -550,6 +572,11 @@ func (s *Server) serveManagementControlPanel(c *gin.Context) {
 	c.File(filePath)
 }
 
+func (s *Server) serveMetricsUI(c *gin.Context) {
+	filePath := filepath.Join("ui", "metrics.html")
+	c.File(filePath)
+}
+
 func (s *Server) enableKeepAlive(timeout time.Duration, onTimeout func()) {
 	if timeout <= 0 || onTimeout == nil {
 		return

internal/cmd/run.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/api"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/config"
+	"github.com/router-for-me/CLIProxyAPI/v6/internal/usage"
 	"github.com/router-for-me/CLIProxyAPI/v6/sdk/cliproxy"
 	log "github.com/sirupsen/logrus"
 )
@@ -49,6 +50,9 @@ func StartService(cfg *config.Config, configPath string, localPassword string) {
 	}
 
 	err = service.Run(runCtx)
+
+	usage.StopMetricsPersistence()
+
 	if err != nil && !errors.Is(err, context.Canceled) {
 		log.Fatalf("proxy service exited with error: %v", err)
 	}

internal/config/config.go

@@ -10,6 +10,7 @@ import (
 	"os"
 	"strings"
 	"syscall"
+	"time"
 
 	"github.com/router-for-me/CLIProxyAPI/v6/sdk/config"
 	"golang.org/x/crypto/bcrypt"
@@ -60,6 +61,15 @@ type Config struct {
 
 	// RemoteManagement nests management-related options under 'remote-management'.
 	RemoteManagement RemoteManagement `yaml:"remote-management" json:"-"`
+
+	// MetricsFile is the path to the JSON file where metrics will be stored.
+	MetricsFile string `yaml:"metrics-file,omitempty" json:"metrics-file,omitempty"`
+
+	// LoopDelay is the interval at which metrics are saved to the file.
+	LoopDelay time.Duration `yaml:"loop-delay,omitempty" json:"loop-delay,omitempty"`
+
+	// CrashOnError determines if the application should crash if saving metrics fails.
+	CrashOnError bool `yaml:"crash-on-error,omitempty" json:"crash-on-error,omitempty"`
 }
 
 // RemoteManagement holds management API configuration under 'remote-management'.

internal/logging/gin_logger.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
 	"github.com/router-for-me/CLIProxyAPI/v6/internal/util"
 	log "github.com/sirupsen/logrus"
 )
@@ -22,6 +23,10 @@ import (
 //   - gin.HandlerFunc: A middleware handler for request logging
 func GinLogrusLogger() gin.HandlerFunc {
 	return func(c *gin.Context) {
+		requestID := uuid.New().String()
+		c.Set("request_id", requestID)
+		c.Header("X-Request-ID", requestID)
+
 		start := time.Now()
 		path := c.Request.URL.Path
 		raw := util.MaskSensitiveQuery(c.Request.URL.RawQuery)