Visto 用户手册

开始使用

01 · 先理解 Visto

Visto 在你控制的电脑或服务器上运行，用浏览器进入工作空间。它把项目、媒体文件、不同版本、审阅反馈和分享记录放在同一条协作流程里。存储可以位于部署主机，也可以由 Owner 连接 WebDAV 或 S3 兼容服务。

“本地优先”意味着你决定数据部署在哪里。选择远程存储、配置外部通知或开放远程访问后，相关数据仍会经过你启用的服务和网络。

五个最常用的概念

图解： 一个项目可以有多个资产；一个资产可以有多个版本；审阅引用选定的版本。上传新版以后，旧审阅仍保留原来审阅的版本，下一轮应明确选择新版。

按身份选择阅读路线

适用与限制

本手册重点说明 Server 浏览器工作台。原生安装完整示例以 Apple Silicon macOS 为准；其他平台和 Docker 的正式可用性以对应 Release 的说明和验收范围为准。没有可下载的正式 Release 时，不要把开发候选当作稳定版。此次文档制作时官方仓库仍为 Private，正式 Release 数量为 0；下面的安装步骤是供已获得对应包的使用者和后续正式发布使用。

开始使用

02 · 做完你的第一个项目

本章面向已经能打开 Visto 的 Owner 或项目主管。建议先用一张不含敏感内容的图片完成练习，再接入真实项目。

第一步：确认保存位置

Owner 进入 Owner 设置 → 存储与上传安全，至少创建一个可供项目上传使用的存储位置，并开放给需要的项目。项目主管看不到存储或没有创建权限时，请联系 Owner。

第二步：创建项目

在项目列表点“新建项目”，填写名称、项目说明，并选择项目存储位置。建议名称包含作品与交付批次，如“品牌短片 · 10 月交付”；说明写清目标、负责人和交付日期。

第三步：上传一份媒体

进入新项目的“媒体”，选择“上传本地文件”。等上传完成，再等媒体状态变成可预览。上传完成只说明传输结束，后台预览处理可能还在继续。

第四步：创建第一轮审阅

打开素材详情，确认是 V1，点“创建审阅”。填写审阅名称，选择参与成员、通过条件和截止时间；需要外部反馈时，设置访问密码、评论和下载权限，再创建审阅分享。

第五步：收集并处理反馈

用分享入口查看图片或播放视频。提交一条能定位到画面或时间的反馈，项目内核对评论，再回复处理结果。需要正式结论时由具备权限的审阅者提交“通过”“需修改”或“拒绝”。

第六步：提交新版

回到原资产的详情，选择“上传新版本”，上传修订文件。确认 V2 出现在版本历史里，以 V2 创建下一轮审阅。不要为了升级版本而把同一作品反复作为独立资产上传。

第七步：交付与归档

确认最新版本通过、交付链接权限正确、接收者能访问后，再归档项目。归档保留项目记录并暂停项目内写入；备份还需要由部署维护者单独执行。

完成检查

• 项目名称、保存位置和参与成员正确。
• 图片或视频能正常预览；没有未处理的隔离或失败提示。
• 反馈能回到原版本和具体位置。
• V1、V2 的历史都保留，当前版本明确。
• 分享在接收者设备上能打开；下载权限符合交付要求。
• 重要数据已有实际备份，项目归档不能替代备份。

开始使用

03 · 熟悉工作台

工作台围绕项目组织日常任务。进入项目后，首先确认顶部项目名，避免把文件或反馈提交到另一个项目。

全局入口与项目入口

用项目概览判断下一步

“项目脉搏”把当前最值得处理的任务汇总出来。先看失败任务是否影响预览，再看未解决反馈和待处理审阅，最后确认最近版本。计数可能受权限和数据加载影响；读取失败时重新加载，不把空白当作“全部处理完”。

页面保存的判断方法

点击保存、上传、复制或测试后，要看页面的完成提示。按钮显示“处理中”表示还没结束；错误信息应在当前操作区域处理。复制失败时，查看可见文本再手动复制，不连续点按钮造成重复审阅或分享。

安装与初始化

04 · 安装前的准备

如果你只是受邀参与项目，无需安装 Server，使用团队给你的工作空间地址即可。只有负责部署的人员需要本章。

选择部署方式

在开始之前准备好

1. 确认设备架构和安装包匹配。M 系列 Mac 使用 macos-arm64 包。
2. 从 官方 Release 页面 获取同一版本的安装包、SHA-256 和发布说明。页面未开放或没有正式包时，不要换用不明镜像。
3. 准备系统管理员密码、一个强 Owner 密码，以及足够存放原片、预览和备份的磁盘空间。
4. 为素材安排独立目录。不要把整个用户主目录或系统目录当作媒体上传位置。
5. 首次设置在部署主机完成；首次初始化令牌只给这台主机的维护者使用。
6. 已有实例升级时，先读“更新、恢复与回滚”，不要按全新安装覆盖现有数据。

本机地址是什么意思

127.0.0.1 指向当前打开浏览器的设备。在你的 Mac 上，它指向这台 Mac；在同事电脑上，它指向同事电脑。因此同事无法使用你的 127.0.0.1 分享地址访问部署在你 Mac 上的服务。

跨设备协作需要一个接收者能访问到的团队地址，并配置对应网络入口。参见“网络与远程访问”。

安装与初始化

05 · Apple Silicon macOS 安装

本章适用于已经取得对应 macOS ARM64 安装包的维护者。命令中的 <版本> 是占位符，必须替换成你下载的版本；尖括号也要去掉。所有操作都在部署 Visto 的 Mac 上完成。

1. 下载并核对 SHA-256

保存 Visto-Server_<版本>_macos-arm64.tar.gz 与同一 Release 的 .sha256 文件。打开终端，进入下载目录后执行：

cd "$HOME/Downloads"
shasum -a 256 'Visto-Server_<版本>_macos-arm64.tar.gz'

把输出的 64 位摘要与官方发布页或 .sha256 内容逐字对照。不同则停止，不要安装。摘要相同证明下载内容一致，仍需要确认下载来源。

2. 解压到独立目录

新版本使用一个新目录，避免把旧包的脚本与新包混在一起：

mkdir -p "$HOME/Downloads/visto-server-<版本>"
tar -xzf "$HOME/Downloads/Visto-Server_<版本>_macos-arm64.tar.gz" \
  -C "$HOME/Downloads/visto-server-<版本>"
cd "$HOME/Downloads/visto-server-<版本>"

确认当前目录里有 scripts/install-visto-server.sh，再执行安装：

sudo bash scripts/install-visto-server.sh \
  --version '<版本>' \
  --source-dir "$PWD"

终端输入系统管理员密码时不会显示字符，这是系统的正常行为。

3. 处理 macOS 首次运行提示

当前交付方案没有 Apple Developer ID 签名和公证。macOS 可能分别拦截 visto-core 和 visto-server。核对来源和摘要之后，在“系统设置 → 隐私与安全性”找到被阻止的程序，按系统提示“仍要打开”。如果第二个程序随后被拦截，对它单独操作。

这是流程示意，不是 macOS 截图。 手动放行不代表 Apple 已验证开发者。不要全局关闭 Gatekeeper。安装器如果报服务未就绪，先处理拦截再检查服务，不要把退出失败当成安装成功。

sudo launchctl kickstart -k system/com.visto.server
curl -fsS http://127.0.0.1:8787/health/ready

