首页/ 文档/ 安装部署

安装部署

本文介绍在各类平台上部署 BestNav 的几种方式，以及反向代理与 HTTPS 配置。

Docker Compose（推荐）

在任意支持 Docker 的服务器（Linux / macOS / Windows WSL）上，使用以下命令一键启动。镜像为官方自包含构建（内含前端与完整后端，支持 amd64 / arm64 双架构），数据自动保存在 Docker 命名卷中。

Bashmkdir -p ~/bestnav && cd ~/bestnav curl -fsSL https://nav.bestu.top/docker-compose.yml -o docker-compose.yml docker compose up -d

镜像为自包含版本化构建，不再需要本地二进制包；中文页命令默认拉取腾讯云 TCR 源（国内快），海外用户请切换到英文页使用 Docker Hub 源文件（docker-compose-en.yml）。升级只需 docker compose pull && docker compose up -d。

「Docker 容器管理」卡片默认不启用（少跑一个代理容器）。需要的话，用下面的完整 compose 替换官方模板即可：内置只读代理仅放行容器列表与启停，不直挂 docker.sock。

Bashservices: bestnav: image: ccr.ccs.tencentyun.com/bestnav/bestnav:1.0.4 container_name: bestnav hostname: bestnav restart: unless-stopped cap_drop: [ALL] security_opt: [no-new-privileges:true] depends_on: - socket-proxy ports: ["10788:3000"] volumes: - bestnav_data:/app/data - /etc/machine-id:/etc/machine-id:ro - /proc:/host-proc:ro - /sys:/host-disk/sys:ro environment: - TZ=Asia/Shanghai - GOMEMLIMIT=100MiB - GOGC=30 - DOCKER_HOST=tcp://socket-proxy:2375 logging: driver: json-file options: {max-size: "10m", max-file: "3"} healthcheck: test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/health"] interval: 60s timeout: 5s retries: 3 start_period: 10s # 只读代理：仅放行容器列表与启停，承载 Docker 卡片 socket-proxy: # 国内源（推荐）；海外可改为 tecnativa/docker-socket-proxy image: ccr.ccs.tencentyun.com/bestnav/docker-socket-proxy:latest container_name: bestnav-socket-proxy restart: unless-stopped cap_drop: [ALL] environment: - CONTAINERS=1 - ALLOW_START=1 - ALLOW_STOP=1 - ALLOW_RESTARTS=1 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro volumes: bestnav_data: name: bestnav_data

替换后执行 docker compose up -d 重建（数据不丢），Docker 卡片约 15 秒内自动连接。不需要时删除 socket-proxy 服务及 DOCKER_HOST、depends_on 三行即可。

  • 数据默认保存在命名卷 bestnav_data（容器内 /app/data：本地 JSON + 文件搜索 SQLite 索引），升级不会丢失
  • 默认访问端口 10788（容器内固定监听 3000，由 ports 映射），可在 compose 中修改
  • 启动后访问 http://<服务器IP>:10788

环境变量

可通过环境变量定制部署。常用变量如下（写入 compose 的 environment 或 .env 文件）：

Bash# 对外端口：修改 compose 的 ports 映射（如 "8080:3000"），容器内固定 3000 # 外部访问地址，用于生成回调与分享链接 PUBLIC_URL=https://nav.example.com # 时区（影响定时任务与日志时间） TZ=Asia/Shanghai

群晖 DSM

打开 Container Manager → 项目 → 新增，导入 docker-compose.yml（官方自包含镜像，无需任何本地二进制包），或按下载页命令部署。

  • 建议使用桥接网络并固定端口 10788
  • 数据卷挂载到 /volume1/docker/bestnav
  • 在「控制面板 → 外部访问」配置域名与证书后可用 HTTPS 访问

飞牛 fnOS

在飞牛应用中心搜索 BestNav 一键安装，或登录终端执行上述 Docker Compose 命令。安装完成后在「我的应用」中打开。

