worklog/doc/配置规范落地说明.md

配置与部署规范落地说明

变更概述

本次更新根据 架构设计规范.md 第7章 的要求，完善了配置文件分离架构和部署相关文件，提高了配置管理的灵活性和可维护性。

主要变更内容

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

新增配置文件：

• src/main/resources/env.properties - 统一环境配置（所有服务共用）
• src/main/resources/service.properties - 服务个性化配置
• src/main/resources/env.properties.example - 环境配置模板
• 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

主要变更：

1. 新增配置加载函数 load_properties()：

   • 支持自动加载 properties 文件
   • 跳过注释和空行
   • 将配置项导出为环境变量

2. 配置加载顺序（遵循 7.2 规范）：

   # 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

功能特性：

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

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

更新文件：worklog-api/src/main/resources/logback-spring.xml

主要变更：

1. 从环境变量读取配置：

   <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）：

   <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 框架日志配置：

   <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

功能说明：

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

6. 安全配置管理

更新文件：.gitignore

新增忽略项：

# 实际配置文件（敏感信息，仅模板提交）
src/main/resources/env.properties
src/main/resources/service.properties

安全策略：

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

7. 架构设计文档更新

更新文件：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 安全注意事项（更新，补充配置文件权限管理）

目录结构变化

新增目录和文件

开发阶段：

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                 # 新增：状态查看脚本

部署阶段（打包后）：

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

/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 配置
2. 无需配置 env.properties 和 service.properties

生产环境

1. 复制配置模板：

   cd /opt/worklog/worklog-api
   cp conf/env.properties.example conf/env.properties
   cp conf/service.properties.example conf/service.properties
   

2. 修改实际配置：

   vim conf/env.properties        # 修改数据库、Redis 等配置
   vim conf/service.properties    # 修改服务名称、端口等
   

3. 设置文件权限：

   chmod 600 conf/env.properties
   chmod 600 conf/service.properties
   

4. 启动应用：

   ./bin/start.sh
   

5. 查看状态：

   ./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 - 第7章：配置与部署规范
• 架构设计文档.md - 第9章：部署配置
• DEPLOY.md - 部署指南