Zenance 源码部署与数据迁移：先跑通本地账本，再接 Dropbox

Zenance v1.0.0 是 React、TypeScript 与 Vite 构建的个人记账 PWA，本地数据库使用 Dexie 封装的 IndexedDB。部署它时，应用文件、浏览器账本和 Dropbox 同步副本需要分别处理：换了网站部署，不会自动把原浏览器中的账本复制过去。

这篇以已有源码包为起点，说明开发启动、静态部署、同步配置和迁移验证。命令依据该版本的脚本定义，文中的检查项是部署时应核对的结果，不代表已在所有浏览器或主机上验证兼容性。

发行记录提供源码归档，没有对应的 Windows、macOS 或 Android 预编译安装器。解压后，进入包含 package.json 的项目根目录，再运行依赖安装命令。不要在压缩包外层或只有说明文件的目录里直接启动。

bash 复制代码

npm install
npm run dev

项目 README 把 Node.js 18 列为环境下限，但包清单采用 Vite 8 等依赖，不能仅凭 README 的最低数字认定旧环境一定能够构建。实际安装若出现引擎版本不满足，先按依赖声明调整 Node 环境；不建议用忽略引擎检查的方式掩盖兼容问题。

开发脚本实际运行 vite --host。它可能使开发服务监听网络接口，进行手机联调时应了解当前可访问范围。开发服务器用于调试，正式使用应另做生产构建与静态部署。

首次打开后，先建试用账本、确定基准币种，再建账户和少量交易。账本含有账户、交易或预算后，编辑逻辑会锁定基准币种，因此币种不是适合后补的装饰字段。

生产构建使用：

bash 复制代码

npm run build

这个脚本先执行 TypeScript 构建检查，再由 Vite 生成产物。遇到类型错误，应先处理编译输出；只有页面曾在开发模式打开过，不能证明生产包已经可用。

构建结果位于 dist/。把产物部署到支持 HTTPS 的静态站点服务，保留应用需要的资源路径。项目具有设置页等前端路由，部署后还应测试直接访问和刷新相应路径，确认主机的路由回退配置没有把它们当成不存在的文件。

HTTPS 不只是访问栏上的锁。应用的 Web Crypto、持久化存储申请、本机快照等能力涉及安全环境与浏览器支持。若某项在本地开发正常、上线后变灰，先查看访问协议、浏览器能力和页面提示，再判断是否为业务代码错误。

PWA 安装和离线能力也要分开验证。先在线打开应用并等待必要资源加载，再使用浏览器提供的安装入口；随后测试断网访问已有账本与记账。汇率更新和远端同步属于联网能力，不应因记账能离线就一并承诺可用。

IndexedDB 数据属于浏览器的站点存储。一个新域名、一套新的浏览器配置，或者同一台电脑上的另一个浏览器，都不应被直接当成原账本的延续。开发地址切到生产地址时尤其容易误判：页面能加载，数据却可能是另一份空库。

项目设置页把数据功能集中在资料与存储区域，包含手动导出、导入恢复、本机快照、数据库健康检查和持久化存储申请。持久化权限能改善浏览器的存储保留策略，但不能替代迁移前导出文件。

手动导出生成 ZIP。归档中有清单，并按账本组织账户、联系人、分类、预算、预算规则与流水；流水还支持按月份分卷。源码保留了对旧式单 JSON 备份的读取逻辑，因此排查恢复问题时应先确认文件格式，而不是把任意 JSON 都当成有效账本。

本机滚动备份使用 OPFS，保留日、周、月等层次的快照。它仍与浏览器管理的本地存储有关，换设备时需要另行迁移，不能把"有本机快照"理解成远端已经有一份可恢复副本。

恢复操作有覆盖确认，底层也存在清空并重写相关数据表的路径。迁移前应先备份目标环境已有记录，并阅读界面中的恢复范围；不要在唯一一份正式账本上反复试错。

自建实例可使用环境变量配置 Dropbox App Key。项目使用 PKCE 授权流程，示例文件给出的是 Client ID，不需要把客户端密钥硬塞进前端配置。

在项目根目录的环境配置中设置：

dotenv 复制代码

VITE_DROPBOX_APP_KEY=你的DropboxAppKey

按示例选择 Scoped access 和 App folder。授权回调由当前站点来源与 /settings 组成，登记时应与实际访问的协议、域名及端口对应。开发端口改变后，旧回调也需要重新核对，不能只检查域名拼写。

Vite 的前端环境配置会进入构建过程。修改后重新启动开发服务；生产部署则重新构建并替换产物。若页面仍提示未配置，检查当前运行的是哪份构建，以及环境变量是否放在正确的项目根目录。

随后进入设置中的 Dropbox 同步，完成连接，分别查看连接状态、上次同步时间与端到端加密状态。同步对话框单独提供加密启用入口，不能把"Dropbox 已连接"当成"E2EE 已开启"。

启用加密时，应用要求设置并确认口令，随后显示恢复密钥。保存恢复资料，再验证第二台设备能读取预期账本。PIN 应用锁控制本机入口，Dropbox 授权控制云端访问，加密口令用于账本加密，三者不应混用。

建议先用测试账本验证，而不是一上来导入全部历史账目。创建两个账户，记录一笔收入、一笔支出和一笔转账，保存金额与日期，作为之后核对的参照。

刷新后看记录是否仍在；切换月份，确认流水的日期归属；再打开报表，检查分类与金额是否符合这组输入。做转账测试时，应查看两个账户，不能只盯着首页净结余。

导出备份后，在独立浏览器配置中恢复，核对账本数量、账户币种、余额及最近流水。需要同步的部署再补第二设备验证，同时看同步时间和加密状态。最后把地址、备份文件和恢复资料各自保存好，后续升级才有可以对照的基础。

这个项目采用 AGPL-3.0，源码中的许可与版权文件应保留。它适合愿意维护一个浏览器应用的人；若需求是下载后双击安装的本机程序，这份源码包并不是同一种交付形态。

v1.0.0 源码包：