Snap Store 运行手册¶

当前状态¶

• 分支：feat/snap-store，基于 feat/store-publishing-foundation。
• 生命周期：每个 v* 标签都会上传到 candidate 渠道；stable 渠道为手动提升。
• 软件包：Electron x64 Snap，与现有的 AppImage 和 Debian 软件包并存。
• 约束模式：strict，使用固定的 electron-builder 所支持的 core22 基础。在首次提交前请重新检查所支持的基础版本。
• 更新所有者：Snap Store。此构建中应用内更新器不可用。
• Snap 名称：voicestudio（工作流中的 SNAP_NAME）。

该工作流绝不会自行更改列表文案、可见性或 stable 渠道。

包与接口约定¶

使用 VOICESTUDIO_DISTRIBUTION=snap-store 构建。生成的软件包将 snap-store 和 store 分别作为其分发元数据和更新所有者元数据嵌入。直接进行 Linux 构建仍会生成带有现有更新器元数据的 AppImage 和 Debian 软件包。

Snap 仅请求受维护的桌面行为所需的接口：

removable-media 被有意排除。Electron 的文件选择器使用桌面门户（desktop portal），该门户会授予对用户所选确切文件的访问权限，包括可移动介质上的文件。仅在约束测试证明某个受维护的工作流无法使用门户时，才添加更宽泛的接口，并请先在此处记录 Store 审核请求。

Snap 会将 HOME 重写至其可写的用户数据区域。因此，Electron 设置、受管运行时、后端数据、模型和缓存保持可写，并通过 Snap 的数据复制生命周期在刷新后继续存活。用户选择的导入和导出使用门户路径。请分别验证自定义运行时和数据重定位：所选择的门户文件不保证保留可执行权限。

构建与检查¶

从任意分支触发 .github/workflows/snap-store.yml 以进行不上传的构建，或在 x64 Linux 构建机上执行：

export VOICESTUDIO_DISTRIBUTION=snap-store
export VOICESTUDIO_RUST_TARGET=x86_64-unknown-linux-gnu
node scripts/validate_store_foundation.mjs --distribution=snap-store
bun install --frozen-lockfile
bun run check:electron
cd electron
bun x electron-builder --config electron-builder.config.mjs --linux snap --x64 --publish never
node tests/packaging-contract.mjs --artifact
node ../scripts/verify_snap_artifact.mjs
node ../scripts/create_store_artifact_manifest.mjs --distribution=snap-store --platform=linux --arch=x64
node ../scripts/create_snap_store_assets.mjs

安装前请检查以下工作流产物：

• VoiceStudio-<version>-linux-x64.snap
• VoiceStudio-<version>-snap-verification.json
• store-artifact-manifest-linux-x64.json
• snap-store-assets/icon.png、banner.png（3:1 列表横幅）、五张截图及 listing-assets.json

软件包验证器还要求将 electron-builder 的桌面运行时脚本和库展开到 Snap 根目录。嵌套的模板归档或缺少 desktop-init.sh 属于阻断性打包失败。

资产清单仅来源于 store/assets.json；请勿在 Snap 仪表板中分叉列表文案或图片来源。该工作流从不编辑列表，因此请手动在 Snap 仪表板的 Listing 页面中上传 icon.png、banner.png 和截图。横幅由 store/snap/banner.html 以 1920x640 渲染（在 Chromium 中打开并捕获视口），且必须保持 3:1 比例。

Snapcraft 构建（仪表板）¶

snap/snapcraft.yaml 也允许 snapcraft.io 的 Builds 标签页构建此 Snap。它会将最新 GitHub 版本的官方 Linux .deb（已对照该版本的 SHA256SUMS.txt 校验）重新打包，采用与发布工作流相同的严格约束和接口，并禁用应用内更新器，因为 snapd 负责更新。tests/test_snapcraft_yaml.py 使其接口与 electron/electron-builder.config.mjs 中的 snap-store 目标保持一致。上述发布工作流仍是主要路径；如果 Snapcraft Builds 已连接，请将其修订版本发布到 edge 渠道并按常规流程提升。

约束验证¶

先在本地安装测试构建，然后连接录音接口：

sudo snap install --dangerous <file>.snap
sudo snap connect voicestudio:audio-record
snap connections voicestudio
snap run voicestudio

