首页/ 文档/ 日常管理

日常管理

BestNav 是纯本地数据架构：书签、配置、账户与加密密钥全部保存在 ./data 目录。管好这一个目录，就管好了全部数据——本文讲清备份、恢复、升级与迁移的正确姿势。

6 个小节 · 约 8 分钟读完

数据都存在哪里

Docker 版数据保存在命名卷 bestnav_data 中（挂载于容器内 /app/data，无需外部数据库），可用 docker volume inspect bestnav_data 查看宿主机实际路径；飞牛 fpk / 群晖 SPK 等非容器部署的数据目录由安装时指定。目录内的关键内容：

  • settings.json / auth.json：书签卡片配置、主题外观、用户表与密码哈希
  • integrations / ssl_monitors / webhooks：集成卡片凭据、SSL 监控、通知配置
  • backups/：内置备份产出（JSON 与 zip）
  • file_index.db：本地文件搜索的 SQLite 索引（可重建，非原始数据）
  • .secrets：加密密钥（JWT 会话 / 本地 API Key 加密 / 授权验签），只存在于你的服务器

.secrets 丢失 = 已加密保存的 API Key / 密码 / 凭据永久无法解密，任何备份方案都必须包含它。

三重备份策略

由轻到重三层，按需叠加：

  • ① 内置备份（免费）：「设置 → 数据 → 创建备份」一键打包账户、书签、卡片与集成配置、加密密钥，以及 AI 中转站的供应商配置、已分发令牌与逐条账本的一致性快照；可附加文字传输、分享记录与上传文件，导出为单个 zip，上传回来即可完整复原。JSON 备份保留最近 7 份、文件类 zip 各保留 3 份，支持下载存档
  • ② 定时自动备份（Pro）：按 6 / 12 / 24 / 72 / 168 小时间隔后台自动备份到 data/backups，无需人工记忆；面板中可查看上次执行时间与状态，也可随时「立即备份」
  • ③ WebDAV 异地备份（Pro）：把配置备份推送到坚果云 / Nextcloud 等 WebDAV 存储，设备整机损坏也能恢复；写失败时按状态码给出可读诊断（附实际上传目标与当前备份目录），不再只回一个 405/403

服务器层面还可加一道兜底：定时打包整个数据卷（crontab 示例，每天 3:30 执行、保留 7 天）：

Bash# /opt/bestnav/backup.sh docker run --rm -v bestnav_data:/data -v /opt/backups:/backup alpine \ tar -czf /backup/bestnav-data-$(date +%F).tar.gz -C /data . find /opt/backups -name "bestnav-data-*.tar.gz" -mtime +7 -delete # crontab -e 添加： 30 3 * * * /bin/bash /opt/bestnav/backup.sh

备份文件含密码哈希与密钥，权限为 0600——不要把 backups/ 目录暴露到 Web 或他人可读的位置。

你的数据① 内置备份（手动 zip）② 定时自动备份（Pro）③ WebDAV 异地（Pro）恢复入口data/ 一个目录装全部上传备份文件即可复原
图：三层备份由轻到重、可叠加——内置备份管日常，定时备份管忘记，异地备份管整机损坏；三层产物都能回到同一个恢复入口。
  • 备份打包时遇到正在被删除或读不到的文件会跳过并记日志，其余内容照常成包——不再因为一个文件读不到就让整次备份失败
  • 上传文件目录为空时产出的 0 条目 zip 是合法备份，不会被判为损坏
  • 定时备份在面板里能看到上次执行时间与状态，也可随时「立即备份」，不用等下一个周期

恢复备份

在「设置 → 数据」的备份列表点击「恢复」，或直接上传外部备份文件（JSON / zip）恢复；恢复前系统会要求二次确认。

  • 恢复会覆盖当前同名配置，请先为现状「创建备份」留一条回退路
  • 恢复含密钥的备份后，现有登录态可能失效，重新登录即可
  • 整卷灾难恢复：停止服务 → docker run --rm -v bestnav_data:/data -v /opt/backups:/backup alpine sh -c "cd /data && tar xzf /backup/<备份包>" → 启动服务

版本升级

镜像版升级 = 拉取新镜像并重建容器，命名卷数据全程不动：

