运行方式与自部署

Snow Cues 是纯前端应用，可以通过不同方式运行。多数用户直接使用官方 HTTPS 部署即可；自部署适合希望控制分发环境、固定版本、内部统一入口，或在源码 / 构建期扩展算法注册表的用户和维护者。

这篇文档先说明 Snow Cues 有哪些运行方式，再说明为什么需要自部署、如何自部署，以及自部署不会改变哪些安全边界。

Snow Cues 有哪些运行方式

运行方式	推荐程度	适合场景	主要优点	主要限制
官方 HTTPS 部署	推荐	大多数用户	不需要维护部署，安全上下文稳定	依赖官方分发入口
官方 HTTPS 安装的 PWA	推荐	常用设备和移动端入口	像应用一样打开，仍使用官方 HTTPS	仍来自官方部署
自部署 HTTPS 静态站点	高级用户推荐	个人或组织控制分发环境	可固定版本、审计构建、控制域名	需要自己维护部署和升级
localhost / 127.0.0.1	开发推荐	本地开发和调试	浏览器通常视为安全上下文	不适合作为正式共享入口
普通局域网 HTTP	不推荐	临时测试	配置简单	WebCrypto 或文件访问能力可能不可用
file:// 直接打开 HTML	不推荐	无服务环境	直接打开	ES module、WebCrypto、文件访问可能失败
移动端 App 内置浏览器	不推荐	从聊天或其他 App 打开链接	入口方便	安全上下文和 WebCrypto 能力不稳定

正式使用建议选择 Chrome、Edge 等 Chromium 系浏览器。其他浏览器可以尝试，但不作为主要推荐环境。

推荐使用方式

普通用户优先选择：

1. 官方 HTTPS 部署。
2. 由官方 HTTPS 地址安装的 PWA。

需要控制分发环境的用户选择：

1. 自部署到可信 HTTPS 静态站点。
2. 在升级前先验证旧 storageData 和规则链兼容性。

开发或调试选择：

1. localhost。
2. 127.0.0.1。

为什么不是直接打开 HTML

直接打开 file:// HTML 看起来简单，但不适合作为正式运行方式。

原因包括：

• WebCrypto 能力依赖安全上下文。
• ES module 和静态资源路径可能受限。
• File System Access API 可能不可用。
• 移动端和内置浏览器限制更多。

如果浏览器阻断 WebCrypto、模块加载或文件访问能力，Snow Cues 会无法完成敏感操作。

为什么需要自部署

自部署的主要价值不是“把用户数据放到服务器”，而是控制前端应用的分发方式。

你可能需要自部署，如果你希望：

• 减少对官方分发地址的依赖。
• 固定某个版本，避免自动跟随官方更新。
• 在组织内部提供统一入口。
• 审计源码并自行构建。
• 控制访问域名、网络环境或发布节奏。
• 在源码 / 构建期扩展算法注册表。

自部署的好处

自部署可以带来这些实际好处：

• 运行入口由自己控制。
• 可以固定版本，先测试再升级。
• 可以部署在组织内部可信域名。
• 可以保留纯静态前端模型，不引入服务端数据托管。
• 可以在源码层扩展算法模板。

自部署不会带来什么

自部署不会改变 Snow Cues 的核心边界：

• 不会自动备份 storageData。
• 不会提供空间主密码或关键密钥找回。
• 不会提供云同步。
• 不会自动合并冲突。
• 不会让非 Chromium 浏览器变成推荐环境。
• 不会允许运行时导入任意算法代码。
• 不会让服务端参与密码派生。

不要把自部署理解为“搭建自己的密码托管服务器”。Snow Cues 的业务数据仍应由用户显式打开、保存、同步和备份。

自部署前的决策清单

自部署前先确认：

• 你是否愿意维护 HTTPS 静态站点。
• 你是否能保证部署产物来源可信。
• 你是否能在升级前测试旧数据。
• 你是否需要固定版本。
• 你是否需要内部统一入口。
• 你是否有能力维护自定义算法构建。

如果这些问题都不重要，直接使用官方 HTTPS 部署通常更合适。

推荐部署方式

推荐部署到 HTTPS 静态托管环境，例如：

• Cloudflare Pages
• Netlify
• Vercel
• GitHub Pages
• 自维护 HTTPS 静态服务

不建议把普通局域网 HTTP、移动端 App 内置浏览器或直接打开 file:// HTML 作为正式运行方式。

如何自部署

在项目目录中安装依赖并构建：

npm install
npm run build

构建产物会输出到 dist/。将 dist/ 作为静态站点根目录部署即可。

部署后应检查：

1. 站点通过 HTTPS 访问。
2. 在 Chrome、Edge 等 Chromium 系浏览器中打开。
3. 应用页面能正常加载。
4. WebCrypto 相关操作没有被浏览器阻断。
5. 新建或打开 storageData 的流程能正常完成。

本地预览

构建后可以本地预览：

npm run preview

本地开发和预览可使用 localhost 或 127.0.0.1。这不等同于正式部署；正式部署仍建议使用 HTTPS。

部署后如何使用

自部署站点和官方站点一样，只负责分发前端应用。

用户仍然需要自己管理：

• storageData
• 空间主密码
• 单条密码的关键密钥
• 导出备份
• Syncthing 等外部同步工具

更新自部署版本

更新自部署版本前，建议：

1. 先备份现有 storageData。
2. 阅读版本说明，尤其是规则链、导入 Rule、params 或存储格式相关变化。
3. 在测试空间中验证新版本能正常进入空间、查看条目和保存数据。
4. 再替换正式静态产物。

如果某个空间规则使用了 params，不要再用不支持 params 的旧版本打开和维护该空间。

自部署算法扩展

官方构建只包含项目维护者审计过的规则算法模板。自部署版本可以在源码 / 构建期扩展算法注册表并自行构建。

这个能力适合：

• 组织内部固定使用一组经过内部审计的派生算法模板。
• 个人 fork 后加入官方版本暂未提供的 WebCrypto 或 WASM-backed 算法。
• 在不修改业务数据主体模型的前提下，让声明式导入规则选择更多源码内置模板。

不支持：

• 让用户在页面中粘贴 JavaScript、表达式、WASM URL 或远程脚本。
• 让 storageData 携带算法代码。
• 通过 URL 参数决定运行哪个算法实现。
• 通过远程规则市场或第三方 JSON 动态下发算法。

自部署构建和官方构建可能使用不同算法注册表。使用自部署专有算法创建的空间，必须继续使用包含该算法的构建打开；官方构建无法使用未注册算法维护该空间。

自部署维护责任

自部署方需要自己负责：

• 静态站点托管和 HTTPS 配置。
• 构建产物的来源可信度。
• 浏览器兼容性验证。
• 自部署专有算法的安全性、性能和长期维护。
• 向使用者说明当前构建包含哪些算法模板。
• 在升级前验证旧 storageData 和规则链兼容性。

下一步

• 推荐运行环境和安全边界：安全与隐私。
• 自定义 Rule 和 params：核心概念。
• 多设备同步：多设备同步。