config_backup.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317
  1. """DTU 运行数据备份/快照工具。
  2. 功能:
  3. - 原子写 JSON 配置(write_json_atomic)
  4. - 写前自动快照(snapshot_before_write): 内容变化才快照, 每类保留最近 N 份, 节流去重
  5. - 快照列表/读取/删除(list_snapshots/read_snapshot/delete_snapshot/find_latest_snapshot)
  6. - 整机备份包构建与校验(build_bundle/validate_bundle)
  7. 整机备份包(bundle)结构:
  8. {
  9. "format": "dzxj_dtu_backup",
  10. "format_version": 1,
  11. "created_at": "2026-10-13T14:00:00+0800",
  12. "device": {"dtu_id": ..., "customer_id": ..., ...},
  13. "effective_uid_prefix": "A1B2", # 导入时固化, 保证换机后 jumper_uid 前缀不变
  14. "files": {
  15. "dtu_config": {...}, "serial_config": {...}, "mqtt_config": {...},
  16. "devices": {...}, "system_env": "..."
  17. }
  18. }
  19. """
  20. import json
  21. import logging
  22. import os
  23. import re
  24. import time
  25. logger = logging.getLogger('serial_mqtt_gateway')
  26. BUNDLE_FORMAT = 'dzxj_dtu_backup'
  27. BUNDLE_FORMAT_VERSION = 1
  28. MAX_BUNDLE_BYTES = 2 * 1024 * 1024
  29. DEFAULT_KEEP = 20
  30. DEFAULT_MIN_INTERVAL_S = 30
  31. # 快照目录:DATA_DIR/backups(源码运行 = backend/backups;打包后 = exe 同级 data/backups)
  32. try:
  33. from paths import DATA_DIR as _DATA_DIR
  34. except ImportError: # 以包方式导入(backend.modules.config_backup)时的兜底
  35. _DATA_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
  36. BACKUP_DIR = os.path.join(_DATA_DIR, 'backups')
  37. _SNAPSHOT_RE = re.compile(r'^(.+)_(\d{8}_\d{6})(?:_(\d+))?\.json$')
  38. _UID_RE = re.compile(r'^[0-9a-fA-F]{24}$')
  39. _PREFIX_RE = re.compile(r'^[0-9a-fA-F]{4}$')
  40. BUNDLE_FILES = ('dtu_config', 'serial_config', 'mqtt_config', 'devices', 'system_env')
  41. def ensure_backup_dir(backup_dir=BACKUP_DIR):
  42. """确保备份目录存在"""
  43. try:
  44. os.makedirs(backup_dir, exist_ok=True)
  45. except OSError as e:
  46. logger.error(f"创建备份目录失败: {e}")
  47. return backup_dir
  48. def write_json_atomic(path, data):
  49. """原子写 JSON 文件(tmp + os.replace), 避免写一半损坏"""
  50. tmp_path = f"{path}.tmp"
  51. with open(tmp_path, 'w', encoding='utf-8') as f:
  52. json.dump(data, f, indent=2, ensure_ascii=False)
  53. os.replace(tmp_path, path)
  54. def read_json_file(path):
  55. """读取 JSON 文件, 失败抛出异常"""
  56. with open(path, 'r', encoding='utf-8') as f:
  57. return json.load(f)
  58. def _snapshot_name(raw_name):
  59. """校验快照文件名, 防路径穿越; 非法返回 None"""
  60. if not raw_name or os.path.basename(raw_name) != raw_name:
  61. return None
  62. return raw_name if _SNAPSHOT_RE.match(raw_name) else None
  63. def snapshot_stem(name):
  64. """从快照文件名提取原始配置文件 stem, 非法返回 None"""
  65. safe = _snapshot_name(name)
  66. if not safe:
  67. return None
  68. return _SNAPSHOT_RE.match(safe).group(1)
  69. def list_snapshots(backup_dir=BACKUP_DIR, stem=None):
  70. """列出快照, 按修改时间倒序(最新在前)
  71. 返回: [{'name','stem','size','mtime'}, ...]
  72. """
  73. result = []
  74. if not os.path.isdir(backup_dir):
  75. return result
  76. for name in os.listdir(backup_dir):
  77. m = _SNAPSHOT_RE.match(name)
  78. if not m:
  79. continue
  80. if stem and m.group(1) != stem:
  81. continue
  82. path = os.path.join(backup_dir, name)
  83. try:
  84. st = os.stat(path)
  85. except OSError:
  86. continue
  87. result.append({
  88. 'name': name,
  89. 'stem': m.group(1),
  90. 'size': st.st_size,
  91. 'mtime': st.st_mtime,
  92. })
  93. result.sort(key=lambda x: x['mtime'], reverse=True)
  94. return result
  95. def find_latest_snapshot(backup_dir=BACKUP_DIR, stem=None):
  96. """返回最新一份快照信息, 无则 None"""
  97. snaps = list_snapshots(backup_dir, stem=stem)
  98. return snaps[0] if snaps else None
  99. def read_snapshot(name, backup_dir=BACKUP_DIR):
  100. """读取快照内容(JSON), 返回 (data, error)"""
  101. safe = _snapshot_name(name)
  102. if not safe:
  103. return None, '非法快照文件名'
  104. path = os.path.join(backup_dir, safe)
  105. if not os.path.exists(path):
  106. return None, '快照不存在'
  107. try:
  108. with open(path, 'r', encoding='utf-8') as f:
  109. return json.load(f), None
  110. except Exception as e:
  111. return None, f'快照解析失败: {e}'
  112. def delete_snapshot(name, backup_dir=BACKUP_DIR):
  113. """删除快照, 返回 (ok, message)"""
  114. safe = _snapshot_name(name)
  115. if not safe:
  116. return False, '非法快照文件名'
  117. path = os.path.join(backup_dir, safe)
  118. if not os.path.exists(path):
  119. return False, '快照不存在'
  120. try:
  121. os.remove(path)
  122. return True, '已删除'
  123. except OSError as e:
  124. return False, f'删除失败: {e}'
  125. def _rotate_snapshots(backup_dir, stem, keep):
  126. """每类快照只保留最近 keep 份"""
  127. snaps = list_snapshots(backup_dir, stem=stem) # 倒序
  128. for item in snaps[keep:]:
  129. try:
  130. os.remove(os.path.join(backup_dir, item['name']))
  131. logger.info(f"清理旧配置快照: {item['name']}")
  132. except OSError:
  133. pass
  134. def snapshot_before_write(path, backup_dir=BACKUP_DIR, keep=DEFAULT_KEEP,
  135. min_interval_s=DEFAULT_MIN_INTERVAL_S, now=None):
  136. """写文件前对现有内容做快照。
  137. 规则:
  138. - 目标文件不存在或为空 -> 不快照
  139. - 内容与最新快照相同 -> 跳过(去重)
  140. - 距最新快照不足 min_interval_s -> 跳过(节流)
  141. 返回快照文件名, 未创建返回 None
  142. """
  143. now = time.time() if now is None else now
  144. try:
  145. if not os.path.exists(path) or os.path.getsize(path) == 0:
  146. return None
  147. with open(path, 'rb') as f:
  148. current = f.read()
  149. stem = os.path.splitext(os.path.basename(path))[0]
  150. latest = find_latest_snapshot(backup_dir, stem=stem)
  151. if latest:
  152. try:
  153. with open(os.path.join(backup_dir, latest['name']), 'rb') as f:
  154. if f.read() == current:
  155. return None
  156. except OSError:
  157. pass
  158. if now - latest['mtime'] < min_interval_s:
  159. return None
  160. ensure_backup_dir(backup_dir)
  161. base = os.path.join(
  162. backup_dir,
  163. f"{stem}_{time.strftime('%Y%m%d_%H%M%S', time.localtime(now))}.json"
  164. )
  165. target = base
  166. counter = 1
  167. while os.path.exists(target):
  168. target = base[:-5] + f"_{counter}.json"
  169. counter += 1
  170. with open(target, 'wb') as f:
  171. f.write(current)
  172. try:
  173. os.utime(target, (now, now)) # 统一 mtime 与逻辑时间, 保证节流/轮转排序一致
  174. except OSError:
  175. pass
  176. _rotate_snapshots(backup_dir, stem, keep)
  177. logger.info(f"配置快照已保存: {os.path.basename(target)}")
  178. return os.path.basename(target)
  179. except Exception as e:
  180. logger.error(f"配置快照失败({path}): {e}")
  181. return None
  182. def latest_snapshot_content(path, backup_dir=BACKUP_DIR):
  183. """取某配置文件最新快照的内容(用于损坏恢复), 返回 (data, name) 或 (None, None)"""
  184. stem = os.path.splitext(os.path.basename(path))[0]
  185. latest = find_latest_snapshot(backup_dir, stem=stem)
  186. if not latest:
  187. return None, None
  188. data, err = read_snapshot(latest['name'], backup_dir=backup_dir)
  189. if err:
  190. logger.warning(f"读取快照 {latest['name']} 失败: {err}")
  191. return None, latest['name']
  192. return data, latest['name']
  193. def build_bundle(files, device_meta=None, uid_prefix=None, now=None):
  194. """构建整机备份包"""
  195. now = time.time() if now is None else now
  196. prefix = (uid_prefix or '').strip().upper()
  197. return {
  198. 'format': BUNDLE_FORMAT,
  199. 'format_version': BUNDLE_FORMAT_VERSION,
  200. 'created_at': time.strftime('%Y-%m-%dT%H:%M:%S', time.localtime(now)),
  201. 'device': device_meta or {},
  202. 'effective_uid_prefix': prefix if _PREFIX_RE.match(prefix) else None,
  203. 'files': files,
  204. }
  205. def _validate_address_range(value):
  206. if not isinstance(value, dict):
  207. return 'address_range 必须是对象'
  208. start = value.get('start')
  209. end = value.get('end')
  210. if not isinstance(start, int) or not isinstance(end, int):
  211. return 'address_range.start/end 必须是整数'
  212. if not (1 <= start <= 247) or not (1 <= end <= 247) or start > end:
  213. return f'address_range 非法: {start}-{end}(需 1-247 且 start<=end)'
  214. return None
  215. def validate_bundle(obj):
  216. """校验整机备份包, 返回 (ok, message)"""
  217. if not isinstance(obj, dict):
  218. return False, '备份内容不是 JSON 对象'
  219. if obj.get('format') != BUNDLE_FORMAT:
  220. return False, '不是本系统的备份文件(format 不匹配)'
  221. fv = obj.get('format_version')
  222. if not isinstance(fv, int) or not (1 <= fv <= BUNDLE_FORMAT_VERSION):
  223. return False, f'备份格式版本不支持: {fv}'
  224. files = obj.get('files')
  225. if not isinstance(files, dict) or not files:
  226. return False, '缺少 files 字段或为空'
  227. unknown = set(files) - set(BUNDLE_FILES)
  228. if unknown:
  229. return False, f'包含未知文件项: {sorted(unknown)}'
  230. if not any(v not in (None, {} , '') for v in files.values()):
  231. return False, '备份包内没有任何有效文件'
  232. for key, val in files.items():
  233. if val is None:
  234. continue
  235. if key == 'system_env':
  236. if not isinstance(val, str):
  237. return False, 'system_env 必须是文本内容'
  238. continue
  239. if not isinstance(val, dict):
  240. return False, f'{key} 必须是 JSON 对象'
  241. dtu = files.get('dtu_config')
  242. if isinstance(dtu, dict):
  243. if 'address_range' in dtu and dtu['address_range'] is not None:
  244. err = _validate_address_range(dtu['address_range'])
  245. if err:
  246. return False, err
  247. if 'uid_prefix' in dtu and dtu['uid_prefix'] is not None:
  248. if not _PREFIX_RE.match(str(dtu['uid_prefix'])):
  249. return False, f"uid_prefix 非法: {dtu['uid_prefix']}"
  250. pm = dtu.get('port_mappings')
  251. if pm is not None and not isinstance(pm, dict):
  252. return False, 'port_mappings 必须是对象'
  253. dev = files.get('devices')
  254. if isinstance(dev, dict):
  255. for uid, addr in dev.items():
  256. if not _UID_RE.match(str(uid)):
  257. return False, f'devices 中存在非法线架 UID: {uid}'
  258. if not isinstance(addr, int) or not (1 <= addr <= 247):
  259. return False, f'devices 中地址非法: {uid} -> {addr}'
  260. sc = files.get('serial_config')
  261. if isinstance(sc, dict) and 'port' in sc and not isinstance(sc['port'], str):
  262. return False, 'serial_config.port 必须是字符串'
  263. mc = files.get('mqtt_config')
  264. if isinstance(mc, dict) and 'broker' in mc and not isinstance(mc['broker'], str):
  265. return False, 'mqtt_config.broker 必须是字符串'
  266. try:
  267. size = len(json.dumps(obj, ensure_ascii=False).encode('utf-8'))
  268. except (TypeError, ValueError):
  269. return False, '备份内容无法序列化'
  270. if size > MAX_BUNDLE_BYTES:
  271. return False, f'备份内容过大({size} 字节, 上限 {MAX_BUNDLE_BYTES})'
  272. return True, 'ok'