@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/crypto/pem.go

@@ -0,0 +1,112 @@
+package crypto
+
+import (
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"fmt"
+	"strings"
+)
+
+// NormalizePEM 将管理端常见密钥输入规范化为单个标准 PEM 块。
+func NormalizePEM(value string) (string, error) {
+	normalized := strings.TrimSpace(value)
+	if normalized == "" {
+		return "", fmt.Errorf("PEM value is required")
+	}
+	normalized = strings.ReplaceAll(normalized, "\r\n", "\n")
+	normalized = strings.ReplaceAll(normalized, "\r", "\n")
+	normalized = strings.ReplaceAll(normalized, `\r\n`, "\n")
+	normalized = strings.ReplaceAll(normalized, `\n`, "\n")
+	normalized = strings.ReplaceAll(normalized, `\r`, "\n")
+	if canonical, ok := decodeCanonicalPEM(normalized); ok {
+		return canonical, nil
+	}
+	if rebuilt, ok := rebuildCollapsedPEM(normalized); ok {
+		if canonical, valid := decodeCanonicalPEM(rebuilt); valid {
+			return canonical, nil
+		}
+	}
+
+	body := strings.Join(strings.Fields(normalized), "")
+	der, err := base64.StdEncoding.DecodeString(body)
+	if err != nil || len(der) == 0 {
+		return "", fmt.Errorf("value must contain one PEM block or base64 DER value")
+	}
+	pemType, ok := inferDERPEMType(der)
+	if !ok {
+		return "", fmt.Errorf("base64 value does not contain a supported DER key or certificate")
+	}
+	return string(pem.EncodeToMemory(&pem.Block{Type: pemType, Bytes: der})), nil
+}
+
+func decodeCanonicalPEM(value string) (string, bool) {
+	block, rest := pem.Decode([]byte(value))
+	if block == nil || len(block.Bytes) == 0 || strings.TrimSpace(string(rest)) != "" {
+		return "", false
+	}
+	return string(pem.EncodeToMemory(block)), true
+}
+
+func rebuildCollapsedPEM(value string) (string, bool) {
+	const beginPrefix = "-----BEGIN "
+	beginIndex := strings.Index(value, beginPrefix)
+	if beginIndex < 0 || strings.TrimSpace(value[:beginIndex]) != "" {
+		return "", false
+	}
+	typeStart := beginIndex + len(beginPrefix)
+	typeEndRelative := strings.Index(value[typeStart:], "-----")
+	if typeEndRelative < 0 {
+		return "", false
+	}
+	pemType := strings.TrimSpace(value[typeStart : typeStart+typeEndRelative])
+	if pemType == "" {
+		return "", false
+	}
+	beginMarker := "-----BEGIN " + pemType + "-----"
+	endMarker := "-----END " + pemType + "-----"
+	beginMarkerIndex := strings.Index(value, beginMarker)
+	endMarkerIndex := strings.Index(value, endMarker)
+	if beginMarkerIndex < 0 || endMarkerIndex <= beginMarkerIndex || strings.TrimSpace(value[endMarkerIndex+len(endMarker):]) != "" {
+		return "", false
+	}
+	bodyStart := beginMarkerIndex + len(beginMarker)
+	body := strings.Join(strings.Fields(value[bodyStart:endMarkerIndex]), "")
+	if body == "" {
+		return "", false
+	}
+	return beginMarker + "\n" + wrapPEMBody(body) + "\n" + endMarker + "\n", true
+}
+
+func wrapPEMBody(body string) string {
+	var builder strings.Builder
+	for len(body) > 64 {
+		builder.WriteString(body[:64])
+		builder.WriteByte('\n')
+		body = body[64:]
+	}
+	builder.WriteString(body)
+	return builder.String()
+}
+
+func inferDERPEMType(der []byte) (string, bool) {
+	if _, err := x509.ParsePKCS8PrivateKey(der); err == nil {
+		return "PRIVATE KEY", true
+	}
+	if _, err := x509.ParsePKCS1PrivateKey(der); err == nil {
+		return "RSA PRIVATE KEY", true
+	}
+	if _, err := x509.ParseECPrivateKey(der); err == nil {
+		return "EC PRIVATE KEY", true
+	}
+	if _, err := x509.ParsePKIXPublicKey(der); err == nil {
+		return "PUBLIC KEY", true
+	}
+	if _, err := x509.ParsePKCS1PublicKey(der); err == nil {
+		return "RSA PUBLIC KEY", true
+	}
+	if _, err := x509.ParseCertificate(der); err == nil {
+		return "CERTIFICATE", true
+	}
+	return "", false
+}