看到 "status":"ready" 后，打开 http://127.0.0.1:8787/。如果使用了自定义端口，命令和浏览器地址都替换成对应端口。

4. 确认安装后的目录

完成检查： 服务就绪、浏览器能打开向导、未忽略安装失败信息。视频预览还需要下一章的媒体运行时。

安装与初始化

06 · Windows x64 安装与维护

本章面向在 Windows 主机上部署 Server 的维护者。项目成员只需要浏览器，不必安装 Desktop、Node.js 或 Go。以下步骤按当前 Windows 安装及维护脚本编写；正式支持的 Windows 版本、最终包和实机验收以对应 Release 说明为准。没有发布包时，不把候选 ZIP 当成正式稳定版本。

1. 准备机器与安装材料

• 使用 x64 Windows；本章不适用于 Windows ARM64，也不适用于 Desktop 安装器。
• 准备本机管理员权限。安装器需要注册开机任务并保护程序、数据目录的访问权限。
• 准备固定本机程序目录，例如 C:\Program Files\Visto Server。不要在下载临时目录、网络共享目录或云同步目录中直接运行。
• 准备原片、预览和备份容量。数据目录默认为 %ProgramData%\Visto\data，备份应另存一块可靠磁盘。
• 从官方 Release 获取同版本 ZIP、SHA-256 和发布说明。更新时还需要对应版本清单；不存在的下载入口不能用未知镜像替代。

Windows 的主机目录指 Server 所在电脑 的目录，成员电脑上的 D:\素材 不会自动出现在服务器上。映射网络盘也可能只属于你的登录会话，而开机任务使用 SYSTEM 账号；不要用资源管理器能打开网络盘来判断服务一定能读到它。

2. 核对文件并解压

示例版本 1.0.0-rc.1 只是命令格式示例，请替换为你实际获得的版本。先在下载目录检查摘要：

Get-FileHash .\Visto-Server_1.0.0-rc.1_windows-x64.zip -Algorithm SHA256

把完整的 64 位结果与可信发布页或同名 .sha256 对照；不一致时停止安装，重新下载。SHA-256 验证完整性，下载来源仍须核对。

在管理员 PowerShell 中解压到一个尚未使用的固定目录：

Expand-Archive -LiteralPath "$env:USERPROFILE\Downloads\Visto-Server_1.0.0-rc.1_windows-x64.zip" `
  -DestinationPath 'C:\Program Files\Visto Server'
Set-Location 'C:\Program Files\Visto Server'
Get-ChildItem

目录应包含 bin、web、visto-server.json、VistoServer.Security.psm1 和安装/启动/备份/恢复/更新/卸载脚本。当前启动脚本还要求 runtime\ffmpeg\ffmpeg.exe 与 ffprobe.exe；缺失时不能从网上随便补二进制。已有安装不能用解压覆盖来升级。

3. 安装开机任务

在管理员 PowerShell 的程序目录执行：

Set-ExecutionPolicy -Scope Process Bypass -Force
.\Install-VistoServer.ps1

该执行策略只对当前 PowerShell 进程有效。若组织策略禁止运行脚本，交给系统管理员处理，不调整整机策略来绕过组织限制。

安装器注册名为 Visto Server 的计划任务，使用 SYSTEM 账号在开机时运行，异常退出时尝试重启。程序、数据与备份目录会限制普通用户写入；不要安装后再给“所有人”开放写权限，也不要将这些目录替换成目录联接或符号链接。

4. 确认就绪并完成首次设置

Get-ScheduledTask -TaskName 'Visto Server'
Get-ScheduledTaskInfo -TaskName 'Visto Server'
Invoke-WebRequest -Uri 'http://127.0.0.1:8787/health/ready' -UseBasicParsing
.\bin\visto-server.exe --address 127.0.0.1:8787 status

计划任务存在、显示运行中只是进程层证据；健康接口返回成功、浏览器能打开页面才继续首次设置。默认入口为 http://127.0.0.1:8787/。若改过 visto-server.json 的 address，用实际端口检查。

初始化令牌在 %ProgramData%\Visto\data\host-management-token.txt，安装器只显示位置和短指纹。需要时由本机管理员私下读取并填入首次设置页；不要截图、发给成员或打包进求助材料。随后按“首次设置与登录”建立工作空间、Owner 账户及一次性的目录权限选择。

5. 程序、配置、数据分别在哪里

修改配置前保留受保护的原配置副本，修改后重启任务。配置与令牌包含敏感信息，不作为公开求助附件。

6. 日常启动、停止和诊断

Stop-ScheduledTask -TaskName 'Visto Server'
Start-ScheduledTask -TaskName 'Visto Server'
.\bin\visto-server.exe --data-dir "$env:ProgramData\Visto\data" doctor
.\bin\visto-server.exe --data-dir "$env:ProgramData\Visto\data" diagnostics export `
  --output "$env:USERPROFILE\Desktop\visto-diagnostics.zip"

停止命令发出后需确认任务和相关进程确实停止。备份、恢复和更新脚本会进行自己的停服确认，不要删掉检查来强制执行。诊断包先自行检查敏感内容，再按受控方式交给维护者。

7. 备份与恢复

先通知成员暂停写入，再运行：

.\Backup-VistoServer.ps1 -BackupDirectory 'D:\Visto-backups'

成功结果必须同时有 ZIP 与同名 .zip.json 元数据，保留二者并复制到独立位置。该备份覆盖实例数据目录；配置在程序目录、外部本机媒体目录、WebDAV 和 S3 原片需另行保护。不能把一个 ZIP 当成全部项目原片的备份。

恢复分为两步。以下文件名为示例，替换为真实备份：

.\Restore-VistoServer.ps1 -BackupFile 'D:\Visto-backups\visto-server-data-20260930-120000.zip' -CheckOnly
.\Restore-VistoServer.ps1 -BackupFile 'D:\Visto-backups\visto-server-data-20260930-120000.zip' -ConfirmRestore

只读检查通过后，先确认当前数据也有独立备份，再执行替换。不要同时传 -CheckOnly 与 -ConfirmRestore。摘要、归档路径或来源数据目录不符时停止；不编辑元数据骗过检查，也不用恢复命令做跨目录迁移。恢复后检查项目、旧媒体、新上传与分享。

8. 更新与失败恢复

下载同一版本 ZIP、发布摘要和版本清单，保留程序目录配置并准备更新前备份。将路径和摘要替换为真实值：

.\Update-VistoServer.ps1 `
  -PackageArchive 'D:\Downloads\Visto-Server_1.0.1_windows-x64.zip' `
  -ExpectedSha256 '<发布页公布的64位SHA-256>' `
  -ManifestFile 'D:\Downloads\该版本的清单.json' `
  -BackupDirectory 'D:\Visto-backups'

不传 -ManifestFile 时脚本寻找 <安装包完整路径>.manifest.json；只有 ZIP 和摘要并不足够。清单必须与包版本匹配，发布者没提供时联系维护者，不自行拼写。

脚本校验并暂存输入，备份数据、停止任务、替换程序并等待恢复。失败时会尝试还原旧程序及更新前数据。即使脚本报告成功，也要核对健康接口与实际业务；端口能连不代表媒体和数据库已正常。当前 Windows 脚本没有独立的 Rollback-VistoServer.ps1，不要照搬 Unix 回滚命令。自动恢复失败时保留原程序、备份与错误输出，交给维护者处理。

