首页/ 文档/ 问题排查与运维

问题排查与运维

各版本如何查看日志、如何备份数据，以及管理员密码找回等高频运维问题。

各版本如何查看日志

BestNav 所有版本运行同一份 Go 程序，启动与运行日志均输出到标准输出（stdout），由各平台的启动方式负责收集：容器版由 Docker 引擎收集、飞牛版由 systemd-journald 收集、群晖 SPK 由启动脚本重定向写入数据目录下的 bestnav.log 文件。按平台查看方式如下：

  • Docker / 群晖 Container Manager / 威联通 / 极空间（容器版）：docker logs bestnav，或 docker logs -f bestnav 实时跟踪；只看报错：docker logs bestnav 2>&1 | grep "\[ERROR\]"
  • 群晖 SPK 直装版（非容器）：日志在文件 /var/packages/bestnav/target/data/bestnav.log，需用 root 查看：sudo tail -n 100 /var/packages/bestnav/target/data/bestnav.log；实时跟踪：sudo tail -f 同路径
  • 飞牛 fnOS 版：由 systemd 托管（服务名 bestnav，不是已废弃的 bestnav-direct），日志在 journal 不在文件目录。查看：journalctl -u bestnav -n 100 --no-pager；实时跟踪：journalctl -f -u bestnav
  • 排查 Pro 授权 / 插件加载问题（如长时间显示“Pro 功能正在加载中”）：在各自日志上 grep "\[Pro\]"，会直接给出具体失败原因

注意：应用数据目录下的 data/logs/ 只是启动脚本预建的空目录，BestNav 的程序日志不会写进去；飞牛版的启动日志只在 journalctl 中可见。若 systemctl 提示找不到单元，先确认服务名：ls /etc/systemd/system/ | grep bestnav（老版本残留的 bestnav-direct.service 可直接删除）。

如何备份数据

完整备份只需打包数据即可。Docker 版数据在命名卷 bestnav_data（用下方命令打包）；飞牛 fpk / 群晖 SPK 等非容器部署的数据目录由安装时指定（通常位于应用数据盘）。备份内容包含：书签与配置、用户与授权、license.json、auth.json、上传文件、自动备份，以及最关键的 .secrets（加密密钥文件）。

Bash# Docker 版示例：打包命名卷 bestnav_data docker run --rm -v bestnav_data:/data -v $PWD:/backup alpine \ tar -czf /backup/bestnav-data-$(date +%F).tar.gz -C /data . # 飞牛 / 群晖直装示例（目录以实际安装为准） tar -czf bestnav-data-$(date +%F).tar.gz -C /path/to/appdata data
  • .secrets 一旦丢失，已用其加密保存的本地 API Key / 密码 / 密钥将永久无法解密，务必一并备份
  • 也可在「设置 → 数据」中一键导出配置 JSON 作为补充
  • 建议定时脚本化备份（保留最近 7 天），并将备份复制一份到异地或云盘

迁移到新设备：停止旧服务 → 打包 data → 传输到新设备 → 解压到同名 data 目录 → 启动。恢复后 .secrets 与数据将完全一致。

管理员密码找回 / 重置

如果忘记了管理员（创始账号）登录密码，可在服务器上执行命令行重置，无需重装、不会丢失数据。子命令固定为 reset-password（不带任何前置减号），执行后交互式输入两次新密码即可。各平台命令：

Bash# Docker / 群晖 Container Manager / 威联通 / 极空间（官方镜像） docker exec -it bestnav /app/bestnav reset-password # 群晖 SPK 直装版（非容器；先切 root，二进制按架构自动选择，完成后把数据目录还给套件用户） sudo -i cd /var/packages/bestnav/target DATA_DIR=./data ./server/bestnav-linux-$(uname -m | grep -qE "aarch64|arm64" && echo arm64 || echo amd64) reset-password chown -R bestnav data # 飞牛 fnOS 版（二进制在应用目录内，路径从 systemd 单元自动获取） BIN=$(grep ^ExecStart= /etc/systemd/system/bestnav.service | cut -d= -f2) sudo systemctl stop bestnav sudo "$BIN" reset-password sudo systemctl start bestnav
  • 子命令必须写成 reset-password——带减号的 -reset-password / --reset-password 不会被识别，会被当作正常启动处理
  • 飞牛 fpk 与群晖 SPK 的二进制不在 /usr/local/bin（旧文档命令已废弃），请按上方真实路径执行
  • 飞牛的服务单元是 /etc/systemd/system/bestnav.service、服务名 bestnav；老版本的 bestnav-direct.service 已废弃（若残留可 sudo systemctl disable --now bestnav-direct 后删除）
  • 飞牛执行时无需手动指定 DATA_DIR：reset-password 会自动读取 bestnav.service 里的工作目录与环境变量
  • 重置只改登录密码，不动书签、已保存的 API Key 与加密密钥（.secrets）
  • 找不到群晖二进制时先确认架构后缀：ls /var/packages/bestnav/target/server/
  • 普通成员密码由管理员在「设置 → 用户」中重置，无需命令行

加密密钥说明

