364 lines
14 KiB
Markdown
364 lines
14 KiB
Markdown
# 数据库配置
|
||
|
||
<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) |