# 本地容器环境说明

## 1. 目标

本文档说明如何在本机通过 Docker Compose 快速启动电子名片项目所需的完整容器环境。

当前提供的服务包括：

- MySQL 8.0
- Redis 7
- MinIO
- Spring Boot 后端
- Vue 管理后台（Nginx 托管）

对应文件：

- [docker-compose.yml](/Users/slience/postgraduate/easycard/docker-compose.yml)
- [MySQL Dockerfile](/Users/slience/postgraduate/easycard/docker/mysql/Dockerfile)
- [MySQL 配置](/Users/slience/postgraduate/easycard/docker/mysql/conf.d/my.cnf)
- [Redis 配置](/Users/slience/postgraduate/easycard/docker/redis/redis.conf)
- [Backend Dockerfile](/Users/slience/postgraduate/easycard/docker/backend/Dockerfile)
- [Frontend Dockerfile](/Users/slience/postgraduate/easycard/docker/frontend-admin/Dockerfile)
- [Nginx 配置](/Users/slience/postgraduate/easycard/docker/frontend-admin/nginx.conf)

## 2. 启动方式

在项目根目录执行：

```bash
docker compose up -d --build
```

查看状态：

```bash
docker compose ps
```

停止并保留数据卷：

```bash
docker compose down
```

停止并删除数据卷：

```bash
docker compose down -v
```

## 3. 服务说明

### 3.1 MySQL

- 容器名：`easycard-mysql`
- 数据库：`easycard`
- 用户：`root`
- 密码：`root`

说明：

- 首次启动时会自动执行 [easycard_init.sql](/Users/slience/postgraduate/easycard/database/mysql/easycard_init.sql)
- 该脚本当前只负责创建 `easycard` 数据库
- 表结构、平台基础数据、演示数据由后端启动后的 Flyway 脚本统一执行
- 数据持久化目录：`docker/data/mysql`
- 当前不对宿主机暴露端口，仅允许 Docker 内网访问

### 3.2 Redis

- 容器名：`easycard-redis`
- 默认未设置密码

说明：

- 当前为本地开发配置
- 后续若进入联调或准生产环境，建议补充访问密码
- 数据持久化目录：`docker/data/redis`
- 当前不对宿主机暴露端口，仅允许 Docker 内网访问

### 3.3 MinIO

- 容器名：`easycard-minio`
- 用户名：`minioadmin`
- 密码：`minioadmin`

说明：

- `minio-init` 会在启动后自动创建 `easycard` bucket
- 当前脚本默认给该 bucket 开启下载访问，便于本地联调图片访问
- 数据持久化目录：`docker/data/minio`
- 当前不对宿主机暴露端口，仅允许 Docker 内网访问

### 3.4 Backend

- 容器名：`easycard-backend`
- 端口：`8112`

说明：

- 使用 [docker/backend/Dockerfile](/Users/slience/postgraduate/easycard/docker/backend/Dockerfile) 进行多阶段构建
- 容器启动时使用 `docker` profile
- 日志目录挂载到 `docker/data/backend/logs`
- 首次启动会等待 MySQL 健康检查通过后再启动

接口地址：

- [http://localhost:8112/api/v1/system/ping](http://localhost:8112/api/v1/system/ping)
- [http://localhost:8112/swagger-ui/index.html](http://localhost:8112/swagger-ui/index.html)

### 3.5 Frontend Admin

- 容器名：`easycard-frontend-admin`
- 端口：`8081`

说明：

- 使用 [docker/frontend-admin/Dockerfile](/Users/slience/postgraduate/easycard/docker/frontend-admin/Dockerfile) 构建前端产物
- 通过 Nginx 托管前端静态资源
- Nginx 会将 `/api`、`/swagger-ui`、`/v3/api-docs` 反向代理到 backend 服务
- Nginx 日志目录挂载到 `docker/data/nginx/logs`

访问地址：

- [http://localhost:8081](http://localhost:8081)

## 4. 与后端配置的对应关系

当前后端默认配置位于：

- [application.yml](/Users/slience/postgraduate/easycard/backend/easycard-boot/src/main/resources/application.yml)

容器内部联通使用：

- `DB_HOST=mysql`
- `DB_PORT=3306`
- `DB_NAME=easycard`
- `DB_USERNAME=root`
- `DB_PASSWORD=root`
- `REDIS_HOST=redis`
- `REDIS_PORT=6379`
- `REDIS_DATABASE=0`
- MinIO 服务名：`minio`

## 5. 数据挂载目录

当前容器数据与日志均挂载到宿主机目录：

- `docker/data/mysql`
- `docker/data/redis`
- `docker/data/minio`
- `docker/data/backend/logs`
- `docker/data/nginx/logs`

这样做的好处：

- 便于本地排查数据
- 重建容器后数据仍保留
- 便于备份和手工清理

## 6. 注意事项

- `easycard_init.sql` 当前仅适用于手工建库和 Docker 首次建库
- 若重新执行初始化脚本，请先删除 MySQL 数据卷，否则 MySQL 不会再次执行 `/docker-entrypoint-initdb.d`
- 若需要重建表结构和演示数据，请删除 MySQL 数据后重新启动 backend，由 Flyway 重新执行版本脚本
- 若本机已有 8112 或 8081 端口占用，需要同步调整后端和前端端口映射
- 当前仅 `frontend-admin(8081)` 和 `backend(8112)` 对宿主机暴露端口