首次启动时自动生成的 .secrets 包含多套密钥：JWT_SECRET（登录会话）、LICENSE_ENC_KEY（用于加密 / 解密你本地保存的 API Key、密码、密钥）、HMAC_SECRET（授权心跳验签）。它们只存在于你的服务器，BestNav 官方无法获取，也不会上传。

妥善保管 .secrets 与 data 目录备份。迁移或重装时务必先恢复 .secrets，否则已加密的凭据将无法使用。

View Logs per Platform

All BestNav editions run the same Go binary; startup and runtime logs go to stdout, collected differently per platform: the Docker engine for container editions, systemd-journald for fnOS, and a bestnav.log file in the data directory for the Synology SPK (redirected by its start script). How to view per platform:

  • Docker / Synology Container Manager / QNAP / ZSpace (container): docker logs bestnav, or docker logs -f bestnav to follow; errors only with docker logs bestnav 2>&1 | grep "\[ERROR\]"
  • Synology SPK (native install, NOT a container): logs live in /var/packages/bestnav/target/data/bestnav.log, view as root: sudo tail -n 100 /var/packages/bestnav/target/data/bestnav.log; follow with sudo tail -f on the same path
  • fnOS: managed by systemd under the service name bestnav (the retired name was bestnav-direct); logs live in the journal, NOT a file. View with journalctl -u bestnav -n 100 --no-pager; follow with journalctl -f -u bestnav
  • Debugging Pro license / plugin issues (e.g. a stuck “Pro features are loading” banner): grep "\[Pro\]" in the respective log — it prints the exact failure reason

Note: the data/logs/ folder under the app data dir is only an empty dir pre-created by the start scripts — BestNav never writes program logs there; on fnOS startup logs appear only in journalctl. If systemd says the unit is not found, check the name with: ls /etc/systemd/system/ | grep bestnav (you can safely delete a leftover bestnav-direct.service).

Back Up Your Data

A full backup is just a tar of the data. Docker keeps data in the named volume bestnav_data (pack it with the command below); native installs (fnOS / Synology) use the data dir chosen at install time (usually on the app data disk). The backup contains bookmarks & config, users & license, license.json, auth.json, uploaded files, auto-backups, and most importantly .secrets (the encryption key file).

Bash# Docker example: tar the named volume bestnav_data docker run --rm -v bestnav_data:/data -v $PWD:/backup alpine \ tar -czf /backup/bestnav-data-$(date +%F).tar.gz -C /data . # fnOS / Synology native example (use your actual path) tar -czf bestnav-data-$(date +%F).tar.gz -C /path/to/appdata data
  • If .secrets is lost, locally encrypted API Keys / passwords / keys become permanently undecryptable — back it up too
  • Also export config JSON from Settings → Data as a supplement
  • Schedule scripted backups (keep last 7 days) and copy one copy offsite or to cloud

To migrate: stop the old service → tar data → transfer to the new device → extract to the same-name data dir → start. After restore, .secrets and data are identical.

Recover / Reset Admin Password

If you forget the admin (founder) password, reset it from the command line — no reinstall and no data loss. The subcommand is always reset-password (no leading dashes); you will be prompted for the new password twice. Per platform:

Bash# Docker / Synology Container Manager / QNAP / ZSpace (official image) docker exec -it bestnav /app/bestnav reset-password # Synology SPK (native install, not a container; run as root, arch auto-detected, hand the data dir back to the package user afterwards) sudo -i cd /var/packages/bestnav/target DATA_DIR=./data ./server/bestnav-linux-$(uname -m | grep -qE "aarch64|arm64" && echo arm64 || echo amd64) reset-password chown -R bestnav data # fnOS fpk install (binary lives in the app dir; path resolved from the systemd unit) BIN=$(grep ^ExecStart= /etc/systemd/system/bestnav.service | cut -d= -f2) sudo systemctl stop bestnav sudo "$BIN" reset-password sudo systemctl start bestnav
  • The subcommand must be exactly reset-password — -reset-password / --reset-password is not recognized and the program just starts normally
  • On fnOS / Synology SPK the binary is NOT in /usr/local/bin (legacy commands are deprecated) — use the real paths above
  • The fnOS unit is /etc/systemd/system/bestnav.service and the service name is bestnav; the old bestnav-direct.service is retired (remove leftovers with sudo systemctl disable --now bestnav-direct)
  • No need to set DATA_DIR manually on fnOS: reset-password reads WorkingDirectory and Environment= from bestnav.service automatically
  • Reset affects only the login password; bookmarks, stored API Keys and the .secrets encryption key are untouched
  • If the Synology binary name is unclear, check the arch suffix: ls /var/packages/bestnav/target/server/
  • Member passwords are reset by the admin in Settings → Users, no CLI needed

About the Encryption Key

The auto-generated .secrets holds several keys: JWT_SECRET (login sessions), LICENSE_ENC_KEY (encrypts/decrypts your locally stored API Keys, passwords, keys), and HMAC_SECRET (license heartbeat signing). They exist only on your server — BestNav cannot access or upload them.

Keep .secrets and the data backup safe. On migration or reinstall, always restore .secrets first, or encrypted credentials will be unusable.