在树莓派 4B 上部署百度网盘 ARM64 图形客户端#

这次部署的目标，是把 baidunetdisk-arm64-vnc 运行在一台 Raspberry Pi 4 Model B 上。这个项目把百度网盘 Linux ARM64 客户端放进 Docker 容器，并通过 noVNC 提供网页访问，也可以使用 VNC 客户端连接。

最终的访问方式如下：

功能	地址
noVNC 网页界面	`http://10.42.0.185:5800/`
VNC 客户端	`10.42.0.185:5901`
容器内 VNC 端口	`5900`
下载数据目录	树莓派的 `/mnt/pan1/`

其中 5901 是主机端口。树莓派原本已经运行了系统级 wayvnc，占用了主机的 5900，所以不能直接照搬项目 README 中的 5900:5900 映射。

1. 确认硬件和系统#

项目 README 标注 Raspberry Pi 4B 支持 ARM64 镜像，而 Raspberry Pi 5 可能出现段错误。因此部署前先确认设备型号和架构：

1
tr -d '\000' </proc/device-tree/model
2
uname -m

本次输出为：

1
Raspberry Pi 4 Model B Rev 1.5
2
aarch64

树莓派运行 Debian 13，符合项目的 ARM64 使用条件。之后在本机拉取仓库，并同步到树莓派：

1
git clone \
2
  https://github.com/eMUQI/baidunetdisk-arm64-vnc.git \
3
  /home/chacha/repo/baidunetdisk-arm64-vnc
4

5
rsync -av \
6
  /home/chacha/repo/baidunetdisk-arm64-vnc/ \
7
  chacha@10.42.0.185:/home/chacha/repo/baidunetdisk-arm64-vnc/

同步时保留了仓库中的 Dockerfile.arm64、docker-compose.yml、启动脚本和 noVNC 配置，后续的部署参数通过 docker-compose.override.yml 单独覆盖。

2. 在树莓派上安装 Docker#

树莓派最开始没有 Docker 和 Compose，因此先安装 Debian 软件包：

1
ssh -t chacha@10.42.0.185 \
2
  'sudo apt-get update && sudo apt-get install -y docker.io docker-compose'

为了让普通用户可以访问 Docker socket，再把用户加入 docker 组：

1
ssh -t chacha@10.42.0.185 \
2
  'sudo usermod -aG docker chacha'

加入用户组后需要重新建立 SSH 会话。否则即使 docker --version 可以执行，docker info 仍可能报：

1
permission denied while trying to connect to the Docker daemon socket

重新登录后确认 Docker 服务和 Compose 可用：

1
docker info
2
docker compose version

3. 处理树莓派无法访问 Docker Hub 的问题#

树莓派上的 Docker 服务已经正常运行，但直接执行：

1
docker pull emuqi/baidunetdisk-arm64-vnc:latest

访问 registry-1.docker.io 时超时。本机可以访问 Docker Hub，因此改为在本机获取 ARM64 镜像，再把镜像归档传到树莓派。

这里使用 go-containerregistry 提供的 crane，它不需要本地 Docker daemon 就能从 Registry 下载镜像：

1
crane pull \
2
  --platform linux/arm64 \
3
  --format=tarball \
4
  emuqi/baidunetdisk-arm64-vnc:latest \
5
  /tmp/baidunetdisk-arm64-vnc.tar

然后传输并加载镜像：

1
rsync -av --progress \
2
  /tmp/baidunetdisk-arm64-vnc.tar \
3
  chacha@10.42.0.185:/home/chacha/baidunetdisk-arm64-vnc-image.tar
4

5
ssh chacha@10.42.0.185 \
6
  'docker load -i /home/chacha/baidunetdisk-arm64-vnc-image.tar'

加载完成后检查镜像架构：

1
docker image inspect emuqi/baidunetdisk-arm64-vnc:latest \
2
  --format='{{.Os}}/{{.Architecture}}'

应当得到：

1
linux/arm64

镜像加载完成后就不再依赖树莓派直连 Docker Hub。临时归档确认加载成功后即可移入回收站或删除，以释放树莓派上的空间。

4. 处理端口冲突#

项目默认使用以下端口：

1
5800:5800  # noVNC 网页
2
5900:5900  # VNC

检查树莓派端口时发现主机的 5900 已被 wayvnc 占用。为了不影响原有桌面远程服务，只调整主机侧端口，把容器内的 5900 映射到主机 5901。