9. 常见问题按现象处理

10. 卸载与交付检查

.\Uninstall-VistoServer.ps1

默认停止并删除开机任务，保留实例数据；不等于程序目录和外部原片已删除。只有独立备份可读、确定永久清除实例数据后，才使用 -RemoveData。不要将清除命令当成排障方法。

交付前逐项确认：重启电脑后服务就绪；Owner 可登录；成员仅看授权项目；旧媒体能打开；新上传能生成预览；HTTPS 分享可访问；备份 ZIP 与元数据已独立保存。本章完成的是操作说明，Windows 干净机器、文件锁和更新恢复实机验收仍需单独记录。

安装与初始化

07 · Linux amd64 / ARM64 安装与维护

本章面向使用 systemd 的 glibc Linux 主机 的维护者，按当前 Linux 打包与 Unix 运维脚本编写。amd64 与 ARM64 共用步骤，安装包不能混用。正式包、发行版支持和媒体运行时供应以对应 Release 为准；源码里存在安装脚本不代表最终 Linux 包已通过实机验收。

1. 核对系统和架构

uname -m
getconf GNU_LIBC_VERSION
systemctl --version

上述为项目当前契约要求，不代表每个满足版本号的发行版均已验收。准备 sudo 权限、Bash、GNU tar、常用系统工具，以及 curl 和 SHA-256 工具。不要为安装程序替换系统 C 库；不符合基线时使用受支持主机，或按 Docker 章节和发布支持范围选择容器部署。

2. 下载并核对摘要

获取同版本的安装包、SHA-256 和说明。下列 1.0.0-rc.1 为格式示例，替换为实际版本；ARM64 把包名中的 amd64 改为 arm64。

sha256sum Visto-Server_1.0.0-rc.1_linux-amd64.tar.gz

逐字对照可信发布页的 64 位摘要。不要从另一个包、架构或版本复制摘要。来源或摘要不明时停止。更新时还要准备同版本清单。

3. 解压并安装

在独立、尚未使用的本机目录解压；下面命令不在现有程序目录上覆盖文件：

mkdir -p "$HOME/visto-install-1.0.0-rc.1"
tar -tzf Visto-Server_1.0.0-rc.1_linux-amd64.tar.gz
tar -xzf Visto-Server_1.0.0-rc.1_linux-amd64.tar.gz -C "$HOME/visto-install-1.0.0-rc.1"
cd "$HOME/visto-install-1.0.0-rc.1"
ls bin web scripts
sudo bash scripts/install-visto-server.sh \
  --version 1.0.0-rc.1 \
  --source-dir "$PWD"

解压后应有 bin/visto-core、bin/visto-server、web/index.html、完整维护脚本及许可声明。安装器复制程序到版本目录、生成受保护配置、注册并启动 systemd 服务。缺文件、架构错误或版本目录已存在时先排查，不加覆盖参数绕过。

首次安装默认监听 127.0.0.1:8787。需要不同端口时，安装命令可增加 --address 127.0.0.1:8788；之后所有检查与代理都用实际端口。已经部署的实例不能用再次安装同版本来做更新。

4. 确认服务与浏览器入口

sudo systemctl status visto.service --no-pager
curl -fsS http://127.0.0.1:8787/health/ready
sudo /opt/visto/current/bin/visto-server --address 127.0.0.1:8787 status

服务 active 后还需健康检查成功、页面可打开。服务器有浏览器时打开 http://127.0.0.1:8787/。如果是无桌面的远程主机，自己电脑里的 127.0.0.1 指向自己电脑，并不指向服务器。

有 SSH 权限的维护者可临时把远端回环端口转到本机，用于首次设置和诊断：

ssh -N -L 18787:127.0.0.1:8787 <你的SSH用户>@<服务器地址>

保持连接，在自己电脑浏览器打开 http://127.0.0.1:18787/。尖括号内容必须替换；此通道只供授权维护者使用，日常成员和客户使用正式 HTTPS 工作空间地址。首次设置令牌默认在 /etc/visto/host-management-token，由主机管理员私下读取使用，勿公开配置内容。

5. 安装后的目录地图

如果安装时使用自定义数据目录或部署覆盖变量，记录真实路径，维护命令也要匹配该实例，不能假定所有主机都用默认值。外部媒体根权限与服务沙箱需要一致；系统管理员应按实际存储方案配置，不通过关闭全部服务保护来解决读写问题。

6. 视频预览与媒体运行时

Linux Server 的当前打包脚本生成主程序、网页和维护工具，不在该脚本内自动打入 FFmpeg。页面打开后仍需核对视频处理运行时。

sudo /opt/visto/current/bin/visto-server --help
sudo /opt/visto/current/bin/visto-server media-runtime --help

使用该版本 Release 提供的同架构运行时及对应安装说明。不要把 macOS 运行时安装命令和清单直接搬到 Linux，也不要重命名 Windows 或另一架构的文件。发布者未提供经过核对的 Linux 运行时与来源材料时，视频预览交付仍是未就绪项，联系维护者，不能以网页可登录替代视频可用。

运行时安装后重启服务，上传小型测试视频，等待处理完成、播放预览并提交时间点评论；再验证一份图片。只有这些业务步骤成功，才能确认该实例的媒体链路可用。

7. 启停、日志和诊断

sudo systemctl stop visto.service
sudo systemctl start visto.service
sudo systemctl restart visto.service
sudo journalctl -u visto.service -n 100 --no-pager
sudo tail -n 100 /var/log/visto/server.err
sudo /opt/visto/current/bin/visto-server --data-dir /var/lib/visto doctor

服务启动失败时先读日志，再检查配置和依赖；不要反复重装或删除数据。日志可能含路径和用户信息，提供求助材料前脱敏。服务修改配置后需重启；网页中的业务设置按页面反馈判断保存是否完成。

8. 备份并验证覆盖范围

sudo /opt/visto/current/scripts/backup-visto-server.sh

也可在独立备份磁盘上指定保存目录，须确认磁盘已挂载且容量足够：

sudo /opt/visto/current/scripts/backup-visto-server.sh --backup-dir /mnt/backup/visto

脚本先证明服务停止，再归档数据目录并生成数据库事实元数据，之后启动服务。只有归档和元数据均成功生成才算本次备份完成。备份放另一磁盘或可信远程位置；外部媒体、WebDAV、S3、/etc/visto 的部署配置另行备份。迁移到新主机还涉及恢复路径约束，不能直接承诺跨主机/跨目录恢复。

9. 更新、恢复与回滚

更新使用实际下载的包、摘要和同版本清单。示例输入需全部替换：

sudo /opt/visto/current/scripts/update-visto-server.sh \
  --package '/实际路径/Visto-Server_1.0.1_linux-amd64.tar.gz' \
  --sha256 '<发布页公布的64位SHA-256>' \
  --manifest '/实际路径/该版本的清单.json'

脚本验证布局，准备新版本、备份数据、停服并切换 current，失败时尝试还原。没有清单时停止，不手工改 current 或覆盖运行中的程序。更新成功后检查旧数据与新上传，不只看进程。

恢复先跑只读检查；示例归档名替换为真实备份：

sudo /opt/visto/current/scripts/restore-visto-server.sh \
  --backup-file '/var/backups/visto/实际备份.tar.gz' --check-only
sudo /opt/visto/current/scripts/restore-visto-server.sh \
  --backup-file '/var/backups/visto/实际备份.tar.gz' --confirm-restore

