SnapLog 后台说明书
后台是一个网页，电脑和手机浏览器都能开，不用装客户端。整站三个页面：
/dashboard设备与日志总览/live实时日志/history历史记录查询
一、注册、登录与认领设备
注册 / 登录
- 打开后台，在登录页切到「注册」：用户名 3~32 位（字母或数字开头，可用
_ - .），密码至少 6 位；邀请码可选（若你们的部署启用了邀请制才需要）。注册成功即自动登录。 - 登录状态保存在 Cookie 里，有效期 72 小时。登录有风控：单个用户 15 分钟内连续失败 10 次、或单个 IP 失败 30 次，会锁定 15 分钟。
认领设备（4 位认领码）
1
拿到认领码设备壳体标签上印着；也可以连它的热点进配置页看；接串口时开机打印里有
claim=XXXX 一行。为了避免看错，认领码里不含 O/0、I/1 这类易混字符。2
打开认领页访问
https://iot.snapwhere.app/claim?c=XXXX，或在后台里点「认领设备」手填 4 位码。3
绑定已登录就直接绑定；未登录可填账号密码「登录并认领」或「注册并认领」。绑定后跳到总览页，设备出现在列表里。
解绑会作废旧认领码。解绑后设备回到「待激活」状态，云端会重新生成一个认领码，旧码立即失效（云端日志仍然保留）。
删除设备会连同它的全部日志、分享链接、用量记录一起清掉；如果设备还通着电，它下次心跳会以一台全新的「待认领」设备、日志为空重新出现 —— 想让它别回来，请先断电再删。
删除设备会连同它的全部日志、分享链接、用量记录一起清掉；如果设备还通着电，它下次心跳会以一台全新的「待认领」设备、日志为空重新出现 —— 想让它别回来，请先断电再删。
二、设备与日志总览
| 设备表 | 名称 / 设备编号 · 串口配置（固定显示 UART1 · 波特率）· 状态 · 最后上报 · 已存日志大小 · 操作 |
|---|---|
| 筛选 | 按状态（全部 / 在线 / 离线）+ 按名称或编号搜索 |
| 行内操作 | 改名、进实时日志、进历史查询、分享、解绑、删除 |
| 用量卡 | 今日上行流量（进度条 + 数值）、账户总存储、设备数、当月带宽；超额会有明确提示 |
| 最近日志 | 总览页直接带一块实时卡片，不用进 /live 也能瞄一眼最新几行 |
在线状态怎么算
设备每 30 秒发一次心跳；云端同时靠 MQTT 遗嘱消息（LWT）判断断线 —— 拔电、断网时通常 1~2 秒内就会变离线，不用等超时。页面还会在状态翻转的那一刻被推送唤醒并自动刷新，所以正常上下电几乎是即时可见。
三、实时日志 /live
这是最常用的页面：像坐在机器旁边看串口，同时能下发命令、开录制、切 TF 卡落档。
选设备与连接状态
- 左上角选设备；旁边的徽标显示在线状态，另一个徽标显示数据流（SSE）连接状态。
- 底部实时显示链路延迟、最近事件、当前速率（行/秒）。
两种显示主题（同一个串口，两种看法）
| 日志流 Flow | 解析展示：每行带时间戳、方向标记（◀ 收 / ▶ 发 / ● 系统）与按级别着色。适合「看发生了什么」。 |
|---|---|
| 嵌入式调试模式 Debug | 完整串口终端（xterm.js），忠实透传字节，能敲命令、看回显、看进度条重绘。适合「像用 PuTTY 一样操作设备」。 |
两个主题底色一致，切换时不会闪。快捷键：Ctrl+L 清屏、Ctrl+U/K/W 删行删词、Ctrl+P/N 翻历史、Shift+PageUp/Down 翻页、Ctrl+/ 看全部键位。
日志流按级别着色：ERROR 红、WARN 黄（两者额外带左侧色条与淡底色，扫屏时一眼看到）、DEBUG / TRACE 灰色递进；INFO 与解析不出级别的原始输出保持正文色（设备解析不出级别时兜底就是 INFO，染色等于把整屏都染了）。着色不是过滤——一行都不会少。
常用按钮
| 存储到云端 | 录制开关。只有「存储中」的日志才写进云端数据库，才占存储配额；不录也照样能实时看。 |
|---|---|
| TF 卡留档 | 三档下拉：关（不写卡，零磨损）/ 仅断网时（Wi-Fi 或云端断开才落卡）/ 始终写（在线时也留一份完整档）。菜单里能看到卡容量、文件数、本次写入行数、写失败行数。需要设备在线才能下发。 |
| 暂停 / 继续 | 冻结屏幕方便细看，后台继续收；点「继续」时缓冲的行原样补回，一条不丢。 |
| ASCII / HEX | 显示格式，两个主题共用（HEX 为 hexdump 三段式）。切格式不丢原始字节，可来回无损重渲染。 |
| 下载 | 导出本次会话日志，文件名 snaplog-<设备号>-<日期>-<时间>.txt。 |
| 放大 / 全屏 | 放大把日志卡撑开；全屏铺满屏幕（Esc 退出）。 |
| 清空 | 只清本地显示，云端照常记录。 |
| 串口参数 | 波特率（1200…1500000，也可自定义 300~3000000）、数据位/校验、停止位 →「应用并保存」，会下发到设备并写入 NVS，掉电保持。 |
「更多」菜单里还有什么
- 上行开关：设备侧直接掐断上传，真省带宽（和「录制」不是一回事，见下文）。
- 上行过滤：按级别（只上 ERROR 等）、按采样（每 N 条取 1）、按关键字（≤47 字符，不区分大小写）；三级可叠加，在设备端就把无关行丢掉。被过滤的行不占行编号，不会造成假的「日志缺口」告警。
- 日志缺口：按行编号（seq）检测跳号，列出每一段的区间、缺多少行、什么时候发现的 —— 这是判断「日志到底全不全」的客观依据。
- 行尾结束符：CRLF / LF / CR / 不追加。
- 重连数据流：手动重连 SSE。
录制、上行、过滤，三个开关分别省什么
· 录制省的是存储配额（不录也照样传上来、照样能看）；
· 上行开关省的是带宽（设备侧就不发了）；
· 过滤也省带宽（设备侧丢行）。
一句话：看不计额度，录才计额度。
· 录制省的是存储配额（不录也照样传上来、照样能看）；
· 上行开关省的是带宽（设备侧就不发了）；
· 过滤也省带宽（设备侧丢行）。
一句话：看不计额度，录才计额度。
AI 分析侧栏
右侧三个页签：对话（选中日志行后可直接「就选中内容提问」）、任务（模板库 + 自定义监控任务，命中规则会在状态感知 chips 里弹出并引用日志原文）、进行中（运行中的任务与诊断文档）。AI 由服务端代理调用，并发与超时都有限制，忙时会排队。
四、历史记录查询 /history
| 检索条件 | 类型（全部 / 录制日志 / 任务记录）、设备、关键词、时间范围（可自定义起止时间，或用「近 1 小时」「今天」「近 7 天」快捷按钮） |
|---|---|
| 结果 | 先列出命中的设备清单（台数、条数、最近时间），点一台进入文本流查看 |
| 单条详情 | 时间、设备行号（seq）、记录 ID、原始内容（或 HEX）、「查看前后 20 行」上下文 |
| 导出 | 导出当前查询结果，支持 TXT 纯文本与 CSV 表格 |
历史页目前没有「按级别」筛选（后端支持，界面未开放）。要按级别找，请在关键词里填级别文字，或回到实时页用过滤。
TF 文件导出
历史查询页头部有「TF 文件导出」按钮 —— 它像打开一个文件夹那样，直接读设备那张 TF 卡。
1
选设备（设备必须在线：卡插在设备上，设备不在线谁也读不到）
2
读卡点「刷新」，列出卡上所有
NNNN.log / NNNN.done 文件及大小3
勾选后下载单个文件下载为纯文本，多个文件打包成 zip
| 写卡开关 | 关着也能浏览和导出——关的是「写」，不是「读」。卡里之前留下的档照常能取。 |
|---|---|
| 内容与过滤 | 卡上写的是过滤之前的原始全量，不受「只上 ERROR」影响。 |
| 限制 | 一次最多 8 个文件、合计 ≤ 16 MB；文件名必须是 NNNN.log / NNNN.done；同一台设备同时只能有一个导出任务。 |
| 耗时 | 实测约 2.5~3 KB/s：24 KB 约 9 秒、67 KB 约 24 秒。单次取文件超时 90 秒，建议单个文件不超过 200 KB。 |
大文件怎么办：受 MQTT 往返限制，目前单次导出只适合 200 KB 以内的文件。更大的档建议：把卡拔下来用读卡器直接读（就是普通文本文件），或用 USB 串口
#SDGET <nnnn.log> 原样打出。五、分享（免登录只读链接）
- 在设备行点「分享」→ 填备注 → 选权限：实时日志只读（默认开）、历史查询（默认关）、允许串口 TX 写入（默认关）→ 选有效期：1 小时 / 24 小时（默认）/ 7 天 → 生成链接。
- 对方打开链接不用注册登录，看到的是只读页面（可选填名字用于审计）。
- 收回：撤销后链接立即失效（404）；也可删除，或等它到期。
六、配额与用量
| 每日上行流量 | 100 MB / 账户（名下所有设备合计），单设备上限同为 100 MB；每天 UTC 00:00 重置 |
|---|---|
| 每月上行带宽 | 20 GB / 账户（软限额，只告警不切断） |
| 存储配额 | 300 MB / 账户 |
| 日志保留 | 单设备 40 MB 或 7 天，先到者为准（滚动覆盖最旧的） |
| 设备数上限 | 20 台 / 账户 |
用量到 60% 会提示，到 100% 会拒收并给出明确提示（不会悄悄丢）。清理日志只腾出存储空间，今日已用的流量额度不会回退。另外：开着页面实时看是不计额度的，只有「存储中」的日志才落库。
七、使用注意
- 必须设备在线的操作：读/导出 TF 卡、下发 TF 卡模式、下发串口参数、OTA。离线时会返回明确错误提示。
- OTA 期间设备会短暂离线（内存不足以同时维持两条 TLS 连接），在线状态掉一小会儿属正常，中途断电不会变砖。
- 本地显示上限 250 行：只影响当前页面显示，不影响云端记录。
- 时间统一按 UTC+8 显示；日志按（设备号, 行号）去重，重复上报不会产生重复行。
- 嵌入式调试模式单字符往返约 1 秒（本地先占位、设备回显后核销），HEX 视图不参与核销；未定义的组合键会原样透传给设备。
八、附：设备端串口命令
USB 插电脑就是免驱串口，任意串口工具打开后敲 #HELP 回车可看到全部命令。常用的：
#STATUS | 看全部状态（Wi-Fi、云端、串口、TF 卡、缓冲水位） |
|---|---|
#UART <波特率> <位> <校验> <停止位> | 改串口参数，例：#UART 115200 8 N 1 |
#WIFI <名称> <密码> | 配网（不用连热点也能配） |
#SD [?|0|1|2] | TF 卡落档模式：0 关 / 1 仅断网时 / 2 始终写 |
#SDLIST | 列出卡上的日志文件 |
#SDGET <nnnn.log> | 把卡上某个文件原样打到串口（云端不通时的现场兜底） |
#SDCLEAR YES | 清空卡上日志（需带 YES 二次确认） |
#FILTER [?|OFF|LEVEL x|EVERY n|KW x] | 上行过滤 |
#LOG 1/0 / #SPILL 1/0 | 上行开关 / flash 落盘开关 |
#LCD 1/0 / #BRIDGE 1/0 | 屏幕开关 / USB 桥接开关 |
#REBOOT | 重启 |
SnapLog · 后台说明书 · 对应固件 V3.26.0-CLOUD · 后台 iot.snapwhere.app