469 lines
16 KiB
Markdown
469 lines
16 KiB
Markdown
# 配置管理
|
||
|
||
<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应用的配置，确保其在不同环境下的正常运行。 |