恢复会替换当前实例数据，先另做当前数据备份。归档与同名元数据必须一起保留，只支持检查认可的原数据目录；旧格式元数据或路径不符被拒绝时，不手改元数据。

回滚程序版本先检查保留的版本：

sudo ls /opt/visto/releases
sudo /opt/visto/current/scripts/rollback-visto-server.sh \
  --to-version '<仍保留的版本号>' --confirm-rollback

回滚程序不等于把数据库和媒体恢复到任意历史时刻。数据兼容性与恢复需求要分别判断；目标版本已清理或数据不兼容时联系维护者。成功后重新检查健康、登录、媒体与分享。

10. 网络与常见问题

默认 Core 仅监听回环。日常远程访问用受维护的 HTTPS 反向代理，再在工作空间配置外部访问地址；不要直接把 8787 暴露到公网。防火墙开放的是代理入口，浏览器里的本机地址不能发给客户。

11. 卸载与最终检查

sudo bash /opt/visto/current/scripts/uninstall-visto-server.sh

默认停止并注销服务、移除程序发布目录，保留用户数据、备份和日志。卸载前另存配置和完整备份；--keep-releases 可保留程序版本。--purge-data 会额外删除数据和备份目录，只有明确永久清除并确认独立备份可恢复时才使用，不能当排障步骤。

交付清单：安装架构正确；整机重启后健康成功；首次设置与权限正确；图片与视频预览通过；真实存储可读写；外部 HTTPS 分享可达；备份归档与元数据已独立保存；更新和恢复在对应平台受控验证。本章仅完成文档和源码参数核对，不宣称 Linux amd64 / ARM64 的最终包、运行时、安装及重启验收通过。

安装与初始化

08 · 安装视频处理运行时

视频预览、媒体探测和部分衍生产物需要 FFmpeg 与 ffprobe。原生 Server 安装包不包含它们；运行时由主机维护者单独安装。Owner 网页可以显示运行状态，但不会下载、提权或安装主机程序。

安装前确认

• 原生 Server 已经安装并可运行 visto-server。
• 当前机器是 Apple Silicon macOS；本章运行时不能用于 Intel、Windows 或 Linux。
• 使用官方公开仓库中固定的公钥。不要使用下载归档里附带的公钥来证明同一个归档可信。
• 官方仓库未公开时，公钥下载可能返回 404。已获授权的维护者可以使用随审核材料取得的同一固定公钥文件；普通用户应等待可用的公开安装入口。

在线安装

以下运行时版本依据当前安装说明固定为 ffmpeg-8.1.2-macos-lgpl.2。以后以对应发布说明为准，不自行猜测“最新版”地址。

mkdir -p "$HOME/Downloads/visto-runtime"
RUNTIME_VERSION='ffmpeg-8.1.2-macos-lgpl.2'
RUNTIME_BASE="https://visto-server-updates.pages.dev/media-runtime/$RUNTIME_VERSION"

curl -fL "$RUNTIME_BASE/media-runtime-manifest.json" \
  -o "$HOME/Downloads/visto-runtime/media-runtime-manifest.json"
curl -fL "$RUNTIME_BASE/media-runtime-manifest.json.sig" \
  -o "$HOME/Downloads/visto-runtime/media-runtime-manifest.json.sig"
curl -fL 'https://raw.githubusercontent.com/huangdiyou/Visto/main/keys/media-runtime-root-public-key.txt' \
  -o "$HOME/Downloads/visto-runtime/media-runtime-root-public-key.txt"

上面三个下载都成功后再运行：

sudo /Library/Visto/current/bin/visto-server --json media-runtime install \
  --media-runtime managed \
  --manifest "$HOME/Downloads/visto-runtime/media-runtime-manifest.json" \
  --signature "$HOME/Downloads/visto-runtime/media-runtime-manifest.json.sig" \
  --public-key "$(cat "$HOME/Downloads/visto-runtime/media-runtime-root-public-key.txt")" \
  --non-interactive --confirm-download

管理器会验证签名、下载清单指定的归档，并验证内容和媒体能力。签名、哈希或能力检查失败时，停止并保留报错；不要绕过检查切换运行时。

重启与验证

sudo launchctl kickstart -k system/com.visto.server
curl -fsS http://127.0.0.1:8787/health/ready

检查结果包含 "ffmpeg":true 和 "ffprobe":true。再进入演示项目上传一个短视频，确认能生成预览并播放。两项为 true 说明程序被检测到，实际视频播放还要用媒体验证。

失败时怎么处理

运行时清单有签名；免费 Server 的版本更新提示清单不签名。这是两条不同的分发流程。

安装与初始化

09 · Docker 部署说明

本章供已有 Docker 经验的维护者使用。当前公共源码白名单尚未包含 Compose 全套交付，因此不要把本章当作已存在的公开 Docker 下载入口。请使用对应版本明确提供并验收的完整 Docker 源码或交付目录；只拿到 macOS 公共快照时，请选择 macOS 安装路径。

前置条件与结构

需要 Docker Engine 26+、Docker Compose v2、至少 4 GB 可用内存、足够持久卷空间和可用的本机端口。官方 Compose 分为 core 与 web：浏览器连接 Web，Web 代理 Core；Core 的 8787 端口不应直接暴露给宿主机。

在提供 compose.yaml 的部署目录里生成首次初始化令牌：

export VISTO_HOST_MANAGEMENT_TOKEN="$(openssl rand -base64 32)"
docker compose up -d --build
docker compose ps

本机浏览器打开 http://127.0.0.1:8080/，输入刚生成的令牌并完成首次设置。令牌不要提交到仓库或发给成员。记录当前部署目录、Compose 配置、固定镜像与数据卷信息，以便维护时使用。

日常命令

docker compose ps
docker compose logs --tail 100 core
docker compose exec core visto-server doctor
docker compose down

down 用于停止这套部署。不要添加 -v，否则可能删除持久业务数据卷。项目数据、加密秘密和默认托管媒体位于数据卷；额外挂载和远程存储还要独立备份。

备份与恢复

在同一部署目录，由维护者运行交付中的脚本：

./scripts/docker/backup-visto-docker.sh --backup-dir ./backups

恢复会替换当前卷，先核对备份与同名 JSON 元数据、SHA-256、目标部署及异盘副本，再执行：

./scripts/docker/restore-visto-docker.sh \
  --backup-file './backups/<实际备份文件>.tar.gz' \
  --confirm-restore

这些 Docker 脚本的选项与 macOS 原生脚本不同，不混用 --check-only 或原生安装路径。更新时只使用该版本发布说明公布的固定 image@sha256: 引用，不猜测镜像仓库或可变 latest 标签。更新失败、断网、磁盘不足等最终容器实机回归仍须在目标环境验收；本文不把静态脚本检查记成实机通过。

安装与初始化

10 · 首次设置与登录

首次打开一个尚未初始化的实例，会看到“先建立你的本地工作空间”。这个过程创建数据库中的工作空间和 Owner，不会替你移动已有媒体。

看图操作： 先核对初始化令牌，再填写身份信息；最下方的主机目录权限影响后续存储配置，提交前决定好。

填写首次设置

macOS 读取初始化令牌：

sudo cat /Library/Visto/config/host-management-token

令牌用于首次领取初始化权限，和日常登录密码不同。不要把该输出贴到聊天、截图或公开 Issue。

