Web_BLS_RCUAction_Server/openspec/changes/2026-03-03-database-initialization-config/summary.md

配置化数据库初始化 - 实现总结

日期：2026年3月3日
功能：使数据库初始化和分区维护可配置化

变更内容

1. 新增环境变量

• 变量名：ENABLE_DATABASE_INITIALIZATION
• 类型：Boolean
• 默认值：true（启用）
• 说明：控制是否在服务启动时执行数据库初始化和分区维护

2. 修改的文件

src/config/config.js

• 行 69：新增配置项 enableDatabaseInitialization
• 逻辑：enableDatabaseInitialization: process.env.ENABLE_DATABASE_INITIALIZATION !== 'false' （默认 true）

src/index.js

• 第 21-28 行：修改初始化逻辑

  • 添加条件判断：if (config.enableDatabaseInitialization)
  • 启用时：执行 dbInitializer.initialize()
  • 禁用时：记录日志并跳过

• 第 36-47 行：修改分区维护定时任务

  • 添加条件判断：仅当 config.enableDatabaseInitialization 为 true 时，才注册定时任务
  • 禁用时：记录日志说明定时任务已禁用

.env

• 末尾新增配置注释和示例：

  # Database Initialization Configuration
  # Set to 'false' to skip automatic database creation, schema setup, and partition management
  # When disabled, the service will start consuming Kafka messages and writing to existing database immediately
  # Default: true (enable database initialization)
  ENABLE_DATABASE_INITIALIZATION=true
  

.env.example

• 末尾新增配置说明（同上）

docs/DATABASE_INITIALIZATION_CONFIG.md（新增）

• 详细的使用指南和配置说明
• 包含多种使用场景
• 故障排查建议

行为变化

启用初始化（ENABLE_DATABASE_INITIALIZATION=true）

启动服务
  ↓
执行 dbInitializer.initialize()
  ├─ 检查/创建数据库
  ├─ 执行 init_db.sql（创建 schema 和主表）
  └─ 创建未来 30 天的分区
  ↓
注册定时任务：每天 00:00 检查并创建新分区
  ↓
初始化项目元数据缓存
  ↓
启动 Kafka 消费者
  ↓
开始处理消息

禁用初始化（ENABLE_DATABASE_INITIALIZATION=false）

启动服务
  ↓
跳过 dbInitializer.initialize()
  ↓
不注册分区维护定时任务
  ↓
初始化项目元数据缓存
  ↓
启动 Kafka 消费者
  ↓
开始处理消息（直接）

向后兼容性

✅ 完全向后兼容

• 不执行此配置时，默认行为为 true（启用初始化）
• 现有部署无需修改即可继续运行
• 新部署可根据需要设置为 false 以跳过初始化

适用场景

场景	配置值	说明
首次部署	true	自动完成初始化
生产环境（已初始化）	false	跳过初始化，直接消费
多实例部署	实例1：true 其他：false	一个实例初始化，其他跳过
容器编排（K8s）	false	初始化 Job 单独执行，应用跳过

关键改进

1. 启动速度：禁用初始化可减少启动时间 5-10 秒（避免分区检查）
2. 灵活部署：支持多实例场景，避免并发创建表
3. 生产友好：可明确控制何时执行 DDL 操作
4. 日志清晰：明确说明初始化状态和定时任务是否启用

测试验证

测试 1：启用初始化（默认）

ENABLE_DATABASE_INITIALIZATION=true npm run dev
# 预期：看到初始化日志

测试 2：禁用初始化

ENABLE_DATABASE_INITIALIZATION=false npm run dev
# 预期：看到"Database initialization is disabled"日志，跳过初始化，直接消费消息

测试 3：多实例启动

# 终端 1
ENABLE_DATABASE_INITIALIZATION=true npm run dev

# 等待初始化完成，然后在另一个终端

# 终端 2
ENABLE_DATABASE_INITIALIZATION=false npm run dev
# 预期：第二个实例直接启动消费，无冲突

依赖无变化

• 不需要新增 npm 包
• 不需要修改数据库结构
• 不需要修改 Kafka 配置

后续可扩展

• 可进一步细化：分离"创建表"开关和"分区维护"开关
• 可添加"从外部 API 初始化元数据"的选项
• 可支持自定义初始化 SQL 脚本路径