Bashcd ~/bestnav # 1. 先备份数据（设置 → 数据 → 创建备份，或用上方脚本打包数据卷） # 2. 拉取新镜像并重建容器 docker compose pull && docker compose up -d # 3. 验证 curl -s http://127.0.0.1:10788/api/health
  • compose 中 image 锁定了具体版本号时，先把它改为新版号或 latest 再 pull
  • 从旧版 tar.gz 挂载方式（模型 A）升级：先把旧容器挂载目录中的数据拷入新命名卷（docker cp 或临时 alpine 容器）再启动
  • 飞牛 fnOS 版：在飞牛应用中心更新（数据保留）；或替换应用目录内 server/bestnav 后执行 sudo systemctl restart bestnav
  • 群晖 SPK 直装版：从官网下载新版 SPK，在套件中心「手动安装」直接覆盖升级，数据与配置自动保留，无需卸载
  • 群晖 Container Manager / 威联通 / 极空间（容器版）：与上方 Docker 版步骤相同

跨大版本升级请先阅读发布说明中的「破坏性变更」；升级后若有异常，可用「设置 → 数据」恢复升级前备份。

迁移到新设备

迁移的本质是搬运数据（必须含 .secrets）。推荐用内置备份 zip 搬运，跨平台最省心：

  • 旧设备：停止服务，「设置 → 数据 → 创建备份」导出 zip（或用备份脚本打包命名卷）并传输
  • 新设备：按「安装部署」启动新版容器，在「设置 → 数据 → 恢复」导入 zip
  • 整卷搬迁：docker run --rm -v 新卷:/data -v /path/to/backup:/backup alpine sh -c "cd /data && tar xzf /backup/<备份包>"
  • 启动并验证：docker compose up -d 后先做恢复性检查再切流量
  • 按新环境更新 PUBLIC_URL 与反向代理；防火墙 / 安全组放行端口

Pro 授权与设备硬件指纹绑定：同机重装系统后重新激活会自动恢复授权；更换设备暂不支持换绑，需重新购买授权；如有特殊情况可联系客服咨询。

日常巡检清单

  • 容器健康：docker compose ps 应为 healthy/up；本地 curl http://127.0.0.1:10788/api/health 应返回成功
  • 磁盘空间：关注 ./data 体积变化，重点是被备份 zip、上传背景图与文件索引占用的空间
  • 数据卷可写：页面报错或无法登录时，确认数据卷权限（命名卷已预置 uid 1000 属主；自行改用 bind 挂载时需 chown 1000:1000）
  • 端口冲突：修改 compose ports 或更换主机端口后需重建容器
  • 搜索无结果：文件搜索索引可重建（设置 → 数据 → 重建索引），索引丢失不是数据丢失

查看各平台日志、找回管理员密码、加密密钥详解，请移步 问题排查与运维。

控制台 Docker 与服务与 SSL 监控截图
图：巡检在控制台一屏完成——上方是容器清单与资源占用，下方是服务与 SSL 监控的在线状态与响应耗时。

Where Your Data Lives

Docker keeps data in the named volume bestnav_data (mounted at /app/data, no external database); run docker volume inspect bestnav_data to find the host path. Native installs (fnOS fpk / Synology SPK) use the data dir chosen at install time. Key contents:

  • settings.json / auth.json: bookmark & card config, themes, user table and password hashes
  • integrations / ssl_monitors / webhooks: integration credentials, SSL monitors, notification config
  • backups/: built-in backup output (JSON & zip)
  • file_index.db: SQLite index for local file search (rebuildable, not source data)
  • .secrets: encryption keys (session JWT / local API-key encryption / license signing) — only on your server

Lose .secrets and every locally encrypted API key / password / credential becomes permanently undecryptable — include it in every backup.

Three Layers of Backup

Stack these three layers as needed:

  • 1) Built-in backup (free): Settings → Data → Create Backup packs accounts, bookmarks, cards, integration settings, encryption keys, plus the relay providers, issued tokens and a consistent snapshot of the request ledger in one click; optionally add texts, shares and uploaded files into a single zip that fully restores on re-upload. JSON backups keep the last 7, each file-based zip keeps 3, all downloadable
  • 2) Scheduled auto backup (Pro): automatic backups to data/backups every 6 / 12 / 24 / 72 / 168 hours, with last-run status and a Run Now button
  • 3) WebDAV offsite backup (Pro): push config backups to Jianguoyun / Nextcloud-style WebDAV storage — recover even after total device failure; when a write fails the message names the HTTP status, the actual upload target and your current backup folder instead of a bare 405/403

