AI客流分析配置：从环境准备到验证的完整流程

AI客流分析配置的核心是把视频流接入、分析服务和结果存储三部分串起来。
本文以常见的Linux服务器加Docker方式为例，适合零基础用户从零搭建一套可验证的客流统计环境。
如果你用的是Windows主机或没有独立显卡，部分步骤需要调整，文中会标注适用条件。

部署前需要确认的运行环境

开始操作前，先确认服务器满足以下条件，避免装到一半卡在依赖问题上。

• 操作系统：Ubuntu 20.04/22.04 或 CentOS 7/8，本文命令以 Ubuntu 为例。
• 硬件：CPU 4 核以上、内存 8GB 以上；如果要做多路视频实时分析，建议有 NVIDIA 显卡并安装对应驱动。
• 软件：Docker 和 Docker Compose 已安装，可用 docker --version 和 docker compose version 检查。
• 网络：服务器能访问摄像头所在网段，摄像头支持 RTSP 协议，并已知 RTSP 地址、用户名和密码。
• 存储：预留至少 20GB 空间用于存放截图和日志。

如果 Docker 尚未安装，可执行以下命令（Ubuntu）：

sudo apt update
sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker

安装完成后运行 docker run hello-world，能正常输出说明 Docker 可用。

获取并启动客流分析服务

大多数开源客流分析项目提供 Docker 镜像或 Compose 文件。
以下以通用目录结构为例，实际镜像名称请以你选用的项目文档为准。

1. 创建项目目录并进入：

mkdir -p /opt/ai-footfall && cd /opt/ai-footfall

1. 新建 docker-compose.yml，写入服务定义（示例结构，镜像和端口按项目实际修改）：

version: "3.8"
services:
  footfall:
    image: your-registry/footfall-analysis:latest
    container_name: footfall
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - ./config:/app/config
      - ./data:/app/data
    environment:
      - TZ=Asia/Shanghai

1. 启动服务：

docker compose up -d
docker compose logs -f --tail=100

日志中出现服务监听端口或启动成功的提示后，用浏览器访问 http://服务器IP:8080，能看到登录页或管理界面即表示服务已运行。

配置摄像头和客流分析参数

服务启动后，核心工作是把摄像头视频流接进来，并设置检测区域。
不同项目界面差异较大，但配置逻辑基本一致。

进入管理后台后，找到摄像头或视频源管理页面，新增一路摄像头，填写以下信息：

• 名称：便于识别的门店或区域名称。
• 视频流地址：格式通常为 rtsp://用户名:密码@摄像头IP:554/Streaming/Channels/101，具体路径以摄像头说明书为准。
• 分析区域：在画面上框选需要统计客流的门口或通道区域，避免把路过行人算进去。
• 检测灵敏度：先使用默认值，后续根据误报情况微调。

保存后，在预览页面确认能看到实时画面。
如果画面黑屏或提示连接失败，优先检查 RTSP 地址、摄像头是否开启 ONVIF/RTSP 服务、服务器与摄像头之间网络是否互通。
可以在服务器上执行 ffplay rtsp://... 或 curl -v rtsp://... 做初步连通性测试。

常见配置错误和避坑提醒

配置过程中有几类问题出现频率较高，提前注意能省不少时间。

• RTSP 地址写错：密码中包含 @、# 等特殊字符时，需要做 URL 编码，否则解析会失败。
• 端口冲突：8080 被其他服务占用时，修改 Compose 文件左侧端口，例如 18080:8080，然后重新 docker compose up -d。
• 容器时区不对：日志时间与本地不一致时，确认 TZ=Asia/Shanghai 已生效，重启容器后复查。
• 分析区域过大：区域框选覆盖了非客流通道，会导致统计数量偏高，建议只框选门口有效通行区域。
• 未做数据持久化：volumes 未挂载时，容器重建会丢失配置和统计数据，务必确认挂载目录存在且可写。

修改配置后，使用 docker compose restart 让服务重新加载，不要直接删除容器，以免丢失未挂载的数据。

验证客流统计是否生效

服务运行和摄像头接入完成后，需要实际验证统计结果是否准确。

1. 在摄像头画面中安排一人按正常速度走过检测区域，观察后台是否产生一条客流记录。
2. 查看统计页面或数据库中的计数是否增加，时间戳是否与当前时间一致。
3. 检查 ./data 目录下是否生成截图或日志文件，确认数据落盘正常。
4. 连续测试 3 到 5 次，统计数量应与实际通行次数一致；如果偏差明显，回到分析区域和灵敏度设置中调整。

如果计数始终为 0，先看容器日志是否有解码或推理报错，再确认视频流帧率是否过低。
部分摄像头默认子码流分辨率较低，可能影响检测效果，可切换到主码流测试。

关于稳定运行的几点建议

配置完成后，建议把服务设置为开机自启，并定期清理截图和日志目录，避免磁盘占满导致服务异常。
对于多门店场景，可以按门店分别部署实例，再通过统一后台汇总数据，但要注意每路视频都会占用 CPU 或 GPU 资源，扩容前先评估服务器负载。

如果后续需要调整统计规则或接入新的摄像头，优先在测试环境验证通过后再更新到生产环境，减少对现有统计的影响。