← 返回应用

jotbox 帮助

jotbox 是单用户端到端加密笔记系统:笔记在浏览器里加密后才上传到服务器,服务器只存密文。备份文件同样是加密的 JSON,只有用当初备份时的密码才能恢复。

⚠️ 密码丢失警告

主密码只存在你的脑子里,服务器不知道它,也无法帮你找回。一旦忘记主密码,所有笔记和备份都将永久无法解密,没有任何找回途径。请务必把主密码记在安全的地方(例如密码管理器或纸质记录)。修改密码后,旧备份仍需用旧密码才能恢复。

如果主密码改由 Cloudflare 环境变量 MASTER_PASSWORD 配置(见第六节),密码本身存在 Cloudflare Dashboard 里(你可以在 Dashboard 看到并找回它,容错更高),但相应地,能登录 Dashboard 的人也就知道了主密码;服务器同样不存明文,数据仍在浏览器端加密。两种模式的利弊见第六节。

一、备份与恢复总览

应用内置四种备份目标,都在「设置」里配置;此外还有默认开启的双数据库备份(见第七节):

目标说明
WebDAV备份到你自己的 WebDAV 服务器(NAS、自建服务或支持 WebDAV 的网盘)。应用通过同源中继代发请求,密码不会被记录。
OneDrive备份到你的个人 OneDrive 的应用专属文件夹(Apps/<应用名>/)。应用只能读写这个文件夹,看不到网盘里的其他文件。需要你先在 Azure 注册一个应用(免费,见第二节)。
阿里云盘备份到阿里云盘根目录下的 jotbox 文件夹。官方开放平台 OAuth 授权,需要你先在开放平台注册开发者应用(见第八节)。
和彩云备份到和彩云(中国移动云盘)根目录下的 jotbox 文件夹。需要你从浏览器 DevTools 复制 Authorization 粘贴到设置里(见第九节)。注意:和彩云没有官方开放接口,本功能用的是逆向的网页接口,接口变动可能导致备份失效,请同时用其他备份。

备份文件是加密 JSON,文件名形如 jotbox-backup-20261117.json。同一天多次备份会覆盖同一文件。

备份步骤

  1. 在「设置」里配好备份目标(WebDAV、OneDrive、阿里云盘或和彩云,见下)。
  2. 点「立即备份」。成功后会弹出提示,包含文件名和大小。
  3. 建议定期备份,尤其是在修改密码或导入大量内容之前。

恢复步骤

  1. 在「设置」里选择备份来源:WebDAV(输入文件名)或 OneDrive / 阿里云盘 / 和彩云(从备份列表里选一个)。
  2. 点「从备份恢复」,输入备份时的主密码(如果之后改过密码,这里填旧密码)。
  3. 恢复会把备份里的笔记本、笔记、标签和附件导入当前数据库,原有内容不受影响;同名内容会并存,不会覆盖。
恢复需要先解锁应用(登录状态),且备份文件里的附件会重新加密后上传;附件较多时请耐心等待。

二、OneDrive 设置(Azure 应用注册)

OneDrive 备份需要你用自己的微软帐户在 Azure 门户注册一个应用——这是微软的要求,注册免费,应用只属于你自己。本应用不会替你注册,你需要按下面步骤手动完成一次,以后就不用再管了。