package/dist/resources/templates/go-backend/internal/core/crypto/pem_test.go

@@ -0,0 +1,44 @@
+package crypto
+
+import (
+	"crypto/rand"
+	"crypto/rsa"
+	"crypto/x509"
+	"encoding/base64"
+	"encoding/pem"
+	"strings"
+	"testing"
+)
+
+func TestNormalizePEMAcceptsCanonicalBoundaryForms(t *testing.T) {
+	key, err := rsa.GenerateKey(rand.Reader, 1024)
+	if err != nil {
+		t.Fatalf("generate key: %v", err)
+	}
+	der := x509.MarshalPKCS1PrivateKey(key)
+	canonical := string(pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: der}))
+	inputs := []string{
+		canonical,
+		strings.ReplaceAll(canonical, "\n", `\n`),
+		strings.Join(strings.Fields(canonical), " "),
+		base64.StdEncoding.EncodeToString(der),
+	}
+	for _, input := range inputs {
+		normalized, err := NormalizePEM(input)
+		if err != nil {
+			t.Fatalf("normalize PEM input: %v", err)
+		}
+		if normalized != canonical {
+			t.Fatalf("normalized PEM differs from canonical value")
+		}
+	}
+}
+
+func TestNormalizePEMRejectsMultipleBlocksAndTrailingMaterial(t *testing.T) {
+	block := string(pem.EncodeToMemory(&pem.Block{Type: "PUBLIC KEY", Bytes: []byte{1, 2, 3}}))
+	for _, input := range []string{block + block, block + "trailing"} {
+		if _, err := NormalizePEM(input); err == nil {
+			t.Fatalf("invalid PEM accepted: %q", input)
+		}
+	}
+}

package/dist/resources/templates/go-backend/internal/core/crypto/provider.go

