ae97de3d69
- 配置文件直接放在 src/main/resources/ 目录下 - 更新 assembly.xml 从 resources 目录获取配置文件 - 更新 .gitignore 忽略路径 - 同步更新架构设计文档和配置规范落地说明
288 lines
11 KiB
Markdown
288 lines
11 KiB
Markdown
# 配置与部署规范落地说明
|
||
|
||
## 变更概述
|
||
|
||
本次更新根据 [`架构设计规范.md 第7章`](file:///home/along/MyCode/wanjiabuluo/worklog/doc/规范/架构设计规范.md) 的要求，完善了配置文件分离架构和部署相关文件，提高了配置管理的灵活性和可维护性。
|
||
|
||
## 主要变更内容
|
||
|
||
### 1. 配置文件分离架构（7.1 & 7.2 规范）
|
||
|
||
**新增配置文件**：
|
||
|
||
- [`src/main/resources/env.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/env.properties) - 统一环境配置（所有服务共用）
|
||
- [`src/main/resources/service.properties`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/service.properties) - 服务个性化配置
|
||
- [`src/main/resources/env.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/env.properties.example) - 环境配置模板
|
||
- [`src/main/resources/service.properties.example`](file:///home/along/MyCode/wanjiabuluo/worklog/worklog-api/src/main/resources/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
|
||
# 实际配置文件（敏感信息，仅模板提交）
|
||
src/main/resources/env.properties
|
||
src/main/resources/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/
|
||
├── application.yml # 主配置文件
|
||
├── application.yml.example # 主配置模板
|
||
├── bootstrap.yml # 启动配置（新增）
|
||
├── logback-spring.xml # 更新：增强日志配置
|
||
├── env.properties # 统一环境配置（敏感信息，不提交）
|
||
├── env.properties.example # 环境配置模板
|
||
├── service.properties # 服务个性化配置（敏感信息，不提交）
|
||
└── service.properties.example # 服务配置模板
|
||
|
||
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) - 部署指南
|