# Docker 部署指南

本项目提供三种 Docker 构建方式，适用于不同场景。

## 构建方式对比

| 方式 | Dockerfile | 适用场景 | 构建速度 | 依赖条件 |
|------|------------|----------|----------|----------|
| 快速构建 | `Dockerfile.quick` | 本地开发迭代 | 最快 | 本地已编译 JAR |
| 离线构建 | `Dockerfile` | CI/CD 离线环境 | 中等 | 需要 `.m2-repo` 目录 |
| 完整构建 | `Dockerfile.fullbuild` | 全新环境 | 最慢 | 需要 martial-tool 源码 |

---

## 方式一：快速构建（推荐日常开发）

适用于本地开发，需要先在本地编译项目。

```bash
# 1. 本地编译
mvn clean package -DskipTests

# 2. 构建镜像并启动
docker-compose up --build
```

或一条命令：

```bash
mvn clean package -DskipTests && docker-compose up --build
```

**前提条件**：
- 本地已安装 JDK 17+ 和 Maven 3.9+
- martial-tool 依赖已安装到本地 Maven 仓库

**docker-compose.yml 配置**：
```yaml
martial-api:
  build:
    context: .
    dockerfile: Dockerfile.quick
```

---

## 方式二：离线构建

适用于 CI/CD 环境或无法访问 Maven 仓库的场景。

```bash
# 1. 准备离线依赖（首次或依赖变更时执行）
cp -r ~/.m2/repository .m2-repo

# 2. 构建镜像并启动
docker-compose up --build
```

**前提条件**：
- 本地 `~/.m2/repository` 包含所有项目依赖
- `.m2-repo` 目录已复制到项目根目录

**docker-compose.yml 配置**：
```yaml
martial-api:
  build:
    context: .
    dockerfile: Dockerfile
```

**注意**：`.m2-repo` 目录较大（通常几百MB），建议添加到 `.gitignore`。

---

## 方式三：完整构建

适用于全新环境，从零开始构建整个项目（包括 BladeX 框架）。

```bash
# 需要在包含 martial-tool 和 martial-master 的父目录执行
cd /path/to/parent-directory
docker build -f martial-master/Dockerfile.fullbuild -t martial-api:latest .
```

**目录结构要求**：
```
parent-directory/
├── martial-tool/      # BladeX 框架源码
└── martial-master/    # 本项目
```

**特点**：
- 完全自包含，不依赖本地环境
- 构建时间最长（需编译两个项目）
- 适合首次部署或 CI/CD 完整构建

---

## 常用命令

```bash
# 启动所有服务
docker-compose up -d

# 重新构建并启动
docker-compose up -d --build

# 强制重新创建容器
docker-compose up -d --force-recreate

# 查看日志
docker logs -f martial-api

# 停止所有服务
docker-compose down

# 停止并删除数据卷（慎用，会清除数据库数据）
docker-compose down -v
```

---

## 环境变量

可在 `docker-compose.yml` 中配置以下环境变量：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `SPRING_PROFILE` | Spring 配置文件 | `docker` |
| `JAVA_OPTS` | JVM 参数 | `-Xms512m -Xmx1024m -XX:+UseG1GC` |
| `SPRING_DATASOURCE_URL` | 数据库连接 | 见 docker-compose.yml |
| `SPRING_DATA_REDIS_HOST` | Redis 地址 | `redis` |

---

## 故障排查

### 1. JAR 文件不存在
```
COPY target/blade-api.jar: not found
```
**解决**：先执行 `mvn clean package -DskipTests`

### 2. .m2-repo 目录不存在
```
COPY .m2-repo: not found
```
**解决**：执行 `cp -r ~/.m2/repository .m2-repo` 或改用 `Dockerfile.quick`

### 3. martial-tool 目录不存在
```
COPY martial-tool: not found
```
**解决**：确保在正确的父目录执行，或改用其他构建方式

### 4. Flyway 迁移失败
```
Migration checksum mismatch
```
**解决**：执行 `mvn flyway:repair` 修复迁移记录