feat: add preview and diff endpoints for config versions

- Implemented PreviewConfigVersion and DiffConfigVersion functions to provide configuration previews and differences. - Updated API router to include new endpoints for preview and diff. - Enhanced config version publishing to include custom headers in the rendered configuration. - Added tests for preview and diff functionalities, ensuring correct behavior with custom headers. - Updated frontend to support previewing and publishing configurations with a detailed change summary.
2026-10-07 16:16:37 +08:00 · 2026-03-10 16:23:49 +08:00
parent b76fb822f8
commit 08e4de4898
10 changed files with 830 additions and 187 deletions
@@ -24,6 +24,41 @@ type SupportFile struct {
 	Content string `json:"content"`
 }

+type ConfigPreviewResult struct {
+	SnapshotJSON   string        `json:"snapshot_json"`
+	RenderedConfig string        `json:"rendered_config"`
+	SupportFiles   []SupportFile `json:"support_files"`
+	Checksum       string        `json:"checksum"`
+	RouteCount     int           `json:"route_count"`
+}
+
+type ConfigDiffResult struct {
+	ActiveVersion   string   `json:"active_version,omitempty"`
+	AddedDomains    []string `json:"added_domains"`
+	RemovedDomains  []string `json:"removed_domains"`
+	ModifiedDomains []string `json:"modified_domains"`
+}
+
+type snapshotRoute struct {
+	Domain        string                        `json:"domain"`
+	OriginURL     string                        `json:"origin_url"`
+	Enabled       bool                          `json:"enabled"`
+	EnableHTTPS   bool                          `json:"enable_https"`
+	CertID        *uint                         `json:"cert_id,omitempty"`
+	RedirectHTTP  bool                          `json:"redirect_http"`
+	CustomHeaders []ProxyRouteCustomHeaderInput `json:"custom_headers,omitempty"`
+	Remark        string                        `json:"remark,omitempty"`
+}
+
+type configBundle struct {
+	Routes         []*model.ProxyRoute
+	SnapshotRoutes []snapshotRoute
+	SnapshotJSON   string
+	RenderedConfig string
+	SupportFiles   []SupportFile
+	Checksum       string
+}
+
 const nginxCertDirPlaceholder = "__ATSF_CERT_DIR__"

 func ListConfigVersions() ([]*model.ConfigVersion, error) {
@@ -34,23 +69,83 @@ func GetActiveConfigVersion() (*model.ConfigVersion, error) {
 	return model.GetActiveConfigVersion()
 }

-func PublishConfigVersion(createdBy string) (*ReleaseResult, error) {
-	routes, err := model.GetEnabledProxyRoutes()
+func PreviewConfigVersion() (*ConfigPreviewResult, error) {
+	bundle, err := buildCurrentConfigBundle(false)
 	if err != nil {
 		return nil, err
 	}
-	if len(routes) == 0 {
+	return &ConfigPreviewResult{
+		SnapshotJSON:   bundle.SnapshotJSON,
+		RenderedConfig: bundle.RenderedConfig,
+		SupportFiles:   bundle.SupportFiles,
+		Checksum:       bundle.Checksum,
+		RouteCount:     len(bundle.Routes),
+	}, nil
+}
+
+func DiffConfigVersion() (*ConfigDiffResult, error) {
+	bundle, err := buildCurrentConfigBundle(false)
+	if err != nil {
+		return nil, err
+	}
+	result := &ConfigDiffResult{
+		AddedDomains:    []string{},
+		RemovedDomains:  []string{},
+		ModifiedDomains: []string{},
+	}
+	activeVersion, err := model.GetActiveConfigVersion()
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			for _, route := range bundle.SnapshotRoutes {
+				result.AddedDomains = append(result.AddedDomains, route.Domain)
+			}
+			return result, nil
+		}
+		return nil, err
+	}
+	result.ActiveVersion = activeVersion.Version
+	activeRoutes, err := parseSnapshotRoutes(activeVersion.SnapshotJSON)
+	if err != nil {
+		return nil, err
+	}
+	currentMap := make(map[string]snapshotRoute, len(bundle.SnapshotRoutes))
+	for _, route := range bundle.SnapshotRoutes {
+		currentMap[route.Domain] = route
+	}
+	activeMap := make(map[string]snapshotRoute, len(activeRoutes))
+	for _, route := range activeRoutes {
+		activeMap[route.Domain] = route
+	}
+	for domain, currentRoute := range currentMap {
+		activeRoute, ok := activeMap[domain]
+		if !ok {
+			result.AddedDomains = append(result.AddedDomains, domain)
+			continue
+		}
+		if !snapshotRouteConfigEqual(activeRoute, currentRoute) {
+			result.ModifiedDomains = append(result.ModifiedDomains, domain)
+		}
+	}
+	for domain := range activeMap {
+		if _, ok := currentMap[domain]; !ok {
+			result.RemovedDomains = append(result.RemovedDomains, domain)
+		}
+	}
+	sort.Strings(result.AddedDomains)
+	sort.Strings(result.RemovedDomains)
+	sort.Strings(result.ModifiedDomains)
+	return result, nil
+}
+
+func PublishConfigVersion(createdBy string) (*ReleaseResult, error) {
+	bundle, err := buildCurrentConfigBundle(true)
+	if err != nil {
+		return nil, err
+	}
+	if len(bundle.Routes) == 0 {
 		return nil, errors.New("没有可发布的启用规则")
 	}
-	snapshotJSON, err := renderSnapshot(routes)
-	if err != nil {
-		return nil, err
-	}
-	renderedConfig, supportFiles, err := renderNginxConfig(routes)
-	if err != nil {
-		return nil, err
-	}
-	supportFilesJSON, err := json.Marshal(supportFiles)
+	supportFilesJSON, err := json.Marshal(bundle.SupportFiles)
 	if err != nil {
 		return nil, err
 	}
@@ -60,10 +155,10 @@ func PublishConfigVersion(createdBy string) (*ReleaseResult, error) {
 	}
 	record := &model.ConfigVersion{
 		Version:          version,
-		SnapshotJSON:     snapshotJSON,
-		RenderedConfig:   renderedConfig,
+		SnapshotJSON:     bundle.SnapshotJSON,
+		RenderedConfig:   bundle.RenderedConfig,
 		SupportFilesJSON: string(supportFilesJSON),
-		Checksum:         checksumBundle(renderedConfig, supportFiles),
+		Checksum:         bundle.Checksum,
 		IsActive:         true,
 		CreatedBy:        createdBy,
 	}
@@ -84,7 +179,7 @@ func PublishConfigVersion(createdBy string) (*ReleaseResult, error) {
 	}
 	return &ReleaseResult{
 		Version: record,
-		Routes:  routes,
+		Routes:  bundle.Routes,
 	}, nil
 }

@@ -110,26 +205,9 @@ func ActivateConfigVersion(id uint) (*model.ConfigVersion, error) {
 }

 func renderSnapshot(routes []*model.ProxyRoute) (string, error) {
-	type snapshotRoute struct {
-		Domain       string `json:"domain"`
-		OriginURL    string `json:"origin_url"`
-		Enabled      bool   `json:"enabled"`
-		EnableHTTPS  bool   `json:"enable_https"`
-		CertID       *uint  `json:"cert_id,omitempty"`
-		RedirectHTTP bool   `json:"redirect_http"`
-		Remark       string `json:"remark,omitempty"`
-	}
-	items := make([]snapshotRoute, 0, len(routes))
-	for _, route := range routes {
-		items = append(items, snapshotRoute{
-			Domain:    route.Domain,
-			OriginURL: route.OriginURL,
-			Enabled:   route.Enabled,
-			EnableHTTPS: route.EnableHTTPS,
-			CertID: route.CertID,
-			RedirectHTTP: route.RedirectHTTP,
-			Remark:    route.Remark,
-		})
+	items, err := buildSnapshotRoutes(routes)
+	if err != nil {
+		return "", err
 	}
 	data, err := json.Marshal(items)
 	if err != nil {
@@ -143,8 +221,12 @@ func renderNginxConfig(routes []*model.ProxyRoute) (string, []SupportFile, error
 	builder.WriteString("# This file is generated by ATSFlare. Do not edit manually.\n")
 	supportFiles := make([]SupportFile, 0)
 	for _, route := range routes {
+		customHeaders, err := decodeStoredCustomHeaders(route.CustomHeaders)
+		if err != nil {
+			return "", nil, fmt.Errorf("路由 %s 自定义请求头无效", route.Domain)
+		}
 		if !route.EnableHTTPS {
-			builder.WriteString(renderHTTPProxyServer(route.Domain, route.OriginURL))
+			builder.WriteString(renderHTTPProxyServer(route.Domain, route.OriginURL, customHeaders))
 			continue
 		}
 		if route.CertID == nil || *route.CertID == 0 {
@@ -161,13 +243,105 @@ func renderNginxConfig(routes []*model.ProxyRoute) (string, []SupportFile, error
 		if route.RedirectHTTP {
 			builder.WriteString(renderHTTPRedirectServer(route.Domain))
 		} else {
-			builder.WriteString(renderHTTPProxyServer(route.Domain, route.OriginURL))
+			builder.WriteString(renderHTTPProxyServer(route.Domain, route.OriginURL, customHeaders))
 		}
-		builder.WriteString(renderHTTPSServer(route.Domain, route.OriginURL, certificate.ID))
+		builder.WriteString(renderHTTPSServer(route.Domain, route.OriginURL, certificate.ID, customHeaders))
 	}
 	return builder.String(), dedupeSupportFiles(supportFiles), nil
 }

+func buildCurrentConfigBundle(requireRoutes bool) (*configBundle, error) {
+	routes, err := model.GetEnabledProxyRoutes()
+	if err != nil {
+		return nil, err
+	}
+	if requireRoutes && len(routes) == 0 {
+		return nil, errors.New("没有可发布的启用规则")
+	}
+	snapshotRoutes, err := buildSnapshotRoutes(routes)
+	if err != nil {
+		return nil, err
+	}
+	snapshotJSON, err := json.Marshal(snapshotRoutes)
+	if err != nil {
+		return nil, err
+	}
+	renderedConfig, supportFiles, err := renderNginxConfig(routes)
+	if err != nil {
+		return nil, err
+	}
+	return &configBundle{
+		Routes:         routes,
+		SnapshotRoutes: snapshotRoutes,
+		SnapshotJSON:   string(snapshotJSON),
+		RenderedConfig: renderedConfig,
+		SupportFiles:   supportFiles,
+		Checksum:       checksumBundle(renderedConfig, supportFiles),
+	}, nil
+}
+
+func buildSnapshotRoutes(routes []*model.ProxyRoute) ([]snapshotRoute, error) {
+	items := make([]snapshotRoute, 0, len(routes))
+	for _, route := range routes {
+		customHeaders, err := decodeStoredCustomHeaders(route.CustomHeaders)
+		if err != nil {
+			return nil, fmt.Errorf("路由 %s 自定义请求头无效", route.Domain)
+		}
+		items = append(items, snapshotRoute{
+			Domain:        route.Domain,
+			OriginURL:     route.OriginURL,
+			Enabled:       route.Enabled,
+			EnableHTTPS:   route.EnableHTTPS,
+			CertID:        route.CertID,
+			RedirectHTTP:  route.RedirectHTTP,
+			CustomHeaders: customHeaders,
+			Remark:        route.Remark,
+		})
+	}
+	return items, nil
+}
+
+func parseSnapshotRoutes(snapshotJSON string) ([]snapshotRoute, error) {
+	text := strings.TrimSpace(snapshotJSON)
+	if text == "" {
+		return []snapshotRoute{}, nil
+	}
+	var routes []snapshotRoute
+	if err := json.Unmarshal([]byte(text), &routes); err != nil {
+		return nil, errors.New("历史版本快照格式不合法")
+	}
+	for index := range routes {
+		normalizedHeaders, err := normalizeCustomHeaders(routes[index].CustomHeaders)
+		if err != nil {
+			return nil, err
+		}
+		routes[index].CustomHeaders = normalizedHeaders
+	}
+	return routes, nil
+}
+
+func snapshotRouteConfigEqual(left snapshotRoute, right snapshotRoute) bool {
+	if left.Domain != right.Domain || left.OriginURL != right.OriginURL || left.EnableHTTPS != right.EnableHTTPS || left.RedirectHTTP != right.RedirectHTTP || !uintPointerEqual(left.CertID, right.CertID) {
+		return false
+	}
+	if len(left.CustomHeaders) != len(right.CustomHeaders) {
+		return false
+	}
+	for index := range left.CustomHeaders {
+		if left.CustomHeaders[index] != right.CustomHeaders[index] {
+			return false
+		}
+	}
+	return true
+}
+
+func uintPointerEqual(left *uint, right *uint) bool {
+	if left == nil || right == nil {
+		return left == nil && right == nil
+	}
+	return *left == *right
+}
+
 func checksum(content string) string {
 	sum := sha256.Sum256([]byte(content))
 	return hex.EncodeToString(sum[:])
@@ -199,18 +373,36 @@ func nextVersionNumber(now time.Time) (string, error) {
 	return fmt.Sprintf("%s-%03d", prefix, count+1), nil
 }

-func renderHTTPProxyServer(domain string, originURL string) string {
-	return fmt.Sprintf("server {\n    listen 80;\n    server_name %s;\n\n    location / {\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_pass %s;\n    }\n}\n\n", domain, originURL)
+func renderHTTPProxyServer(domain string, originURL string, customHeaders []ProxyRouteCustomHeaderInput) string {
+	return fmt.Sprintf("server {\n    listen 80;\n    server_name %s;\n\n    location / {\n%s        proxy_pass %s;\n    }\n}\n\n", domain, renderProxyHeaderBlock(customHeaders), originURL)
 }

 func renderHTTPRedirectServer(domain string) string {
 	return fmt.Sprintf("server {\n    listen 80;\n    server_name %s;\n\n    return 301 https://$host$request_uri;\n}\n\n", domain)
 }

-func renderHTTPSServer(domain string, originURL string, certificateID uint) string {
+func renderHTTPSServer(domain string, originURL string, certificateID uint, customHeaders []ProxyRouteCustomHeaderInput) string {
 	certPath := fmt.Sprintf("%s/%s", nginxCertDirPlaceholder, certificateCertFileName(certificateID))
 	keyPath := fmt.Sprintf("%s/%s", nginxCertDirPlaceholder, certificateKeyFileName(certificateID))
-	return fmt.Sprintf("server {\n    listen 443 ssl;\n    server_name %s;\n    ssl_certificate %s;\n    ssl_certificate_key %s;\n\n    location / {\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n        proxy_pass %s;\n    }\n}\n\n", domain, certPath, keyPath, originURL)
+	return fmt.Sprintf("server {\n    listen 443 ssl;\n    server_name %s;\n    ssl_certificate %s;\n    ssl_certificate_key %s;\n\n    location / {\n%s        proxy_pass %s;\n    }\n}\n\n", domain, certPath, keyPath, renderProxyHeaderBlock(customHeaders), originURL)
+}
+
+func renderProxyHeaderBlock(customHeaders []ProxyRouteCustomHeaderInput) string {
+	var builder strings.Builder
+	builder.WriteString("        proxy_set_header Host $host;\n")
+	builder.WriteString("        proxy_set_header X-Real-IP $remote_addr;\n")
+	builder.WriteString("        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n")
+	builder.WriteString("        proxy_set_header X-Forwarded-Proto $scheme;\n")
+	for _, header := range customHeaders {
+		builder.WriteString(fmt.Sprintf("        proxy_set_header %s %s;\n", header.Key, quoteNginxHeaderValue(header.Value)))
+	}
+	return builder.String()
+}
+
+func quoteNginxHeaderValue(value string) string {
+	escaped := strings.ReplaceAll(value, `\`, `\\`)
+	escaped = strings.ReplaceAll(escaped, `"`, `\"`)
+	return fmt.Sprintf(`"%s"`, escaped)
 }

 func certificateCertFileName(id uint) string {
@@ -79,6 +79,127 @@ func TestCreateProxyRouteRejectsHTTPSWithoutCertificate(t *testing.T) {
 	}
 }

+func TestPublishConfigVersionRendersCustomHeaders(t *testing.T) {
+	setupServiceTestDB(t)
+
+	_, err := CreateProxyRoute(ProxyRouteInput{
+		Domain:    "custom.example.com",
+		OriginURL: "https://origin.internal",
+		Enabled:   true,
+		CustomHeaders: []ProxyRouteCustomHeaderInput{
+			{Key: "X-Trace-Id", Value: "$request_id"},
+			{Key: "X-Env", Value: "staging edge"},
+		},
+	})
+	if err != nil {
+		t.Fatalf("CreateProxyRoute failed: %v", err)
+	}
+
+	result, err := PublishConfigVersion("root")
+	if err != nil {
+		t.Fatalf("PublishConfigVersion failed: %v", err)
+	}
+	if !strings.Contains(result.Version.RenderedConfig, `proxy_set_header X-Trace-Id "$request_id";`) {
+		t.Fatal("expected rendered config to include custom header")
+	}
+	if !strings.Contains(result.Version.RenderedConfig, `proxy_set_header X-Env "staging edge";`) {
+		t.Fatal("expected rendered config to include quoted custom header value")
+	}
+	if !strings.Contains(result.Version.SnapshotJSON, "custom_headers") {
+		t.Fatal("expected snapshot to include custom headers")
+	}
+}
+
+func TestPreviewAndDiffConfigVersion(t *testing.T) {
+	setupServiceTestDB(t)
+
+	stableRoute, err := CreateProxyRoute(ProxyRouteInput{
+		Domain:    "stable.example.com",
+		OriginURL: "https://origin-a.internal",
+		Enabled:   true,
+	})
+	if err != nil {
+		t.Fatalf("CreateProxyRoute stable failed: %v", err)
+	}
+	modifiedRoute, err := CreateProxyRoute(ProxyRouteInput{
+		Domain:    "api.example.com",
+		OriginURL: "https://origin-api-a.internal",
+		Enabled:   true,
+	})
+	if err != nil {
+		t.Fatalf("CreateProxyRoute modified failed: %v", err)
+	}
+	removedRoute, err := CreateProxyRoute(ProxyRouteInput{
+		Domain:    "old.example.com",
+		OriginURL: "https://origin-old.internal",
+		Enabled:   true,
+	})
+	if err != nil {
+		t.Fatalf("CreateProxyRoute removed failed: %v", err)
+	}
+	if _, err = PublishConfigVersion("root"); err != nil {
+		t.Fatalf("initial PublishConfigVersion failed: %v", err)
+	}
+
+	if _, err = UpdateProxyRoute(modifiedRoute.ID, ProxyRouteInput{
+		Domain:    "api.example.com",
+		OriginURL: "https://origin-api-b.internal",
+		Enabled:   true,
+		CustomHeaders: []ProxyRouteCustomHeaderInput{
+			{Key: "X-Release", Value: "candidate"},
+		},
+	}); err != nil {
+		t.Fatalf("UpdateProxyRoute failed: %v", err)
+	}
+	if _, err = UpdateProxyRoute(removedRoute.ID, ProxyRouteInput{
+		Domain:    "old.example.com",
+		OriginURL: "https://origin-old.internal",
+		Enabled:   false,
+	}); err != nil {
+		t.Fatalf("disable removed route failed: %v", err)
+	}
+	if _, err = CreateProxyRoute(ProxyRouteInput{
+		Domain:    "new.example.com",
+		OriginURL: "https://origin-new.internal",
+		Enabled:   true,
+	}); err != nil {
+		t.Fatalf("CreateProxyRoute new failed: %v", err)
+	}
+	if _, err = UpdateProxyRoute(stableRoute.ID, ProxyRouteInput{
+		Domain:    stableRoute.Domain,
+		OriginURL: stableRoute.OriginURL,
+		Enabled:   true,
+		Remark:    "remark only change",
+	}); err != nil {
+		t.Fatalf("UpdateProxyRoute stable failed: %v", err)
+	}
+
+	preview, err := PreviewConfigVersion()
+	if err != nil {
+		t.Fatalf("PreviewConfigVersion failed: %v", err)
+	}
+	if !strings.Contains(preview.RenderedConfig, `proxy_set_header X-Release "candidate";`) {
+		t.Fatal("expected preview config to include modified custom header")
+	}
+	if preview.RouteCount != 3 {
+		t.Fatalf("expected 3 enabled routes in preview, got %d", preview.RouteCount)
+	}
+
+	diff, err := DiffConfigVersion()
+	if err != nil {
+		t.Fatalf("DiffConfigVersion failed: %v", err)
+	}
+	if len(diff.AddedDomains) != 1 || diff.AddedDomains[0] != "new.example.com" {
+		t.Fatalf("unexpected added domains: %#v", diff.AddedDomains)
+	}
+	if len(diff.RemovedDomains) != 1 || diff.RemovedDomains[0] != "old.example.com" {
+		t.Fatalf("unexpected removed domains: %#v", diff.RemovedDomains)
+	}
+	if len(diff.ModifiedDomains) != 1 || diff.ModifiedDomains[0] != "api.example.com" {
+		t.Fatalf("unexpected modified domains: %#v", diff.ModifiedDomains)
+	}
+}
+
 func TestCreateTLSCertificateRejectsInvalidPEM(t *testing.T) {
 	setupServiceTestDB(t)

@@ -1,20 +1,30 @@
 package service

 import (
+	"encoding/json"
 	"errors"
 	"gin-template/model"
 	"net/url"
+	"regexp"
 	"strings"
 )

+var proxyHeaderKeyPattern = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
+
+type ProxyRouteCustomHeaderInput struct {
+	Key   string `json:"key"`
+	Value string `json:"value"`
+}
+
 type ProxyRouteInput struct {
-	Domain       string `json:"domain"`
-	OriginURL    string `json:"origin_url"`
-	Enabled      bool   `json:"enabled"`
-	EnableHTTPS  bool   `json:"enable_https"`
-	CertID       *uint  `json:"cert_id"`
-	RedirectHTTP bool   `json:"redirect_http"`
-	Remark       string `json:"remark"`
+	Domain        string                        `json:"domain"`
+	OriginURL     string                        `json:"origin_url"`
+	Enabled       bool                          `json:"enabled"`
+	EnableHTTPS   bool                          `json:"enable_https"`
+	CertID        *uint                         `json:"cert_id"`
+	RedirectHTTP  bool                          `json:"redirect_http"`
+	CustomHeaders []ProxyRouteCustomHeaderInput `json:"custom_headers"`
+	Remark        string                        `json:"remark"`
 }

 func ListProxyRoutes() ([]*model.ProxyRoute, error) {
@@ -65,6 +75,14 @@ func buildProxyRoute(route *model.ProxyRoute, input ProxyRouteInput) (*model.Pro
 	domain := strings.ToLower(strings.TrimSpace(input.Domain))
 	originURL := strings.TrimSpace(input.OriginURL)
 	remark := strings.TrimSpace(input.Remark)
+	customHeaders, err := normalizeCustomHeaders(input.CustomHeaders)
+	if err != nil {
+		return nil, err
+	}
+	customHeadersJSON, err := json.Marshal(customHeaders)
+	if err != nil {
+		return nil, err
+	}
 	if domain == "" {
 		return nil, errors.New("域名不能为空")
 	}
@@ -98,10 +116,51 @@ func buildProxyRoute(route *model.ProxyRoute, input ProxyRouteInput) (*model.Pro
 	route.EnableHTTPS = input.EnableHTTPS
 	route.CertID = input.CertID
 	route.RedirectHTTP = input.RedirectHTTP
+	route.CustomHeaders = string(customHeadersJSON)
 	route.Remark = remark
 	return route, nil
 }

+func normalizeCustomHeaders(headers []ProxyRouteCustomHeaderInput) ([]ProxyRouteCustomHeaderInput, error) {
+	if len(headers) == 0 {
+		return []ProxyRouteCustomHeaderInput{}, nil
+	}
+	normalized := make([]ProxyRouteCustomHeaderInput, 0, len(headers))
+	for _, header := range headers {
+		key := strings.TrimSpace(header.Key)
+		value := strings.TrimSpace(header.Value)
+		if key == "" && value == "" {
+			continue
+		}
+		if key == "" {
+			return nil, errors.New("自定义请求头名称不能为空")
+		}
+		if !proxyHeaderKeyPattern.MatchString(key) {
+			return nil, errors.New("自定义请求头名称格式不合法")
+		}
+		if strings.ContainsAny(key, "\r\n") || strings.ContainsAny(value, "\r\n") {
+			return nil, errors.New("自定义请求头不能包含换行")
+		}
+		normalized = append(normalized, ProxyRouteCustomHeaderInput{
+			Key:   key,
+			Value: value,
+		})
+	}
+	return normalized, nil
+}
+
+func decodeStoredCustomHeaders(raw string) ([]ProxyRouteCustomHeaderInput, error) {
+	text := strings.TrimSpace(raw)
+	if text == "" {
+		return []ProxyRouteCustomHeaderInput{}, nil
+	}
+	var headers []ProxyRouteCustomHeaderInput
+	if err := json.Unmarshal([]byte(text), &headers); err != nil {
+		return nil, errors.New("自定义请求头配置格式不合法")
+	}
+	return normalizeCustomHeaders(headers)
+}
+
 func validateOriginURL(raw string) error {
 	if raw == "" {
 		return errors.New("源站地址不能为空")