第 1 步:新建应用注册

  1. 打开 portal.azure.com,用你的个人 Microsoft 帐户登录。
  2. 进入「Microsoft Entra ID」(也叫 Azure Active Directory)→ 左侧「应用注册」→「新注册」。
  3. 「名称」随便填,例如 jotbox(这个名字会出现在 OneDrive 的 Apps/ 文件夹里)。
  4. 「受支持的帐户类型」选择 「仅个人 Microsoft 帐户」(Accounts in any organizational directory…不要选)。
  5. 「重定向 URI」:平台选 「单页应用程序 (SPA)」,地址填本应用的完整地址(浏览器地址栏里显示的地址,例如 https://jotbox.pages.dev/)。必须与地址栏完全一致,包括末尾的斜杠;平台一定要选 SPA,选成“Web”会导致登录后换令牌失败。
  6. 点「注册」。

第 2 步:复制应用程序(客户端) ID

  1. 注册成功后,在应用的「概述」页找到「应用程序(客户端) ID」(一串 GUID)。
  2. 把它复制到 jotbox「设置 → OneDrive 设置」里的「Client ID」一栏,点保存。
  3. 不需要创建客户端密码(client secret)。本应用是公共客户端,使用 PKCE 授权码流程,不用、也不应生成 secret。

第 3 步:添加 API 权限

  1. 在应用注册页左侧点「API 权限」→「添加权限」→「Microsoft Graph」→「委托的权限」。
  2. 搜索并勾选 Files.ReadWrite.AppFolder(读写应用文件夹),点「添加权限」。
  3. 个人帐户不需要管理员同意,登录授权时你本人点「同意」即可。offline_access 是标准权限,登录时一并授权,不用单独添加。

第 4 步:在应用里连接

  1. 回到 jotbox「设置 → OneDrive 设置」,点「连接 OneDrive」。
  2. 浏览器会跳转到 Microsoft 登录页:登录并确认授权(应用只能访问它自己的文件夹)。
  3. 授权后会自动跳回 jotbox,显示已连接。之后点「立即备份」即可;备份文件会出现在你 OneDrive 的 Apps/jotbox/ 文件夹里(文件夹名取自你在 Azure 填的应用名称)。
令牌存储说明:OneDrive 的访问令牌和刷新令牌只存在你本机浏览器的 localStorage 里(键名 jb_onedrive_tokens),不会发给 jotbox 服务器。令牌过期后应用会自动用刷新令牌续期;点「断开连接」会清除本地令牌。如需彻底撤销授权,请到 account.microsoft.com 的「隐私 → 应用和服务」里移除该应用。令牌只能读写应用专属文件夹,即使泄露也看不到你网盘的其他内容,但仍请不要在公共电脑上保持连接状态。

常见问题

三、WebDAV 设置

  1. 在「设置 → WebDAV 设置」里填写服务器地址(例如你的 NAS 或网盘的 WebDAV 地址,须以 http:// 或 https:// 开头)、用户名和密码。
  2. 点「测试连接」:成功会显示 HTTP 状态码;失败请检查地址、用户名、密码,以及服务器是否允许 PROPFIND 请求。
  3. 点「立即备份」上传;恢复时输入备份文件名(例如 jotbox-backup-20261117.json),点「从 WebDAV 恢复」。
密码存储说明:WebDAV 地址和用户名存在本机浏览器 localStorage(键名 jb_webdav)。密码默认不保存,每次备份/恢复都要重新输入;只有勾选「记住密码」时,密码才会存入本机 localStorage(键名 jb_webdav_pw),取消勾选或点「清除已记住的密码」即可删除。备份请求经应用服务器中继转发,中继不记录密码和请求内容。建议使用 HTTPS 的 WebDAV 地址。

四、导入与导出

在主界面的「导入/导出」菜单里:

功能说明
导出 JEX导出为 Joplin 交换格式(.jex,tar 包),可在 Joplin 里直接导入。内容是解密后的明文,请妥善保管导出的文件。
导出 Markdown按笔记本分文件夹导出 .md 文件(.tar 包),每篇笔记带 YAML front matter(标题、创建时间、更新时间、标签),附件随附在旁,适合归档或迁移到其他工具。内容是明文。
导出 JSON 备份导出加密 JSON 备份(与一键备份相同格式),下载到本地。恢复时需要备份时的主密码。
导入 JEX导入 Joplin 导出的 .jex 文件,或本应用导出的 JEX。笔记本、笔记、标签和附件会一并导入;资源通过笔记正文里的引用关联到笔记。
导入 Markdown导入本应用导出的 Markdown tar 包,或单个 .md 文件(导入为当前笔记本里的一篇笔记)。
导入 JSON 备份导入加密 JSON 备份文件,需要输入备份时的主密码。
注意:JEX 和 Markdown 导出的是明文内容,文件本身没有任何加密。不要把导出的文件发到不受信任的地方;用完请及时删除或加密保存。

五、令牌与数据存储说明

六、主密码:环境变量设置(MASTER_PASSWORD)

默认情况下,主密码在首次打开应用时设置,验证器存在数据库里。也可以改用 Cloudflare 环境变量 MASTER_PASSWORD 来配置主密码——密码存在 Cloudflare Dashboard 里,数据库即使被清空也能用同一密码重新登录,容错更高。

设置步骤

  1. 登录 Cloudflare Dashboard → Pages → jotbox → Settings → Environment variables → Production。
  2. 添加变量 MASTER_PASSWORD,类型选 Secret,值填你的主密码,保存。
  3. 重新部署一次(Deployments → 最新部署 → ⋯ → Retry deployment,或推一次新部署):环境变量改动只在下次部署生效,不重新部署不会生效。
  4. 重新打开应用,直接用该密码登录即可(首次登录时应用会自动完成初始化)。

修改密码(环境变量模式)

  1. 在 Dashboard 把 MASTER_PASSWORD 改成新值,保存。
  2. 重新部署一次。
  3. 用新密码登录:登录会成功,但数据仍用旧密码加密,应用会提示你输入一次旧密码做迁移。
  4. 按提示输入旧密码验证(验证是只读的,不改任何数据);建议先导出一份 JSON 备份;然后点「开始重新加密」,应用会把全部数据(笔记本、笔记、标签、附件)用新密码重新加密。
  5. 迁移完成后,全部 Agent Token 失效,需重新生成。
注意:迁移中途关闭页面是安全的——已迁移的部分用新密钥解密,剩余的仍用旧密钥,下次登录可断点续跑。但如果忘记旧密码,数据将无法迁移也无法解密(与普通模式下忘记密码一样)。应用内「设置 → 修改密码」在环境变量模式下不可用,请按上面步骤操作。

删除环境变量

在 Dashboard 删除 MASTER_PASSWORD 并重新部署后,应用会回到数据库验证器模式:首次登录时应用已自动保存了一个备用验证器,删除变量后仍可用同一密码登录(前提是删除前至少成功登录过一次)。

两种模式的权衡

模式优点注意
数据库验证器(默认)密码只存在你脑子里,服务器和 Dashboard 都不知道密码忘记密码无法找回;数据库被清空后需重新设置
环境变量密码存在 Dashboard,可查看可找回;数据库清空后同一密码仍能登录能登录 Cloudflare Dashboard 的人也就知道了主密码;修改密码需走 Dashboard + 重新部署 + 迁移三步

无论哪种模式,加密方式不变:密钥始终由你在浏览器里输入的密码经 PBKDF2 派生,数据在浏览器端加密后才上传,数据库里只有密文。

七、双数据库备份

系统默认开启双数据库模式:同步库(jotbox-db)是实时数据库,备份库(jotbox-backup-db)是它的全量副本。一个定时任务每 6 小时自动把同步库的全部数据复制到备份库,只复制密文(服务器不解密),无需你做任何配置。

在「设置 → 双数据库备份」里可以看到两个库名和上次备份的时间、来源(自动/手动)与状态,也可以点「立即备份」手动触发一次复制。

从备份库恢复

  1. 在「设置 → 双数据库备份」里点「从备份库恢复」,二次确认后,备份库的内容会完全覆盖同步库——备份之后的新增和修改会丢失。恢复前建议先导出一份 JSON 备份。
  2. 如果备份后没有改过密码,恢复后可直接继续使用,当前会话不受影响。
  3. 如果备份后改过密码,恢复会把密码验证器还原成备份时的旧值:当前会话立即失效,需要用备份时的密码重新登录。
双数据库备份保护的是数据库本身(误删、损坏、误操作覆盖);它与 WebDAV / OneDrive / 阿里云盘 / 和彩云备份互补——后者把加密备份文件存到你自己的网盘,即使 Cloudflare 账号出问题也能恢复。建议两者都用。

八、阿里云盘设置(开放平台 OAuth)

阿里云盘备份走官方开放平台,需要你先注册一个开发者应用——本应用不会替你注册,你需要按下面步骤手动完成一次,以后就不用再管了。

第 1 步:注册开发者应用

  1. 打开阿里云盘开放平台(open.aliyundrive.com),用你的阿里云盘账号登录,创建一个应用。注意:据社区反馈,该注册页面偶尔会返回 500 错误,如打不开请稍后再试或换个浏览器。
  2. 创建应用时记下 Client ID 和 Client Secret。Client Secret 只显示一次,请妥善保存。

第 2 步:在应用里授权

  1. 在「设置 → 阿里云盘备份」里填入 Client ID 和 Client Secret,点「保存凭据」。
  2. 点「打开授权页」,在新标签页登录阿里云盘并选择一个文件夹授权(应用只能读写你选的文件夹;备份会放在该文件夹下的 jotbox 子文件夹里,所以请选择根目录或一个你愿意放备份的文件夹)。
  3. 授权页会直接显示一串授权码(code),把它复制回来粘贴到「授权码」输入框,点「完成授权」。授权码有效期 10 分钟,只能用一次;过期了就重新打开授权页拿一个。
  4. 状态显示「已连接」后,就可以点「立即备份」了。

常见问题

Client Secret 和 refresh_token 只存在你自己的浏览器 localStorage 里,服务端不保存、不记录。换浏览器或清掉 localStorage 后需要重新授权。

九、和彩云设置(中国移动云盘)

⚠️ 和彩云没有官方开放接口,本功能用的是逆向的网页接口(参考开源项目 OpenList 的驱动),接口随时可能变动导致备份失效。OpenList 也表示该驱动基于遗留产品、不会主动维护。请务必同时用双数据库备份或其他网盘备份,不要只依赖和彩云。

和彩云登录需要短信验证,应用无法替你登录。你需要先在浏览器登录和彩云,把登录凭证复制给应用:

获取 Authorization

  1. 在浏览器打开 yun.139.com 并登录你的和彩云账号。
  2. 按 F12 打开开发者工具,切换到「网络」(Network)标签。
  3. 刷新页面,在请求列表里点任意一个 yun.139.com 的请求(例如 file/list),在右侧「请求标头」里找到 Authorization,复制它的值。
  4. 回到 jotbox,在「设置 → 和彩云备份」里把值粘贴到 Authorization 输入框(Basic 前缀可以不粘,粘了也没关系),点「保存 Authorization」。保存时会校验格式,格式不对会提示重新复制。
  5. 状态会显示 Authorization 的有效期。有效期不足 15 天时,每次备份/列出/下载都会自动刷新凭证并保存新值;如果已经过期,无法自动刷新,需要重新登录和彩云并粘贴新的 Authorization。

常见问题

Authorization 相当于你的和彩云登录凭证,只存在你自己的浏览器 localStorage 里,服务端不保存、不记录。请不要把它发给别人;换浏览器或清掉 localStorage 后需要重新粘贴。

← 返回应用