在仓库目录中新增 docker-compose.override.yml：

1
services:
2
  baidunetdisk-vnc:
3
    environment: !override
4
      - USER_ID=1000
5
      - GROUP_ID=1000
6
      - TAKE_CONFIG_OWNERSHIP=0
7
    volumes: !override
8
      - ${PWD}/bdnetdisk-config:/config
9
      - /mnt/pan1:/config/baidunetdiskdownload
10
    ports: !override
11
      - "5800:5800"
12
      - "5901:5900"

!override 用来替换基础 Compose 文件中的同名列表，而不是把旧端口和新端口追加到一起。本次树莓派使用 Docker Compose 2.26.1，支持这种写法。

5. 将下载数据放到 NTFS 硬盘#

下载盘挂载在树莓派的 /mnt/pan1/。实际检查结果如下：

1
/dev/sda1  fuseblk  /mnt/pan1  466G total, 291G available

Compose 中的映射关系是：

1
/mnt/pan1                             -> /config/baidunetdiskdownload
2
/home/chacha/repo/.../bdnetdisk-config -> /config

这里特意把配置目录和下载目录分开：配置仍然保存在树莓派系统盘的 ext4 文件系统中，下载内容则写入外接硬盘。

第一次切换挂载后，容器启动失败并不断重启，日志显示：

1
chown: cannot read directory '/config/baidunetdiskdownload/...': Input/output error
2
terminated with error 123

原因不是 Docker 不能读取目录，而是基础镜像的初始化脚本默认会递归执行 chown，而 NTFS 的 fuseblk 挂载不适合在容器启动时对整棵目录树执行 Linux 所有权修改。

因此在覆盖配置中加入：

1
environment: !override
2
  - USER_ID=1000
3
  - GROUP_ID=1000
4
  - TAKE_CONFIG_OWNERSHIP=0

关闭自动接管 /config 的所有权后，容器保留 USER_ID=1000 和 GROUP_ID=1000，并直接使用 NTFS 挂载点已有的权限。当前 /mnt/pan1/ 对 chacha 可写，容器内的下载目录也通过了写权限检查。

如果你的 NTFS 挂载权限不是可写状态，需要先调整挂载参数；不要只修改 Compose 而忽略宿主机文件系统权限。

6. 启动和验证#

进入项目目录，先检查 Compose 展开的最终配置：

1
cd /home/chacha/repo/baidunetdisk-arm64-vnc
2
docker compose config

确认卷映射和端口无误后启动：

1
docker compose up -d --force-recreate
2
docker compose ps

验证结果应当包含：

1
baidunetdisk-vnc   Up
2
0.0.0.0:5800->5800/tcp
3
0.0.0.0:5901->5900/tcp

再从树莓派本机检查网页服务：

1
curl -I http://127.0.0.1:5800/

返回 HTTP/1.1 200 OK 后，可以从同一局域网的浏览器打开：

1
http://10.42.0.185:5800/

VNC 客户端则连接：

1
10.42.0.185:5901

常见问题#

现象	原因	处理方式
`permission denied` 访问 Docker socket	用户组变更尚未进入当前 SSH 会话	加入 `docker` 组后重新登录
`docker pull` 访问 Registry 超时	树莓派到 Docker Hub 的网络不通	在本机用 `crane` 拉取 ARM64 归档，再 `docker load`
`address already in use`	主机端口已被其他服务占用	修改主机侧端口，例如 `5901:5900`
容器反复 `Restarting (123)`	NTFS 挂载上执行递归 `chown` 失败	设置 `TAKE_CONFIG_OWNERSHIP=0`
能打开网页但下载目录不可写	宿主机挂载权限不足	检查 `findmnt`、挂载参数和目录写权限

总结#

这次部署真正需要处理的并不只是执行一次 docker compose up -d，而是三个设备环境差异：树莓派只应使用 ARM64 镜像、树莓派本身无法访问 Docker Hub、外接 NTFS 硬盘不适合被容器初始化脚本递归修改所有权。

最终方案是：本机获取并转运 ARM64 镜像，树莓派用 Compose 运行容器；网页端口保留为 5800，VNC 主机端口调整为 5901；配置放在 ext4，下载数据放在 /mnt/pan1/，并关闭基础镜像的自动所有权接管。这样既保留了原有 wayvnc 服务，也让百度网盘下载文件直接落到大容量硬盘上。

音乐

音乐