QAUP_Management/doc/working/20250110_qaup.sh更新说明.md

# qaup.sh 启动脚本更新说明

**日期**: 2025-01-10
**版本**: v2.0
**状态**: ✅ 已完成

---

## 📋 更新内容

### 新增功能

1. ✅ **环境变量加载功能**
   - 自动从 `.env` 文件加载环境变量
   - 支持配置文件不存在时的友好提示
   - 过滤注释行和空行

2. ✅ **Spring Profile 自动指定**
   - 默认使用 `prod,druid` profile
   - 支持通过环境变量 `SPRING_PROFILES_ACTIVE` 覆盖
   - 启动时显示使用的 profile

3. ✅ **代码优化**
   - 添加详细注释
   - 改进错误提示信息
   - 统一代码格式

---

## 🔧 主要修改点

### 1. 新增变量定义

```bash
# 环境变量配置文件路径
ENV_FILE=$APP_HOME/.env

# Spring Profile配置（生产环境使用prod，开发环境使用dev）
# 可通过环境变量 SPRING_PROFILES_ACTIVE 覆盖，默认为 prod,druid
SPRING_PROFILES=${SPRING_PROFILES_ACTIVE:-prod,druid}
```

### 2. start() 函数增强

**增加环境变量加载逻辑**:
```bash
# ========== 加载环境变量配置 ==========
if [ -f "$ENV_FILE" ]; then
    echo "Loading environment variables from $ENV_FILE"
    # 导出环境变量，忽略注释行和空行
    export $(cat $ENV_FILE | grep -v '^#' | grep -v '^$' | xargs)
    echo "Environment variables loaded successfully"
else
    echo "Warning: $ENV_FILE not found, using default configuration"
fi
# ========================================
```

**增加 Profile 提示和指定**:
```bash
echo "Starting $AppName with profile: $SPRING_PROFILES"

# 启动应用，指定Spring Profile
nohup java $JVM_OPTS -jar $AppName --spring.profiles.active=$SPRING_PROFILES > /dev/null 2>&1 &
```

### 3. case 语句优化

```bash
*)
    echo -e "\033[0;31m 未知操作 \033[0m  \033[0;34m {start|stop|restart|status} \033[0m"
esac
```

---

## 🚀 使用方式

### 基本使用（生产环境）

```bash
# 1. 创建环境变量文件
cp .env.example .env

# 2. 编辑配置
vim .env

# 3. 启动应用（自动使用 prod,druid profile）
./qaup.sh start

# 输出示例：
# Loading environment variables from /app/.env
# Environment variables loaded successfully
# Starting qaup-admin.jar with profile: prod,druid
# Start qaup-admin.jar success...
```

### 指定不同的 Profile

```bash
# 方式1: 通过环境变量
SPRING_PROFILES_ACTIVE=dev,druid ./qaup.sh start

# 方式2: 在脚本中修改 SPRING_PROFILES 默认值
# 编辑 qaup.sh，修改第17行：
SPRING_PROFILES=${SPRING_PROFILES_ACTIVE:-dev,druid}
```

### 无 .env 文件时的行为

```bash
./qaup.sh start

# 输出示例：
# Warning: /app/.env not found, using default configuration
# Starting qaup-admin.jar with profile: prod,druid
# Start qaup-admin.jar success...

# 应用将使用配置文件中的默认值启动
```

---

## 📊 与配置文件的配合

### 完整的配置加载流程

```
1. qaup.sh 启动
   ↓
2. 加载 .env 文件（如果存在）
   ↓
3. 导出环境变量到系统
   ↓
4. 启动 Java 应用，指定 profile=prod,druid
   ↓
5. Spring Boot 加载配置优先级：
   a. 环境变量（来自 .env）
   b. application-prod.yml
   c. application-druid.yml
   d. application.yml
   ↓
6. 最终配置 = 环境变量覆盖配置文件中的 ${VAR:default} 值
```

### 示例

**配置文件** (`application-prod.yml`):
```yaml
data:
  collector:
    airport-api:
      base-url: ${AIRPORT_API_BASE_URL:http://localhost:8090}
```

**.env 文件**:
```bash
AIRPORT_API_BASE_URL=http://192.168.1.100:8090
```

