martial-master/docs/guides/docker-deployment.md

Docker 部署指南

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

构建方式对比

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

---

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

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

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

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

或一条命令：

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

前提条件：

• 本地已安装 JDK 17+ 和 Maven 3.9+
• martial-tool 依赖已安装到本地 Maven 仓库

docker-compose.yml 配置：

martial-api:
  build:
    context: .
    dockerfile: Dockerfile.quick

---

方式二：离线构建

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

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

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

前提条件：

• 本地 ~/.m2/repository 包含所有项目依赖
• .m2-repo 目录已复制到项目根目录

docker-compose.yml 配置：

martial-api:
  build:
    context: .
    dockerfile: Dockerfile

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

---

方式三：完整构建

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

# 需要在包含 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 完整构建

---

常用命令

# 启动所有服务
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 修复迁移记录