refactor(nginx): 抽取共享 Nginx 模板包并发布 v1.5.1

2026-09-28 15:37:14 +08:00
parent faf43293e5
commit 1ada58af02
17 changed files with 437 additions and 130 deletions
@@ -0,0 +1,176 @@
+// Package nginxtmpl 提供本机 Nginx 与公网 Agent 共用的纯文本模板函数。
+//
+// 这里只做字符串渲染，不读文件、不执行进程、不依赖业务模型，
+// 因此 internal/nginx 与 internal/agent 都可以安全导入而不产生循环依赖。
+package nginxtmpl
+
+import (
+	"fmt"
+	"strings"
+)
+
+// DefaultIndent 是 Nginx server 块内指令的默认缩进。
+const DefaultIndent = "    "
+
+// TLSConfig 描述证书与 TLS 协议版本偏好。
+type TLSConfig struct {
+	CertPath  string
+	KeyPath   string
+	TLS13Only bool
+}
+
+// SecurityHeaders 描述安全响应头；HTTPS 为 false 时不输出 HSTS。
+type SecurityHeaders struct {
+	Enabled           bool
+	HTTPS             bool
+	HSTSMaxAgeSeconds int
+}
+
+// AccessControl 描述 allow / deny 顺序；Allow 非空时末尾自动追加 deny all。
+// ChinaDeny 是可选的完整指令片段，插在 deny 黑名单之后、allow 白名单之前，
+// 让两端共享顺序结构，同时保留各自的 geo 变量名。
+type AccessControl struct {
+	Allow     []string
+	Deny      []string
+	ChinaDeny string
+}
+
+// LimitConfig 描述 location 级限流指令；Zone 是已合法化的 zone 前缀。
+type LimitConfig struct {
+	Zone  string
+	Rate  int
+	Burst int
+	Conn  int
+}
+
+// SSLDirectives 生成证书与 TLS 协议指令，缩进固定为 server 块内层级。
+func SSLDirectives(cfg TLSConfig) string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "%sssl_certificate %s;\n", DefaultIndent, cfg.CertPath)
+	fmt.Fprintf(&b, "%sssl_certificate_key %s;\n", DefaultIndent, cfg.KeyPath)
+	if cfg.TLS13Only {
+		fmt.Fprintf(&b, "%sssl_protocols TLSv1.3;\n", DefaultIndent)
+		return b.String()
+	}
+	fmt.Fprintf(&b, "%sssl_protocols TLSv1.2 TLSv1.3;\n", DefaultIndent)
+	return b.String()
+}
+
+// ServerSecurityHeaders 生成统一的安全响应头；HSTS 只在 HTTPS 且 Enabled 时输出。
+func ServerSecurityHeaders(cfg SecurityHeaders) string {
+	if !cfg.Enabled || !cfg.HTTPS {
+		return ""
+	}
+	maxAge := cfg.HSTSMaxAgeSeconds
+	if maxAge <= 0 {
+		maxAge = 31536000
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "%sadd_header Strict-Transport-Security \"max-age=%d; includeSubDomains\" always;\n", DefaultIndent, maxAge)
+	fmt.Fprintf(&b, "%sadd_header X-Content-Type-Options \"nosniff\" always;\n", DefaultIndent)
+	fmt.Fprintf(&b, "%sadd_header X-Frame-Options \"SAMEORIGIN\" always;\n", DefaultIndent)
+	fmt.Fprintf(&b, "%sadd_header Referrer-Policy \"strict-origin-when-cross-origin\" always;\n", DefaultIndent)
+	return b.String()
+}
+
+// AccessDirectives 生成 allow / deny：先 deny 黑名单，再 allow 白名单，最后 deny all。
+func AccessDirectives(cfg AccessControl, indent string) string {
+	var b strings.Builder
+	for _, ip := range cfg.Deny {
+		if ip = strings.TrimSpace(ip); ip != "" {
+			fmt.Fprintf(&b, "%sdeny %s;\n", indent, ip)
+		}
+	}
+	b.WriteString(strings.TrimRight(cfg.ChinaDeny, "\n"))
+	if strings.TrimSpace(cfg.ChinaDeny) != "" {
+		b.WriteString("\n")
+	}
+	allowCount := 0
+	for _, ip := range cfg.Allow {
+		if ip = strings.TrimSpace(ip); ip != "" {
+			fmt.Fprintf(&b, "%sallow %s;\n", indent, ip)
+			allowCount++
+		}
+	}
+	if allowCount > 0 {
+		fmt.Fprintf(&b, "%sdeny all;\n", indent)
+	}
+	return b.String()
+}
+
+// LimitDirectives 生成 location 级限流指令：连接数在前，请求速率在后。
+func LimitDirectives(cfg LimitConfig, indent string) string {
+	zone := strings.TrimSpace(cfg.Zone)
+	if zone == "" {
+		return ""
+	}
+	var b strings.Builder
+	if cfg.Conn > 0 {
+		fmt.Fprintf(&b, "%slimit_conn %s_conn %d;\n", indent, zone, cfg.Conn)
+	}
+	if cfg.Rate > 0 {
+		if cfg.Burst > 0 {
+			fmt.Fprintf(&b, "%slimit_req zone=%s_req burst=%d nodelay;\n", indent, zone, cfg.Burst)
+		} else {
+			fmt.Fprintf(&b, "%slimit_req zone=%s_req nodelay;\n", indent, zone)
+		}
+	}
+	return b.String()
+}
+
+// UpgradeHeaders 生成 WebSocket 代理头；connectionExpr 由调用方提供（map 变量或字面量）。
+// proxy_http_version 由调用方保留在原有位置，避免改变既有输出顺序。
+func UpgradeHeaders(indent, connectionExpr string) string {
+	connectionExpr = strings.TrimSpace(connectionExpr)
+	if connectionExpr == "" {
+		connectionExpr = "$connection_upgrade"
+	}
+	var b strings.Builder
+	fmt.Fprintf(&b, "%sproxy_set_header Upgrade $http_upgrade;\n", indent)
+	fmt.Fprintf(&b, "%sproxy_set_header Connection %s;\n", indent, connectionExpr)
+	return b.String()
+}
+
+// RateLimitZone 生成 http 上下文的请求速率 zone 定义；zone 需包含完整后缀。
+func RateLimitZone(zone string, rate int) string {
+	zone = strings.TrimSpace(zone)
+	if zone == "" || rate <= 0 {
+		return ""
+	}
+	return fmt.Sprintf("limit_req_zone $binary_remote_addr zone=%s:10m rate=%dr/s;\n", zone, rate)
+}
+
+// ConnLimitZone 生成 http 上下文的连接数 zone 定义；zone 需包含完整后缀。
+func ConnLimitZone(zone string) string {
+	zone = strings.TrimSpace(zone)
+	if zone == "" {
+		return ""
+	}
+	return fmt.Sprintf("limit_conn_zone $binary_remote_addr zone=%s:10m;\n", zone)
+}
+
+// ZoneName 把前缀与片段合法化为 zone 名：只保留小写字母与数字，其余换成下划线。
+func ZoneName(prefix string, parts ...string) string {
+	var b strings.Builder
+	writeZonePart(&b, prefix)
+	for _, part := range parts {
+		if strings.TrimSpace(part) == "" {
+			continue
+		}
+		if b.Len() > 0 {
+			b.WriteByte('_')
+		}
+		writeZonePart(&b, part)
+	}
+	return b.String()
+}
+
+func writeZonePart(b *strings.Builder, part string) {
+	for _, r := range strings.ToLower(part) {
+		if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') {
+			b.WriteRune(r)
+			continue
+		}
+		b.WriteByte('_')
+	}
+}