CarrotSkin/backend

Fork 0

Files

lan a4b6c5011e

SonarQube Analysis / sonarqube (push) Has been cancelled

Details

chore(git): 更新.gitignore以忽略新的本地文件

2025-11-30 08:33:17 +08:00

16 KiB

Raw Blame History

配置管理

**本文档引用的文件** - [config.go](file://pkg/config/config.go) - [manager.go](file://pkg/config/manager.go) - [main.go](file://cmd/server/main.go) - [check-env.sh](file://scripts/check-env.sh) - [dev.sh](file://scripts/dev.sh) - [system_config.go](file://internal/model/system_config.go) - [rbac_model.conf](file://configs/casbin/rbac_model.conf)

简介

CarrotSkin项目的配置管理系统采用Viper库实现，提供了一套完整的配置管理解决方案。该系统支持从环境变量、.env文件等多种来源加载配置，确保了应用在不同环境下的灵活性和可移植性。配置系统设计遵循了安全性和易用性的原则，为开发者提供了清晰的配置管理接口。

本系统的主要特点包括：

基于Viper库的配置管理
支持环境变量和.env文件
线程安全的单例模式
丰富的默认配置值
灵活的配置覆盖机制

Section sources

配置系统架构

CarrotSkin的配置系统采用分层架构设计，核心组件包括配置结构体、配置管理器和配置加载器。系统通过Viper库实现配置的解析和管理，确保了配置的一致性和可靠性。

graph TD
A[环境变量] --> B[Viper配置管理器]
C[.env文件] --> B
B --> D[Config结构体]
D --> E[ServerConfig]
D --> F[DatabaseConfig]
D --> G[RedisConfig]
D --> H[RustFSConfig]
D --> I[JWTConfig]
D --> J[LogConfig]
D --> K[UploadConfig]
D --> L[EmailConfig]
M[配置管理器] --> D
M --> N[全局配置实例]
O[应用程序] --> M
style A fill:#f9f,stroke:#333
style C fill:#f9f,stroke:#333
style B fill:#bbf,stroke:#333
style D fill:#ff9,stroke:#333
style M fill:#9f9,stroke:#333
style O fill:#f96,stroke:#333

Diagram sources

Section sources

配置加载流程

CarrotSkin的配置加载流程是一个多步骤的过程，确保配置能够正确地从各种来源加载并应用。加载流程包括环境变量前缀设置、默认值配置、环境变量映射和最终的配置解析。

flowchart TD
Start([开始]) --> LoadDotEnv["加载.env文件"]
LoadDotEnv --> SetDefaults["设置默认值"]
SetDefaults --> SetPrefix["设置环境变量前缀 CARROTSKIN"]
SetPrefix --> EnableAutoEnv["启用自动环境变量"]
EnableAutoEnv --> SetupMappings["设置环境变量映射"]
SetupMappings --> UnmarshalConfig["解析配置到结构体"]
UnmarshalConfig --> OverrideEnv["从环境变量覆盖特殊配置"]
OverrideEnv --> ReturnConfig["返回配置实例"]
ReturnConfig --> End([结束])
style Start fill:#4CAF50,stroke:#333
style End fill:#4CAF50,stroke:#333
style LoadDotEnv fill:#2196F3,stroke:#333
style SetDefaults fill:#2196F3,stroke:#333
style SetPrefix fill:#2196F3,stroke:#333
style EnableAutoEnv fill:#2196F3,stroke:#333
style SetupMappings fill:#2196F3,stroke:#333
style UnmarshalConfig fill:#2196F3,stroke:#333
style OverrideEnv fill:#2196F3,stroke:#333
style ReturnConfig fill:#2196F3,stroke:#333

Diagram sources

config.go

Section sources

config.go

可配置选项详解

CarrotSkin项目提供了丰富的可配置选项，涵盖了服务器、数据库、Redis、对象存储、JWT、日志、文件上传和邮件等多个模块。每个模块都有详细的配置参数，满足不同场景的需求。

服务器配置

服务器配置控制应用的基本运行参数，包括端口、模式和超时设置。

配置项	环境变量	类型	描述	默认值
server.port	SERVER_PORT	string	服务器监听端口	:8080
server.mode	SERVER_MODE	string	运行模式 (debug/production)	debug
server.read_timeout	SERVER_READ_TIMEOUT	duration	读取超时时间	30s
server.write_timeout	SERVER_WRITE_TIMEOUT	duration	写入超时时间	30s

Section sources

config.go

数据库配置

数据库配置管理与PostgreSQL数据库的连接参数和连接池设置。

配置项	环境变量	类型	描述	默认值
database.driver	DATABASE_DRIVER	string	数据库驱动	postgres
database.host	DATABASE_HOST	string	数据库主机地址	localhost
database.port	DATABASE_PORT	int	数据库端口	5432
database.username	DATABASE_USERNAME	string	数据库用户名	-
database.password	DATABASE_PASSWORD	string	数据库密码	-
database.database	DATABASE_NAME	string	数据库名称	-
database.ssl_mode	DATABASE_SSL_MODE	string	SSL模式	disable
database.timezone	DATABASE_TIMEZONE	string	时区设置	Asia/Shanghai
database.max_idle_conns	DATABASE_MAX_IDLE_CONNS	int	最大空闲连接数	10
database.max_open_conns	DATABASE_MAX_OPEN_CONNS	int	最大打开连接数	100
database.conn_max_lifetime	DATABASE_CONN_MAX_LIFETIME	duration	连接最大生命周期	1h

Section sources

config.go

Redis配置

Redis配置管理Redis缓存服务的连接信息和连接池设置。

配置项	环境变量	类型	描述	默认值
redis.host	REDIS_HOST	string	Redis主机地址	localhost
redis.port	REDIS_PORT	int	Redis端口	6379
redis.password	REDIS_PASSWORD	string	Redis密码	-
redis.database	REDIS_DATABASE	int	Redis数据库编号	0
redis.pool_size	REDIS_POOL_SIZE	int	连接池大小	10

Section sources

config.go

对象存储(RustFS)配置

对象存储配置管理S3兼容的对象存储服务(RustFS)的连接信息和存储桶设置。

配置项	环境变量	类型	描述	默认值
rustfs.endpoint	RUSTFS_ENDPOINT	string	对象存储端点	127.0.0.1:9000
rustfs.access_key	RUSTFS_ACCESS_KEY	string	访问密钥	-
rustfs.secret_key	RUSTFS_SECRET_KEY	string	密钥	-
rustfs.use_ssl	RUSTFS_USE_SSL	bool	是否使用SSL	false
rustfs.buckets	RUSTFS_BUCKET_*	map[string]string	存储桶映射	-

Section sources

config.go

JWT配置

JWT配置管理JSON Web Token的密钥和过期时间设置。

配置项	环境变量	类型	描述	默认值
jwt.secret	JWT_SECRET	string	JWT密钥	-
jwt.expire_hours	JWT_EXPIRE_HOURS	int	JWT过期小时数	168(7天)

Section sources

config.go

日志配置

日志配置管理应用日志的级别、格式和文件滚动设置。

配置项	环境变量	类型	描述	默认值
log.level	LOG_LEVEL	string	日志级别	info
log.format	LOG_FORMAT	string	日志格式	json
log.output	LOG_OUTPUT	string	日志输出路径	logs/app.log
log.max_size	LOG_MAX_SIZE	int	单个日志文件最大大小(MB)	100
log.max_backups	LOG_MAX_BACKUPS	int	保留旧日志文件的最大个数	3
log.max_age	LOG_MAX_AGE	int	保留旧日志文件的最大天数	28
log.compress	LOG_COMPRESS	bool	是否压缩归档日志	true

Section sources

config.go

文件上传配置

文件上传配置管理文件上传的大小限制和允许的文件类型。

配置项	环境变量	类型	描述	默认值
upload.max_size	UPLOAD_MAX_SIZE	int64	最大上传文件大小	10MB
upload.allowed_types	-	[]string	允许的文件MIME类型	["image/png", "image/jpeg"]
upload.texture_max_size	UPLOAD_TEXTURE_MAX_SIZE	int64	纹理文件最大大小	2MB
upload.avatar_max_size	UPLOAD_AVATAR_MAX_SIZE	int64	头像文件最大大小	1MB

Section sources

config.go

邮件配置

邮件配置管理SMTP邮件服务的连接信息和发件人设置。

配置项	环境变量	类型	描述	默认值
email.enabled	EMAIL_ENABLED	bool	是否启用邮件服务	false
email.smtp_host	EMAIL_SMTP_HOST	string	SMTP主机地址	-
email.smtp_port	EMAIL_SMTP_PORT	int	SMTP端口	587
email.username	EMAIL_USERNAME	string	SMTP用户名	-
email.password	EMAIL_PASSWORD	string	SMTP密码	-
email.from_name	EMAIL_FROM_NAME	string	发件人名称	-

Section sources

config.go

默认配置与覆盖机制

CarrotSkin的配置系统采用分层覆盖机制，确保配置的灵活性和可靠性。系统首先设置合理的默认值，然后通过环境变量进行覆盖，最后处理特殊的配置覆盖逻辑。

默认配置设置

系统通过setDefaults()函数设置所有配置项的默认值，确保在没有提供外部配置时应用仍能正常运行。

classDiagram
class Config {
+Server ServerConfig
+Database DatabaseConfig
+Redis RedisConfig
+RustFS RustFSConfig
+JWT JWTConfig
+Casbin CasbinConfig
+Log LogConfig
+Upload UploadConfig
+Email EmailConfig
}
class ServerConfig {
+Port string
+Mode string
+ReadTimeout time.Duration
+WriteTimeout time.Duration
}
class DatabaseConfig {
+Driver string
+Host string
+Port int
+Username string
+Password string
+Database string
+SSLMode string
+Timezone string
+MaxIdleConns int
+MaxOpenConns int
+ConnMaxLifetime time.Duration
}
class RedisConfig {
+Host string
+Port int
+Password string
+Database int
+PoolSize int
}
class RustFSConfig {
+Endpoint string
+AccessKey string
+SecretKey string
+UseSSL bool
+Buckets map[string]string
}
class JWTConfig {
+Secret string
+ExpireHours int
}
class LogConfig {
+Level string
+Format string
+Output string
+MaxSize int
+MaxBackups int
+MaxAge int
+Compress bool
}
Config "1" *-- "1" ServerConfig
Config "1" *-- "1" DatabaseConfig
Config "1" *-- "1" RedisConfig
Config "1" *-- "1" RustFSConfig
Config "1" *-- "1" JWTConfig
Config "1" *-- "1" LogConfig
Config "1" *-- "1" UploadConfig
Config "1" *-- "1" EmailConfig

Diagram sources

config.go

Section sources

config.go

配置覆盖流程

配置覆盖流程确保了配置的优先级顺序：环境变量 > .env文件 > 默认值。系统通过overrideFromEnv()函数处理特殊的配置覆盖逻辑。

sequenceDiagram
participant App as 应用程序
participant ConfigMgr as 配置管理器
participant Viper as Viper库
participant Env as 环境变量
participant DotEnv as .env文件
App->>ConfigMgr : 调用 config.Init()
ConfigMgr->>ConfigMgr : 执行 once.Do()
ConfigMgr->>DotEnv : 加载 .env 文件
ConfigMgr->>Viper : 设置默认值
ConfigMgr->>Viper : 设置环境变量前缀 CARROTSKIN
ConfigMgr->>Viper : 启用自动环境变量
ConfigMgr->>Viper : 绑定环境变量映射
Viper->>Env : 读取环境变量
Viper->>Viper : 解析配置到结构体
ConfigMgr->>Env : 从环境变量覆盖特殊配置
ConfigMgr->>App : 返回配置实例

Diagram sources

Section sources

config.go

配置文件编写指南

为帮助初学者快速上手，以下是配置文件的编写指南。

.env文件示例

创建.env文件并填入以下内容：

# 数据库配置
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=carrot
DATABASE_PASSWORD=secret
DATABASE_NAME=carrotskin
DATABASE_SSL_MODE=disable

# 对象存储配置
RUSTFS_ENDPOINT=127.0.0.1:9000
RUSTFS_ACCESS_KEY=minioadmin
RUSTFS_SECRET_KEY=minioadmin
RUSTFS_USE_SSL=false

# JWT配置
JWT_SECRET=your-jwt-secret-key-change-this-in-production

# 服务器配置
SERVER_PORT=:8080
SERVER_MODE=debug

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379

配置验证脚本

使用提供的check-env.sh脚本验证配置的完整性：

./scripts/check-env.sh

该脚本会检查必需的环境变量是否设置，并提供配置概览和安全建议。

Section sources

动态配置与环境特定配置

对于经验丰富的开发者，CarrotSkin提供了动态配置和环境特定配置的最佳实践。

环境特定配置

通过环境变量前缀CARROTSKIN，可以在不同环境中使用不同的配置：

# 开发环境
CARROTSKIN_SERVER_PORT=:8080 \
CARROTSKIN_DATABASE_HOST=localhost \
CARROTSKIN_REDIS_HOST=localhost \
go run cmd/server/main.go

# 生产环境
CARROTSKIN_SERVER_PORT=:80 \
CARROTSKIN_DATABASE_HOST=prod-db.example.com \
CARROTSKIN_REDIS_HOST=prod-redis.example.com \
go run cmd/server/main.go

动态配置管理

系统提供了线程安全的配置访问接口，支持在运行时安全地获取配置：

// 获取配置实例
cfg, err := config.GetConfig()
if err != nil {
    log.Fatalf("配置获取失败: %v", err)
}

// 或使用panic方式获取（确保配置已初始化）
cfg := config.MustGetConfig()

// 获取特定模块配置
rustFSConfig := config.MustGetRustFSConfig()

Section sources

配置验证与最佳实践

配置验证

CarrotSkin提供了多种配置验证机制，确保配置的正确性和安全性：

必需变量检查：通过check-env.sh脚本检查必需的环境变量
配置合理性检查：检查JWT密钥长度、数据库密码等安全相关配置
运行时验证：在应用启动时验证配置的有效性

最佳实践

使用.env文件管理开发配置：避免将敏感信息硬编码在代码中
设置强密码和密钥：确保JWT密钥至少32字符，使用随机字符串
环境隔离：为不同环境（开发、测试、生产）使用不同的配置
配置备份：定期备份重要的配置文件
监控配置变更：记录配置变更历史，便于问题追踪

Section sources

check-env.sh

结论

CarrotSkin的配置管理系统提供了一套完整、灵活且安全的配置管理解决方案。通过Viper库的强大功能，系统能够从多种来源加载配置，并提供了丰富的默认值和灵活的覆盖机制。配置系统的设计考虑了不同用户的需求，既为初学者提供了简单的配置文件编写指南，又为经验丰富的开发者提供了动态配置和环境特定配置的最佳实践。

该系统的线程安全设计和单例模式确保了配置的一致性和可靠性，而详细的配置选项和验证机制则保证了应用的稳定运行。通过遵循本文档提供的指南和最佳实践，开发者可以有效地管理和维护CarrotSkin应用的配置，确保其在不同环境下的正常运行。

16 KiB Raw Blame History Unescape Escape

配置管理

目录

简介

配置系统架构

配置加载流程

可配置选项详解

服务器配置

数据库配置

Redis配置

对象存储(RustFS)配置

JWT配置

日志配置

文件上传配置

邮件配置

默认配置与覆盖机制

默认配置设置

配置覆盖流程

配置文件编写指南

.env文件示例

配置验证脚本

动态配置与环境特定配置

环境特定配置

动态配置管理

配置验证与最佳实践

配置验证

最佳实践

结论

16 KiB

Raw Blame History