FygoOS（飞牛国际版）

FygoOS 是飞牛 fnOS 的国际版，安装形态与 fnOS 完全一致（fpk 包 + systemd 服务托管），但需要安装 intl 专用包：用下载页的「下载 FPK（FygoOS）」按钮，或取归档中的 bestnav-intl-*.fpk。

国内版与 intl 版功能完全相同，区别仅在打包时注入的发行标识（用于地区化展示与国际支付）。升级方式与飞牛一致：在应用中心上传新版本 fpk，数据自动保留。

其他 NAS（Unraid / TrueNAS / QNAP）

同样基于上述 Docker Compose 部署：Unraid 可在「Docker」中通过 Compose 或模板添加；TrueNAS（Scale）通过 Apps / 自定义应用导入 compose；QNAP 可使用 Container Station 或 SSH 执行命令。部署后绑定固定端口与数据卷即可。

威联通 QNAP

在 QNAP 上推荐两种方式部署：一是打开 Container Station，导入 docker-compose.yml 并创建容器；二是 SSH 登录后直接执行上述 Docker Compose 命令。数据卷建议挂载到 /share/Container/bestnav 以便统一管理。

  • Container Station → 应用程序 → 创建 → 导入 YAML
  • 固定端口 10788，并在「网络与虚拟交换机」放行
  • 共用前述环境变量与反向代理配置即可启用 HTTPS

极空间 ZSpace

极空间同样基于 Docker 部署：在「应用中心 → Docker」中导入 docker-compose.yml，或通过 SSH 执行命令。极空间适合家庭影音与私有化导航场景，挂载数据卷到 Docker 共享目录后启动即可。

  • 应用中心 → Docker → 导入 compose 文件
  • 数据卷挂载到 /mnt/zspace/docker/bestnav
  • 启动后访问 http://<极空间IP>:10788

反向代理与 HTTPS

生产环境建议用 Nginx / Caddy 反代并启用 HTTPS。以下为 Caddy 示例（自动申请证书）：

Bashnav.example.com { reverse_proxy 127.0.0.1:10788 encode gzip }

Nginx 示例：

