Repository navigation
Troubleshooting
旧用户中心会拒收超过 24 小时的待传记录，反复重试不会改变原操作时间。将用户中心升级到 1.0.24 或更新版本，重新登录后重试即可补传历史记录；不要清空队列。若仍失败，检查客户端和服务端系统时钟，操作时间不得超前服务端超过 5 分钟。
先确认操作系统文件管理器能够看到卷和 episode 文件。Delta Viewer 不包含 ext4 驱动；ext4 卡在标准 Windows/macOS 上不能直接选择。macOS 用户可按Paragon extFS 只读教程挂载，必须确认 Mount in Read-only mode 和只读卷状态。Ubuntu 原生 deb 可选择当前用户有权读取的只读挂载目录。不要为了读取数据直接格式化仍含数据的卡。
扫描完成后不会打开本地目标目录选择框。初始列表的“待读取”表示只发现了 session，还没有遍历其图像；首条记录会直接从只读源路径加载，状态和画面显示后变为“快速预览”，完整检查结束后再显示精确统计。检查完成前导出按钮保持禁用。其他记录可双击，或聚焦后按 Enter/空格按需加载。若某条记录失败，可用相同操作重试，并在顶栏打开“操作错误历史”。检查期间应保持源卷挂载；源发生变化时重新扫描后再加载。
正常界面不会复制完整 session，因此不需要预留等量 app-local-data 空间。初始 session 发现只读取浅层目录；网络映射盘的带宽即使足够，单文件 metadata 往返延迟仍会影响后续完整检查，但不应阻塞状态、画面和标注区的快速预览。若“待读取”阶段本身仍很久，先确认源根目录只包含 session 目录、映射盘连接稳定，并检查系统文件管理器枚举同一目录是否也慢。导出仍需要目标卷具备足够空间，FAT/FAT32 不适合作为大文件导出卷。
0.17.64 起，NAS 上的逐帧 JPEG 会用 30 帧 Camera 0 起播跑道和四路小画面独立有界预读。旧版本在拖到中间后可能重新等待最多 360 个 Camera 0 文件，Linux 通过文件管理器打开的 SMB 还可能被误判为本地盘；遇到“中间无法继续播放”或小画面经常停住时，应先升级到 0.17.64 或更高版本。升级后仍持续缓冲时，检查 NAS 同时下载任务、Wi-Fi/交换机负载和系统文件管理器读取同一 JPEG 的速度。
标注账号登录后会尝试加载本机保存的 NAS 目录。若 NFS/SMB 挂载仍存在但服务器无响应，应用会在五秒后显示 SOURCE_UNRESPONSIVE 并恢复操作；无需结束进程，可以直接退出登录、重新配置 NAS 或选择本地数据。系统文件管理器访问同一路径也卡住时，应先恢复办公网络或由管理员修复挂载，不要反复强制访问 hard NFS 目录。
应用会把原始消息保存到操作错误历史，并归类为 PERMISSION_DENIED。macOS 先确认 Finder 能打开该卷，再在“系统设置 -> 隐私与安全性 -> 文件与文件夹”允许 Delta Viewer 访问可移动宗卷；Windows 和 Ubuntu 用户确认当前账号能读取挂载目录。检查、回放和导出不需要写权限；保存标注需要在 episode 根目录原子更新 description.json。如果必须保持介质严格只读，则不要通过 chmod 或关闭系统保护绕过，只使用检查、回放和导出功能。
确认当前 episode 根目录可写，并且现有 description.json 是普通文件而不是目录或符号链接。应用只会更新这个文件，不会修改 JPEG、states.jsonl 或骨架。严格只读挂载无法保存标注；将数据放到经过授权的可写介质或调整挂载策略后重试。
旧版本自动导入留下的 app-local-data/imports 不会被当前版本自动删除。退出应用并确认不再需要后再手工归档或清理，避免误删仍在使用的数据。
1.0.63 登录后会后台检查官方 GitHub 最新正式 Release。检查不影响审核；失败时打开“版本与更新”查看原因和重试。GitHub 匿名 API 限流会自动切换到同仓库官方最新 Release 跳转查询，不要求配置 Token。网络完全无法访问 GitHub 时，可在能访问的机器从 官方 Release 下载后安装。1.0.62 及更早客户端需手动安装 1.0.63 一次来切换新来源。
下载后不会自动安装，选择“保存并重启更新”或“稍后”。正在导出或扫描时先等待完成；当前复核、审核操作保存失败时先处理保存问题，保持窗口打开并重试。缓存校验失败时可重新下载。Ubuntu 安装阶段可能需要系统提权确认。
不要使用第三方 updater 或签名。客户端只接受官方精确版本、当前平台、1–64 MiB 且大小、SHA-256 和 Minisign 签名全部匹配的包。持续失败时提供应用版本、平台和更新详情错误，不附账号、源路径或采集数据。
警告不等于文件损坏。常见原因包括缺帧、图像/状态数量不同、状态帧号跳变或时间间隔超过基准中位数三倍。先在回放中定位相关帧，再决定是否确认并导出。
本地标注只保存原始路径和数据指纹，不复制 episode 数据。重新连接同一张源卡，并确认操作系统把它挂载到标注时的相同路径；应用不会自动把旧标注改绑到另一个目录。如果路径已被其他内容占用，或源文件发生变化，该条批量导出会失败，以免把轨迹码附到错误数据上。其他有效条目仍会继续。
macOS 可能使 Foxglove 保存的最近文件权限句柄失效。不要修改 MCAP；在 Foxglove 中使用 Open local file(s) 重新选择该文件。
官方 Release 的正式安装包已内置并校验 FFmpeg。出现该错误时先确认安装来自官方 Release 且 hash 匹配；不要把本地 debug app 当作发布包。问题报告中附上应用版本、平台、导出错误摘要和安装文件 hash，不要附原始图像或账号密码。
账号只能由用户中心管理员创建或重新设置。先在服务主机打开 https://localhost:17880/，确认用户中心健康，再由管理员处理账号；不要直接编辑服务端 users.json 或替换密码哈希。客户端导入配置失败时，确认所选文件是管理员生成的 DOHC-User-Center-Client.json，且客户端能访问配置中的用户中心地址。若服务主机因 DHCP 获得了新地址，在登录页底部点击“重新导入用户中心配置”并选择管理员提供的新文件；客户端只允许迁移到相同 service ID 且 TLS 健康检查通过的用户中心。已经登录的客户端在用户中心短暂断开时仍可继续本地工作，退出后需要服务恢复才能重新登录。
0.15.0 的 macOS DMG 存在无效 app 资源封印，会触发“已损坏”，不能通过安全设置绕过。请删除该 DMG 和 app，安装 0.15.2 或更高版本；0.15.1 没有公开 Release，Windows 0.15.0 不受影响。
0.15.2 及更高版本没有 Developer ID 或 Apple notarization，因此首次启动出现“Apple 无法验证”或“无法确认开发者”属于预期策略阻止。先确认下载自本仓库、芯片架构正确并核对 SHA256SUMS.txt，再按安装与升级使用“系统设置 -> 隐私与安全性 -> 仍要打开”完成一次性授权。不要关闭 Gatekeeper，也不要运行移除 quarantine 的命令。
若 0.15.2 或更高版本仍显示“已损坏”，不要绕过。hash 不符时删除文件并重新下载；hash 相同时在 GitHub Issue 中附上版本、macOS 版本、芯片架构和 DMG hash，不要附原始采集数据或密码。