@@ -0,0 +1,130 @@
+package crypto
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/google/wire"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// ProviderSet 加密模块 Wire 依赖注入集合
+//
+// 有 EncryptionKey 时使用 AES-256-GCM，无密钥时使用 NoopEncryptor（仅开发环境）。
+var ProviderSet = wire.NewSet(
+	ProvideEncryptor,
+	ProvideEnvelopeEncryptor,
+)
+
+// ProvideEncryptor 从配置中构建加密器
+func ProvideEncryptor(cfg *config.Config, logger *zap.Logger) (Encryptor, error) {
+	if cfg.EncryptionKey == "" {
+		if cfg.IsProduction() {
+			return nil, fmt.Errorf("required config ENCRYPTION_KEY is not set")
+		}
+		logger.Warn("encryption_key is empty, using noop encryptor")
+		return &NoopEncryptor{}, nil
+	}
+	enc, err := NewAesGcmEncryptor(cfg.EncryptionKey)
+	if err != nil {
+		return nil, err
+	}
+	logger.Info("AES-256-GCM encryptor initialized")
+	return enc, nil
+}
+
+// ProvideEnvelopeEncryptor 从活动密钥和只读历史密钥文件构建版本化加密器。
+func ProvideEnvelopeEncryptor(cfg *config.Config, logger *zap.Logger) (EnvelopeEncryptor, error) {
+	if cfg == nil {
+		return nil, fmt.Errorf("config is required")
+	}
+	if strings.TrimSpace(cfg.EncryptionKeyID) == "" {
+		return nil, fmt.Errorf("required config ENCRYPTION_KEY_ID is not set")
+	}
+	if strings.TrimSpace(cfg.EncryptionKey) == "" {
+		return nil, fmt.Errorf("required config ENCRYPTION_KEY is not set")
+	}
+
+	readKeys, err := LoadEnvelopeKeyringFile(cfg.EncryptionKeyringFile, "ENCRYPTION_KEYRING_FILE")
+	if err != nil {
+		return nil, err
+	}
+	keyring, err := NewAESGCMEnvelopeKeyring(cfg.EncryptionKeyID, cfg.EncryptionKey, readKeys)
+	if err != nil {
+		return nil, fmt.Errorf("initialize envelope keyring: %w", err)
+	}
+	logger.Info("AES-256-GCM envelope keyring initialized", zap.String("active_key_id", cfg.EncryptionKeyID))
+	return keyring, nil
+}
+
+// LoadEnvelopeKeyringFile 从受限普通文件读取只读历史密钥。
+func LoadEnvelopeKeyringFile(path, configName string) (map[string]string, error) {
+	path = strings.TrimSpace(path)
+	if path == "" {
+		return nil, nil
+	}
+	configName = strings.TrimSpace(configName)
+	if configName == "" {
+		return nil, fmt.Errorf("envelope keyring config name is required")
+	}
+	info, err := os.Lstat(path)
+	if err != nil {
+		return nil, fmt.Errorf("stat %s: %w", configName, err)
+	}
+	if !info.Mode().IsRegular() || info.Mode()&os.ModeSymlink != 0 {
+		return nil, fmt.Errorf("%s must be a regular file", configName)
+	}
+	if info.Mode().Perm()&0o002 != 0 {
+		return nil, fmt.Errorf("%s must not be world-writable", configName)
+	}
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("open %s: %w", configName, err)
+	}
+	defer file.Close()
+
+	decoder := json.NewDecoder(io.LimitReader(file, 1<<20))
+	first, err := decoder.Token()
+	if err != nil {
+		return nil, fmt.Errorf("decode %s: %w", configName, err)
+	}
+	opening, ok := first.(json.Delim)
+	if !ok || opening != '{' {
+		return nil, fmt.Errorf("%s must contain a JSON object", configName)
+	}
+	keys := make(map[string]string)
+	for decoder.More() {
+		token, err := decoder.Token()
+		if err != nil {
+			return nil, fmt.Errorf("decode %s key: %w", configName, err)
+		}
+		keyID, ok := token.(string)
+		if !ok {
+			return nil, fmt.Errorf("%s contains a non-string key", configName)
+		}
+		var material string
+		if err := decoder.Decode(&material); err != nil {
+			return nil, fmt.Errorf("decode %s key %q: %w", configName, keyID, err)
+		}
+		if existing, duplicate := keys[keyID]; duplicate && existing != material {
+			return nil, fmt.Errorf("%s key %q has conflicting material", configName, keyID)
+		}
+		keys[keyID] = material
+	}
+	closing, err := decoder.Token()
+	if err != nil {
+		return nil, fmt.Errorf("decode %s closing delimiter: %w", configName, err)
+	}
+	if delimiter, ok := closing.(json.Delim); !ok || delimiter != '}' {
+		return nil, fmt.Errorf("%s has an invalid closing delimiter", configName)
+	}
+	if decoder.Decode(&struct{}{}) != io.EOF {
+		return nil, fmt.Errorf("%s contains trailing data", configName)
+	}
+	return keys, nil
+}

package/dist/resources/templates/go-backend/internal/core/crypto/provider_test.go

