nex_buddy/server/app/services/firmware.py

194 lines
6.7 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

"""固件包服务:版本比较、落盘、镜像校验、选版本逻辑。
为什么不用第三方 semver 库:设备固件版本就是 ``MAJOR.MINOR.PATCH`` 三段,
带后缀的(``0.2.0-rc1``)只需要「比正式版小」这一条规则,二十行代码够了,
少一个依赖对部署更友好。
"""
from __future__ import annotations
import hashlib
import os
import re
import shutil
import uuid
from pathlib import Path
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
from app.core.config import settings
from app.models import Device, Firmware
# 固件包落盘目录:默认 <项目根>/data/firmware(运行时资源,不入库)
DATA_DIR = settings.data_dir / "firmware"
MAX_SIZE = 8 * 1024 * 1024 # 8 MB:app3M 分区上限 3 MB,留足余量但不至于被灌爆
CHUNK = 256 * 1024 # 流式读写块大小
VERSION_RE = re.compile(r"^(\d{1,3})\.(\d{1,3})\.(\d{1,3})(?:-([0-9A-Za-z.\-]{1,16}))?$")
class FirmwareError(ValueError):
"""上传/校验失败,调用方直接转 400。"""
# ------------------------------------------------------------------ 版本
def parse_version(text: str) -> tuple[int, int, int, str]:
"""``0.2.0-rc1`` -> (0, 2, 0, "rc1");预发布段为空表示正式版。"""
m = VERSION_RE.match((text or "").strip())
if not m:
raise FirmwareError(f"版本号格式不对:{text!r},应为 0.1.2 或 0.2.0-rc1")
return int(m.group(1)), int(m.group(2)), int(m.group(3)), (m.group(4) or "")
def version_code(text: str) -> int:
"""压成整数便于 SQL 排序。预发布版减一档,保证 0.2.0-rc1 < 0.2.0。"""
major, minor, patch, pre = parse_version(text)
code = major * 1_000_000 + minor * 1_000 + patch
return code - 1 if pre else code
def compare(a: str, b: str) -> int:
"""a>b 返回 1,相等 0,小于 -1。占位/空串视为最小。"""
if not a:
return 0 if not b else -1
if not b:
return 1
try:
ca, cb = version_code(a), version_code(b)
except FirmwareError:
return 0
return (ca > cb) - (ca < cb)
# ------------------------------------------------------------------ 镜像校验
def check_image(head: bytes, size: int) -> None:
"""ESP32 应用镜像以 0xE9 开头(magic + segment count)。
这一步能拦住 90% 的误传:传了 zip、传了 bootloader、传了别的项目的 bin,
都是在这里被挡下的,不会等到设备端刷砖才发现。
"""
if not head:
raise FirmwareError("文件是空的")
if head[0] != 0xE9:
raise FirmwareError("不是 ESP32 应用镜像(首字节应为 0xE9),请确认选的是 xxx.ino.bin")
if size < 64 * 1024:
raise FirmwareError(f"镜像只有 {size} 字节,太小了,多半传错了文件")
if size > MAX_SIZE:
raise FirmwareError(f"镜像 {size / 1048576:.1f} MB 超过 {MAX_SIZE // 1048576} MB 上限")
def safe_name(version: str, sha: str) -> str:
"""落盘名带 8 位哈希:同版本重传不会互相覆盖,也便于肉眼核对。"""
return f"{version}-{sha[:8]}.bin"
async def save_stream(stream, filename: str) -> tuple[Path, int, str]:
"""把上传流写到磁盘,边写边算 sha256。
先写 ``.part`` 再 rename:中途断开不会留下半个 bin 被当成有效固件。
"""
DATA_DIR.mkdir(parents=True, exist_ok=True)
tmp = DATA_DIR / f".upload-{uuid.uuid4().hex}.part"
digest = hashlib.sha256()
size = 0
head = b""
try:
with tmp.open("wb") as f:
while True:
chunk = await stream.read(CHUNK)
if not chunk:
break
if not head:
head = chunk[:16]
size += len(chunk)
if size > MAX_SIZE:
raise FirmwareError(f"文件超过 {MAX_SIZE // 1048576} MB 上限")
digest.update(chunk)
f.write(chunk)
check_image(head, size)
sha = digest.hexdigest()
target = DATA_DIR / safe_name(Path(filename).stem, sha)
shutil.move(tmp, target)
return target, size, sha
except Exception:
tmp.unlink(missing_ok=True)
raise
def path_of(fw: Firmware) -> Path:
return DATA_DIR / fw.filename
def remove_file(fw: Firmware) -> None:
try:
path_of(fw).unlink(missing_ok=True)
except OSError:
pass
# ------------------------------------------------------------------ 选版本
async def latest_published(db: AsyncSession, model: str, channel: str = "stable") -> Firmware | None:
stmt = (
select(Firmware)
.where(
Firmware.model == model,
Firmware.channel == channel,
Firmware.published.is_(True),
)
.order_by(Firmware.version_code.desc())
.limit(1)
)
return await db.scalar(stmt)
async def resolve_for_device(db: AsyncSession, device: Device) -> tuple[Firmware | None, bool]:
"""设备该升到哪一版。返回 (固件, 是否管理员点名下发)。
优先级:管理员指定目标 > 同机型同通道的最新已发布版。
点名下发允许「降级」(回滚到已知好版本),所以这里不比版本大小;
自动更新则必须严格新于当前版本,否则设备会陷入「升了又升」的死循环。
"""
if device.target_firmware_id:
fw = await db.get(Firmware, device.target_firmware_id)
if fw is not None:
return fw, True
fw = await latest_published(db, device.model or "JC3636K518C_I_W", "stable")
if fw is None:
return None, False
if compare(fw.version, device.fw_version) <= 0:
return None, False
if fw.min_version and compare(device.fw_version, fw.min_version) < 0:
# 跨版本太远:先让设备升到 min_version 那一版(如果它存在且已发布)
step = await db.scalar(
select(Firmware)
.where(
Firmware.model == fw.model,
Firmware.channel == fw.channel,
Firmware.version == fw.min_version,
Firmware.published.is_(True),
)
.limit(1)
)
return (step, False) if step else (fw, False)
return fw, False
async def device_counts(db: AsyncSession, model: str | None = None) -> dict[str, int]:
"""按版本统计在线设备数,管理端列表里显示「已有多少台在这个版本」。"""
stmt = select(Device.fw_version, Device.id)
if model:
stmt = stmt.where(Device.model == model)
rows = (await db.execute(stmt)).all()
out: dict[str, int] = {}
for ver, _id in rows:
out[ver or ""] = out.get(ver or "", 0) + 1
return out
def env_storage_hint() -> str:
return os.fspath(DATA_DIR)