# 数据库配置

<cite>
**本文档中引用的文件**  
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [database.go](file://utility/config/database.go)
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [v_1_schema_migrations.go](file://internal/dao/internal/v_1_schema_migrations.go)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构概述](#架构概述)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)

## 简介
本文档详细说明了kami_backend项目中MySQL数据库服务的Docker Compose配置。文档深入分析了数据库镜像版本选择、root密码、数据库名称、端口映射和数据卷持久化配置。同时解释了数据库初始化脚本的执行机制，包括字符集和排序规则的设置。文档还阐述了数据库与kami_backend应用服务之间的连接配置，以及如何通过环境变量传递数据库连接信息。此外，提供了数据库备份和恢复的Docker Compose集成方案，以及性能调优建议。

## 项目结构
项目结构中包含多个服务组件，其中kami_backend是核心后端服务。数据库配置主要位于`manifest/config/`目录下的`config.yaml`文件中，而Docker Compose配置则位于根目录和`manifest/docker/`目录下的`docker-compose.yml`文件中。数据库相关的DAO（数据访问对象）代码位于`internal/dao/`目录下，遵循GoFrame框架的代码生成模式。

```mermaid
graph TD
A[项目根目录] --> B[docker-compose.yml]
A --> C[manifest/]
C --> D[config/]
D --> E[config.yaml]
C --> F[docker/]
F --> G[docker-compose.yml]
A --> H[internal/]
H --> I[dao/]
I --> J[internal/]
J --> K[v_1_migrations.go]
J --> L[v_1_schema_migrations.go]
A --> M[utility/]
M --> N[config/]
N --> O[database.go]
```

**图示来源**
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [v_1_schema_migrations.go](file://internal/dao/internal/v_1_schema_migrations.go)
- [database.go](file://utility/config/database.go)

**节来源**
- [docker-compose.yml](file://docker-compose.yml)
- [manifest/config/config.yaml](file://manifest/config/config.yaml)

## 核心组件
核心数据库组件包括MySQL服务配置、数据库连接管理、数据迁移机制和健康检查脚本。`config.yaml`文件定义了数据库连接参数，包括两个数据库实例（default和v1）的连接字符串。`database.go`提供了获取数据库连接的接口。数据迁移通过`v_1_migrations.go`和`v_1_schema_migrations.go`中的DAO对象管理。`wait-for-it.sh`脚本确保应用在数据库可用后才启动。

**节来源**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)
- [database.go](file://utility/config/database.go#L0-L9)
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [v_1_schema_migrations.go](file://internal/dao/internal/v_1_schema_migrations.go)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)

## 架构概述
系统采用微服务架构，kami_backend服务通过Docker Compose与MySQL数据库集成。应用服务通过配置文件中的连接字符串连接到数据库，使用GoFrame框架的数据库抽象层进行数据访问。数据持久化通过Docker卷实现，确保数据在容器重启后不丢失。健康检查机制确保应用在数据库就绪后才开始处理请求。

```mermaid
graph LR
A[kami_backend应用] --> |连接| B[MySQL数据库]
B --> C[数据卷持久化]
A --> D[配置文件config.yaml]
D --> E[数据库连接参数]
A --> F[wait-for-it.sh]
F --> |健康检查| B
G[Docker Compose] --> A
G --> B
```

**图示来源**
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)

## 详细组件分析

### MySQL服务配置分析
MySQL服务配置通过环境变量和配置文件双重管理。数据库连接信息在`config.yaml`中明确定义，包括主机地址、端口、用户名、密码、数据库名称和连接参数。

#### 数据库连接配置
```mermaid
classDiagram
class DatabaseConfig {
+string default.link
+bool default.debug
+string default.charset
+int default.maxIdle
+int default.maxOpen
+string default.maxLifetime
+string v1.link
+bool v1.debug
+string v1.charset
+int v1.maxIdle
+int v1.maxOpen
+string v1.maxLifetime
}
class ConnectionPool {
+int maxIdle
+int maxOpen
+string maxLifetime
+getConnection()
+releaseConnection()
}
DatabaseConfig --> ConnectionPool : "配置"
```

**图示来源**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)

#### 数据库初始化机制
```mermaid
sequenceDiagram
participant Docker as Docker引擎
participant MySQL as MySQL容器
participant App as kami_backend应用
participant Script as wait-for-it.sh
Docker->>MySQL : 启动容器
MySQL->>MySQL : 初始化数据库
Docker->>App : 启动应用容器
App->>Script : 执行wait-for-it.sh
Script->>MySQL : 检查3306端口
MySQL-->>Script : 端口开放
Script-->>App : 数据库可用
App->>MySQL : 建立连接
App->>MySQL : 执行数据迁移
```

**图示来源**
- [docker-compose.yml](file://docker-compose.yml)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)

#### 数据迁移管理
```mermaid
flowchart TD
A[启动应用] --> B{数据库连接}
B --> |成功| C[检查migrations表]
C --> D{有未应用的迁移?}
D --> |是| E[执行迁移脚本]
E --> F[更新migrations表状态]
F --> G[应用启动完成]
D --> |否| G
B --> |失败| H[重试或退出]
H --> I[等待数据库就绪]
I --> B
```

**图示来源**
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [v_1_schema_migrations.go](file://internal/dao/internal/v_1_schema_migrations.go)
- [database.go](file://utility/config/database.go)

**节来源**
- [v_1_migrations.go](file://internal/dao/internal/v_1_migrations.go)
- [v_1_schema_migrations.go](file://internal/dao/internal/v_1_schema_migrations.go)
- [database.go](file://utility/config/database.go)

### 概念概述
系统采用GoFrame框架进行数据库操作，遵循DAO（数据访问对象）模式。数据库连接通过连接池管理，提高性能和资源利用率。数据迁移使用基于时间戳的版本控制，确保数据库模式变更的可追溯性和一致性。字符集统一设置为utf8mb4，支持完整的Unicode字符集，包括表情符号。

## 依赖分析
kami_backend服务依赖于MySQL数据库服务，通过Docker Compose的网络配置进行通信。应用通过`1panel-network`外部网络与数据库交互。数据库连接依赖于正确的连接字符串配置，包括主机、端口、用户名、密码和数据库名称。数据迁移功能依赖于`migrations`和`schema_migrations`系统表的存在和正确结构。

```mermaid
graph TD
A[kami_backend] --> B[MySQL]
A --> C[Redis]
B --> D[数据卷]
A --> E[配置文件]
E --> F[数据库连接参数]
A --> G[wait-for-it.sh]
G --> B
H[Docker Compose] --> A
H --> B
H --> I[其他微服务]
```

**图示来源**
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)

**节来源**
- [docker-compose.yml](file://docker-compose.yml)
- [config.yaml](file://manifest/config/config.yaml)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)

## 性能考虑
数据库连接池配置对系统性能有重要影响。`v1`数据库的`maxOpen`设置为1000，而`default`数据库的`maxOpen`设置为10，这表明`v1`数据库预期有更高的并发访问。`maxLifetime`设置为30秒，确保连接不会长时间保持，避免数据库服务器资源耗尽。字符集设置为utf8mb4而非utf8，虽然占用更多存储空间，但支持更完整的字符集，避免数据截断问题。

## 故障排除指南
当遇到数据库连接问题时，首先检查`config.yaml`中的连接字符串是否正确，特别是密码和数据库名称。确认MySQL容器是否正常运行，可以通过`docker ps`命令查看。使用`wait-for-it.sh`脚本确保应用在数据库就绪后才启动。检查数据卷挂载是否正确，确保数据持久化配置无误。查看应用日志中的数据库错误信息，定位具体问题。

**节来源**
- [config.yaml](file://manifest/config/config.yaml#L27-L57)
- [wait-for-it.sh](file://manifest/docker/wait-for-it.sh)
- [database.go](file://utility/config/database.go)

## 结论
本文档全面分析了kami_backend项目中MySQL数据库的Docker Compose配置。通过详细的配置分析、架构说明和组件解析，为数据库的部署、维护和优化提供了完整的指导。配置中体现了微服务架构的最佳实践，包括配置分离、健康检查、数据持久化和连接池管理。建议在生产环境中进一步加强数据库安全配置，如使用更复杂的密码策略和网络访问控制。