**实际运行时的值**:
```
data.collector.airport-api.base-url = http://192.168.1.100:8090
```

---

## ✅ 验证方法

### 1. 验证脚本语法

```bash
bash -n qaup.sh
# 无输出表示语法正确
```

### 2. 验证环境变量加载

```bash
# 创建测试 .env
cat > .env << EOF
TEST_VAR=test_value
AIRPORT_API_BASE_URL=http://test-server:8090
EOF

# 测试启动
./qaup.sh start

# 查看日志，确认：
# 1. 看到 "Loading environment variables" 消息
# 2. 看到 "Starting ... with profile: prod,druid"
# 3. 应用日志中 airport-api.base-url = http://test-server:8090
```

### 3. 验证 Profile 切换

```bash
# 使用 dev profile
SPRING_PROFILES_ACTIVE=dev,druid ./qaup.sh start

# 查看应用日志：
tail -f logs/qaup-admin.jar.log | grep "profiles are active"

# 应该看到：
# The following 2 profiles are active: "dev", "druid"
```

---

## 🔄 与旧版本的对比

| 功能 | 旧版本 | 新版本 |
|-----|--------|--------|
| **环境变量支持** | ❌ 无 | ✅ 自动加载 .env |
| **Profile 指定** | ❌ 无（使用默认） | ✅ 自动指定 prod,druid |
| **配置修改** | ❌ 需重新打包 | ✅ 修改 .env 即可 |
| **启动提示** | ❌ 简单提示 | ✅ 详细信息 |
| **错误处理** | ⚠️ 基础 | ✅ 友好提示 |

---

## ⚠️ 注意事项

### 1. .env 文件格式

```bash
# ✅ 正确格式
DB_HOST=localhost
DB_PORT=5432

# ❌ 错误格式
DB_HOST = localhost           # 等号两边有空格
DB_HOST="localhost"           # 使用了引号
export DB_HOST=localhost      # 使用了 export
```

### 2. 安全建议

```bash
# 设置 .env 文件权限
chmod 600 .env

# 防止提交到 Git
echo ".env" >> .gitignore
```

### 3. 多环境部署

```bash
# 开发环境
SPRING_PROFILES_ACTIVE=dev,druid ./qaup.sh start

# 测试环境
SPRING_PROFILES_ACTIVE=test,druid ./qaup.sh start

# 生产环境（默认）
./qaup.sh start
```

---

## 📚 相关文档

- [配置文件重构说明](./20250110_配置文件重构说明.md)
- [环境变量配置方案](./20250110_环境变量配置方案.md)
- [工作文档目录](./README.md)

---

## 🔍 故障排查

### 问题1: 环境变量未生效

**症状**: 应用仍使用配置文件中的默认值

**排查**:
```bash
# 1. 检查 .env 是否存在
ls -la .env

# 2. 检查启动日志是否有加载提示
# 应该看到: "Loading environment variables from ..."

# 3. 手动测试环境变量加载
source .env
echo $AIRPORT_API_BASE_URL
```

**解决**: 确保 .env 文件格式正确，无空格和引号

---

### 问题2: Profile 未正确激活

**症状**: 应用启动但使用了错误的 profile

**排查**:
```bash
# 查看启动日志
tail -f logs/qaup-admin.jar.log | grep "profiles are active"
```

**解决**:
```bash
# 检查启动脚本中的 SPRING_PROFILES 变量
grep SPRING_PROFILES qaup.sh

# 或显式指定
SPRING_PROFILES_ACTIVE=prod,druid ./qaup.sh restart
```

---

### 问题3: 脚本执行权限

**症状**: `./qaup.sh: Permission denied`

**解决**:
```bash
chmod +x qaup.sh
```

---

## 🎯 下一步建议

### 已完成

1. ✅ 启动脚本更新
2. ✅ 环境变量支持
3. ✅ Profile 自动指定

### 待完成

1. ❌ 测试验证（开发环境和生产环境）
2. ❌ 更新项目文档（README.md, CLAUDE.md）
3. ❌ 创建生产环境 .env 文件模板

---

**文档结束**

**最后更新**: 2025-01-10
**脚本版本**: v2.0
**维护者**: QAUP Team