Docker 故障排查实录：从 Access Denied 到成功运行 WiFi 信号人体成像应用

作者

前言

最近在研究利用 WiFi 信号（CSI）进行人体姿态感应的开源项目 RuView (WiFi-DensePose)。在部署过程中遇到了镜像拉取失败、端口配置错误等一系列典型 Docker 问题。通过一番排查，最终成功跑通了 3D 模拟成像。本文记录了完整的故障排除过程及操作命令。

阶段一：解决镜像拉取权限问题

问题现象：

项目地址：https://github.com/ruvnet/RuView

原仓库作者提供了 docker 安装命令，但我却执行了如下错误命令：

docker run -p 8000:8000 ruvnet/ruview:latest

执行 docker run 时提示 pull access denied 或 repository does not exist。即便配置了国内加速镜像源依然无法拉取。

排查结论：

开源项目的镜像名称可能与项目名有细微差别。在该项目中，虽然 GitHub 仓库名为 RuView，但在 Docker Hub（https://hub.docker.com/）上查询到的有效镜像名为 ruvnet/wifi-densepose。

执行命令：

# 尝试拉取正确的镜像名称
docker pull ruvnet/wifi-densepose:latest

阶段二：容器启动成功但网页打不开

问题现象：

执行如下 docker 运行命令：

docker run -d -p 8000:8000 --name ruview_test ruvnet/wifi-densepose:latest
  • -d：后台运行。
  • -p 8000:8000：将容器的 8000 端口映射到你电脑的 8000 端口。
  • --name ruview_test：给容器起个好记的名字。

容器显示运行中（Up），但在浏览器访问 http://localhost:8000 提示 “This page isn’t working” 或连接重置。

排查步骤：

利用 Docker 的日志功能查看容器内部程序的真实状态：

# 查看容器实时运行日志
docker logs ruview_test

发现关键信息：

通过日志发现，该 Rust 编写的后端服务实际上监听的是 3000 端口，而不是常见的 8000 端口；同时，人体数据流通过 3001 端口的 WebSocket 传输。

  • HTTP server listening on 0.0.0.0:3000
  • WebSocket server listening on 0.0.0.0:3001
  • UI path: /ui/index.html

阶段三：最终正确部署方案

解决方案：

重新映射端口，确保 HTTP 服务和数据流通道同时开启，并访问正确的 UI 资源路径。

执行命令：

1. 清理旧容器：

docker rm -f ruview_test

2. 正确映射端口启动：

# 映射 3000(UI/API) 和 3001(数据流)
docker run -d -p 3000:3000 -p 3001:3001 --name ruview_active ruvnet/wifi-densepose:latest

3. 访问地址：

在浏览器输入：http://localhost:3000/ui/index.html

总结：Docker 排查三板斧

在遇到容器无法访问时，建议遵循以下逻辑：

  1. 名称核对：检查 Docker Hub 上的真正 Repo 名称。
  2. 日志为王：通过 docker logs 观察程序内部输出，寻找真实的监听端口（Listening Port）。
  3. 路径匹配：确认是否有特定的资源子路径（如 /ui/），而不是直接访问根目录。

成功效果：

目前已成功看到 3D 渲染界面中由 WiFi 模拟信号生成的人体骨架影像。下一步计划接入 ESP32-S3 硬件，实现物理空间中的真实感应。

作者注：本次排查得益于对日志细节的捕捉。如果你也在折腾 Docker 过程中遇到同样问题，欢迎交流！

发表评论