一次性的主机目录权限

“允许 Owner 在网页端添加本机目录作为存储位置”默认开启。开启后，Owner 网页会话能配置主机目录，适合由你独占管理的机器；不信任所有 Owner 登录环境或部署在共享主机时，应由维护者评估后选择关闭。

该选项首次设置后不能在网页上更改。需要调整时由主机维护者编辑 visto.env 的 VISTO_ALLOW_WEB_HOST_PATHS：0 关闭，1 强制开启，然后重启服务。当前生效状态可在 Owner 设置 → 网络与安全 查看。

关闭后普通网页不能添加本机路径。项目成员仍可使用已经授权给项目的存储；如果必须添加新的主机目录，请联系部署维护者，不要求成员知道服务器真实路径，也不把 Desktop 当作免费版前置条件。

日常登录

初始化完成后，日常使用成员邮箱和密码进入。旧工作空间 / 首次 Owner 可能尚未设置登录邮箱，登录页提示允许邮箱留空时可使用原访问密码。登录后在“我的账户”确认个人身份与可用资料；新增成员使用独立邀请或注册流程。

完成检查与问题处理

• 成功后进入项目列表，而不是仍停留在创建表单。
• 密码错误、令牌错误和创建失败会显示提示，先按提示修正，不重复初始化。
• 已有实例突然出现首次设置页时，先核对浏览器地址和数据目录是否指向原实例。不要立即创建一个新工作空间覆盖问题。
• 忘记 Owner 密码时联系主机维护者，通过当前版本支持的账号恢复方式处理，不删除数据库重新初始化。

项目与素材

11 · 配置文件保存位置

谁来操作： Owner。入口： Owner 设置 → 存储与上传安全。

Visto 需要先有可用且已开放的存储，项目才能选择上传落点。浏览器所在电脑的路径不等于服务器路径：主机目录始终指向运行 Visto 的电脑或容器可见目录。

看图操作： 上方查看现有保存位置和异常，下面的向导按“类型 → 用途 → 位置 → 项目 → 安全”依次完成。

三种存储选择

使用最小必要权限的账号。远程连接先按页面测试连通性；网络策略可能拒绝某些地址，不能把地址填成可访问任意主机的代理。

本机存储：路径、权限和配额

名称用于让项目成员辨认，如“制作素材盘”；主机目录使用运行 Visto 的机器上的绝对路径。建议由维护者先建一个专用目录，给服务运行账号所需权限，再在向导填写；不要为了修复写入错误让所有人拥有整块磁盘的任意权限。

外接盘使用前确认它已挂载，盘名和路径稳定。Docker 中填写的是容器可见路径，宿主机目录需要由维护者正确挂载。容量配额留空时按页面含义不限制，并不意味着磁盘无限大。关注存储剩余空间，预览与备份也需要容量。

WebDAV：每个字段怎么填

创建连接后按界面测试。连接通了但项目上传仍不可用时，继续检查根目录范围、项目开放和用途。修改既有凭据时读清页面“留空保留”说明，不误把密码清空。

S3 兼容：Endpoint、Bucket 与前缀

Endpoint、区域、桶与密钥要属于同一服务。测试失败时区分连通性、认证和对象权限，不连续换填猜测值。上述域名和桶名只用于解释字段，不能直接用作可连接的存储。

完成五步向导

1. 类型： 选择本机、WebDAV 或 S3。
2. 用途： 日常上传选“作为项目上传位置”；交付保存选“作为归档位置”；评论附件选对应用途。归档位置不会自动成为默认上传位置。
3. 位置： 填可辨认的名称和相应连接信息。主机目录权限关闭时，本机路径不能在普通网页添加。
4. 项目： 选择开放范围。保存一个连接不代表所有项目都获得使用权限。
5. 安全： 选择上传安全策略并提交，查看成功或错误提示。

上传安全策略

策略名称不代表扫描引擎已经配置。查看具体检查结果，“未扫描”不能当作“安全扫描通过”。

让项目真正能用

创建后检查存储显示“可用”，用途是上传，开放范围包括当前项目。进入 项目设置 → 项目存储 确认上传位置。若下拉框为空，依次检查：是否有活动存储、是否允许上传、是否对项目开放、是否因配额或错误停用。

修改、停用和删除

修改存储前先查看受影响项目。停用可能阻止后续上传；删除连接和删除原文件不是一回事，按影响说明处理。不要从操作系统直接挪走正在使用的目录；已有媒体引用可能失效。新增归档位置也不会自动把全部媒体复制过去。

完成检查： 项目能选到位置，上传小文件成功，预览可读，空间与权限符合预期。

项目与素材

12 · 创建与管理项目

项目是协作范围。把不同客户、交付批次或权限边界放进不同项目，可以减少误共享和误操作。

创建项目

1. 回到项目列表，点“新建项目”。
2. 填写名称；建议“作品 / 客户 + 批次”，避免多个“新项目”。
3. 选择已开放的“项目存储位置”。没有位置可选时让 Owner 配置，不去寻找扫描导入入口。
4. 在说明里写目标、交付内容、负责人员和时间。
5. 提交并确认进入正确项目。

示例说明：“60 秒品牌短片；主片横版 16:9，社交裁切另立资产；导演先看节奏，客户确认文案；交付日前完成最终审阅。”

项目主管的日常维护

在项目设置维护基本资料和成员；存储只选择 Owner 已授权的范围。更换上传位置主要决定后续落点，不应默认理解为已有媒体已迁移。需要转移主管职责时使用项目提供的转移流程，检查新的主管和自己的保留角色，再确认。

成员看不到项目时

先检查是否登录正确工作空间和账号，再检查项目成员关系、账号状态和期限。用户已经注册或已经在团队里，不代表已被加入该项目。失去成员资格、项目删除或权限不足都可能使项目不可见。

完成检查： 名称和说明正确、上传存储可用、成员在各自账号中可见应参与的项目。

项目与素材

13 · 成员、邀请与权限

Visto 有工作空间账号与项目成员两层关系。团队邀请让一个人拥有自己的账号；项目成员关系决定他能在哪个项目里工作。

常见身份

项目成员默认可有较多协作权限，包括上传、审阅、分享或从项目移除媒体；若某人只需观看，应明确收紧权限，不凭角色名称推断“只读”。

看图操作： 在项目设置里管理成员；工作空间账号与本项目的角色分别确认。

邀请并加入项目

1. Owner 在 Owner 设置 → 账号与注册 创建成员邀请，填写成员邮箱并选择合适的账户类型。
2. 将本次邀请入口交给对应成员；邀请链接和账号不要多人共用。
3. 成员打开邀请页，按页面完成自己的资料和密码设置。
4. Owner 或具备权限的项目主管进入 项目设置 → 成员与权限，将该账号加入项目。
5. 选择项目角色及具体权限；有时间边界时设有效期。
6. 用成员自己的账号确认能看见项目、能做被允许的操作。

开放注册

Owner 可以配置注册策略。允许注册并不自动给新用户任何项目权限；项目主管或 Owner 仍需把用户加入具体项目。

调整或收回访问

成员离开项目时，检查项目成员关系、临时账户期限、已创建的分享和后续通知。移除成员不能收回已被对方下载的文件；外部分享也需要单独检查和撤销。

项目与素材

14 · 上传、搜索与整理素材

谁来操作： 有相应项目上传权限的成员。入口： 进入具体项目 → 媒体。

