# 配置与部署规范落地说明

## 变更概述

本次更新根据 [`架构设计规范.md 第7章`](file:///home/along/MyCode/wanjiabuluo/worklog/doc/规范/架构设计规范.md) 的要求，完善了配置文件分离架构和部署相关文件，提高了配置管理的灵活性和可维护性。

## 主要变更内容

### 1. 配置文件分离架构（7.1 & 7.2 规范）

**新增配置文件**：

- [`src/main/resources/conf/env.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/env.properties) - 统一环境配置（所有服务共用）
- [`src/main/resources/conf/service.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/service.properties) - 服务个性化配置
- [`src/main/resources/conf/env.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/env.properties.example) - 环境配置模板
- [`src/main/resources/conf/service.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/conf/service.properties.example) - 服务配置模板

**配置内容说明**：

- **env.properties** 包含：
  - 数据库配置（MySQL 连接信息、连接池参数）
  - Redis 配置（连接信息、连接池参数）
  - Nacos 配置（注册中心和配置中心）
  - 文件上传配置
  - 日志配置（路径、级别）
  - JVM 配置（堆内存、元空间、GC 策略）
  - 业务配置（Token、日志内容限制等）

- **service.properties** 包含：
  - 服务名称和实例名称
  - 服务端口
  - 环境标识（dev/test/prod）
  - 租户标识（多租户场景）
  - 个性化覆盖配置

### 2. 启动脚本增强（7.2 规范）

**更新文件**：[`deploy/scripts/start.sh`](file:///home/along/MyCode/wanjiabuluo/worklog/deploy/scripts/start.sh)

**主要变更**：

1. **新增配置加载函数** `load_properties()`：
   - 支持自动加载 properties 文件
   - 跳过注释和空行
   - 将配置项导出为环境变量

2. **配置加载顺序**（遵循 7.2 规范）：
   ```bash
   # 1. 加载统一环境配置
   load_properties "${APP_HOME}/conf/env.properties"
   
   # 2. 加载服务个性化配置（覆盖同名参数）
   load_properties "${APP_HOME}/conf/service.properties"
   ```

3. **参数化配置**：
   - JVM 参数从环境变量读取（如未设置则使用默认值）
   - Spring Boot 配置从环境变量读取

### 3. 状态查看脚本（7.3 规范）

**新增文件**：[`deploy/scripts/status.sh`](file:///home/along/MyCode/wanjiabuluo/worklog/deploy/scripts/status.sh)

**功能特性**：

- 检查应用运行状态
- 显示进程详细信息（PID、启动时间、运行时长、CPU/内存占用）
- 显示端口监听情况
- 显示最近日志（最后 10 行）
- 提供快捷命令提示

### 4. 日志配置集中化（7.4 规范）

**更新文件**：[`worklog-api/src/main/resources/logback-spring.xml`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/logback-spring.xml)

**主要变更**：

1. **从环境变量读取配置**：
   ```xml
   <springProperty scope="context" name="LOG_PATH" source="logging.file.path" defaultValue="./logs"/>
   <springProperty scope="context" name="LOG_LEVEL_ROOT" source="logging.level.root" defaultValue="INFO"/>
   <springProperty scope="context" name="LOG_LEVEL_APP" source="logging.level.app" defaultValue="DEBUG"/>
   ```

2. **日志格式标准化**（强制包含 traceId 和 spanId）：
   ```xml
   <property name="LOG_PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId:-}][%X{spanId:-}] %-5level %logger{50} - %msg%n"/>
   ```

3. **日志文件命名**（遵循 7.4 规范）：
   - 主日志：`app.log`（所有级别）
   - SQL 日志：`sql.log`（MyBatis-Plus 独立输出）
   - 所有日志输出到 `logs/` 目录（扁平结构，无子目录）

4. **新增 MyBatis-Plus 框架日志配置**：
   ```xml
   <logger name="com.baomidou.mybatisplus" level="DEBUG" additivity="false">
       <appender-ref ref="SQL_FILE"/>
       <appender-ref ref="CONSOLE"/>
   </logger>
   ```

### 5. Bootstrap 配置文件（7.5 规范）

**新增文件**：[`worklog-api/src/main/resources/bootstrap.yml`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/bootstrap.yml)

**功能说明**：

- 用于 Nacos 配置中心（可选，默认禁用）
- 支持从环境变量读取 Nacos 配置
- 最先加载，优先级高于 application.yml

### 6. 安全配置管理

**更新文件**：[`.gitignore`](file:///home/along/MyCode/wanjiabuluo/worklog/.gitignore)

**新增忽略项**：

```gitignore
# conf 目录下的实际配置文件（敏感信息）
worklog-api/src/main/resources/conf/env.properties
worklog-api/src/main/resources/conf/service.properties
```

**安全策略**：

- 实际配置文件（包含敏感信息）不提交到仓库
- 仅提交配置模板文件（.example）
- 部署时复制模板并修改实际配置

### 7. 架构设计文档更新

**更新文件**：[`doc/架构设计文档.md`](file:///home/along/MyCode/wanjiabuluo/worklog/doc/架构设计文档.md)

**新增章节**：

- **9.4.5 配置文件分离架构**（新增，遵循架构设计规范第7章）
  - 9.4.5.1 配置文件结构
  - 9.4.5.2 配置加载顺序
  - 9.4.5.3 统一环境配置（env.properties）
  - 9.4.5.4 服务个性化配置（service.properties）
  - 9.4.5.5 日志配置集中化
  - 9.4.5.6 配置文件安全管理

- **9.4.6 环境配置文件管理**（更新，简化为单配置文件策略）
- **9.4.7 安全注意事项**（更新，补充配置文件权限管理）

## 目录结构变化

### 新增目录和文件

**开发阶段**：

```text
worklog-api/src/main/resources/
├── conf/                                    # 配置文件目录（开发阶段）
│   ├── env.properties                       # 统一环境配置
│   ├── service.properties                   # 服务个性化配置
│   ├── env.properties.example               # 环境配置模板
│   └── service.properties.example           # 服务配置模板
├── bootstrap.yml                            # 启动配置（新增）
└── logback-spring.xml                       # 更新：增强日志配置

deploy/                                       # 项目根目录
└── scripts/
    └── status.sh                            # 新增：状态查看脚本
```

**部署阶段**（打包后）：

### 部署目录结构（生产环境）

```text
/opt/worklog/worklog-api/
├── bin/                          # 脚本目录
│   ├── start.sh                  # 启动脚本（已增强）
│   ├── stop.sh                   # 停止脚本
│   ├── restart.sh                # 重启脚本
│   └── status.sh                 # 状态查看脚本（新增）
├── lib/                          # JAR 包目录
│   └── worklog-api.jar
├── conf/                         # 配置文件目录（新增）
│   ├── env.properties            # 统一环境配置
│   └── service.properties        # 服务个性化配置
└── logs/                         # 日志目录（扁平结构）
    ├── app.log                   # 应用主日志
    ├── sql.log                   # SQL 日志
    ├── console.log               # 控制台日志
    └── gc.log                    # GC 日志
```

## 配置规范对照

| 规范章节 | 规范要求 | 落地实现 | 状态 |
|---------|---------|---------|------|
| 7.1 配置文件分离 | env.properties + service.properties | ✅ 已实现 | ✅ |
| 7.2 配置加载顺序 | 先统一配置，后个性化配置 | ✅ start.sh 中实现 | ✅ |
| 7.3 打包目录结构 | bin/ lib/ conf/ | ✅ 已创建 | ✅ |
| 7.3 脚本完整性 | start/stop/restart/status | ✅ 已补充 status.sh | ✅ |
| 7.4 日志文件命名 | app.log 主日志 | ✅ 已配置 | ✅ |
| 7.4 SQL 日志独立 | sql.log 独立输出 | ✅ 已配置 | ✅ |
| 7.4 日志目录结构 | logs/ 扁平结构 | ✅ 已配置 | ✅ |
| 7.4 traceId/spanId | 强制包含 | ✅ 已配置 | ✅ |
| 7.4 配置参数化 | 从环境变量读取 | ✅ logback-spring.xml | ✅ |
| 7.5 Redis 配置 | 环境变量配置 | ✅ env.properties | ✅ |
| 7.5 Nacos 配置 | 环境变量配置 | ✅ env.properties + bootstrap.yml | ✅ |

## 部署指南

### 开发环境

1. 直接使用 [`application.yml`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/application.yml) 配置
2. 无需配置 env.properties 和 service.properties

### 生产环境

1. **复制配置模板**：
   ```bash
   cd /opt/worklog/worklog-api
   cp conf/env.properties.example conf/env.properties
   cp conf/service.properties.example conf/service.properties
   ```

2. **修改实际配置**：
   ```bash
   vim conf/env.properties        # 修改数据库、Redis 等配置
   vim conf/service.properties    # 修改服务名称、端口等
   ```

3. **设置文件权限**：
   ```bash
   chmod 600 conf/env.properties
   chmod 600 conf/service.properties
   ```

4. **启动应用**：
   ```bash
   ./bin/start.sh
   ```

5. **查看状态**：
   ```bash
   ./bin/status.sh
   ```

## 注意事项

1. **配置文件安全**：
   - 实际配置文件包含敏感信息（数据库密码、Redis 密码等）
   - 已在 .gitignore 中配置忽略，请勿提交到代码仓库
   - 生产环境需设置文件权限为 600

2. **配置加载顺序**：
   - env.properties → service.properties → application.yml
   - 后加载的配置会覆盖前面的同名配置

3. **日志文件**：
   - 主日志：app.log（所有级别）
   - SQL 日志：sql.log（MyBatis-Plus 独立输出）
   - 所有日志包含 traceId 和 spanId，便于链路追踪

4. **环境变量支持**：
   - 启动脚本会自动将 properties 文件的配置导出为环境变量
   - Spring Boot 和 Logback 可通过环境变量或 ${} 占位符读取配置

## 后续计划

根据架构设计规范，后续可继续完善：

1. **Maven Assembly 打包配置**（7.3 规范）：
   - 配置 assembly 插件
   - 自动打包为标准目录结构（bin/ lib/ conf/）

2. **多环境配置优化**：
   - 如需支持多环境，可创建多套 env.properties（env-dev.properties、env-prod.properties）
   - 启动时根据环境参数选择加载不同配置文件

3. **配置中心集成**（可选）：
   - 启用 Nacos 配置中心
   - 将敏感配置迁移到配置中心管理

## 相关文档

- [`架构设计规范.md`](file:///home/along/MyCode/wanjiabuluo/worklog/doc/规范/架构设计规范.md) - 第7章：配置与部署规范
- [`架构设计文档.md`](file:///home/along/MyCode/wanjiabuluo/worklog/doc/架构设计文档.md) - 第9章：部署配置
- [`DEPLOY.md`](file:///home/along/MyCode/wanjiabuluo/worklog/deploy/DEPLOY.md) - 部署指南