保姆级 NasPilot 安装部署｜自建个性化导航主页指南

NAS 上 Docker 装得多了，每个服务都是一个 IP + 端口，记起来非常麻烦。 Homepage、Sun-Panel 我都试过，功能确实很强，但它们都需要挂载 docker.sock，相当于把整台 NAS 的 root 权限交付出去。几十万行源码，我也没有精力逐行审计。

于是自己写了一个导航面板：NasPilot。

它的定位很纯粹：自动读取 Docker 容器并生成服务卡片，新增容器自动出现，删除的容器标记为「已移除」；同时扫描宿主机端口，把飞牛影视、音乐、相册这类非容器原生应用一并收录进来；顺带展示每个服务的响应耗时与主机资源状态。

一、部署

1. 确认前提

一台能跑 Docker 的机器就行——飞牛、群晖、威联通、普通 Linux、树莓派都可以。要求只有两条：Docker 版本 20 以上，以及你知道这台机器的局域网 IP。

我这台是飞牛 evo2，4 核 16G，全程图形界面操作，不用敲命令行。

2. 建目录，写 compose

在 NAS 上找位置建个文件夹，比如 /vol1/docker/naspilot，在里面新建 docker-compose.yml：

services:
  naspilot:
    image: node:22-alpine
    container_name: naspilot
    restart: unless-stopped
    working_dir: /app
    command: ["node", "server/index.js"]
    ports:
      - "8899:8899"
    environment:
      - TZ=Asia/Shanghai
      - NASPLOT_DATA=/app/data
    volumes:
      - ./:/app
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/host/proc:ro
      - /:/host/root:ro

四条挂载各管一件事，先看清再决定删不删：

8899 是面板端口，被占了就改左边那个数字，比如 "9900:8899"，访问地址跟着变。

3. 启动

飞牛的话，Docker → 项目 → 新建，选刚才那个目录，点启动。命令行则是：

cd /vol1/docker/naspilot
docker compose up -d

第一次会拉 node:22-alpine 镜像，几十兆，看网速。起来之后 docker ps 能看到 naspilot 在跑。

4. 打开，同步一次

浏览器进 http://你的NAS的IP:8899。

进去是空的，正常。点右上角设置 → 联动 → 立即同步，等两三秒，所有容器变成卡片出现，名字、端口、运行状态自动带上。

5. 认领飞牛自带应用

飞牛影视、音乐、相册不是 Docker 容器，Docker API 里看不见，得靠端口扫描。

左侧点"待认领"，它会列出扫到的端口，能打开的显示标题和响应耗时，点收录就进主页面。

这一步是空的，就按顺序检查三处：/proc:/host/proc:ro 挂了没、设置 → 联动的"挂载路径"是不是 /host/proc、回主界面点一次刷新。

二、个性化配置

面板能用了，接着调成顺手的样子。

加密码。 设置 → 安全 → 访问密码。设完所有接口都要先登录，Cookie 有效期 30 天，同一个 IP 一分钟错 5 次会被限流。忘了密码就编辑 data/config.json，把 passcode 那段整个删掉，重启容器即恢复免密。

换外观。 设置 → 外观里三样：主题（深色 / 浅色）、卡片密度（紧凑 / 标准 / 宽松）、强调色。

调整顺序。 主界面直接拖卡片，手机上长按拖。不想看的点眼睛图标隐藏，常用的点星标置顶。搜索按 Ctrl+K（Mac 是 ⌘+K），Esc 关弹层。每个入口可以填标签和别名，比如给 qBittorrent 填"下载、bt、种子"，搜哪个词都能出来。

让容器带名字和图标。 不想拿容器名当显示名，在 compose 里加标签：

labels:
  naspilot.name: "影视库"
  naspilot.desc: "4K 片源"
  naspilot.group: "media"
  naspilot.icon: "https://example.com/icon.png"

下次同步卡片就按你写的显示。不想让它出现在面板上加 naspilot.hide: "true"，想手动指定地址加 naspilot.url。图标抓不到会降级成首字母，不会显示破图。

三、备份、更新与排错

备份只需要 data/ 一个目录，里面是 config.json（所有配置）和图标缓存。也可以在设置 → 数据 → 导出，存一份 JSON，换机器时导入能还原全部分组和入口。

更新：解压新版本，用 public/、server/、docker-compose.yml 覆盖旧目录，千万别覆盖 data/，然后 docker restart naspilot，浏览器强制刷新（Ctrl+Shift+R），不然可能还是旧页面。

几个常见问题，基本上都出在挂载上：

磁盘那栏空着——没挂 /:/host/root:ro。这条会读宿主机所有挂载点，介意权限可以删掉，只是看不到磁盘。

容器列表一直空——docker.sock 没挂，或者挂成了 :ro 又在设置里开了"允许启停容器"。改只读就把启停关掉。

待认领一直是空——/host/proc 里读不到 tcp 表，确认挂载路径和设置里的一致。

待认领混进一堆垃圾——状态码页、nginx 默认页这类。设置 → 数据 → 整理自动发现的条目，点清理。

图标不对——站点换图标了。设置 → 数据 → 图标缓存 → 重新抓取，最长 24 小时也会自动更新。

四、注意

挂载 docker.sock 等价授予 root 权限。

👉 单人内网可用；多人使用建议 docker.sock:ro 只读挂载

👉 禁止直接暴露 8899 到公网，远程访问请反向代理 + 额外身份认证

五、源码仓库

• Gitee：https://gitee.com/y6214880/naspilot.git
• GitHub：https://github.com/y6214880/naspilot.git