上传一个或多个文件

1. 确认顶部项目名。
2. 选择“上传本地文件”，从自己电脑选图片或视频。
3. 在上传任务面板查看等待、传输进度、完成或失败。
4. 失败时先看原因，按需要重新上传；未完成前不要关闭浏览器。
5. 传输完成后等待后台媒体识别与预览处理，再打开素材验证。

浏览器上传把选中的文件复制到项目授权的存储。已存在于服务器的文件不会仅因打开页面而被扫描导入；日常上传应始终在项目内完成。

分清三类状态

“上传完成”与“可预览”是不同阶段。源文件在库中但预览失败时，不要先删除重传，先检查运行时和具体任务。

搜索和筛选

按文件名搜索，再用类型、处理状态、开始 / 结束日期和排序缩小范围。找不到刚上传文件时，先点“重置”，确认当前项目、页码和筛选条件，再检查上传结果。

网格适合看画面，列表适合看文件信息。打开素材详情可以重命名、查看预览、元信息和版本历史。

加入已有媒体、复制和剪切

“添加已有媒体”只展示你有权使用的已有媒体，不是任意主机扫描入口。将资产加入另一个项目前，检查目标项目权限和存储要求。

详情中的“复制 / 剪切”是跨项目操作；不要把它等同于已经在另一个物理磁盘复制了完整文件。按页面结果检查目标项目可见性和媒体可读性。“从当前项目移除”进入项目回收站，恢复步骤见“归档与删除”。

命名约定建议

同一作品使用一个资产名称，如“品牌短片主片”；版本保留 V1、V2 的编号。横版、竖版或语言版本若分别交付，可以用不同资产，避免仅靠“最终版 / 最终版2 / 真最终版”区分。

项目与素材

15 · 回收站、归档与删除

这些操作的影响不同。执行前先确认你要解决的是“从当前项目移除素材”“停止协作”还是“彻底删除项目”。

恢复误移除媒体

进入项目“媒体 → 回收站”，找到相应媒体，使用恢复操作并查看提示。回到项目媒体确认文件和版本可读。若底层原文件已经被外部删除，恢复项目关系不会凭空恢复文件。

项目交付后的归档

1. 确认最终版本、正式结论和交付内容。
2. 检查未解决反馈，记录保留原因。
3. 检查外部分享，需要停止访问的先撤销。
4. 确认实际备份和必要的媒体异盘副本。
5. 进入 项目设置 → 危险操作，选择归档并确认。

归档不会自动把素材复制到归档存储，不会自动做异地备份，也不应假定已经撤销所有分享。需要再次修改时先恢复项目，再重新审阅新版本。

删除前必须确认的内容

读清页面对删除范围和可恢复性的提示，核对项目名、版本、分享及备份。不能用项目回收站替代整库恢复。备份恢复通常会影响整个实例，不只是一个项目，请让维护者评估后处理。

审阅与交付

16 · 版本管理与新一轮修订

版本历史让你保留原始审阅上下文。修订同一作品时，从原资产的“上传新版本”进入，而不是把修订文件上传成另一个没有关联的资产。

上传新版

1. 进入项目媒体，打开原资产详情。
2. 在 Version history 区域选择“上传新版本”。
3. 选修订文件，等待上传和处理完成。
4. 确认历史出现 V2 / 下一版本，检查画面和文件信息。
5. 核对 Current 标记；需要调整时使用页面支持的当前版本切换操作。
6. 明确选择新版本，再点“创建审阅”开始下一轮。

选择某一历史版本用于预览，与把它设为资产当前版本是两种操作。仅点开 V1 看画面，不应默认认为当前版本已切换到 V1。

旧评论会怎样

旧审阅与其评论仍属于原先引用的版本。把 V2 上传到资产并不自动把 V1 的审阅换成 V2。客户从旧链接看到旧版时，先检查分享对应的审阅清单；为新版建立新审阅并发送正确链接。

修订说明怎么写

可以在审阅名称和评论中注明改动范围：“V2：调整 00:12–00:18 节奏，修改片尾文案，其他镜头保持。”接收者容易确认改动，你也能追踪哪条反馈已落实。

完成检查： 版本编号正确、预览正确、当前版本明确、下一轮审阅确实引用新版。

审阅与交付

17 · 创建一轮审阅

谁来操作： 有创建审阅权限的项目成员。审阅是一轮明确的确认任务，围绕指定版本组织参与者、截止时间和判断规则。

创建步骤

1. 从素材详情选定版本后点“创建审阅”；也可在项目“审阅”里选择媒体加入清单。
2. 核对每份作品和 V 编号，移除无关内容。
3. 输入审阅名称，例如“主片 V2 · 客户文案确认”。
4. 设置截止时间；长期有效不代表永远开放写入，仍受审阅状态与分享策略影响。
5. 选择审阅成员和需要的负责人。
6. 选择通过条件。
7. 需要外部分享时设置访问密码、下载和评论权限，提交后核对创建反馈。

选择通过条件

草稿与开启

没有分享权限时，创建结果可能保存为草稿。草稿不等于已经对外发送；先检查审阅状态，按页面开启后再创建分享。创建成功但复制链接失败时，审阅可能已经存在，在详情里继续创建或复制分享，不重新发起相同审阅。

看板与详情

项目审阅看板展示不同状态的审阅。打开详情查看固定版本、参与者、评论线程和审核结论。记录每轮的目标，避免把素材级反馈、审阅状态和项目归档混在一起。

完成检查： 清单版本正确、参与人正确、判断规则符合要求、所需分享成功创建且复制。

审阅与交付

18 · 提交精确反馈与审核结论

好的反馈应说明“哪里、问题是什么、期望如何改”。尽量把内容定位到具体版本、时间或画面区域。

视频时间评论

1. 打开对应审阅或分享中的视频，播放到需要反馈的位置并暂停。
2. 选择时间点评论，点“抓取当前时间”，再输入意见。
3. 若问题涉及一段内容，选择时间区间，设置起点和终点。
4. 提交后确认评论出现，重新点击评论检查时间定位。

示例：“00:12.400–00:15.000：字幕先于旁白出现。请把字幕入点后移到第一句话开始。”

图片点位、区域与画面标记

在图片评论区选择对应工具：点位用于一个具体位置，区域用于一块画面，箭头、笔刷或矩形用于表达视觉关系。先在画面上标记，再写说明。提交后点击评论检查标记位置是否正确。

附件与回复

页面开放评论附件时，可附参考图片或文件。附件上传也可能经过安全检查；没有可用附件存储或策略拒绝时，先联系 Owner。涉及客户信息的参考文件只传到正确项目或分享。

回复里写清处理方案。具备权限的处理者可以把线程标为已解决；“已解决”表示反馈处理状态，不自动等于整轮审阅通过。

审核结论

具备结论权限的审阅者在审核结论区域提交：

按本轮通过条件汇总结论。分享开放评论且审阅未处于草稿或结束状态时，访客也可以对当前固定版本提交正式结论；匿名访客以分享会话记录身份。关闭分享评论权限时，访客的新评论与正式结论都不能提交。

审阅与交付

19 · 创建、安全检查与撤销分享

分享让外部人员访问指定审阅内容，不必给他们 Owner 账号或整个工作空间权限。

分享之前先检查四件事