@@ -0,0 +1,92 @@
+package crypto
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+func TestProvideEnvelopeEncryptor(t *testing.T) {
+	logger := zap.NewNop()
+	directory := t.TempDir()
+	keyringPath := filepath.Join(directory, "keyring.json")
+	require.NoError(t, os.WriteFile(keyringPath, []byte(`{"key-v1":"`+envelopeKeyV1+`"}`), 0o600))
+
+	provider, err := ProvideEnvelopeEncryptor(&config.Config{
+		EncryptionKeyID:       "key-v2",
+		EncryptionKey:         envelopeKeyV2,
+		EncryptionKeyringFile: keyringPath,
+	}, logger)
+	require.NoError(t, err)
+
+	prior, err := NewAESGCMEnvelopeKeyring("key-v1", envelopeKeyV1, nil)
+	require.NoError(t, err)
+	ciphertext, err := prior.EncryptWithAssociatedData("prior", []byte("owner"))
+	require.NoError(t, err)
+	plaintext, err := provider.DecryptWithAssociatedData(ciphertext.Value, []byte("owner"))
+	require.NoError(t, err)
+	assert.Equal(t, "prior", plaintext.Value)
+}
+
+func TestProvideEnvelopeEncryptorValidation(t *testing.T) {
+	logger := zap.NewNop()
+	tests := []struct {
+		name   string
+		config config.Config
+	}{
+		{name: "缺少活动版本", config: config.Config{EncryptionKey: envelopeKeyV2}},
+		{name: "缺少活动密钥", config: config.Config{EncryptionKeyID: "key-v2"}},
+		{name: "活动材料冲突", config: config.Config{
+			EncryptionKeyID: "key-v2",
+			EncryptionKey:   envelopeKeyV2,
+		}},
+	}
+
+	for _, test := range tests[:2] {
+		t.Run(test.name, func(t *testing.T) {
+			provider, err := ProvideEnvelopeEncryptor(&test.config, logger)
+			require.Error(t, err)
+			assert.Nil(t, provider)
+		})
+	}
+
+	directory := t.TempDir()
+	conflictPath := filepath.Join(directory, "conflict.json")
+	require.NoError(t, os.WriteFile(conflictPath, []byte(`{"key-v2":"`+envelopeKeyV1+`"}`), 0o600))
+	provider, err := ProvideEnvelopeEncryptor(&config.Config{
+		EncryptionKeyID:       "key-v2",
+		EncryptionKey:         envelopeKeyV2,
+		EncryptionKeyringFile: conflictPath,
+	}, logger)
+	require.Error(t, err)
+	assert.Nil(t, provider)
+}
+
+func TestReadEnvelopeKeyringFileRejectsUnsafeOrAmbiguousFiles(t *testing.T) {
+	directory := t.TempDir()
+	tests := []struct {
+		name    string
+		content string
+		mode    os.FileMode
+	}{
+		{name: "冲突重复版本", content: `{"key-v1":"` + envelopeKeyV1 + `","key-v1":"` + envelopeKeyV2 + `"}`, mode: 0o600},
+		{name: "非对象", content: `[]`, mode: 0o600},
+		{name: "尾随数据", content: `{} {}`, mode: 0o600},
+		{name: "任何人可写", content: `{}`, mode: 0o602},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			path := filepath.Join(directory, test.name+".json")
+			require.NoError(t, os.WriteFile(path, []byte(test.content), test.mode))
+			require.NoError(t, os.Chmod(path, test.mode))
+			_, err := LoadEnvelopeKeyringFile(path, "ENCRYPTION_KEYRING_FILE")
+			require.Error(t, err)
+		})
+	}
+}

package/dist/resources/templates/go-backend/internal/core/database/base_model.go

@@ -0,0 +1,24 @@
+package database
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+)
+
+// BaseModel 基础模型，所有实体嵌入
+type BaseModel struct {
+	// 主键 ID
+	ID int64 `gorm:"column:id;primaryKey;autoIncrement;comment:主键 ID" json:"id"`
+	// 创建时间
+	CreatedAt time.Time `gorm:"column:created_at;autoCreateTime:milli;comment:创建时间" json:"created_at"`
+	// 更新时间
+	UpdatedAt time.Time `gorm:"column:updated_at;autoUpdateTime:milli;comment:更新时间" json:"updated_at"`
+}
+
+// SoftDeleteModel 支持软删除的基础模型
+type SoftDeleteModel struct {
+	BaseModel
+	// 删除时间
+	DeletedAt gorm.DeletedAt `gorm:"column:deleted_at;index;comment:删除时间" json:"-"`
+}

package/dist/resources/templates/go-backend/internal/core/database/clickhouse.go

