树莓派本机摄像头控制台：预览、拍照、录制与 SSH 隧道

本机硬件实验目录里有一段 Python 摄像头控制台：浏览器里可以开预览、调摄像头参数、拍照和录制视频。它适合作为“如何把设备控制包装成一个小型本机 Web 工具”的案例，但不是 ROS 2 节点，也不是已经接入羽毛球识别或机器人控制的产品。

证据边界

这次只审阅了本机 scripts/cam_server.py、scripts/test_cam_server.py 和该工具的 README。测试命令 python3 scripts/test_cam_server.py 通过 12/12 项；测试使用临时目录、模拟 cv2 模块和随机回环端口，不会打开真实摄像头。当前没有可复验的独立 Git 历史，也没有在树莓派上验证相机驱动、真实视频帧率、长时间录制或设备重连，因此本文描述的是源码快照和模拟 HTTP 回归，不是硬件验收报告。

数据流与功能边界

本机浏览器
  ├─ GET /video_feed      multipart JPEG 预览
  ├─ GET /list_photos     查看工具生成的媒体文件名
  ├─ GET /get_photo       读取生成的照片或录像
  └─ POST JSON            启动预览、调参数、拍照、开始/停止录制
            │
            ▼
Python ThreadingHTTPServer（固定监听 127.0.0.1）
  ├─ OpenCV / V4L2 摄像头设备
  ├─ v4l2-ctl 白名单参数控制
  └─ 本机 SAVE_DIR 媒体目录

预览端点把 OpenCV 读到的帧编码为 JPEG，并以 multipart 流持续写给浏览器。摄像头没打开时返回 503，而服务本身仍可启动，让使用者先检查设备后再重试。浏览器还能设置分辨率和帧率预设、拍照格式、亮度、对比度、饱和度、锐度、焦点与缩放；拍照和 AVI 录像则直接写入本机目录。

这里没有消息队列、推理节点或控制器：它解决的是设备预览与文件采集，不应把它描述为完整的 ROS 摄像头驱动、羽毛球检测流水线或实时机器人系统。若要把它接入 ROS 2，仍需另行实现带时间戳和坐标系约定的图像发布节点，并验证 QoS、帧率、延迟、设备断连与资源占用。

为什么只监听回环地址

服务将 HOST 固定为 127.0.0.1，默认端口为 8080；保存目录和端口可以通过环境变量调整，但监听地址没有被开放配置。这样可以避免它意外成为局域网或公网摄像头服务。源码没有用户登录或会话认证，因此回环监听只是网络暴露控制，不是本机用户间的访问隔离；同一台设备上的其他进程仍可能请求控制接口或读取已生成的媒体文件。

从 Mac 远程查看时，让服务继续在树莓派本机运行，再建立只绑定 Mac 回环地址的 SSH 隧道：

ssh -N -L 127.0.0.1:8080:127.0.0.1:8080 <Pi 用户>@<Pi 地址>

隧道建立期间，在 Mac 浏览器打开 http://127.0.0.1:8080；关闭 SSH 后访问也随之中断。这条链路没有给服务本身增加 TLS 或账号体系，不要把 HOST 改为 0.0.0.0，也不要把 8080 配置成路由器端口转发。共享树莓派时，应使用系统账户、文件权限和网络隔离限制其他本机用户，而不是把“只能回环访问”误当作完整认证。

控制请求的几层约束

会修改摄像头状态的路径只接受 POST；对这些路径发 GET 会收到 405 和 Allow: POST。POST 必须是 JSON 对象，正文最多 8 KiB。服务会比较 Origin 与 Host：两者必须指向同一个 localhost/回环主机、使用当前端口和 HTTP scheme；若 Sec-Fetch-Site 明确标记为 same-site 或 cross-site，也会拒绝。它减少了普通网页跨站诱导浏览器控制本机设备的风险，但不能替代身份认证，也不覆盖同机恶意进程。

参数修改还要通过两层检查：

分辨率与帧率只能取预设集合中的值，避免任意输入直接触发设备操作。
摄像头控制项必须在名称白名单内，数值必须是整数并位于该控制项的上下界中。
v4l2-ctl 由参数数组启动，不经 shell 拼接执行；每条调用有 3 秒超时，命令失败会转换为受控错误响应。
无效 JSON、错误媒体类型、超大请求体、相机未开启和不支持的控制项会返回明确的 4xx/5xx 状态，而不是继续尝试设备操作。

若设备没有某个可选控制项，读取函数目前会以 0 作为兜底值，因此“读到 0”无法区分真实数值为零和读取失败。更完整的实现可以分别返回支持状态、当前值和错误原因，避免界面把不支持误显示成正常默认值。

媒体路径与隐私

媒体读取接口只接受工具生成的时间戳文件名格式，再解析真实路径并要求文件直接位于配置的保存目录中且是普通文件。这样可以拒绝路径穿越、目录外文件和指向外部文件的符号链接。响应设置 nosniff、no-store 和 same-origin 资源策略；接口不列出任意目录文件。

不过文件名规则不是访问控制。因为服务没有登录认证，任何能访问本机端口的进程都可能读取符合命名规则的照片与录像。画面可能包含私人空间或他人影像：应只将目录用于该工具生成的媒体，限制目录所有者与权限，避免共享或备份未脱敏画面，并在测试、传输和发布日志时不要附带原始媒体。

当前代码也没有录制时长、总容量、文件保留期或磁盘空间告警。长时间运行可能持续占用存储；下一步应增加最大录制时长/体积、明确的保留策略、空间不足时停止录制并显示错误，以及安全的删除流程。按秒构造的文件名在同一秒重复保存时也可能发生覆盖，适合用唯一后缀并添加碰撞回归。

当前回归覆盖与下一步真机验收

12 项模拟回归覆盖了变更 GET 被拒绝、跨源和错误 Host 拒绝、响应安全头、控制名称/数值校验、请求体大小与类型限制、非法摄像头预设、错误拍照格式、未打开摄像头时拒绝录制、视频流不可用、摄像头打开失败、生成媒体读取和路径穿越/符号链接拒绝，以及媒体列表过滤。它们能验证 HTTP 与输入边界，但不验证 V4L2 驱动、摄像头真实控制能力、MP4/AVI 播放器兼容、声画同步、并发长流或断电时的文件完整性。

接入真实设备前，建议按风险逐步验收：

先在树莓派本机用一个短片段验证相机打开、预览帧尺寸和参数读取；逐项记录不支持的 V4L2 控件。
用 SSH 隧道访问，确认笔记本休眠、隧道中断和重连时不会把服务暴露到局域网。
录制短文件并验证实际编码、可播放性、生成文件权限和磁盘占用；再做最长时长与磁盘将满的故障测试。
检查目录权限、用户组、服务退出后的摄像头释放，以及多个浏览器并发连接时的 CPU/内存和相机读锁行为。
若最终需要局域网多人使用，先增加独立认证、授权、HTTPS、访问审计和媒体清理策略，再重新进行威胁建模；不应通过直接开放监听来绕过隧道。

它和树莓派 ROS 2 入门路线是两种不同层次的资料：本篇是一个受限本机 Web 工具的源码复盘，入门文档则是 ROS 学习路线；两者都不代表已经完成真实 ROS 摄像头节点或机器人硬件联调。更完整的设备和发行版取舍见树莓派 ROS 视觉项目记录。