1. 内容范围： 只包含要让接收者看的媒体与版本。
2. 访问方式： 按需要设置访问密码、到期时间及昵称要求。
3. 允许操作： 评论与下载分别控制；能播放不代表允许下载原片。
4. 可达地址： 接收者必须能访问该主机 / 团队域名；127.0.0.1 只能给本机用。

创建并验证

在创建审阅时设置访问策略，或在审阅详情的“分享与通知”创建分享。确认成功后复制链接，需要密码时将密码与链接妥善交付。

用另一个未登录的浏览器窗口验证：是否要求密码、显示的文件和版本是否正确、评论和下载是否如预期。再在接收者实际使用的网络设备上验证可达性；本机验证通过不能证明外网已能访问。

更新或撤销

在审阅详情的分享记录中查看现有分享、展开链接与密码，按页面支持调整策略、撤销或重新生成入口。撤销后再次从未登录窗口测试失效结果。

重新生成链接会影响原接收者，记得发送新链接。撤销只能阻止后续访问，无法收回已经下载或复制的内容。

为什么客户仍然看到旧版

分享引用的是对应审阅，而审阅固定了媒体版本。上传 V2 后，用 V2 创建新一轮并发送新入口。不要把“当前版本已更新”当成“所有旧链接都自动更新”。

完成检查： 未登录可按策略访问、链接实际可达、范围正确、密码和下载规则正确。

审阅与交付

20 · 给外部审阅者的操作指南

本章可以直接交给客户或合作方。你通常只需要分享链接和发布方提供的访问码；无需安装 Visto，也不要索要团队 Owner 密码。

打开链接

1. 用浏览器打开收到的链接。
2. 页面要求密码时，输入发布方提供的访问码。
3. 要求昵称时，填写能让团队辨认的姓名或公司与姓名。
4. 检查显示的作品名称和版本，选择相应作品查看。

看画面、写反馈

图片可以用点位或区域评论标出问题；视频可以暂停后抓取当前时间，也可选择时间区间。建议格式：“位置 + 问题 + 希望的修改”。提交后确认评论出现在列表。

如页面只开放观看，评论按钮不会可用。下载同样由发布方决定，不能下载时先询问发布方是否需要交付源文件。

提交当前版本的正式结论

分享开放评论且审阅未结束时，可以在“当前版本结论”选择“通过”“需修改”或“拒绝”，填写说明后提交。确认页面显示已记录的结果。该操作针对当前固定版本；文字评论与正式结论是两种记录。分享关闭访客反馈或审阅结束后不能继续提交。

访问失败时

反馈问题时不要把访问密码、完整含令牌链接或客户原片发到公开社区。

设置与维护

21 · 通知、个人资料与活动

通知帮助成员及时看到审阅和协作变化。外部通知是否可用取决于 Owner 配置的渠道和成员自己的接收偏好。

我的账户

点击右上角个人入口，进入“我的账户”。查看身份、维护显示名称、界面语言和接收偏好，保存后确认成功提示。个人姓名会用于评论和成员列表；界面语言会影响导航与部分页面文案。

站内通知

从全局“通知”进入，查看自己有权访问的消息。点消息回到相关项目或审阅，阅读后按页面操作标记状态。没有消息时，先检查是否是正确账号和对应事件是否已发生。

外部渠道

Owner 在 Owner 设置 → 全局通知 配置邮件、飞书或企业微信等已有渠道，填写服务信息后测试。渠道密码、Webhook 和密钥只由 Owner 管理，不发送给普通成员。

“渠道测试成功”说明测试投递成功，不能单独证明每位成员都收得到：还要核对成员接收地址、个人偏好和真实事件投递状态。

活动与审计

项目设置中的活动记录帮助追踪谁在什么时候做过什么；Owner 系统活动用于全局排查。按时间、成员、动作和资源筛选，遇到失败投递时保留状态和错误信息再处理。活动记录不能代替媒体备份。

设置与维护

22 · 网络与远程访问

默认原生 Server 只监听本机；默认 Compose Web 也绑定本机。把分享链接交给异地客户以前，先由部署维护者配置可达地址和 HTTPS 入口。

四个容易混淆的设置

正确的开启顺序

1. 维护者配置 HTTPS 域名、证书及反向代理，确保 Visto 正常工作。
2. 用远程设备访问 HTTPS 地址并验证登录和分享。
3. 在 Owner 设置 → 网络与安全 打开“远程访问必须使用 HTTPS”。
4. 保存后立即生效，再检查团队和分享入口。
5. 防火墙和代理应使 HTTPS 网关成为唯一公开入口。

该开关默认关闭。开启后，非回环明文 API 请求可能返回 426 security.https_required。本机 127.0.0.1 仍可使用 HTTP。正在通过远程 HTTP 操作时，系统会阻止会导致自锁的开启请求；请先切换到 HTTPS 或到部署主机操作。

由部署配置强制

REVIEW_STUDIO_REQUIRE_HTTPS=1 会强制 HTTPS 策略，网页不能关闭，需要维护者改主机配置并重启。代理信任和 Cookie 的安全标记由部署配置及真实请求协议决定，不能只打开网页开关就认为代理已正确配置。

推荐交付给成员的信息

团队的 HTTPS 地址、登录方式、项目邀请、能访问的网络范围及支持联系人。不要把主机配置、初始化令牌或底层存储密钥一并发送。

设置与维护

23 · 备份：保护数据库与媒体

本章命令适用于 macOS 原生 Server，由部署维护者在主机执行。备份会短暂影响服务，选择没有上传和重要审阅的时间窗口。

先分清备份覆盖范围

最常见误区： 数据库里有文件记录，不代表这份备份已经包含全部原片。先清点每个存储的物理落点，再决定备份范围。

创建备份

sudo /Library/Visto/current/scripts/backup-visto-server.sh

脚本会证明服务已经停止，再归档数据，随后按流程启动并检查就绪。停服证明失败时会中止；不要手动伪造成功记录或直接打包正在变化的数据库。

确认完成

1. 命令成功退出并打印实际备份路径。
2. 归档和 <归档文件>.json 元数据均存在。元数据记录摘要和恢复所需信息。
3. 服务重新就绪，浏览器能读取项目。
4. 把这两个文件一起复制到另一块磁盘或可信备份位置。
5. 把数据目录外媒体和部署配置的独立备份与此次备份关联记录。

建议的备份时机

首次完成配置后、重要交付后、每次更新前、每次恢复或大规模存储调整前。按项目价值安排日常周期，并定期在隔离环境检查可恢复性；“文件存在”不等于“恢复已验收”。

设置与维护

24 · 更新、恢复、回滚与卸载

本章适用于 macOS 原生 Server。执行的是主机维护操作，普通项目成员无需运行。占位符必须替换成实际路径、版本和摘要；保留所有命令输出用于定位失败。

更新：安装包、摘要和版本清单要匹配

免费 Server 提示新版本后，由维护者从官方 Release 手动下载。免费版本提示清单不签名，不自动下载或安装；SHA-256 校验是完整性检查，不能替代下载来源的可信度。

当前原生更新脚本还要求版本清单文件。不能只提供包与摘要；未传 --manifest 时脚本会查找 <安装包路径>.manifest.json。按同一 Release 的说明取得版本清单，确认其 version 与包一致。若 Release 未提供可用清单或安装路径，停止并联系维护者，不随意拼写清单绕过缺失。

1. 记录当前版本与运行状态。
2. 创建备份，把归档、元数据和外部媒体副本妥善保存。
3. 下载同一发布的包、摘要与版本清单。
4. 校验 SHA-256，执行：