@@ -0,0 +1,121 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/ClickHouse/clickhouse-go/v2"
+	"github.com/ClickHouse/clickhouse-go/v2/lib/driver"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/core/config"
+)
+
+// ErrClickHouseDisabled 表示 ClickHouse 由配置显式禁用。
+//
+// 调用方应通过 errors.Is(err, ErrClickHouseDisabled) 区分"禁用"与
+// "拨号失败"：禁用是合法运行状态（CI / 本地开发），fallback 到 Postgres；
+// 拨号失败需 fail-fast。
+var ErrClickHouseDisabled = errors.New("clickhouse: disabled by config")
+
+// ═══════════════════════════════════════════════════════════════
+// ClickHouse 连接工厂（Insights 平台列存数据源）
+//
+// 行业参考：
+//   - clickhouse-go/v2 官方推荐：`clickhouse.Open(opts)` 返回 `driver.Conn`
+//   - Cube.js ClickHouse adapter / Looker BigQuery adapter：连接池 + 心跳
+//
+// 设计要点：
+//   - cfg.Enabled=false → 返回 nil conn（CI / 本地默认行为，调用方需 nil-safe）
+//   - 启用时启动期 ping 一次，失败 fail-fast
+//   - dial / read timeout / 连接池参数全部来自配置
+// ═══════════════════════════════════════════════════════════════
+
+// 连接重试参数（与 Postgres 保持一致）
+const (
+	clickHouseMaxRetries    = 5
+	clickHouseRetryInterval = 2 * time.Second
+)
+
+// NewClickHouseConn 创建 ClickHouse driver.Conn
+//
+// 禁用语义（D6 合规）：cfg.Enabled=false 时返回 (nil, ErrClickHouseDisabled)，
+// 让调用方通过 errors.Is(err, ErrClickHouseDisabled) 显式判定，而非返回
+// `nil, nil` 让 caller 静默 nil-check。FactRouter 收到该 sentinel 即 fallback
+// 到 Postgres；其他错误 fail-fast。
+//
+// 启用时按 cfg 拨号 + ping；失败带指数退避重试（容器编排首启场景）。
+func NewClickHouseConn(cfg *config.ClickHouseConfig, logger *zap.Logger) (driver.Conn, error) {
+	if cfg == nil || !cfg.Enabled {
+		logger.Info("clickhouse disabled, skipping connection (insights queries will fall back to postgres)")
+		return nil, ErrClickHouseDisabled
+	}
+
+	addr := fmt.Sprintf("%s:%d", cfg.Host, cfg.Port)
+
+	opts := &clickhouse.Options{
+		Addr: []string{addr},
+		Auth: clickhouse.Auth{
+			Database: cfg.Database,
+			Username: cfg.Username,
+			Password: cfg.Password,
+		},
+		DialTimeout:     cfg.DialTimeout,
+		ReadTimeout:     cfg.ReadTimeout,
+		MaxOpenConns:    cfg.MaxOpenConns,
+		MaxIdleConns:    cfg.MaxIdleConns,
+		ConnMaxLifetime: cfg.ConnMaxLifetime,
+	}
+	if cfg.Compression {
+		opts.Compression = &clickhouse.Compression{Method: clickhouse.CompressionLZ4}
+	}
+	if cfg.Secure {
+		// 默认 TLS 配置；ClickHouse Cloud / 自签 CA 场景由调用方扩展 opts.TLS
+		opts.Protocol = clickhouse.Native
+	}
+
+	var conn driver.Conn
+	var err error
+	for attempt := 1; attempt <= clickHouseMaxRetries; attempt++ {
+		conn, err = clickhouse.Open(opts)
+		if err == nil {
+			// 启动期 ping，验证连接 + 认证
+			pingCtx, cancel := context.WithTimeout(context.Background(), cfg.DialTimeout)
+			pingErr := conn.Ping(pingCtx)
+			cancel()
+			if pingErr == nil {
+				break
+			}
+			err = fmt.Errorf("ping: %w", pingErr)
+			_ = conn.Close()
+		}
+		if attempt < clickHouseMaxRetries {
+			delay := clickHouseRetryInterval * time.Duration(attempt)
+			logger.Warn("clickhouse connection failed, retrying",
+				zap.Int("attempt", attempt),
+				zap.Duration("next_retry_in", delay),
+				zap.String("addr", addr),
+				zap.Error(err),
+			)
+			time.Sleep(delay)
+		}
+	}
+	if err != nil {
+		return nil, fmt.Errorf("connect clickhouse after %d attempts: %w", clickHouseMaxRetries, err)
+	}
+
+	logger.Info("clickhouse connection established",
+		zap.String("addr", addr),
+		zap.String("database", cfg.Database),
+	)
+	return conn, nil
+}
+
+// ProvideClickHouseConfig Wire helper：从 Config 提取 ClickHouseConfig 指针
+//
+// 单独 provider 函数让 Wire 自动绑定，避免在每个 cmd/ injector 中重复手动构造。
+func ProvideClickHouseConfig(cfg *config.Config) *config.ClickHouseConfig {
+	return &cfg.ClickHouse
+}

package/dist/resources/templates/go-backend/internal/core/database/database.go

