# 数据库配置

<cite>
**本文引用的文件**
- [pkg/config/config.go](file://pkg/config/config.go)
- [pkg/database/postgres.go](file://pkg/database/postgres.go)
- [pkg/database/manager.go](file://pkg/database/manager.go)
- [cmd/server/main.go](file://cmd/server/main.go)
- [start.sh](file://start.sh)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件聚焦 CarrotSkin 项目的数据库连接与连接池配置，系统性说明以下内容：
- 连接参数 database.driver、host、port、username、password、database、ssl_mode、timezone 的用途与默认值来源
- 连接池参数 max_idle_conns、max_open_conns、conn_max_lifetime 的工作机制与性能影响
- 如何通过 DATABASE_* 环境变量覆盖默认配置
- 结合 DatabaseConfig 结构体与数据库初始化流程的最佳实践，包含生产环境安全建议与连接池调优策略

## 项目结构
数据库相关能力由配置层与数据库层协同实现：
- 配置层负责加载默认值、绑定环境变量映射，并支持从环境变量覆盖连接池参数
- 数据库层负责根据配置构建 DSN、初始化 GORM 连接、设置连接池并进行连通性测试
- 应用入口在启动时加载配置、初始化数据库并执行迁移

```mermaid
graph TB
subgraph "配置层"
CFG["pkg/config/config.go<br/>DatabaseConfig/默认值/环境映射"]
end
subgraph "数据库层"
DBM["pkg/database/manager.go<br/>Init/GetDB/AutoMigrate/Close"]
PG["pkg/database/postgres.go<br/>New/GetDSN"]
end
subgraph "应用入口"
MAIN["cmd/server/main.go<br/>加载配置/初始化数据库/迁移"]
end
ENV["环境变量<br/>DATABASE_*"]
ENV --> CFG
CFG --> DBM
DBM --> PG
MAIN --> CFG
MAIN --> DBM
```

图表来源
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L50)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)
- [cmd/server/main.go](file://cmd/server/main.go#L27-L50)

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L50)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)
- [cmd/server/main.go](file://cmd/server/main.go#L27-L50)

## 核心组件
- DatabaseConfig 结构体：承载数据库连接与连接池配置
- 配置加载与覆盖：默认值、环境变量映射、连接池参数覆盖
- 数据库初始化：构建 DSN、初始化 GORM、设置连接池、Ping 测试
- 应用启动流程：加载配置 → 初始化数据库 → 自动迁移

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L34-L47)
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L190-L210)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L50)
- [cmd/server/main.go](file://cmd/server/main.go#L27-L50)

## 架构总览
下图展示从配置到数据库连接的关键调用链路与职责分工。

```mermaid
sequenceDiagram
participant Entrypoint as "应用入口(main.go)"
participant Cfg as "配置(Config.Load)"
participant DBMgr as "数据库管理器(database.Init)"
participant DB as "数据库(New)"
participant SQL as "底层sql.DB"
Entrypoint->>Cfg : "加载配置"
Cfg-->>Entrypoint : "返回完整配置"
Entrypoint->>DBMgr : "Init(DatabaseConfig)"
DBMgr->>DB : "New(DatabaseConfig)"
DB->>DB : "构造DSN"
DB->>SQL : "gorm.Open + 获取*sql.DB"
DB->>SQL : "SetMaxIdleConns/SetMaxOpenConns/SetConnMaxLifetime"
DB->>SQL : "Ping() 测试连接"
DB-->>DBMgr : "*gorm.DB"
DBMgr-->>Entrypoint : "初始化完成"
```

图表来源
- [cmd/server/main.go](file://cmd/server/main.go#L27-L50)
- [pkg/config/config.go](file://pkg/config/config.go#L108-L133)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L33)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)

## 详细组件分析

### DatabaseConfig 字段与用途
- database.driver
  - 作用：驱动类型标识，用于控制日志级别与后续扩展点
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_DRIVER
- database.host
  - 作用：数据库主机地址
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_HOST
- database.port
  - 作用：数据库端口
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_PORT
- database.username
  - 作用：数据库用户名
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_USERNAME
- database.password
  - 作用：数据库密码
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_PASSWORD
- database.database
  - 作用：数据库名
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_NAME
- database.ssl_mode
  - 作用：SSL 模式（如 disable/require 等），影响 TLS 连接
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_SSL_MODE
- database.timezone
  - 作用：时区设置，影响时间字段的时区行为
  - 默认值：来自默认配置
  - 环境变量映射：DATABASE_TIMEZONE

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L34-L47)
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L190-L210)

### 连接池配置项与工作机制
- max_idle_conns
  - 作用：最大空闲连接数，控制连接池中空闲连接上限
  - 默认值：来自默认配置
  - 环境变量覆盖：DATABASE_MAX_IDLE_CONNS
- max_open_conns
  - 作用：最大打开连接数，限制并发连接上限
  - 默认值：来自默认配置
  - 环境变量覆盖：DATABASE_MAX_OPEN_CONNS
- conn_max_lifetime
  - 作用：连接最大存活时间，到期后连接会被回收
  - 默认值：来自默认配置
  - 环境变量覆盖：DATABASE_CONN_MAX_LIFETIME（支持时长字符串，如“1h”）

这些参数在 New 中通过底层 sql.DB 设置，并在 Ping 成功后生效。

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L34-L47)
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L49-L53)

