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。同一天多次备份会覆盖同一文件。
备份步骤
- 在「设置」里配好备份目标(WebDAV、OneDrive、阿里云盘或和彩云,见下)。
- 点「立即备份」。成功后会弹出提示,包含文件名和大小。
- 建议定期备份,尤其是在修改密码或导入大量内容之前。
恢复步骤
- 在「设置」里选择备份来源:WebDAV(输入文件名)或 OneDrive / 阿里云盘 / 和彩云(从备份列表里选一个)。
- 点「从备份恢复」,输入备份时的主密码(如果之后改过密码,这里填旧密码)。
- 恢复会把备份里的笔记本、笔记、标签和附件导入当前数据库,原有内容不受影响;同名内容会并存,不会覆盖。
二、OneDrive 设置(Azure 应用注册)
OneDrive 备份需要你用自己的微软帐户在 Azure 门户注册一个应用——这是微软的要求,注册免费,应用只属于你自己。本应用不会替你注册,你需要按下面步骤手动完成一次,以后就不用再管了。
第 1 步:新建应用注册
- 打开
portal.azure.com,用你的个人 Microsoft 帐户登录。 - 进入「Microsoft Entra ID」(也叫 Azure Active Directory)→ 左侧「应用注册」→「新注册」。
- 「名称」随便填,例如
jotbox(这个名字会出现在 OneDrive 的Apps/文件夹里)。 - 「受支持的帐户类型」选择 「仅个人 Microsoft 帐户」(Accounts in any organizational directory…不要选)。
- 「重定向 URI」:平台选 「单页应用程序 (SPA)」,地址填本应用的完整地址(浏览器地址栏里显示的地址,例如
https://jotbox.pages.dev/)。必须与地址栏完全一致,包括末尾的斜杠;平台一定要选 SPA,选成“Web”会导致登录后换令牌失败。 - 点「注册」。
第 2 步:复制应用程序(客户端) ID
- 注册成功后,在应用的「概述」页找到「应用程序(客户端) ID」(一串 GUID)。
- 把它复制到 jotbox「设置 → OneDrive 设置」里的「Client ID」一栏,点保存。
- 不需要创建客户端密码(client secret)。本应用是公共客户端,使用 PKCE 授权码流程,不用、也不应生成 secret。
第 3 步:添加 API 权限
- 在应用注册页左侧点「API 权限」→「添加权限」→「Microsoft Graph」→「委托的权限」。
- 搜索并勾选
Files.ReadWrite.AppFolder(读写应用文件夹),点「添加权限」。 - 个人帐户不需要管理员同意,登录授权时你本人点「同意」即可。
offline_access是标准权限,登录时一并授权,不用单独添加。
第 4 步:在应用里连接
- 回到 jotbox「设置 → OneDrive 设置」,点「连接 OneDrive」。
- 浏览器会跳转到 Microsoft 登录页:登录并确认授权(应用只能访问它自己的文件夹)。
- 授权后会自动跳回 jotbox,显示已连接。之后点「立即备份」即可;备份文件会出现在你 OneDrive 的
Apps/jotbox/文件夹里(文件夹名取自你在 Azure 填的应用名称)。
jb_onedrive_tokens),不会发给 jotbox 服务器。令牌过期后应用会自动用刷新令牌续期;点「断开连接」会清除本地令牌。如需彻底撤销授权,请到 account.microsoft.com 的「隐私 → 应用和服务」里移除该应用。令牌只能读写应用专属文件夹,即使泄露也看不到你网盘的其他内容,但仍请不要在公共电脑上保持连接状态。
常见问题
- 登录时报错 AADSTS50011(重定向 URI 不匹配):Azure 里填的重定向 URI 与当前应用地址不一致。请回到应用注册 →「身份验证」,把 SPA 重定向 URI 改成浏览器地址栏里的完整地址(注意末尾斜杠)。
- 换令牌时被浏览器报 CORS 错误:重定向 URI 的平台选错了(选成了 Web)。改成「单页应用程序 (SPA)」即可。
- 备份文件超过 4 MiB 时上传失败:这是 OneDrive 简单上传的限制。当前版本不支持分块上传,请改用 WebDAV 备份,或用「导出 JSON 备份」下载后手动上传到 OneDrive。
- 提示授权已过期:刷新令牌失效时会出现,点「断开连接」后再重新连接即可。
三、WebDAV 设置
- 在「设置 → WebDAV 设置」里填写服务器地址(例如你的 NAS 或网盘的 WebDAV 地址,须以
http://或https://开头)、用户名和密码。 - 点「测试连接」:成功会显示 HTTP 状态码;失败请检查地址、用户名、密码,以及服务器是否允许 PROPFIND 请求。
- 点「立即备份」上传;恢复时输入备份文件名(例如
jotbox-backup-20261117.json),点「从 WebDAV 恢复」。
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 备份文件,需要输入备份时的主密码。 |
五、令牌与数据存储说明
- 登录会话令牌存在 sessionStorage(键名
jb_token),关闭浏览器标签页即失效,有效期 24 小时。 - 主密码从不离开浏览器,也从不存储;服务器只存密码验证器(单向派生值),无法反推出密码。环境变量模式下,登录时浏览器发送密码的 SHA-256 摘要给服务器校验,密码明文仍不离开浏览器;但服务器通过环境变量持有密码本身,见第六节。
- WebDAV:地址+用户名存 localStorage(
jb_webdav);密码默认不存,勾选「记住密码」才存(jb_webdav_pw)。 - OneDrive:Client ID 存 localStorage(
jb_onedrive);访问令牌+刷新令牌存 localStorage(jb_onedrive_tokens)。 - 备份文件是加密 JSON,只有用备份时的主密码才能解密;JEX / Markdown 导出是明文。
- 清理浏览器数据(localStorage)会丢失已保存的 WebDAV / OneDrive 设置和令牌,但不会影响服务器上的笔记(重新登录即可);OneDrive 断开后重新连接即可继续使用。
六、主密码:环境变量设置(MASTER_PASSWORD)
默认情况下,主密码在首次打开应用时设置,验证器存在数据库里。也可以改用 Cloudflare 环境变量 MASTER_PASSWORD 来配置主密码——密码存在 Cloudflare Dashboard 里,数据库即使被清空也能用同一密码重新登录,容错更高。
设置步骤
- 登录 Cloudflare Dashboard → Pages → jotbox → Settings → Environment variables → Production。
- 添加变量
MASTER_PASSWORD,类型选 Secret,值填你的主密码,保存。 - 重新部署一次(Deployments → 最新部署 → ⋯ → Retry deployment,或推一次新部署):环境变量改动只在下次部署生效,不重新部署不会生效。
- 重新打开应用,直接用该密码登录即可(首次登录时应用会自动完成初始化)。
修改密码(环境变量模式)
- 在 Dashboard 把
MASTER_PASSWORD改成新值,保存。 - 重新部署一次。
- 用新密码登录:登录会成功,但数据仍用旧密码加密,应用会提示你输入一次旧密码做迁移。
- 按提示输入旧密码验证(验证是只读的,不改任何数据);建议先导出一份 JSON 备份;然后点「开始重新加密」,应用会把全部数据(笔记本、笔记、标签、附件)用新密码重新加密。
- 迁移完成后,全部 Agent Token 失效,需重新生成。
删除环境变量
在 Dashboard 删除 MASTER_PASSWORD 并重新部署后,应用会回到数据库验证器模式:首次登录时应用已自动保存了一个备用验证器,删除变量后仍可用同一密码登录(前提是删除前至少成功登录过一次)。
两种模式的权衡
| 模式 | 优点 | 注意 |
|---|---|---|
| 数据库验证器(默认) | 密码只存在你脑子里,服务器和 Dashboard 都不知道密码 | 忘记密码无法找回;数据库被清空后需重新设置 |
| 环境变量 | 密码存在 Dashboard,可查看可找回;数据库清空后同一密码仍能登录 | 能登录 Cloudflare Dashboard 的人也就知道了主密码;修改密码需走 Dashboard + 重新部署 + 迁移三步 |
无论哪种模式,加密方式不变:密钥始终由你在浏览器里输入的密码经 PBKDF2 派生,数据在浏览器端加密后才上传,数据库里只有密文。
七、双数据库备份
系统默认开启双数据库模式:同步库(jotbox-db)是实时数据库,备份库(jotbox-backup-db)是它的全量副本。一个定时任务每 6 小时自动把同步库的全部数据复制到备份库,只复制密文(服务器不解密),无需你做任何配置。
在「设置 → 双数据库备份」里可以看到两个库名和上次备份的时间、来源(自动/手动)与状态,也可以点「立即备份」手动触发一次复制。
从备份库恢复
- 在「设置 → 双数据库备份」里点「从备份库恢复」,二次确认后,备份库的内容会完全覆盖同步库——备份之后的新增和修改会丢失。恢复前建议先导出一份 JSON 备份。
- 如果备份后没有改过密码,恢复后可直接继续使用,当前会话不受影响。
- 如果备份后改过密码,恢复会把密码验证器还原成备份时的旧值:当前会话立即失效,需要用备份时的密码重新登录。
八、阿里云盘设置(开放平台 OAuth)
阿里云盘备份走官方开放平台,需要你先注册一个开发者应用——本应用不会替你注册,你需要按下面步骤手动完成一次,以后就不用再管了。
第 1 步:注册开发者应用
- 打开阿里云盘开放平台(
open.aliyundrive.com),用你的阿里云盘账号登录,创建一个应用。注意:据社区反馈,该注册页面偶尔会返回 500 错误,如打不开请稍后再试或换个浏览器。 - 创建应用时记下
Client ID和Client Secret。Client Secret 只显示一次,请妥善保存。
第 2 步:在应用里授权
- 在「设置 → 阿里云盘备份」里填入 Client ID 和 Client Secret,点「保存凭据」。
- 点「打开授权页」,在新标签页登录阿里云盘并选择一个文件夹授权(应用只能读写你选的文件夹;备份会放在该文件夹下的
jotbox子文件夹里,所以请选择根目录或一个你愿意放备份的文件夹)。 - 授权页会直接显示一串授权码(code),把它复制回来粘贴到「授权码」输入框,点「完成授权」。授权码有效期 10 分钟,只能用一次;过期了就重新打开授权页拿一个。
- 状态显示「已连接」后,就可以点「立即备份」了。
常见问题
- 提示"请重新授权":refresh_token 有效期 90 天,超过后需要重新走一遍授权流程(第 2 步)。正常使用时每次备份都会自动刷新 token,不会过期。
- 提示"授权码无效":授权码 10 分钟过期且只能用一次,请重新打开授权页拿一个新的。
- 找不到备份文件:备份在授权时选的文件夹下的
jotbox子文件夹里;如果授权时选了某个子文件夹,备份就在它下面。
九、和彩云设置(中国移动云盘)
和彩云登录需要短信验证,应用无法替你登录。你需要先在浏览器登录和彩云,把登录凭证复制给应用:
获取 Authorization
- 在浏览器打开
yun.139.com并登录你的和彩云账号。 - 按
F12打开开发者工具,切换到「网络」(Network)标签。 - 刷新页面,在请求列表里点任意一个
yun.139.com的请求(例如file/list),在右侧「请求标头」里找到Authorization,复制它的值。 - 回到 jotbox,在「设置 → 和彩云备份」里把值粘贴到 Authorization 输入框(
Basic前缀可以不粘,粘了也没关系),点「保存 Authorization」。保存时会校验格式,格式不对会提示重新复制。 - 状态会显示 Authorization 的有效期。有效期不足 15 天时,每次备份/列出/下载都会自动刷新凭证并保存新值;如果已经过期,无法自动刷新,需要重新登录和彩云并粘贴新的 Authorization。
常见问题
- 提示"Authorization 已过期":按上面步骤重新登录 yun.139.com 并粘贴新的 Authorization。
- 提示"格式不对":请确认复制的是请求头里
Authorization的完整值(很长的一串 base64),不要只复制一部分,也不要复制成 Cookie。 - 备份失败但其他网盘正常:可能是和彩云接口变动。先试试重新粘贴 Authorization;如果还是失败,说明接口已变,需要等应用适配,期间请用其他备份方式。