194 lines
6.7 KiB
Python
194 lines
6.7 KiB
Python
"""固件包服务:版本比较、落盘、镜像校验、选版本逻辑。
|
||
|
||
为什么不用第三方 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)
|