@@ -0,0 +1,112 @@
+package database
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"go.uber.org/zap"
+	"gorm.io/driver/postgres"
+	"gorm.io/gorm"
+	gormlogger "gorm.io/gorm/logger"
+	"gorm.io/gorm/schema"
+	"moul.io/zapgorm2"
+
+	"{{module}}/internal/core/config"
+	"{{module}}/internal/core/observability"
+)
+
+type parameterizedGORMLogger struct {
+	gormlogger.Interface
+}
+
+func (l parameterizedGORMLogger) LogMode(level gormlogger.LogLevel) gormlogger.Interface {
+	return parameterizedGORMLogger{Interface: l.Interface.LogMode(level)}
+}
+
+func (l parameterizedGORMLogger) ParamsFilter(_ context.Context, query string, _ ...interface{}) (string, []interface{}) {
+	return query, nil
+}
+
+func newGORMLogger(logger *zap.Logger, verbose bool) gormlogger.Interface {
+	gormLogger := zapgorm2.New(logger)
+	gormLogger.IgnoreRecordNotFoundError = true
+	if verbose {
+		gormLogger.LogLevel = gormlogger.Info
+		return parameterizedGORMLogger{Interface: gormLogger}
+	}
+	gormLogger.LogLevel = gormlogger.Warn
+	return parameterizedGORMLogger{Interface: gormLogger}
+}
+
+// 数据库连接重试参数（Docker/K8s 环境下多服务并发启动时，PostgreSQL 可能暂时拒绝连接）
+const (
+	dbMaxRetries    = 5
+	dbRetryInterval = 2 * time.Second
+)
+
+// NewDB 创建 GORM 数据库连接，带指数退避重试
+func NewDB(cfg *config.DatabaseConfig, logger *zap.Logger, metrics *observability.MetricsService) (*gorm.DB, error) {
+	dsn := fmt.Sprintf(
+		"host=%s port=%d user=%s password=%s dbname=%s sslmode=%s TimeZone=Asia/Shanghai",
+		cfg.Host, cfg.Port, cfg.Username, cfg.Password, cfg.Name, sslMode(cfg.SSL),
+	)
+
+	gormCfg := &gorm.Config{
+		Logger:                                   newGORMLogger(logger, cfg.Logging),
+		NamingStrategy:                           schema.NamingStrategy{SingularTable: true},
+		DisableForeignKeyConstraintWhenMigrating: true,
+	}
+
+	// 带重试的连接：容器编排环境中 PostgreSQL 可能暂时不可达
+	var db *gorm.DB
+	var err error
+	for attempt := 1; attempt <= dbMaxRetries; attempt++ {
+		db, err = gorm.Open(postgres.Open(dsn), gormCfg)
+		if err == nil {
+			break
+		}
+		if attempt < dbMaxRetries {
+			delay := dbRetryInterval * time.Duration(attempt)
+			logger.Warn("database connection failed, retrying",
+				zap.Int("attempt", attempt),
+				zap.Duration("next_retry_in", delay),
+				zap.Error(err),
+			)
+			time.Sleep(delay)
+		}
+	}
+	if err != nil {
+		return nil, fmt.Errorf("connect database after %d attempts: %w", dbMaxRetries, err)
+	}
+
+	sqlDB, err := db.DB()
+	if err != nil {
+		return nil, fmt.Errorf("get sql.DB: %w", err)
+	}
+
+	sqlDB.SetMaxOpenConns(cfg.MaxOpenConns)
+	sqlDB.SetMaxIdleConns(cfg.MaxIdleConns)
+	if cfg.ConnMaxLifetime > 0 {
+		sqlDB.SetConnMaxLifetime(cfg.ConnMaxLifetime)
+	}
+	// 空闲连接超时：防止 PostgreSQL 侧或网络层断开后 Go 侧仍使用坏连接（driver: bad connection）
+	if cfg.ConnMaxIdleTime > 0 {
+		sqlDB.SetConnMaxIdleTime(cfg.ConnMaxIdleTime)
+	}
+
+	// 注册查询指标采集插件
+	if err := db.Use(NewMetricsPlugin(metrics)); err != nil {
+		return nil, errors.Join(fmt.Errorf("register metrics plugin: %w", err), sqlDB.Close())
+	}
+
+	return db, nil
+}
+
+func sslMode(ssl bool) string {
+	if ssl {
+		return "require"
+	}
+	return "disable"
+}