buff/backend/HEARTBEAT_CONFIG_UPDATE.md

心跳实时配置更新功能

📋 功能概述

通过心跳机制实现客户端配置的实时更新，无需重启应用即可应用新的配置。

🔧 实现原理

后端实现

心跳API (/api/user/heartbeat) 在每次响应中包含最新的客户端配置信息：

{
  "code": 200,
  "msg": "成功",
  "data": {
    "expire_time": "2026-12-31T23:59:59",
    "server_time": "2026-01-06T17:23:25.000000",
    "session_status": "active",
    "next_heartbeat": 30,
    "session_expires_at": "2026-01-07T17:23:25.000000",
    "session_extend_enabled": true,
    "session_extend_threshold_hours": 4,
    "client_configs": {
      "api_timeout_seconds": 30,
      "client_heartbeat_interval_seconds": 30,
      "max_heartbeat_failures": 10,
      "max_network_failures": 15
    }
  }
}

客户端实现

客户端在每次心跳成功时检查并更新配置：

// 检查是否有配置更新
if (updatedUserInfo.client_configs) {
  console.log('检测到配置更新:', updatedUserInfo.client_configs)

  // 更新全局配置
  Object.assign(props.globalConfig, newConfig)

  // 如果心跳间隔发生变化，需要重新启动心跳
  if (oldInterval !== newInterval) {
    console.log(`心跳间隔从 ${oldInterval} 秒变为 ${newInterval} 秒，重新启动心跳`)
    stopHeartbeat()
    startHeartbeat()
  }
}

📊 配置项说明

配置项	说明	默认值	影响
api_timeout_seconds	API请求超时秒数	30	API调用的超时时间
client_heartbeat_interval_seconds	客户端心跳间隔秒数	30	心跳检测频率
max_heartbeat_failures	最大心跳失败次数	10	超过后暂停心跳检测
max_network_failures	网络异常最大失败次数	15	超过后自动登出

🔄 配置更新流程

1. 管理员修改配置：

   UPDATE system_config SET config_value='60' WHERE config_key='client_heartbeat_interval_seconds';
   

   1. 客户端自动更新：
   2. 心跳请求 → 服务器返回最新配置
   3. 客户端检测到配置变化 → 更新本地配置

   4. 如有必要，重新启动相关服务

   5. 实时生效：

   6. 无需重启应用

   7. 立即生效

   🛡️ 安全特性

   • 验证机制：只有有效的用户会话才能获取配置
   • 类型安全：配置值会自动转换为正确的数据类型
   • 容错处理：配置更新失败不影响心跳功能
   • 日志记录：配置更新会被记录到客户端日志

   📈 优势

   🚀 实时性

   • 配置变更秒级生效
   • 支持动态调整系统行为

   🔧 维护性

   • 热更新，无需重启
   • 集中化配置管理
   • 支持A/B测试和灰度发布

   📊 可观测性

   • 配置变更可追踪
   • 客户端日志记录
   • 管理员可监控配置生效情况

   🧪 测试验证

   后端测试

   cd /Users/wuzilong/work/00code/Buff/backend
   python test_heartbeat_config.py
   

客户端测试

1. 启动应用并登录
2. 修改数据库配置
3. 观察客户端日志中的配置更新信息
4. 验证新配置是否生效

📝 使用示例

修改心跳间隔

-- 将心跳间隔改为60秒
UPDATE system_config SET config_value='60' WHERE config_key='client_heartbeat_interval_seconds';

客户端会在下次心跳时自动调整间隔，并输出日志：

检测到配置更新: {client_heartbeat_interval_seconds: 60}
心跳间隔从 30 秒变为 60 秒，重新启动心跳

修改失败重试次数

-- 增加网络异常容忍度
UPDATE system_config SET config_value='20' WHERE config_key='max_network_failures';

客户端会自动应用新配置，提高网络异常的容忍度。

🔍 监控和调试

日志监控

客户端会在检测到配置更新时输出详细日志：

[心跳] 检测到配置更新: {...}
[心跳] 心跳间隔从 X 秒变为 Y 秒，重新启动心跳

配置验证

可以通过以下方式验证配置是否正确应用：

1. 客户端日志：查看心跳日志中的配置更新信息
2. 数据库查询：检查system_config表的配置值
3. API测试：调用心跳API查看返回的client_configs

🚨 注意事项

• 配置更新只在心跳成功时进行
• 网络异常时不会更新配置（避免配置丢失）
• 敏感配置需要重启应用才能生效
• 建议在低峰期进行重要配置变更

---

此功能让系统具备了真正的动态配置能力，大大提升了系统的灵活性和可维护性。