### 环境变量覆盖与默认值
- 默认值来源
  - 通过 viper.SetDefault 设置，确保即使未提供对应环境变量也能有合理默认
- 环境变量映射
  - 使用 viper.BindEnv 将配置键映射到 DATABASE_* 前缀的环境变量
- 连接池参数覆盖
  - 通过 overrideFromEnv 从环境变量读取整型或时长字符串并覆盖默认值

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L190-L210)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)

### 数据库初始化流程与 DSN 构造
- DSN 构造
  - New 中依据 DatabaseConfig 组装 DSN，包含 host、port、user、password、dbname、sslmode、TimeZone
- GORM 初始化
  - 根据 driver 决定日志级别；禁用迁移时的外键约束以避免循环依赖
- 连接池设置
  - SetMaxIdleConns、SetMaxOpenConns、SetConnMaxLifetime
- 连通性测试
  - Ping 成功后返回 gorm.DB 实例

章节来源
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)

### 应用启动中的数据库初始化
- 配置加载：Load 会加载 .env 并解析为 Config
- 数据库初始化：Init 接收 DatabaseConfig，内部调用 New 完成连接与池设置
- 自动迁移：AutoMigrate 按顺序迁移模型，确保外键依赖关系正确
- 资源清理：Close 关闭底层 sql.DB