Add a server-level safety net by tarring the whole data volume on a schedule (daily at 3:30, keep 7 days):

Bash# /opt/bestnav/backup.sh docker run --rm -v bestnav_data:/data -v /opt/backups:/backup alpine \ tar -czf /backup/bestnav-data-$(date +%F).tar.gz -C /data . find /opt/backups -name "bestnav-data-*.tar.gz" -mtime +7 -delete # crontab -e: 30 3 * * * /bin/bash /opt/bestnav/backup.sh

Backups contain password hashes and keys (file mode 0600) — never expose backups/ over the Web or to other users.

Your data1) Built-in backup (zip)2) Scheduled backup (Pro)3) WebDAV off-site (Pro)Restore entryeverything lives in data/upload a backup to restore
Diagram: the three layers stack — built-in for daily use, scheduled for when you forget, off-site for when the box dies; all three feed the same restore entry.
  • If a file disappears or cannot be read mid-pack it is skipped and logged while the rest of the backup still completes — one unreadable file no longer fails the whole run
  • A zip with zero entries from empty upload folders is a valid backup, not a corrupt one
  • Scheduled backups show their last run time and status in the panel, and Run Now is always available when you do not want to wait for the next cycle

Restoring

Click Restore in the Settings → Data backup list, or upload an external JSON / zip backup; a confirmation step is required first.

  • Restore overwrites current config — create a fresh backup of the present state first as a rollback
  • After restoring a backup that contains keys, existing sessions may expire; just sign in again
  • Full-volume disaster recovery: stop the service → docker run --rm -v bestnav_data:/data -v /opt/backups:/backup alpine sh -c "cd /data && tar xzf /backup/" → start again

Upgrading

Image upgrade = pull the new image and recreate the container. The named volume is never touched:

Bashcd ~/bestnav # 1. back up first (Settings → Data → Create Backup, or the volume script above) # 2. pull the new image and recreate docker compose pull && docker compose up -d # 3. verify curl -s http://127.0.0.1:10788/api/health
  • If image: pins a specific version tag, bump it (or use latest) before pulling
  • Upgrading from the legacy tar.gz layout (Model A): copy data from the old mounted dir into the new named volume (docker cp or a temporary alpine container) first
  • fnOS: update in the fnOS App Center (data preserved), or replace server/bestnav in the app dir and run sudo systemctl restart bestnav
  • Synology SPK: download the new SPK from the site and manual-install it in Package Center — it upgrades in place and keeps your data, no uninstall needed
  • Synology Container Manager / QNAP / ZSpace (container): same as the Docker steps above

For major versions, read the breaking-changes notes first; if anything looks off after upgrading, restore the pre-upgrade backup from Settings → Data.

Migrating to a New Device

Migration is really just moving your data (must include .secrets). The built-in backup zip is the easiest cross-platform way:

  • Old device: stop the service, export a zip via Settings → Data → Create Backup (or tar the named volume) and transfer it
  • New device: start the new container per Installation, then import the zip via Settings → Data → Restore
  • Whole-volume move: docker run --rm -v :/data -v /path/to/backup:/backup alpine sh -c "cd /data && tar xzf /backup/"
  • Start and verify health before switching traffic
  • Update PUBLIC_URL and the reverse proxy; open the port in firewall / security groups

Pro licenses bind to a hardware fingerprint: re-activating on the same machine after an OS reinstall restores automatically; device changes require contacting support.

Routine Checks

  • Health: docker compose ps should show healthy/up; curl http://127.0.0.1:10788/api/health should succeed
  • Disk: watch ./data growth — backup zips, uploaded backgrounds and the file index are the main consumers
  • Volume writable: if pages error or login fails, check volume permissions (the named volume ships with uid 1000 ownership; for bind mounts chown 1000:1000 the host dir)
  • Port conflict: change compose ports, then recreate the container
  • No search results: the file index is rebuildable (Settings → Data → Rebuild Index) — index loss is not data loss

For per-platform logs, admin password reset and the encryption-key deep dive, see Troubleshooting & Ops.

Console Docker and service/SSL monitoring screenshot
Diagram: the daily sweep fits one Console screen — containers and their resource use on top, service and SSL monitoring with online state and response times below.