sudo /Library/Visto/current/scripts/update-visto-server.sh \
  --package '/实际路径/Visto-Server_<版本>_macos-arm64.tar.gz' \
  --sha256 '<官方公布的64位SHA-256>' \
  --manifest '/实际路径/该版本的清单.json'

脚本在校验、停服和备份保护后切换程序，检查健康状态；失败时按工具的恢复流程处理。不要手工改 current 链接。

更新后检查

curl -fsS http://127.0.0.1:8787/health/ready
sudo /Library/Visto/current/bin/visto-server --json \
  --address 127.0.0.1:8787 status

再用浏览器确认项目、旧文件、新上传、视频播放和分享。健康接口通过不能代替业务数据检查。

日常服务启停与日志

维护前确认没有在途上传或重要审阅。默认 macOS 实例可以用系统服务管理器停止或启动：

# 停止
sudo launchctl bootout system/com.visto.server
# 启动
sudo launchctl bootstrap system /Library/LaunchDaemons/com.visto.server.plist
# 已加载服务的重启
sudo launchctl kickstart -k system/com.visto.server

启动或重启后再次查 health/ready 并在网页验证。若提示服务不存在或已加载，先确认当前服务状态和实际安装配置，不反复执行。默认日志位于 /Library/Logs/Visto；保留相关时间段的错误即可，发给他人前脱敏。网页全局设置通常保存后立即生效，主机环境配置的修改则按要求重启。

恢复：先只读检查，再执行替换

恢复会替换当前实例的数据目录，会影响备份之后的业务变化。先保存当前实例的备份；确认目标主机、数据目录、归档和同名元数据。

sudo /Library/Visto/current/scripts/restore-visto-server.sh \
  --backup-file '/实际路径/备份.tar.gz' \
  --check-only

只读检查通过且你已确认覆盖影响后执行：

sudo /Library/Visto/current/scripts/restore-visto-server.sh \
  --backup-file '/实际路径/备份.tar.gz' \
  --confirm-restore

两种模式不能同时使用。当前恢复保护要求原数据目录一致；跨目录恢复可能被拒绝。拒绝时保留错误，不手工解压覆盖数据库，也不修改元数据去伪装路径。

恢复后确认服务就绪、项目和版本符合备份时间，原文件可读，外部存储仍可访问；数据目录外原片需要独立恢复与核对。

回滚到保留的程序版本

sudo /Library/Visto/current/scripts/rollback-visto-server.sh \
  --to-version '<已保留的版本>' \
  --confirm-rollback

程序回滚与数据恢复目的不同；不能假定旧程序一定兼容当前数据库。让工具执行对应保护，按具体失败说明处理。不要删除恢复点、备份或失败日志。

卸载

默认卸载保留用户数据和备份：

sudo /Library/Visto/current/scripts/uninstall-visto-server.sh --yes

卸载程序不会自动抹掉外接盘或远程存储上的文件。--purge-data 会扩大删除影响，只在确认不需要数据并有可用备份时按该版本说明使用。

帮助与参考

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 账号替代所有成员操作。

更新或恢复失败

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

帮助与参考

26 · 常见问题

我需要安装 Desktop 才能用吗？

本手册的免费 Server 浏览器工作流不以 Desktop 为前置依赖。团队已经部署 Server 时，你只需要地址、账号或分享入口。

数据会自动上传到云端吗？

媒体按 Owner 配置的保存位置存储。本机部署和远程存储是不同选择；启用 WebDAV / S3、外部通知或远程分享时，相应数据会经过所配置服务与网络。

同一个文件名会自动合并成版本吗？

不要依赖文件名相同自动合并。需要修订原作品时，打开原资产并使用“上传新版本”，再核对版本历史。

上传新版后，旧分享会显示新版吗？

不要这样假定。审阅引用固定版本；用新版创建下一轮审阅并发送正确入口，旧审阅继续保留旧版本的上下文。

注册后为什么看不到项目？

账号存在不代表已加入项目。请 Owner 或项目主管添加项目成员关系并核对状态、期限和权限。

为什么网页不能再改本机目录权限？

这个开关只在首次设置时询问一次。后续由主机配置修改并重启，避免 Owner 网页会话自行改变主机访问边界。

归档后文件已经复制到归档盘了吗？

没有这个保证。项目归档是生命周期操作，物理存储复制和备份是独立操作，必须分别确认完成结果。

拷贝数据库就算备份全部媒体吗？

不算。需要一致性数据库和加密秘密，也要清点系统托管媒体、外部目录及远程文件。参见“备份”。

安全扫描没有结果，是不是安全？

“未扫描”“等待”或“引擎不可用”不能等同安全通过。结合策略、实际引擎和检查结果处理。

网页显示有更新会自动安装吗？

免费 Server 只提示版本，主机维护者手动从官方发布页下载校验并更新。媒体运行时的签名安装流程另行处理。

能把本机分享地址发给客户吗？

127.0.0.1 只对当前设备有效。客户需要一个可达的团队地址和符合策略的 HTTPS 入口。

手机上能打开代表移动端已验收吗？

不代表。本手册网页做响应式阅读适配，产品在不同手机、浏览器和文件格式上的兼容性仍以对应版本验收为准。

帮助与参考

27 · 交付检查单与求助模板

项目主管：每轮审阅前

• 选定的资产、版本和审阅目标一致。
• 参与者、负责人和通过条件符合本轮要求。
• 截止时间与访问有效期符合安排。
• 分享密码、评论、下载范围已核对。
• 从未登录窗口和接收者网络验证入口。

项目成员：提交新版本后

• 上传成功且处理状态可用。
• 新版出现在原资产历史中，当前版本正确。
• 修订说明包含处理的反馈范围。
• 下一轮审阅引用新版，不误发旧链接。

维护者：部署或更新后

• 服务就绪，媒体运行时可用。
• 使用正确账号读回既有项目与旧文件。
• 小文件上传、图片预览、视频播放和外部分享可用。
• 备份归档、元数据、外部媒体与主机配置备份齐全。
• 重启后的数据与服务仍可读，或明确记录未测。

报告问题时提供什么

复制下面模板给团队维护者；公开问题只发脱敏内容。安全问题通过项目的安全报告入口私下提交。

问题标题：
Visto 版本 / 部署方式：
系统 / 浏览器版本：
发生时间与时区：
我的身份（Owner / 项目主管 / 成员 / 分享访客）：
所在页面与操作：
复现步骤：
1.
2.
3.
预期结果：
实际结果与错误提示：
影响范围（单文件 / 单项目 / 所有用户）：
最近是否更新、改存储或改网络：
已经做过的检查：
脱敏截图或日志片段：

不要公开发送原数据库、客户原片、存储密码、初始化令牌、私钥或完整带访问令牌的分享链接。截图也要检查浏览器地址、账号、主机路径和客户信息。

手册版本与验证边界

本版对照当前主线源代码、安装说明及维护脚本编写，真实截图来自独立演示数据。界面截图覆盖首次设置、存储向导、创建项目、媒体、版本、审阅、外部图片评论、成员设置及归档说明；流程图为解释操作关系的原创示意。

本文不把写好安装命令等同于在所有平台实际安装通过，不把网页验收等同于产品首发验收。正式发布前仍需使用最终包、最终地址和目标系统执行完整路径复核，并补对应版本说明。