6194c64b4f
- 添加多架构Docker构建和推送说明 - 详细说明服务器部署流程 - 说明CentOS环境下的docker-compose配置 - 添加日志查看和监控指引 - 完善从本地开发到服务器部署的完整工作流程
273 lines
5.5 KiB
Markdown
273 lines
5.5 KiB
Markdown
# PeiPei 后端项目
|
|
|
|
基于 Spring Boot 的多模块项目，为 PeiPei 应用提供后端服务。
|
|
|
|
## 项目结构
|
|
|
|
- **play-admin**: 主要的 Spring Boot 应用模块
|
|
- **play-common**: 公共工具类和共享代码
|
|
- **play-generator**: 代码生成工具
|
|
|
|
## 构建要求
|
|
|
|
- **Java 11** (必须)
|
|
- **Maven 3.6+**
|
|
|
|
## 快速开始
|
|
|
|
### 1. 安装 Java 11
|
|
|
|
在 macOS 上使用 Homebrew:
|
|
```bash
|
|
brew install --cask zulu@11
|
|
```
|
|
|
|
设置 Java 11 为默认版本:
|
|
|
|
#### 临时设置 (当前会话):
|
|
```bash
|
|
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
|
|
```
|
|
|
|
#### 永久设置方法:
|
|
|
|
**方法1: Shell 配置 (推荐)**
|
|
添加到 `~/.zshrc` 或 `~/.bash_profile`:
|
|
```bash
|
|
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
|
|
export PATH="$JAVA_HOME/bin:$PATH"
|
|
```
|
|
|
|
**方法2: Maven 专用**
|
|
创建 `~/.mavenrc`:
|
|
```bash
|
|
export JAVA_HOME=$(/usr/libexec/java_home -v 11)
|
|
```
|
|
|
|
**方法3: VS Code 项目配置**
|
|
项目已配置 `.vscode/settings.json` 使用 Java 11:
|
|
```json
|
|
{
|
|
"java.configuration.runtimes": [
|
|
{
|
|
"name": "JavaSE-11",
|
|
"path": "/usr/libexec/java_home -v 11"
|
|
}
|
|
],
|
|
"java.jdt.ls.java.home": "/usr/libexec/java_home -v 11"
|
|
}
|
|
```
|
|
|
|
### 2. 构建项目
|
|
|
|
```bash
|
|
# 清理并构建所有模块
|
|
mvn clean install
|
|
|
|
# 或者仅编译
|
|
mvn clean compile
|
|
```
|
|
|
|
### 3. 运行应用
|
|
|
|
```bash
|
|
# 运行主应用
|
|
java -jar play-admin/target/play-admin-1.0.jar
|
|
|
|
# 或使用 Maven
|
|
cd play-admin
|
|
mvn spring-boot:run
|
|
```
|
|
|
|
## 配置说明
|
|
|
|
项目在所有模块中统一使用 Java 11:
|
|
- 所有模块都配置为 Java 11 源码和目标版本
|
|
- Lombok 注解自动处理
|
|
- 无需显式配置注解处理器
|
|
|
|
## 开发说明
|
|
|
|
- 项目已更新为所有模块统一使用 Java 11
|
|
- Lombok 依赖使用 `scope=provided` 启用自动注解处理
|
|
- Maven 编译插件继承 Spring Boot 父 POM 配置
|
|
|
|
### 代码格式化和质量检查
|
|
|
|
项目集成了 Spotless 和 Checkstyle 插件:
|
|
|
|
#### Spotless (代码格式化)
|
|
- 基于空格的缩进 (4个空格)
|
|
- 自动清理尾随空白字符
|
|
- 文件末尾添加换行符
|
|
- 基本的导入组织
|
|
|
|
常用命令:
|
|
```bash
|
|
# 检查代码格式
|
|
mvn spotless:check
|
|
|
|
# 自动格式化代码
|
|
mvn spotless:apply
|
|
```
|
|
|
|
#### Checkstyle (代码规范检查)
|
|
- 使用 Sun Java 编码规范 (比 Google 规范更宽松)
|
|
- 在编译时自动检查代码规范
|
|
- 与 Java 11 和 Lombok 兼容
|
|
|
|
常用命令:
|
|
```bash
|
|
# 检查代码规范
|
|
mvn checkstyle:check
|
|
|
|
# 生成规范检查报告
|
|
mvn checkstyle:checkstyle
|
|
```
|
|
|
|
#### 集成命令
|
|
```bash
|
|
# 格式化代码并编译
|
|
mvn spotless:apply compile
|
|
|
|
# 完整检查 (格式化 + 规范检查 + 编译)
|
|
mvn spotless:apply checkstyle:check compile
|
|
```
|
|
|
|
## 部署说明
|
|
|
|
### Docker 构建和推送
|
|
|
|
项目支持多架构 Docker 构建，特别适合在 Apple Silicon Mac 上为 Linux 服务器构建镜像。
|
|
|
|
#### 构建镜像
|
|
|
|
```bash
|
|
# 构建服务器部署镜像 (Linux amd64)
|
|
./build-docker.sh amd64
|
|
|
|
# 构建本地开发镜像 (Apple Silicon arm64)
|
|
./build-docker.sh arm64
|
|
|
|
# 自动检测架构构建
|
|
./build-docker.sh
|
|
|
|
# 查看帮助
|
|
./build-docker.sh -h
|
|
```
|
|
|
|
#### 推送到私有仓库
|
|
|
|
```bash
|
|
# 推送 amd64 镜像到私有仓库 (用于服务器部署)
|
|
./push-docker.sh
|
|
```
|
|
|
|
### 服务器部署
|
|
|
|
#### 部署环境
|
|
- **服务器**: CentOS Linux
|
|
- **架构**: amd64
|
|
- **容器**: Docker + Docker Compose
|
|
|
|
#### 部署步骤
|
|
|
|
1. **服务器上的配置文件**
|
|
```bash
|
|
# 服务器主目录有专门的 docker-compose 文件
|
|
~/docker-compose.yml # 为 CentOS 环境优化的配置
|
|
```
|
|
|
|
2. **启动服务**
|
|
```bash
|
|
# 在服务器主目录执行
|
|
cd ~
|
|
docker-compose up -d
|
|
```
|
|
|
|
3. **查看日志**
|
|
```bash
|
|
# 应用日志位置
|
|
~/log/ # 应用日志目录
|
|
|
|
# 查看实时日志
|
|
tail -f ~/log/detail.log
|
|
tail -f ~/log/error.log
|
|
|
|
# 查看容器日志
|
|
docker-compose logs -f
|
|
```
|
|
|
|
#### 部署文件说明
|
|
|
|
- **~/docker-compose.yml**: 为 CentOS 环境定制的 Docker Compose 配置
|
|
- **~/log/**: 应用日志输出目录
|
|
- 配置文件已针对服务器环境进行优化，可直接使用
|
|
|
|
## 模块介绍
|
|
|
|
### play-admin
|
|
主要的 Spring Boot 应用，包含:
|
|
- REST API 接口
|
|
- 安全配置
|
|
- 数据库集成
|
|
- 微信集成
|
|
|
|
### play-common
|
|
共享工具库，包含:
|
|
- 公共域对象
|
|
- 工具类
|
|
- Redis 配置
|
|
- 安全工具
|
|
|
|
### play-generator
|
|
代码生成工具，包含:
|
|
- MyBatis Plus 代码生成
|
|
- 基于模板的代码生成
|
|
|
|
## 故障排除
|
|
|
|
### 常见问题
|
|
|
|
**编译失败: "cannot find symbol" 错误**
|
|
- 确保使用 Java 11: `java -version` 应显示 Java 11
|
|
- 设置正确的 JAVA_HOME: `export JAVA_HOME=$(/usr/libexec/java_home -v 11)`
|
|
- 清理并重新编译: `mvn clean compile`
|
|
|
|
**Maven 使用错误的 Java 版本**
|
|
- 检查 Maven 版本: `mvn -version`
|
|
- 创建 `~/.mavenrc` 文件设置 JAVA_HOME
|
|
- 或在命令前加环境变量: `JAVA_HOME=$(/usr/libexec/java_home -v 11) mvn clean compile`
|
|
|
|
**VS Code Java 支持问题**
|
|
- 确保安装了 Extension Pack for Java
|
|
- 检查 `.vscode/settings.json` 中的 Java 配置
|
|
- 重新加载窗口: Cmd+Shift+P → "Developer: Reload Window"
|
|
|
|
**Spotless 格式化问题**
|
|
- 修复格式问题: `mvn spotless:apply`
|
|
- 跳过格式检查: `mvn compile -Dspotless.check.skip=true`
|
|
|
|
### 验证配置
|
|
```bash
|
|
# 验证 Java 版本
|
|
java -version
|
|
|
|
# 验证 Maven Java 版本
|
|
mvn -version
|
|
|
|
# 验证编译
|
|
mvn clean compile
|
|
|
|
# 验证完整构建
|
|
mvn clean install
|
|
```
|
|
|
|
## 构建状态
|
|
|
|
✅ 所有模块使用 Java 11 编译成功
|
|
✅ Lombok 注解自动处理
|
|
✅ 模块间配置一致
|
|
✅ Spotless 代码格式化已配置
|
|
✅ Checkstyle 代码规范检查已配置
|
|
✅ VS Code Java 配置已设置 |