# 配置管理

<cite>
**本文档引用的文件**
- [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)
</cite>

## 目录
1. [简介](#简介)
2. [配置系统架构](#配置系统架构)
3. [配置加载流程](#配置加载流程)
4. [可配置选项详解](#可配置选项详解)
5. [默认配置与覆盖机制](#默认配置与覆盖机制)
6. [配置文件编写指南](#配置文件编写指南)
7. [动态配置与环境特定配置](#动态配置与环境特定配置)
8. [配置验证与最佳实践](#配置验证与最佳实践)
9. [结论](#结论)

## 简介

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

本系统的主要特点包括：
- 基于Viper库的配置管理
- 支持环境变量和.env文件
- 线程安全的单例模式
- 丰富的默认配置值
- 灵活的配置覆盖机制

**Section sources**
- [config.go](file://pkg/config/config.go#L1-L305)
- [manager.go](file://pkg/config/manager.go#L1-L68)

## 配置系统架构

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

```mermaid
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**
- [config.go](file://pkg/config/config.go#L14-L24)
- [manager.go](file://pkg/config/manager.go#L8-L17)

**Section sources**
- [config.go](file://pkg/config/config.go#L1-L305)
- [manager.go](file://pkg/config/manager.go#L1-L68)

## 配置加载流程

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

```mermaid
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](file://pkg/config/config.go#L108-L132)

**Section sources**
- [config.go](file://pkg/config/config.go#L108-L132)

## 可配置选项详解

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](file://pkg/config/config.go#L26-L32)

### 数据库配置

数据库配置管理与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](file://pkg/config/config.go#L34-L47)

### 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](file://pkg/config/config.go#L49-L56)

### 对象存储(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](file://pkg/config/config.go#L58-L65)

### 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](file://pkg/config/config.go#L67-L71)

### 日志配置

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

| 配置项 | 环境变量 | 类型 | 描述 | 默认值 |
|--------|----------|------|------|--------|
| 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](file://pkg/config/config.go#L79-L88)

### 文件上传配置

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

| 配置项 | 环境变量 | 类型 | 描述 | 默认值 |
|--------|----------|------|------|--------|
| 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](file://pkg/config/config.go#L90-L96)

### 邮件配置

邮件配置管理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](file://pkg/config/config.go#L98-L106)

## 默认配置与覆盖机制

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

### 默认配置设置

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

```mermaid
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](file://pkg/config/config.go#L13-L24)

**Section sources**
- [config.go](file://pkg/config/config.go#L135-L188)

### 配置覆盖流程

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

```mermaid
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**
- [config.go](file://pkg/config/config.go#L108-L132)
- [config.go](file://pkg/config/config.go#L238-L304)

**Section sources**
- [config.go](file://pkg/config/config.go#L238-L304)

## 配置文件编写指南

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

### .env文件示例

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

```bash
# 数据库配置
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`脚本验证配置的完整性：

```bash
./scripts/check-env.sh
```

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

**Section sources**
- [check-env.sh](file://scripts/check-env.sh#L1-L78)
- [dev.sh](file://scripts/dev.sh#L1-L29)

## 动态配置与环境特定配置

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

### 环境特定配置

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

```bash
# 开发环境
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
```

### 动态配置管理

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

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

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

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

**Section sources**
- [manager.go](file://pkg/config/manager.go#L19-L63)
- [main.go](file://cmd/server/main.go#L27-L124)

## 配置验证与最佳实践

### 配置验证

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

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

### 最佳实践

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

**Section sources**
- [check-env.sh](file://scripts/check-env.sh#L1-L78)

## 结论

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

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