首页/ 文档/ 日常管理

日常管理

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

数据都存在哪里

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 / 密码 / 凭据永久无法解密，任何备份方案都必须包含它。

三重备份策略

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

  • ① 内置备份（免费）：「设置 → 数据 → 创建备份」一键打包账户、书签、卡片与集成配置、加密密钥等全部核心数据；可附加文字传输、分享记录与背景图，导出为单个 zip，上传回来即可完整复原。备份保留最近 7 份，支持下载存档
  • ② 定时自动备份（Pro）：按 6 / 12 / 24 / 72 / 168 小时间隔后台自动备份到 data/backups，无需人工记忆；面板中可查看上次执行时间与状态，也可随时「立即备份」
  • ③ WebDAV 异地备份（Pro）：把配置备份推送到坚果云 / Nextcloud 等 WebDAV 存储，设备整机损坏也能恢复

服务器层面还可加一道兜底：定时打包整个数据卷（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 或他人可读的位置。

恢复备份

在「设置 → 数据」的备份列表点击「恢复」，或直接上传外部备份文件（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 或更换主机端口后需重建容器
  • 搜索无结果：文件搜索索引可重建（设置 → 数据 → 重建索引），索引丢失不是数据丢失

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

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, integrations and encryption keys in one click; optionally add texts, shares and background images into a single zip that fully restores on re-upload. Keeps the last 7 copies, 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

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.

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.