294 lines
6.0 KiB
Markdown
294 lines
6.0 KiB
Markdown
# 配置重构后的编译说明
|
||
|
||
**日期**: 2025-01-10
|
||
**适用版本**: v1.0.1+
|
||
|
||
---
|
||
|
||
## ❓ 配置重构后，编译命令需要改吗？
|
||
|
||
### 答案：❌ 不需要改！
|
||
|
||
---
|
||
|
||
## 📋 编译命令保持不变
|
||
|
||
### 开发环境编译
|
||
|
||
```bash
|
||
# 完整编译
|
||
mvn clean install
|
||
|
||
# 跳过测试（更快）
|
||
mvn clean install -DskipTests
|
||
|
||
# 只编译 admin 模块
|
||
cd qaup-admin
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
### 生产环境打包
|
||
|
||
```bash
|
||
# 打包生产版本
|
||
mvn clean package -DskipTests
|
||
|
||
# 或指定 profile（可选）
|
||
mvn clean package -DskipTests -Pprod
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 为什么不需要修改？
|
||
|
||
### 1. 配置文件自动打包
|
||
|
||
Maven 会自动将 `src/main/resources/` 下的所有文件打包到 jar 中，包括：
|
||
|
||
```
|
||
qaup-admin/src/main/resources/
|
||
├── application.yml ✅ 自动打包
|
||
├── application-dev.yml ✅ 自动打包
|
||
├── application-prod.yml ✅ 自动打包
|
||
└── application-druid.yml ✅ 自动打包
|
||
```
|
||
|
||
### 2. 环境变量是运行时机制
|
||
|
||
- `.env` 文件**不打包**到 jar 中（也不应该打包）
|
||
- 环境变量在应用**启动时**由 `qaup.sh` 加载
|
||
- 与编译过程无关
|
||
|
||
### 3. Profile 在运行时指定
|
||
|
||
- Profile 通过 `--spring.profiles.active` 在启动时指定
|
||
- 不影响编译过程
|
||
|
||
---
|
||
|
||
## 📦 打包后的结构
|
||
|
||
### jar 包内部结构
|
||
|
||
```
|
||
qaup-admin.jar
|
||
├── BOOT-INF/
|
||
│ ├── classes/
|
||
│ │ ├── application.yml ✅ 打包
|
||
│ │ ├── application-dev.yml ✅ 打包
|
||
│ │ ├── application-prod.yml ✅ 打包
|
||
│ │ ├── application-druid.yml ✅ 打包
|
||
│ │ └── com/qaup/... (Java类)
|
||
│ └── lib/ (依赖jar)
|
||
├── META-INF/
|
||
└── org/springframework/boot/loader/
|
||
```
|
||
|
||
### 部署目录结构
|
||
|
||
```
|
||
/app/ # 部署目录
|
||
├── qaup-admin.jar # 打包的jar（包含所有配置文件）
|
||
├── qaup.sh # 启动脚本
|
||
├── .env ❌ 不打包，部署时手动创建
|
||
├── .env.example 📝 可选（建议通过Git获取）
|
||
└── logs/ # 日志目录
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 完整的开发-部署流程
|
||
|
||
### 1️⃣ 开发阶段（本地）
|
||
|
||
```bash
|
||
# 方式1: IDEA 中直接启动
|
||
# 自动使用 dev profile，无需编译
|
||
|
||
# 方式2: Maven 启动
|
||
cd qaup-admin
|
||
mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid
|
||
```
|
||
|
||
### 2️⃣ 打包阶段
|
||
|
||
```bash
|
||
# 在项目根目录执行
|
||
mvn clean package -DskipTests
|
||
|
||
# 生成的 jar 包位置
|
||
ls -lh qaup-admin/target/qaup-admin.jar
|
||
```
|
||
|
||
### 3️⃣ 部署阶段
|
||
|
||
```bash
|
||
# 1. 复制文件到服务器
|
||
scp qaup-admin/target/qaup-admin.jar user@server:/app/
|
||
scp qaup.sh user@server:/app/
|
||
scp .env.example user@server:/app/
|
||
|
||
# 2. 在服务器上创建配置
|
||
cd /app
|
||
cp .env.example .env
|
||
vim .env
|
||
|
||
# 3. 启动应用
|
||
./qaup.sh start
|
||
```
|
||
|
||
---
|
||
|
||
## 🔒 重要提醒
|
||
|
||
### ✅ 应该做的
|
||
|
||
1. **打包所有配置文件到 jar**
|
||
```bash
|
||
# application*.yml 会自动打包
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
2. **在部署时创建 .env**
|
||
```bash
|
||
# 在服务器上创建
|
||
cp .env.example .env
|
||
vim .env
|
||
```
|
||
|
||
3. **通过 Git 管理配置模板**
|
||
```bash
|
||
# .gitignore
|
||
.env # 忽略实际配置
|
||
!.env.example # 保留模板
|
||
```
|
||
|
||
### ❌ 不应该做的
|
||
|
||
1. **不要把 .env 打包到 jar**
|
||
- 包含敏感信息
|
||
- 每个环境配置不同
|
||
|
||
2. **不要在编译时指定环境变量**
|
||
```bash
|
||
# ❌ 错误
|
||
mvn clean package -DAIRPORT_API_BASE_URL=http://...
|
||
|
||
# ✅ 正确：编译时不指定，运行时通过 .env 加载
|
||
mvn clean package -DskipTests
|
||
```
|
||
|
||
3. **不要打包备份文件**
|
||
```bash
|
||
# 打包前删除
|
||
rm qaup-admin/src/main/resources/*.backup
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 建议的 .gitignore 配置
|
||
|
||
```bash
|
||
# 环境变量配置（重要！）
|
||
.env
|
||
.env.local
|
||
.env.production
|
||
.env.*.local
|
||
|
||
# 配置备份文件
|
||
*.backup
|
||
|
||
# 日志文件
|
||
logs/
|
||
*.log
|
||
|
||
# Maven 构建目录
|
||
target/
|
||
|
||
# IDEA 项目文件
|
||
.idea/
|
||
*.iml
|
||
```
|
||
|
||
---
|
||
|
||
## 🆚 配置重构前后对比
|
||
|
||
| 项目 | 重构前 | 重构后 |
|
||
|-----|--------|--------|
|
||
| **编译命令** | `mvn clean package` | `mvn clean package` ✅ 不变 |
|
||
| **配置修改** | 修改配置文件 → 重新打包 | 修改 .env → 重启应用 |
|
||
| **环境切换** | 修改配置文件 → 重新打包 | 切换 .env → 重启应用 |
|
||
| **敏感信息** | 打包到 jar 中 ❌ | 保存在 .env 中 ✅ |
|
||
|
||
---
|
||
|
||
## 💡 常见问题
|
||
|
||
### Q1: `.env.example` 要打包到 jar 吗？
|
||
|
||
**A**: 📝 建议不打包
|
||
|
||
**原因**:
|
||
- 可以通过 Git 获取
|
||
- 减小 jar 体积
|
||
- 部署时从项目源码复制
|
||
|
||
**操作**:
|
||
```bash
|
||
# 部署时从项目获取
|
||
git clone <repo>
|
||
cp <project>/.env.example /app/.env
|
||
```
|
||
|
||
### Q2: 如果我只修改了 .env，需要重新编译吗？
|
||
|
||
**A**: ❌ 不需要
|
||
|
||
```bash
|
||
# 只需要
|
||
vim .env
|
||
./qaup.sh restart
|
||
```
|
||
|
||
### Q3: 如果我修改了 application-prod.yml，需要重新编译吗？
|
||
|
||
**A**: ✅ 需要
|
||
|
||
```bash
|
||
# 修改配置文件后
|
||
mvn clean package -DskipTests
|
||
|
||
# 重新部署 jar
|
||
scp qaup-admin/target/qaup-admin.jar user@server:/app/
|
||
./qaup.sh restart
|
||
```
|
||
|
||
**建议**: 尽量使用环境变量方式，避免重新打包
|
||
|
||
---
|
||
|
||
## 🎯 最佳实践总结
|
||
|
||
1. ✅ **编译命令保持不变**: `mvn clean package -DskipTests`
|
||
2. ✅ **配置文件自动打包**: 所有 `application*.yml` 都会打包
|
||
3. ✅ **环境变量运行时加载**: `.env` 不打包，部署时创建
|
||
4. ✅ **敏感信息不打包**: 密码、地址等通过 `.env` 管理
|
||
5. ✅ **一次打包，多环境部署**: 通过不同的 `.env` 文件区分环境
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [配置文件重构说明](../working/20250110_配置文件重构说明.md)
|
||
- [环境变量配置方案](../working/20250110_环境变量配置方案.md)
|
||
- [qaup.sh 更新说明](../working/20250110_qaup.sh更新说明.md)
|
||
- [CLAUDE.md - 项目说明](../../CLAUDE.md)
|
||
|
||
---
|
||
|
||
**文档结束**
|
||
|
||
**最后更新**: 2025-01-10
|
||
**维护者**: QAUP Team
|