chore(init): 初始化解忧商行项目并完成 Phase 0 基座

This commit is contained in:
yml2213
2026-10-30 11:46:10 +08:00
commit 8d9481c251
689 changed files with 138703 additions and 0 deletions
+275
View File
@@ -0,0 +1,275 @@
package config
import (
"errors"
"os"
"strconv"
"strings"
"time"
)
type Config struct {
AppEnv string
AppAddr string
MySQLDSN string
RedisAddr string
RedisPassword string
RedisDB int
JWTSecret string
PaymentConfigEncryptionKey string
FieldEncryptionKey string
FieldEncryptionLegacyKey string
ExternalUploadSecret string
ExternalUploadAllowedIPs []string
BootstrapAdminUsername string
BootstrapAdminPassword string
BootstrapAdminNickname string
Storage StorageConfig
StorageMirror StorageConfig
SMS SMSConfig
Realname RealnameConfig
Log LogConfig
RateLimit RateLimitConfig
Database DatabaseConfig
BackupStatusFile string
}
type StorageConfig struct {
Endpoint string
Bucket string
AccessKeyID string
SecretAccessKey string
Region string
BucketLookup string
}
type SMSConfig struct {
Provider string
AliyunAccessKeyID string
AliyunAccessKeySecret string
AliyunEndpoint string
AliyunSignName string
AliyunLoginTemplateCode string
}
type RealnameConfig struct {
Provider string
CloudMarketURL string
CloudMarketAppCode string
// IDHashKey 用于计算身份证号盲索引;留空时回退到 FIELD_ENCRYPTION_KEY。
IDHashKey string
}
type LogConfig struct {
Level string
Dir string
EnableConsole bool
EnableFile bool
// RetainDays 日志保留天数(含当天);过期的 .log / .log.gz 会被清理。0 表示不自动清理。
RetainDays int
}
type RateLimitConfig struct {
Enabled bool
RequestsPerMinute int
}
type DatabaseConfig struct {
MaxOpenConns int
MaxIdleConns int
ConnMaxLifetime time.Duration
ConnMaxIdleTime time.Duration
SlowQueryThreshold time.Duration
}
func Load() Config {
return Config{
AppEnv: getEnv("APP_ENV", "development"),
AppAddr: getEnv("APP_ADDR", ":18088"),
MySQLDSN: getEnv("MYSQL_DSN", "hfb:secret@tcp(127.0.0.1:13306)/hfb_sys?charset=utf8mb4&parseTime=True&loc=Local"),
RedisAddr: getEnv("REDIS_ADDR", "127.0.0.1:16379"),
RedisPassword: getEnv("REDIS_PASSWORD", ""),
RedisDB: getEnvInt("REDIS_DB", 0),
JWTSecret: getEnv("JWT_SECRET", "change-me"),
PaymentConfigEncryptionKey: getEnv("PAYMENT_CONFIG_ENCRYPTION_KEY", ""),
FieldEncryptionKey: getEnv("FIELD_ENCRYPTION_KEY", ""),
// 旧密钥回退:生产环境必须显式设置(空 = 禁用回退,用于密钥轮换收敛);
// 非生产默认填历史硬编码密钥,兼容开发/测试库的存量密文。不能用 getEnv 的 fallback——
// 那样生产删掉 env 会重新注入已泄露的硬编码密钥,破坏轮换闭环。
FieldEncryptionLegacyKey: fieldEncryptionLegacyKey(getEnv("APP_ENV", "development")),
ExternalUploadSecret: getEnv("EXTERNAL_UPLOAD_SECRET", ""),
ExternalUploadAllowedIPs: getEnvList("EXTERNAL_UPLOAD_ALLOWED_IPS"),
BootstrapAdminUsername: getEnv("ADMIN_BOOTSTRAP_USERNAME", ""),
BootstrapAdminPassword: getEnv("ADMIN_BOOTSTRAP_PASSWORD", ""),
BootstrapAdminNickname: getEnv("ADMIN_BOOTSTRAP_NICKNAME", "超级管理员"),
Storage: StorageConfig{
Endpoint: getEnv("STORAGE_ENDPOINT", "http://localhost:19090"),
Bucket: getEnv("STORAGE_BUCKET", "hfb-sys"),
AccessKeyID: getEnv("STORAGE_ACCESS_KEY_ID", "minioadmin"),
SecretAccessKey: getEnv("STORAGE_SECRET_ACCESS_KEY", "minioadmin"),
Region: getEnv("STORAGE_REGION", ""),
BucketLookup: getEnv("STORAGE_BUCKET_LOOKUP", "auto"),
},
// StorageMirror 仅在对象存储迁移期间使用。镜像端配置完整时,新上传文件会同步写入两个存储端。
StorageMirror: StorageConfig{
Endpoint: getEnv("STORAGE_MIRROR_ENDPOINT", ""),
Bucket: getEnv("STORAGE_MIRROR_BUCKET", ""),
AccessKeyID: getEnv("STORAGE_MIRROR_ACCESS_KEY_ID", ""),
SecretAccessKey: getEnv("STORAGE_MIRROR_SECRET_ACCESS_KEY", ""),
Region: getEnv("STORAGE_MIRROR_REGION", ""),
BucketLookup: getEnv("STORAGE_MIRROR_BUCKET_LOOKUP", "auto"),
},
SMS: SMSConfig{
Provider: getEnv("SMS_PROVIDER", "mock"),
AliyunAccessKeyID: getEnv("ALIYUN_ACCESS_KEY_ID", ""),
AliyunAccessKeySecret: getEnv("ALIYUN_ACCESS_KEY_SECRET", ""),
AliyunEndpoint: getEnv("ALIYUN_SMS_ENDPOINT", "dysmsapi.aliyuncs.com"),
AliyunSignName: getEnv("ALIYUN_SMS_SIGN_NAME", ""),
AliyunLoginTemplateCode: getEnv("ALIYUN_SMS_LOGIN_TEMPLATE_CODE", ""),
},
Realname: RealnameConfig{
Provider: getEnv("REALNAME_PROVIDER", "mock"),
CloudMarketURL: getEnv("REALNAME_CLOUDMARKET_URL", "https://eid.shumaidata.com/eid/check"),
CloudMarketAppCode: getEnv("REALNAME_CLOUDMARKET_APPCODE", ""),
IDHashKey: getEnv("REALNAME_ID_HASH_KEY", ""),
},
Log: LogConfig{
Level: getEnv("LOG_LEVEL", "info"),
Dir: getEnv("LOG_DIR", "logs"),
EnableConsole: getEnvBool("LOG_ENABLE_CONSOLE", true),
EnableFile: getEnvBool("LOG_ENABLE_FILE", true),
RetainDays: getEnvInt("LOG_RETAIN_DAYS", 14),
},
RateLimit: RateLimitConfig{
Enabled: getEnvBool("RATE_LIMIT_ENABLED", true),
RequestsPerMinute: getEnvInt("RATE_LIMIT_REQUESTS_PER_MINUTE", 300),
},
Database: DatabaseConfig{
MaxOpenConns: getEnvIntMin("DATABASE_MAX_OPEN_CONNS", 50, 1),
MaxIdleConns: getEnvIntMin("DATABASE_MAX_IDLE_CONNS", 10, 0),
ConnMaxLifetime: time.Duration(getEnvIntMin("DATABASE_CONN_MAX_LIFETIME_MINUTES", 30, 1)) * time.Minute,
ConnMaxIdleTime: time.Duration(getEnvIntMin("DATABASE_CONN_MAX_IDLE_TIME_MINUTES", 5, 0)) * time.Minute,
SlowQueryThreshold: time.Duration(getEnvIntMin("DATABASE_SLOW_QUERY_THRESHOLD_MS", 500, 1)) * time.Millisecond,
},
BackupStatusFile: getEnv("BACKUP_STATUS_FILE", "/var/run/hfb-backup-status/status.json"),
}
}
func (c Config) ValidateProductionSecurity() error {
if !IsProductionEnv(c.AppEnv) {
return nil
}
if !strings.EqualFold(strings.TrimSpace(c.SMS.Provider), "aliyun") {
return errors.New("SMS_PROVIDER must be aliyun in production")
}
if strings.TrimSpace(c.SMS.AliyunAccessKeyID) == "" || strings.TrimSpace(c.SMS.AliyunAccessKeySecret) == "" ||
strings.TrimSpace(c.SMS.AliyunSignName) == "" || strings.TrimSpace(c.SMS.AliyunLoginTemplateCode) == "" {
return errors.New("aliyun SMS credentials, sign name, and template code are required in production")
}
if strings.TrimSpace(c.JWTSecret) == "" || isPlaceholder(c.JWTSecret) || len([]byte(c.JWTSecret)) < 32 {
return errors.New("JWT_SECRET must be a non-default random value of at least 32 bytes in production")
}
keyLen := len([]byte(c.PaymentConfigEncryptionKey))
if isPlaceholder(c.PaymentConfigEncryptionKey) || (keyLen != 16 && keyLen != 24 && keyLen != 32) {
return errors.New("PAYMENT_CONFIG_ENCRYPTION_KEY must be 16, 24, or 32 bytes in production")
}
fieldKeyLen := len([]byte(c.FieldEncryptionKey))
if c.FieldEncryptionKey == "" || isPlaceholder(c.FieldEncryptionKey) || (fieldKeyLen != 16 && fieldKeyLen != 24 && fieldKeyLen != 32) {
return errors.New("FIELD_ENCRYPTION_KEY must be 16, 24, or 32 bytes in production")
}
legacyKeyLen := len([]byte(c.FieldEncryptionLegacyKey))
if c.FieldEncryptionLegacyKey != "" && (isPlaceholder(c.FieldEncryptionLegacyKey) || (legacyKeyLen != 16 && legacyKeyLen != 24 && legacyKeyLen != 32)) {
return errors.New("FIELD_ENCRYPTION_LEGACY_KEY must be empty or 16, 24, or 32 bytes in production")
}
if c.FieldEncryptionKey == c.FieldEncryptionLegacyKey {
return errors.New("FIELD_ENCRYPTION_KEY must differ from FIELD_ENCRYPTION_LEGACY_KEY in production (set a new primary key to rotate)")
}
if c.BootstrapAdminPassword != "" && isPlaceholder(c.BootstrapAdminPassword) {
return errors.New("ADMIN_BOOTSTRAP_PASSWORD must not use the example placeholder in production")
}
return nil
}
func getEnv(key, fallback string) string {
value := os.Getenv(key)
if value == "" {
return fallback
}
return value
}
// historicFieldEncryptionKey 是迁移前 pkg/crypto 的硬编码密钥,仅用于解密历史存量密文。
const historicFieldEncryptionKey = "hfb-sys-2024-secret-key-32bytes!"
// fieldEncryptionLegacyKey 解析 FIELD_ENCRYPTION_LEGACY_KEY:
// - 生产环境:必须显式设置,空表示禁用回退(密钥轮换收敛后删除 env 即关闭旧密钥)。
// 不能用硬编码默认值,否则轮换闭环不成立。
// - 非生产环境:未设置时回退到历史硬编码密钥,兼容开发/测试库的存量密文(零配置)。
func fieldEncryptionLegacyKey(appEnv string) string {
if IsProductionEnv(appEnv) {
// 生产显式空 = 禁用;未设置也视为禁用。
return os.Getenv("FIELD_ENCRYPTION_LEGACY_KEY")
}
if v := os.Getenv("FIELD_ENCRYPTION_LEGACY_KEY"); v != "" {
return v
}
return historicFieldEncryptionKey
}
func getEnvInt(key string, fallback int) int {
value := os.Getenv(key)
if value == "" {
return fallback
}
parsed, err := strconv.Atoi(value)
if err != nil {
return fallback
}
return parsed
}
func getEnvIntMin(key string, fallback, minimum int) int {
value := getEnvInt(key, fallback)
if value < minimum {
return fallback
}
return value
}
func getEnvBool(key string, fallback bool) bool {
value := os.Getenv(key)
if value == "" {
return fallback
}
parsed, err := strconv.ParseBool(value)
if err != nil {
return fallback
}
return parsed
}
func getEnvList(key string) []string {
raw := os.Getenv(key)
if raw == "" {
return nil
}
parts := strings.Split(raw, ",")
values := make([]string, 0, len(parts))
for _, part := range parts {
value := strings.TrimSpace(part)
if value != "" {
values = append(values, value)
}
}
return values
}
func isPlaceholder(value string) bool {
normalized := strings.ToLower(strings.TrimSpace(value))
return normalized == "change-me" || strings.HasPrefix(normalized, "change-") || strings.Contains(normalized, "change-to-")
}
// IsProductionEnv 判断 AppEnv 是否为生产环境(与 ValidateProductionSecurity 同口径)。
func IsProductionEnv(appEnv string) bool {
return strings.ToLower(strings.TrimSpace(appEnv)) == "production"
}
+139
View File
@@ -0,0 +1,139 @@
package config
import (
"os"
"testing"
)
const historicKey = "hfb-sys-2024-secret-key-32bytes!"
func TestIsProductionEnv(t *testing.T) {
cases := []struct {
in string
want bool
}{
{"production", true},
{"PRODUCTION", true},
{" production ", true},
{"development", false},
{"", false},
{"staging", false},
}
for _, c := range cases {
if got := IsProductionEnv(c.in); got != c.want {
t.Fatalf("IsProductionEnv(%q) = %v, want %v", c.in, got, c.want)
}
}
}
func TestLoadDatabaseConfigFromEnvironment(t *testing.T) {
t.Setenv("DATABASE_MAX_OPEN_CONNS", "80")
t.Setenv("DATABASE_MAX_IDLE_CONNS", "16")
t.Setenv("DATABASE_CONN_MAX_LIFETIME_MINUTES", "45")
t.Setenv("DATABASE_CONN_MAX_IDLE_TIME_MINUTES", "7")
t.Setenv("DATABASE_SLOW_QUERY_THRESHOLD_MS", "750")
cfg := Load()
if cfg.Database.MaxOpenConns != 80 || cfg.Database.MaxIdleConns != 16 {
t.Fatalf("database pool = %+v, want open=80 idle=16", cfg.Database)
}
if cfg.Database.ConnMaxLifetime.Minutes() != 45 || cfg.Database.ConnMaxIdleTime.Minutes() != 7 {
t.Fatalf("database lifetimes = %s/%s, want 45m/7m", cfg.Database.ConnMaxLifetime, cfg.Database.ConnMaxIdleTime)
}
if cfg.Database.SlowQueryThreshold.Milliseconds() != 750 {
t.Fatalf("slow query threshold = %s, want 750ms", cfg.Database.SlowQueryThreshold)
}
}
func TestLoadDatabaseConfigInvalidValuesUseDefaults(t *testing.T) {
t.Setenv("DATABASE_MAX_OPEN_CONNS", "0")
t.Setenv("DATABASE_MAX_IDLE_CONNS", "-1")
t.Setenv("DATABASE_CONN_MAX_LIFETIME_MINUTES", "0")
t.Setenv("DATABASE_CONN_MAX_IDLE_TIME_MINUTES", "-1")
t.Setenv("DATABASE_SLOW_QUERY_THRESHOLD_MS", "0")
cfg := Load()
if cfg.Database.MaxOpenConns != 50 || cfg.Database.MaxIdleConns != 10 {
t.Fatalf("invalid pool values = %+v, want defaults open=50 idle=10", cfg.Database)
}
if cfg.Database.ConnMaxLifetime.Minutes() != 30 || cfg.Database.ConnMaxIdleTime.Minutes() != 5 || cfg.Database.SlowQueryThreshold.Milliseconds() != 500 {
t.Fatalf("invalid database durations = %+v, want defaults", cfg.Database)
}
}
// TestFieldEncryptionLegacyKeyNonProductionDefaultsToHistoric 验证非生产环境未设置 legacy 时
// 回退到历史硬编码密钥(开发态零配置兼容旧密文)。
func TestFieldEncryptionLegacyKeyNonProductionDefaultsToHistoric(t *testing.T) {
unsetEnv(t, "FIELD_ENCRYPTION_LEGACY_KEY")
if got := fieldEncryptionLegacyKey("development"); got != historicKey {
t.Fatalf("non-production default legacy = %q, want %q", got, historicKey)
}
}
// TestFieldEncryptionLegacyKeyNonProductionExplicitOverride 验证非生产环境显式设置 legacy 时用该值。
func TestFieldEncryptionLegacyKeyNonProductionExplicitOverride(t *testing.T) {
t.Setenv("FIELD_ENCRYPTION_LEGACY_KEY", "explicit-legacy-16bytes!")
if got := fieldEncryptionLegacyKey("development"); got != "explicit-legacy-16bytes!" {
t.Fatalf("non-production explicit legacy = %q, want explicit-legacy-16bytes!", got)
}
}
// TestFieldEncryptionLegacyKeyProductionEmptyDisablesFallback 验证生产环境未设置/留空 legacy
// 返回空(禁用回退),而不是注入历史硬编码密钥。
// 这是密钥轮换闭环的关键:删除 env 必须真正关闭旧密钥。
func TestFieldEncryptionLegacyKeyProductionEmptyDisablesFallback(t *testing.T) {
t.Setenv("FIELD_ENCRYPTION_LEGACY_KEY", "")
if got := fieldEncryptionLegacyKey("production"); got != "" {
t.Fatalf("production empty legacy = %q, want empty (fallback disabled); injecting historic key breaks rotation closure", got)
}
}
// TestFieldEncryptionLegacyKeyProductionExplicitValue 验证生产环境显式设置 legacy 时用该值
// (轮换期间保留旧密钥解密存量)。
func TestFieldEncryptionLegacyKeyProductionExplicitValue(t *testing.T) {
t.Setenv("FIELD_ENCRYPTION_LEGACY_KEY", "prod-old-key-32bytes-0123456789")
if got := fieldEncryptionLegacyKey("production"); got != "prod-old-key-32bytes-0123456789" {
t.Fatalf("production explicit legacy = %q, want prod-old-key-32bytes-0123456789", got)
}
}
// TestValidateProductionSecurityRejectsPrimaryEqualsLegacy 验证生产环境 primary 等于 legacy 时报错。
func TestValidateProductionSecurityRejectsPrimaryEqualsLegacy(t *testing.T) {
t.Setenv("APP_ENV", "production")
t.Setenv("JWT_SECRET", "a-very-long-random-jwt-secret-at-least-32-bytes!!")
t.Setenv("PAYMENT_CONFIG_ENCRYPTION_KEY", "0123456789abcdef0123456789abcdef")
t.Setenv("FIELD_ENCRYPTION_KEY", "0123456789abcdef0123456789abcdef")
t.Setenv("FIELD_ENCRYPTION_LEGACY_KEY", "0123456789abcdef0123456789abcdef")
cfg := Load()
if err := cfg.ValidateProductionSecurity(); err == nil {
t.Fatal("ValidateProductionSecurity should reject FIELD_ENCRYPTION_KEY == LEGACY_KEY")
}
}
// TestValidateProductionSecurityRejectsInvalidLegacyKey 验证生产环境显式设置 legacy 时也校验长度。
func TestValidateProductionSecurityRejectsInvalidLegacyKey(t *testing.T) {
t.Setenv("APP_ENV", "PRODUCTION")
t.Setenv("JWT_SECRET", "a-very-long-random-jwt-secret-at-least-32-bytes!!")
t.Setenv("PAYMENT_CONFIG_ENCRYPTION_KEY", "0123456789abcdef0123456789abcdef")
t.Setenv("FIELD_ENCRYPTION_KEY", "abcdef0123456789abcdef0123456789")
t.Setenv("FIELD_ENCRYPTION_LEGACY_KEY", "too-short")
cfg := Load()
if err := cfg.ValidateProductionSecurity(); err == nil {
t.Fatal("ValidateProductionSecurity should reject invalid FIELD_ENCRYPTION_LEGACY_KEY")
}
}
func unsetEnv(t *testing.T, key string) {
t.Helper()
old, ok := os.LookupEnv(key)
if err := os.Unsetenv(key); err != nil {
t.Fatalf("unset %s: %v", key, err)
}
t.Cleanup(func() {
if ok {
_ = os.Setenv(key, old)
return
}
_ = os.Unsetenv(key)
})
}