VISTO USER GUIDE / 25

按现象排查问题

先记录“发生了什么、在哪个版本和页面、最近改变了什么”，再做最小检查。失败时不要删除数据或绕过权限、哈希、路径和恢复保护。

页面打不开

确认浏览器地址是否是这台主机的地址。原生 macOS 默认本机 8787，Docker 默认本机 8080；实际端口以部署配置为准。

curl -i http://127.0.0.1:8787/health/ready

• 连接被拒绝：检查服务是否运行、端口和 Gatekeeper。
• 返回未就绪：保留响应，查看服务日志与数据库 / 运行时状态。
• 本机能访问而远程失败：检查监听、HTTPS 网关、网络和防火墙。
• 426：使用正确 HTTPS 入口，核对强制 HTTPS 策略。

无法创建项目或上传

上传完成但视频没有预览

确认媒体安全检查、后台队列、失败任务和 FFmpeg / ffprobe 状态。部分增强失败可能只影响时间轴缩略图等功能，按页面说明判断，不一概把素材记为完全不可用。

curl -fsS http://127.0.0.1:8787/health/ready

程序检测正常后，再看具体任务错误、文件格式和磁盘空间。文件损坏、来源不可读与运行时未安装需要不同处理。

文件被隔离或拒绝

Owner 到 存储与上传安全 → 隔离与异常 查看文件、检查结果和原因。“刷新状态”用于重新读取现有结果，不代表强制重做安全扫描。只有确认原因和风险后，才使用页面允许的放行或拒绝操作。普通成员不能绕过隔离去分享或下载。

原片曾能打开，现在提示不可读

检查外接盘是否挂载、NAS / S3 是否在线、连接权限是否改变、本机文件是否被移走或删除。不要立即重新导入全部文件。项目回收站恢复的是项目关系，底层媒体丢失仍需从实际媒体备份恢复。

分享打不开、过期或没有按钮

先核对当前分享是否被撤销、密码和有效期、审阅状态及链接地址。没有评论或下载按钮，检查对应访问策略；接收者打不开本机地址时，需要正确团队网络入口。

保存冲突、登录失效

设置被其他会话修改时，重新载入最新值后再提交，避免覆盖别人的改动。登录失效时重新登录并确认角色；不要用 Owner 账号替代所有成员操作。

更新或恢复失败

保留当前数据、安装包、版本清单、摘要、备份、元数据和输出。先解决缺失文件、错误版本或路径不一致。停服证明、哈希或恢复检查不通过时，停止后续写入，联系维护者。