Bashlocation / { proxy_pass http://127.0.0.1:10788; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; }

验证安装

浏览器打开首页后，创建管理员账户即可开始使用。若无法访问，请按以下顺序排查：

  • 确认容器状态：docker compose ps 应为 healthy/up
  • 确认端口：本地 curl http://127.0.0.1:10788 是否返回页面
  • 确认防火墙：云厂商安全组与系统防火墙放行端口 10788
  • 反代场景检查 PUBLIC_URL 与证书是否匹配

Docker Compose (recommended)

On any Docker host (Linux / macOS / Windows WSL), start with one command. The image is a self-contained official build (frontend + full backend, multi-arch amd64/arm64); data lives in a named volume.

Bashmkdir -p ~/bestnav && cd ~/bestnav curl -fsSL https://nav.bestu.top/docker-compose-en.yml -o docker-compose.yml docker compose up -d

The image is versioned and self-contained — no local binaries needed. This English page pulls from Docker Hub; mainland-China users should switch to the Chinese page for the Tencent TCR source file (docker-compose.yml). Upgrade with docker compose pull && docker compose up -d.

The Docker container-management card is disabled by default (one less helper container). To enable it, replace the official template with the full compose below: a built-in read-only proxy allows only container list/start/stop — docker.sock is never mounted into BestNav.

Bashservices: bestnav: image: winchtester/bestnav:1.0.4 container_name: bestnav hostname: bestnav restart: unless-stopped cap_drop: [ALL] security_opt: [no-new-privileges:true] depends_on: - socket-proxy ports: ["10788:3000"] volumes: - bestnav_data:/app/data - /etc/machine-id:/etc/machine-id:ro - /proc:/host-proc:ro - /sys:/host-disk/sys:ro environment: - TZ=Asia/Shanghai - GOMEMLIMIT=100MiB - GOGC=30 - DOCKER_HOST=tcp://socket-proxy:2375 logging: driver: json-file options: {max-size: "10m", max-file: "3"} healthcheck: test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/api/health"] interval: 60s timeout: 5s retries: 3 start_period: 10s # Read-only proxy for the Docker card (container list + start/stop only) socket-proxy: # Upstream official image (global); China mirror: ccr.ccs.tencentyun.com/bestnav/docker-socket-proxy:latest image: tecnativa/docker-socket-proxy container_name: bestnav-socket-proxy restart: unless-stopped cap_drop: [ALL] environment: - CONTAINERS=1 - ALLOW_START=1 - ALLOW_STOP=1 - ALLOW_RESTARTS=1 volumes: - /var/run/docker.sock:/var/run/docker.sock:ro volumes: bestnav_data: name: bestnav_data

After replacing, run docker compose up -d to recreate (data is kept); the card connects within ~15 seconds. To disable, remove the socket-proxy service plus the DOCKER_HOST and depends_on lines.

  • Data lives in the named volume bestnav_data (mounted at /app/data: local JSON + file-search SQLite index), safe across upgrades
  • Default port 10788 (container always listens on 3000, mapped via ports)
  • Open http://:10788 after start

Environment Variables

Customize the deployment via env vars (in compose environment or a .env file):

Bash# Host port: edit the compose ports mapping (e.g. "8080:3000"); the container always listens on 3000 PUBLIC_URL=https://nav.example.com TZ=Asia/Shanghai

Synology DSM

Open Container Manager → Project → Create, import docker-compose.yml (official self-contained image, no local binaries), or follow the download-page command.

  • Use bridged network with a fixed port 10788
  • Mount volume to /volume1/docker/bestnav
  • Configure domain & cert via External Access for HTTPS

fnOS

Install from fnOS App Center in one click, or run the Docker Compose command above via terminal, then open it in My Apps.

FygoOS (fnOS international)

FygoOS is the international edition of fnOS. It installs exactly like fnOS (fpk package + systemd service) but needs the dedicated intl package: use the "Download FPK (FygoOS)" button on the download page, or grab bestnav-intl-*.fpk from the archive.

Both editions ship identical features — the only difference is the distribution flag injected at build time (used for regional display and international payments). Upgrading works the same as fnOS: upload the new fpk in App Center and your data is preserved.

Other NAS (Unraid / TrueNAS / QNAP)

Deploy with the same Docker Compose above: Unraid via Docker Compose/template, TrueNAS Scale via Custom App, QNAP via Container Station or SSH. Bind a fixed port and a data volume after deploy.

QNAP

On QNAP, deploy via Container Station by importing docker-compose.yml, or run the Docker Compose command over SSH. Mount the data volume to /share/Container/bestnav for easy management.

  • Container Station → Applications → Create → Import YAML
  • Fix port 10788 and allow it in Network & Virtual Switch
  • Reuse the env vars and reverse proxy above for HTTPS

ZSpace

ZSpace also deploys via Docker: import docker-compose.yml in App Center → Docker, or run the command over SSH. Great for home media and self-hosted nav — mount the data volume to the Docker shared folder and start.

  • App Center → Docker → Import compose file
  • Mount volume to /mnt/zspace/docker/bestnav
  • Open http://:10788 after start

Reverse Proxy & HTTPS

For production, put BestNav behind Nginx / Caddy with HTTPS. Caddy example (auto TLS):

Bashnav.example.com { reverse_proxy 127.0.0.1:10788 encode gzip }

Nginx example:

Bashlocation / { proxy_pass http://127.0.0.1:10788; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; }

Verify

Open the home page, create an admin account, and you are ready. If unreachable, check in order:

  • docker compose ps should be healthy/up
  • Local curl http://127.0.0.1:10788 returns a page
  • Firewall / security group allows port 10788
  • Reverse-proxy: PUBLIC_URL and cert must match