章节来源
- [cmd/server/main.go](file://cmd/server/main.go#L27-L50)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L50)
- [pkg/database/manager.go](file://pkg/database/manager.go#L52-L99)
- [pkg/database/manager.go](file://pkg/database/manager.go#L101-L114)

## 依赖关系分析

```mermaid
classDiagram
class Config {
+ServerConfig Server
+DatabaseConfig Database
+RedisConfig Redis
+RustFSConfig RustFS
+JWTConfig JWT
+CasbinConfig Casbin
+LogConfig Log
+UploadConfig Upload
+EmailConfig Email
}
class DatabaseConfig {
+string Driver
+string Host
+int Port
+string Username
+string Password
+string Database
+string SSLMode
+string Timezone
+int MaxIdleConns
+int MaxOpenConns
+duration ConnMaxLifetime
}
class Manager {
+Init(cfg, logger) error
+GetDB() (*gorm.DB, error)
+MustGetDB() *gorm.DB
+AutoMigrate(logger) error
+Close() error
}
class Postgres {
+New(cfg) (*gorm.DB, error)
+GetDSN(cfg) string
}
Config --> DatabaseConfig : "包含"
Manager --> DatabaseConfig : "使用"
Postgres --> DatabaseConfig : "使用"
Manager --> Postgres : "调用"
```

图表来源
- [pkg/config/config.go](file://pkg/config/config.go#L13-L24)
- [pkg/config/config.go](file://pkg/config/config.go#L34-L47)
- [pkg/database/manager.go](file://pkg/database/manager.go#L22-L50)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)

## 性能考量
- 连接池参数建议
  - max_idle_conns：建议与 max_open_conns 保持一定比例，避免过多空闲连接占用资源
  - max_open_conns：应结合数据库最大连接数与应用并发量综合评估，避免超过数据库限制导致连接排队
  - conn_max_lifetime：建议设置为小于数据库连接超时阈值，确保连接健康与复用效率
- 日志级别
  - 当 driver 为 postgres 时，GORM 日志级别提升为 Info，便于调试；在生产环境可考虑降低日志级别以减少开销
- 迁移策略
  - AutoMigrate 顺序需保证被引用表先于引用表创建，避免外键约束冲突

章节来源
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L25-L32)
- [pkg/database/manager.go](file://pkg/database/manager.go#L52-L99)

## 故障排查指南
- 未初始化即使用数据库
  - 现象：调用 GetDB 返回错误提示“数据库未初始化”
  - 处理：确保在应用启动阶段先调用 database.Init
- 连接失败
  - 检查 DSN 参数是否正确（host/port/username/password/database/ssl_mode/timezone）
  - 确认数据库可达与凭据有效
- 连接池异常
  - 检查 max_idle_conns、max_open_conns 是否设置过小或过大
  - 检查 conn_max_lifetime 是否导致频繁重建连接
- 环境变量未生效
  - 确认环境变量前缀与键名匹配（DATABASE_*）
  - 确认 overrideFromEnv 可正确解析整型与 duration 类型

章节来源
- [pkg/database/manager.go](file://pkg/database/manager.go#L35-L41)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L13-L60)
- [pkg/config/config.go](file://pkg/config/config.go#L190-L210)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)

## 结论
- CarrotSkin 的数据库配置采用“默认值 + 环境变量覆盖”的设计，既保证开箱即用，又允许灵活定制
- 连接池参数通过 DATABASE_MAX_IDLE_CONNS、DATABASE_MAX_OPEN_CONNS、DATABASE_CONN_MAX_LIFETIME 进行覆盖，建议结合业务并发与数据库能力进行调优
- 生产环境建议启用 SSL（ssl_mode）、严格凭据管理与最小权限原则，并适当降低日志级别以优化性能

## 附录

### 环境变量与默认值对照表
- database.driver
  - 环境变量：DATABASE_DRIVER
  - 默认值：postgres
- database.host
  - 环境变量：DATABASE_HOST
  - 默认值：localhost
- database.port
  - 环境变量：DATABASE_PORT
  - 默认值：5432
- database.username
  - 环境变量：DATABASE_USERNAME
  - 默认值：空字符串
- database.password
  - 环境变量：DATABASE_PASSWORD
  - 默认值：空字符串
- database.database
  - 环境变量：DATABASE_NAME
  - 默认值：空字符串
- database.ssl_mode
  - 环境变量：DATABASE_SSL_MODE
  - 默认值：disable
- database.timezone
  - 环境变量：DATABASE_TIMEZONE
  - 默认值：Asia/Shanghai
- database.max_idle_conns
  - 环境变量：DATABASE_MAX_IDLE_CONNS
  - 默认值：10
- database.max_open_conns
  - 环境变量：DATABASE_MAX_OPEN_CONNS
  - 默认值：100
- database.conn_max_lifetime
  - 环境变量：DATABASE_CONN_MAX_LIFETIME
  - 默认值：1h

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L190-L210)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)

### 生产环境安全与连接池调优建议
- 安全建议
  - 将 ssl_mode 设为 require 或 verify-full（视数据库支持而定），并配合证书校验
  - 使用专用数据库用户与最小权限策略，定期轮换密码
  - 通过环境变量注入敏感信息，避免硬编码
- 连接池调优
  - 初步以 max_idle_conns ≈ 1/10 max_open_conns 开始，结合压测结果调整
  - 将 conn_max_lifetime 设置为略小于数据库连接超时阈值，平衡资源回收与连接复用
  - 监控数据库连接数与等待队列，动态调整 max_open_conns

章节来源
- [pkg/config/config.go](file://pkg/config/config.go#L135-L188)
- [pkg/config/config.go](file://pkg/config/config.go#L238-L280)
- [pkg/database/postgres.go](file://pkg/database/postgres.go#L49-L53)

### 启动脚本中的数据库环境变量示例
- 示例脚本展示了如何设置 DATABASE_HOST、DATABASE_PORT、DATABASE_USERNAME、DATABASE_PASSWORD、DATABASE_NAME、DATABASE_SSL_MODE、DATABASE_TIMEZONE 等环境变量

章节来源
- [start.sh](file://start.sh#L1-L41)