Snap 遵循 Canonical 的 Electron browser-support 指南：在打包的 Snap 启动器中设置 allow-sandbox: false 和 --no-sandbox，同时保留 confinement: strict。该接口默认自动连接，无需特权版 allow-sandbox: true 的 Store 批准。全新安装应可从桌面启动器直接启动，无需终端或手动设置沙箱。显式断开某个接口属于用户选择；请检查 snap connections voicestudio 并在需要时手动重新连接。在测试从较旧本地修订版本的升级时，请验证现有连接状态，而不是假设元数据变更会自动重新连接。

启动器标志仅限于 Snap 产物。AppImage、Debian、macOS、Windows 和开发启动保留其现有沙箱配置。旧的预检和可选 Zenity 对话框已移除。

安全权衡：严格 Snap 约束仍通过 AppArmor、seccomp 和命名空间限制应用，但 Chromium 的每进程沙箱在此 Snap 中已对所有进程禁用，包括内嵌的网站预览和赞助表单。这些是不同的安全边界，而非等效的层次。请保持上下文隔离、对远程内容禁用 Node 集成、隔离的浏览器会话以及拒绝浏览器权限。Electron 的通用指南建议不要在生产环境使用 --no-sandbox；本软件包刻意遵循 Canonical 针对 Snap 的特定做法。请勿将此标志扩展到其他发行版，也不要切换到 classic/devmode 约束模式。

在干净且受支持的主机上完成所有项目：

• 全新安装、browser-support 自动连接，以及通过桌面和终端的首次启动；
• 首次运行的托管式 Python 安装和离线重启；
• 安装模型，然后执行离线合成；
• 麦克风采集、音频播放和听写；
• 网站预览、地址栏导航和赞助表单展示；
• GPU 发现，并在硬件可用时执行一次基于 GPU 的生成；
• 通过门户在主目录和可移动介质上进行文件导入/导出；
• 项目打开/保存和监视文件夹访问；
• 自定义运行时和数据位置的选择、重启和清理；
• 可选加入的局域网共享，包括后端绑定和第二设备请求；
• 刷新到更新的 candidate 修订版，并回滚到先前的修订版；
• 卸载而不影响 AppImage/Debian 数据或安装。

任一项目失败都会阻塞分支。应优先采用更窄的接口或门户流程；不要仅为通过测试而切换到经典限制。

提交与证据¶

一次性设置，由所有者完成：

1. 注册名称，并确认 Snapcraft 账户对其具有控制权： snapcraft register voicestudio，然后执行 snapcraft status voicestudio。
2. 创建一个名为 snap-store 的 GitHub 环境（可选择设置必需的 审查者），并将上传凭据以 SNAPCRAFT_STORE_CREDENTIALS 形式存储在其中：

snapcraft export-login --snaps=voicestudio \
  --acls=package_access,package_push,package_update,package_release \
  --expires=<date> credentials.txt

推送最终的 vX.Y.Z 标签后，工作流会构建 Snap、检查标签是否与 package.json 匹配、上传并将其发布到 candidate 渠道。该工作流先上传，然后在即将发布前检查最新的 v* 标签，因此较旧标签的修订版会被上传，而 candidate 不会移动。运行摘要会记录 Store 修订版和渠道。可以通过从该标签重新派发工作流并启用 upload 来重试标签构建。

升级到 stable 需要在独立完成安装、刷新和回滚验证之后，获得所有者的单独批准：由仓库所有者派发工作流，并将 promote_revision 设置为已验证的 candidate 修订版。该作业会拒绝任何其他触发账户。

在升级到 stable 之前，请获取 audio-record 的 Store 自动连接批准，并在全新的 Store 安装上验证录音。browser-support plug 使用其默认自动连接策略，不请求特权的 Chromium 沙箱访问。请记录全新安装和升级两种场景下的实际连接状态和首次启动证据。

对于每个提交的修订版，请保留：

• 软件包和 store-artifact-manifest-linux-x64.json；
• Store 修订版号和渠道；
• 下载的 Snap 断言及其 SHA-256 摘要；
• 自动/人工审查发现及其解决方案；
• snap connections、安装、刷新、回滚和离线测试日志；
• 工作流运行 URL 和源代码提交。

只有在 Store 断言已下载并与所提交的修订版匹配后，才能在最终来源记录中设置 signingVerification。

提交前请重新核对 Canonical 的当前文档：严格限制、接口、桌面文件门户 和 修订版/渠道管理。

回滚或下架¶

要恢复一台测试机器，请使用 sudo snap revert voicestudio 或指定已知良好的修订版。对于渠道回滚，请让所有者将先前已知良好的修订版重新发布到该渠道，在另一台主机上验证刷新，并记录新的渠道映射。关闭渠道或更改上架可见性是所有者操作；在执行任一操作之前，请记录其对现有安装的影响。