smart-cam RK3576/RK3588 通用部署说明

版本信息

• Docker镜像：smart-cam-universal:20261013
• 镜像归档：smart-cam-universal-20261013.tar
• 目标平台：RK3576、RK3588 / Linux arm64
• 发布日期：2026-10-13
• 部署方式：盒子终端运行sudo bash deploy.sh，根据中文提示逐项输入

本目录是完整的离线镜像与部署配套包。自动清理程序不打入Docker镜像，但完整程序随交付目录提供，部署时直接从包内安装，不再访问公司的清理程序Git仓。只有扫图配置向导会在部署时从公司Git服务器获取optimize-version分支。

客户平台的自动追踪档位、完整巡航计划和手动录像直接通过盒子现有 HTTP API 对接， 不增加MQTT配置或常驻桥接进程。新增接口见客户平台新增功能_HTTP指令说明.md， 原有摄像头控制接口保持不变，见smart-cam_HTTP指令说明.md。 重复设置当前追踪档位是幂等操作，不改写配置或重置追踪；18080写接口会在业务处理前 拒绝非对象顶层JSON并返回400 invalid_request，不会把调用方格式错误升级为500。

同一个基础镜像同时包含RK3576和RK3588的检测、分类、密度估计模型。部署脚本从/proc/device-tree/compatible自动识别芯片，不询问也不猜测平台；随后写入对应模型路径，并通过容器环境变量传递平台。容器首次启动时删除另一平台模型，config.json不增加平台字段。

本版本包含的能力

识别、录像与上传

• RK3576和RK3588本地鸟类检测、分类和密度分析，共用同一份业务程序。
• RK3576分类模型为51类、batch=1；RK3588分类模型为55类、batch=4，程序按模型输入和输出动态确定批量及类别数。
• 当前两个平台的检测模型均为YOLOv5-P6四输出；检测输入尺寸直接从RKNN张量读取， 不限定640x640。原始YOLOv5支持3/4个检测头并自动推导各头stride，anchors统一从 /smart-cam/models/yolov5_anchor.txt加载；一输出或九输出YOLOv8 RKNN自动跳过anchors。
• 直播和标注录像左下角的“AI智能识别”使用固定基线，不随无鸟、有鸟或物种摘要换行上下跳动； 摘要仍逐帧匹配当前画面：密度估计取整结果不超过15只时，数量和第二行 物种统计直接取当前画面实际绘制的全部可见框，右下角仅保留深蓝色密度底图；没有框时只显示 “AI智能识别”，不显示“0只”。超过15只时显示密度估计数量和真实密度图。计数后不再显示 “（密度估计）”。
• 两套模型均已在RKNN Runtime 2.3.2、NPU驱动0.9.8上完成实机初始化和张量约束校验。
• 检测前后缓冲录像、原始录像和VOC标注输出。
• 主取流和原始录像均在RTSP SETUP前只选视频轨，并从SDP/caps自动匹配H.264/H.265；不会因天地伟业音视频多轨或配置编码过期产生not-linked、空视频或容器重启。
• SFTP文件上传与Kafka消息确认。
• Kafka消息时间使用录像文件名中的北京时间字段并保持原...SSSZ格式，例如 video_20261013_100229_030.mp4生成2026-10-13T10:02:29.030Z；原topic、key和消息结构不变。
• 标注录像按墙钟补齐时间轴；VOC XML写临时文件并原子发布，异常断电不会再暴露零字节成品XML。
• 自动部署会将宿主机设为Asia/Shanghai，再通过海康ISAPI或天地伟业SDK把摄像头 设为UTC+08:00的北京时间；设置后必须有成功响应/回读，否则部署回滚。
• 上传设备使用独立SSH私钥；部署时后台密码仅用于一次性写入公钥，密码不保存到config.json。
• 扫图批次和录像上传完成记录持久化，可区分已确认、待重试状态。

扫图、巡航与自动追踪

• 同一镜像同时包含海康威视ARM64 HCNetSDK和天地伟业NetSDK；摄像头品牌由camera.vendor唯一决定。
• 切换厂商时同步切换RTSP路径、SDK和原始录像管线。采集链路以摄像头SDP实际发布的caps为准，自动选择H.264或H.265的RTP解包、解析和MPP硬解；配置中的编码字段只作为诊断提示，摄像头后台切换编码后不需要同步修改它。
• 摄像头同时发布视频和音频RTP轨道时，程序在RTSP SETUP前只选择视频轨，再把视频动态pad显式连接到自动解析链路；不会因音视频轨顺序变化、未消费音频pad或配置编码过期触发GStreamer not-linked、无画面和容器重启循环。直播管线关闭时直接进入NULL状态，避免RTSP动态pad拆除期间的EOS竞态。
• RTSP输入只建立一个持续采集会话，不再为了探测分辨率额外连接一次摄像头；真实输入宽高直接从正式会话每帧caps读取，再由RGA转换到video.width/height。这兼容主码流单会话或TEARDOWN释放较慢的摄像头固件，并降低启动连接压力。
• 天地伟业官方Linux SDK只有x86-64版本，镜像内已封装ARM64静态QEMU、x86加载器和隔离worker，不要求宿主机安装额外兼容环境。
• 天地伟业云台优先通过摄像头内网HTTP 80端口的ONVIF执行绝对pan/tilt移动，并用官方SDK坐标回读闭环校验；首次使用会自动测量并持久化该型号的tilt坐标映射。zoom仍由官方SDK控制。ONVIF不可用时才降级为SDK闭环点动，不修改也不依赖摄像头公网FRP映射。海康威视继续使用原HCNetSDK路径，两个厂商互不影响。
• 天地伟业标定小步移动和离散zoom档位使用实机粒度判断，失败退出前会主动停止全部PTZ动作。pan/tilt/zoom到位误差只取config.json中的配置，不再叠加隐藏的更严格阈值。
• 天地伟业HTTP PTZ复用Digest认证会话，并只对401、短暂400/5xx和网络瞬断作有限重试；开机时摄像头网口晚于Docker就绪也会自动退避重连，网络恢复后巡航自行恢复，不需要重启容器。smart-cam.service同时声明network-online.target顺序依赖，但驱动自恢复不依赖宿主机是否正确实现该target。
• 按config.json中的多个每日时间执行全域扫图。
• 计划时刻错过或被占用时，在配置的补偿窗口内按重试间隔继续尝试。
• 根据扫图检测结果自动生成并串联巡航计划。
• 永久人工巡航点不会被后续扫图删除，会自动合并进每版巡航计划。
• 自动点和人工点使用相同的驻留、录像、物种变化触发和点内自动追踪规则。
• 自动或手动录像一旦开始，当前巡航点立即进入镜头移动保护；即使驻留或单目标追踪倒计时已经结束，录像期间也不会切换下一点或返回同一点锚点，当前自动追踪继续工作。录像时间不计入单目标追踪的2分钟预算；本段录像完整收尾后才按原巡航倒计时决定继续当前点或前往下一点。保护不重置5分钟驻留倒计时，也不改变录像时长、推理和物种触发逻辑。
• 人工控制摄像头时，巡航和自动追踪共同让出云台；超过配置保护时间后返回人工接管前的巡航点，并重置完整驻留时间。
• 人工控制保护采用5分钟滑动计时：保护期内再次操作会从最后一次操作重新计时；人工会话结束并回到原巡航点前，扫图、巡航和自动追踪均不得控制云台。
• 人工接管扫图时不再停止或删除扫图任务；程序记住当前网格点，人工停止操作满5分钟后返回该点、重新对焦和拍照，再从原进度继续。
• 整个人工控制过程视为一个录像去重会话：首次出现鸟时录像，随后仅在出现新物种时再次录像；人工期间绝不自动追踪。
• 人工控制只由平台调用smart-cam的PTZ HTTP接口触发，每条平台PTZ请求刷新5分钟滑动保护；不再根据画面变化或轮询PTZ坐标猜测人工操作。摄像头厂商客户端绕过HTTP接口时，smart-cam不会让出控制权。
• smart-camctl patrol preview按顺序循环查看扫图生成的自动巡航点，不混入永久人工点；smart-camctl points goto <ID>直接查看指定永久人工点。两种命令共用同一套patrol.preview_hold_seconds预览逻辑：切点时中断当前录像，倒计时内只禁止自动触发录像，手动录像和自动追踪均可使用；到期不复位镜头、不打断追踪，从当前画面直接接成该点的一次完整巡航驻留周期。
• 自动追踪按目标中心偏差、目标框面积和当前zoom比例计算每一步，并按速度档在线学习摄像头响应；单鸟默认面积30%，多鸟联合框默认面积50%，两者可分别配置。
• 同一组目标达到巡航点内的追踪时间上限后，状态会保持为阻塞；短暂漏检或事件间隙不会重新开启同一超时会话，也不会重复刷停止日志。只有连续无目标达到auto_tracking.rearm_absence_seconds、出现新的稳定目标ID、切换巡航点或显式重置后才重新追踪。
• 高倍zoom下的中心缓冲区会根据相机最小实测步长自动扩大；跨过中心后，只有反向偏差超过动态反转带才允许电机反向，不再依赖可能早于下一批画面失效的固定计时器。小于最小可控步长的边缘偏差使用小幅缩小处理，避免上下或左右震荡。

直播

• MPP根据RTSP实际caps自动硬解H.264或H.265；GStreamer按实际帧stride转换为紧密BGR，避免把Rockchip NV12缓冲区误当作无stride图像而产生横向花屏。
• 在软件颜色转换前将推理输入限制为15 FPS，避免把随后会丢弃的25 FPS帧全部转换；原始录像仍直接使用摄像头码流。
• 解码后的处理和识别直播共用video.width/height这一组分辨率，默认1920x1080；不再设置第二套输出宽高，也不会把1080p处理帧无效放大成伪4K。硬件和网络允许时可改为2560x1440；设为3840x2160才是真4K处理和输出，但不适合作为2GiB容器的通用默认值。
• RKNN检测器仍会按模型自身输入尺寸（例如640x640）在内部letterbox；调整video.width/height不会改变RKNN模型结构，但会改变叠加画布、识别后直播和标注录像的像素尺寸。
• 输入链路最多取15 FPS；低于15 FPS时保持摄像头实际帧率，不强制补到15 FPS。这样兼容5 FPS等低帧率H.264/H.265主码流，避免videorate drop-only与固定帧率caps产生not-negotiated重连。
• RTSP服务端口保持监听以接受新连接；没有客户端时不创建缩放和编码管线，不传输直播数据，但端口和公网FRP映射仍属于本设备，不能给其他服务复用。
• 容器内部始终部署本地直播控制服务和按需OvenMediaEngine链路。
• 本地直播网关监听盒子15555端口，公网直播为可选项。
• 选择公网直播时，部署脚本将映射单独写入/usr/local/0.34.3_linux_arm64/smart-cam-live.ini，并由独立的smart-cam-live-frpc.service运行。
• 部署程序不会读取、修改或重启已有frpc_sys.service及其摄像头HTTP、SDK、RTSP、WebSocket映射。
• 公网直播域名、端口和token不会写入Docker内的/smart-cam/config/config.json。
• 不选择公网直播时，不创建新的公网映射，也不修改设备上已有FRP配置；盒子内部直播链路仍完整安装。

运维与可靠性

• 中文摘要运维工具smart-camctl。
• 巡航、自动追踪、摄像头控制权、扫图定时、上传确认和人工点位状态汇总。
• 巡航和自动追踪实时日志副本，10MiB轮转并保留3份历史。
• 每天19:00进入“仅上传”模式，停止采集、推理、录像、直播、扫图、巡航和追踪。
• 每天06:00恢复完整运行模式。
• 设备重启后根据北京时间恢复正确的日间或夜间模式；开机3分钟后再复核一次， 避免RTC错误、NTP大幅校时时模式判断过早。
• 06:00和19:00分别执行明确的日间、夜间动作，两个边界timer不做离线补跑；开机或 校时后的当前模式只由模式恢复服务计算，避免两个过期边界在开机时同时补跑。
• Kafka持续异常看门狗，每30分钟检查一次；它以文本方式读取可能含NUL字节的producer日志， 只有同时存在近期Kafka错误和超过30分钟仍未完成的上传包才允许重启。正在录像时最多等待 90秒让当前三件套正常收尾，并在真正重启前取得扫图重启禁止锁、二次检查扫图状态， 因此不会因空闲期broker重连日志误重启，也不会在扫图期间重启容器。
• 识别后直播冻结看门狗，每30分钟对比画面左上角时间区域；同样受扫图重启禁止锁 约束，并在扫图和夜间模式下跳过。
• 自动清理程序由交付包内的cleanup-smartcam-data安装，处理录像磁盘空间和低磁盘恢复。
• 安装清理程序时同时安装/etc/logrotate.d/smart-cam-usbdevice，防止Rockchip系统的adbd/usbdevice在USB FunctionFS未绑定时持续写满/var/log/usbdevice.log；每小时清理还会在该日志超过100MiB时独立截断，避免依赖系统logrotate是否正常运行。该规则不改smart-cam录像或推理逻辑。
• smart-camctl record start可随时强制开始一段完整录像；若当时正在录像，旧段立即标记作废且不进入Kafka/SFTP，清理任务会整体删除其原始视频、标注视频、XML和临时分片。
• 部署切换容器后会主动检查全部smart-cam固定端口；旧smart-cam或无关进程/服务占用时自动停止占用者并重试，部署失败则恢复被停服务。
• 每小时清理会回收超过60分钟且经互斥锁、活动标记、状态API和最终meta共同确认的 未完整scan；完整但未上传的scan不会被当成失败任务删除。
• 计划扫图失败后默认每60秒重试一次，但只在计划时刻后的30分钟补扫窗口内重试。

具体运维指令和每个输出字段的含义不重复写在README中，请查看同目录的运维命令.md。

交付目录

smart-cam-universal-20261013-all/
├── smart-cam-universal-20261013.tar RK3576/RK3588、海康/天地伟业统一Docker镜像归档
├── deploy.sh                       对话式全自动部署脚本
├── README.md                       本文档
├── 运维命令.md                     运维指令与输出解释
├── SHA256SUMS                      全部交付文件校验值
├── VERSION                         版本和镜像信息
├── cleanup-smartcam-data/          随包提供的自动清理程序（不含重复unit和流程PNG）
├── frp/
│   ├── frpc                        FRP 0.34.3 arm64客户端
│   └── smart-cam-live-frpc.service 独立的公网直播systemd服务
├── scripts/                        日夜模式、看门狗和YOLOv5元数据导出脚本
└── systemd/                        全部service、timer和watchdog单元（含自动清理）

部署前提

• 目标设备是RK3576或RK3588 arm64 Linux，并使用systemd；脚本从device-tree自动识别平台并选择镜像内对应模型。
• 整个目录已经完整下载或复制到目标盒子；不能只复制deploy.sh。
• 目标设备能访问后台SFTP服务器和扫图配置向导的公司Git仓；选择公网直播时还要能访问FRP服务器。安装自动清理程序不需要访问Git。
• 部署用户有sudo权限。
• Docker数据目录除镜像包占用外，至少还需要“镜像tar大小 + 512MiB”的可用空间。
• 摄像头RTSP、SDK和HTTP网络从盒子可达。

摄像头连接始终使用填写的内网地址和厂商标准端口：海康为HTTP 80、SDK 8000、 RTSP 554；天地伟业为HTTP 80、SDK入口 3000、辅助端口 3001、RTSP 554。 摄像头公网端口映射仅供人工远程访问，部署程序不会读取、修改或覆盖这些FRP配置。 海康校时会自动协商Basic/Digest认证；最终返回401时立即停止，避免错误密码被重复尝试后锁定账号。

脚本会检测Docker、Git、Python、curl、FFmpeg、flock和ss。缺失时在支持APT的系统上自动安装。

完整部署

把整个目录下载或传输到目标设备后执行：

cd /path/to/smart-cam-universal-20261013-all
sudo bash deploy.sh

脚本可从任意目录调用，它始终按自身所在目录查找镜像包和配套文件。

对话中需要准备的信息

脚本只询问以下信息，密码隐藏输入：

1. 设备编号，默认使用当前主机名。
2. 摄像头品牌，默认hikvision。
3. 摄像头IP，默认192.168.2.10。
4. 摄像头用户名，默认admin。
5. 摄像头密码，默认semi406406，输入不回显。
6. 是否使用默认后台60.10.24.48:60013，默认是；选择其他后台时依次询问 域名或IP、SSH/SFTP端口、用户名和密码，存储根目录固定为 /storage2/file/remote_sync。
7. 后台服务器密码；使用默认后台时也会询问，已有有效设备密钥时可以直接回车 复用；输入不回显且不会写入配置。
8. 是否配置公网直播，默认否；选择是后询问域名和已分配的公网端口。
9. 显示完整配置摘要后询问确认开始部署 [Y/n]；输入n时不修改系统、容器或配置。

所有问题都在实际部署前完成。为避免占用其他设备端口，新设备第一次启用公网直播时，公网端口没有猜测值，必须填写服务器侧已经分配的空闲端口；已有smart-cam专用配置时才默认复用其中的端口。

时区固定为Asia/Shanghai。海康使用SDK端口8000和RTSP路径/Streaming/Channels/101；天地伟业使用SDK基准端口3000和RTSP路径/1/1。脚本打印不含密码的完整摘要，得到最终确认后才开始部署。

自动执行的步骤

1. 校验SHA256SUMS、arm64架构、RK3576/RK3588 device-tree和磁盘空间。
2. 检查并安装系统依赖，设置固定时区Asia/Shanghai。
3. 直接执行交付包内cleanup-smartcam-data/scripts/install.sh安装自动清理程序；它从顶层systemd/安装清理service和timer，不访问公司清理仓。安装或重新启用后5秒内先清理一次，之后从每次清理完成时起每60分钟执行一次。
4. 只有scan-calibrator会从公司Git获取optimize-version分支并放到/home/ykzai/scan-calibrator。
5. 从tar导入统一镜像，校验双平台标签，并只在NPU上探测自动识别平台对应的三份RKNN模型。扫图向导从公司Git更新后，再由交付包覆盖安装已经验证的PTZ独占控制文件。
6. 停止systemd对旧容器的拉起；如果存在smart-cam容器，将其停止并重命名为带时间戳的备份，不删除旧容器。天地伟业设备会等待25秒释放旧SDK会话，避免正确密码被摄像头短暂误判为认证失败。
7. 创建最新版smart-cam容器，传入自动识别的平台并继续使用宿主机/userdata/data持久化目录；启动时删除另一平台模型。容器限制为2GiB内存、3GiB memory+swap，异常增长只会触发容器级保护，不再拖垮整机。
8. 根据摄像头品牌通过海康ISAPI或天地伟业SDK设置UTC+08:00和当前北京时间，并校验返回结果；失败则停止部署并恢复旧容器。
9. 使用对应平台模型路径及设备、摄像头、后台参数生成配置；不写平台字段，不在主部署脚本中调整扫图范围参数。
10. 先验证已有SSH上传密钥；仅在无效时请求后台密码登记并立即复验。
11. 按选择安装或跳过公网FRP直播映射。
12. 安装06:00/19:00定时任务、开机模式恢复和两个看门狗。
13. 启动容器并根据当前是日间还是夜间执行对应健康检查；容器就绪后重新启动清理timer，确保新设备立即执行首次安全清理。

部署中每一步都会打印[当前步骤/总步骤]和结果；容器切换后的任一步失败都会删除未完成的新容器，并将旧容器恢复为smart-cam及原先的运行状态。

主程序的实时帧队列保持小容量并共享只读画面引用；RKNN初始化完成后立即释放分类和密度模型的原始文件缓冲，OpenCV线程数及glibc arena也受限，并定期归还空闲堆页。这些措施控制正常常驻内存，Docker限制负责阻断异常内存增长，两层共同避免smart-cam导致宿主机OOM。

扫图参数单独配置

主部署脚本不会询问或覆盖点位的扫图角度、步长、倍率和容差。部署结束会打印：

scan参数交互式配置向导已clone到/home/ykzai/scan-calibrator，执行bash /home/ykzai/scan-calibrator/interactive.sh即可开始配置扫图参数。

按提示另行执行该向导即可。

向导启动时会检查完整扫图状态；没有扫图任务时临时暂停后台巡航，等待已经在执行的PTZ动作结束后再进入交互。标定期间所有PTZ读取和移动都标记为scan_calibrator，避免巡航或自动追踪抢占云台；向导正常结束、回复3或按Ctrl+C退出时自动恢复进入向导前的巡航状态。

数据与配置位置

• Docker内主配置：/smart-cam/config/config.json
• 宿主持久化数据：/userdata/data
• 永久人工巡航点：/userdata/data/patrol/manual_points.json
• 当前巡航计划：/userdata/data/patrol/current_plan.json
• 巡航/追踪运维日志：/userdata/data/ops-logs
• 上传SSH私钥：/userdata/data/secrets/upload_sftp_key
• 可选公网直播FRP配置：/usr/local/0.34.3_linux_arm64/smart-cam-live.ini

/userdata/data不会在部署、升级或旧容器重命名时删除。

切换摄像头品牌

摄像头IP、账号和密码只有一个来源：video.source。厂商只有一个开关：camera.vendor。配置中不要再添加camera.host、camera.username、camera.password、camera.sdk、camera.http或scan.vendor。

摄像头地址和认证信息不变时，只修改容器内/smart-cam/config/config.json的一个字段：

"camera": {
  "vendor": "tiandy"
}

值只能是tiandy或hikvision。然后执行：

docker restart smart-cam

启动程序会根据该字段及video.source统一生成运行时RTSP、SDK和HTTP连接，因此直播/推理取流与扫图/巡航/自动追踪不会选到不同厂商。如果新摄像头地址、账号或密码不同，只修改video.source，不要在camera内重复配置。

安全设计

• 后台密码通过隐藏输入读取，仅经标准输入传给一次性密钥登记程序。
• 后台密码不进入shell命令参数、不写入环境变量、不保存到JSON。
• 登记完成后上传只使用/userdata/data/secrets/upload_sftp_key，文件权限为0600。
• 固定FRP token只保存在宿主机FRP配置中，该文件以0600权限安装，并且不进入Docker配置。
• 标准摄像头密码是建立RTSP连接的必要信息，会以URL编码形式存在容器配置中；部署过程中的临时配置目录在退出时删除。

定时任务和看门狗

部署后启用以下单元：

• smart-cam.service
• smart-cam-mode-restore.service
• smart-cam-mode-restore.timer：timer启用3分钟后按已校正的北京时间复核模式
• smart-cam-daily-start.timer：每天06:00
• smart-cam-daily-stop.timer：每天19:00
• smart-cam-kafka-watchdog.timer：每30分钟
• smart-cam-stream-watchdog.timer：每30分钟
• cleanup-smartcam-data.timer：启动或重新启用后5秒内首次检查，之后每次清理完成60分钟后再次检查
• cleanup-smartcam-data-resume.timer
• smart-cam-live-frpc.service：仅选择公网直播时安装并启动；与已有摄像头FRP服务相互独立

日夜切换单元的职责是互斥且不重复的：smart-cam-mode-restore.service只在开机时根据当前北京时间恢复一次，smart-cam-mode-restore.timer使用OnActiveSec=3min，只在timer启用3分钟后、系统校时完成后复核一次；它不会像OnBootSec那样在运行很久的设备上首次部署时立即补跑。06:00和19:00两个边界service分别只执行明确的日间、夜间切换。两个边界timer使用Persistent=false，设备关机期间错过的旧边界不会在开机时同时补跑，当前模式统一由restore服务判定。smart-cam.service只依赖restore服务的完成结果，不再通过ExecStartPre重复执行恢复脚本。

两个看门狗只会在自己一次检查完成后再计时30分钟。它们在重启容器前同时获取扫图重启禁止锁和容器生命周期锁，因此不会在扫图期间重启，也不会与日间/夜间模式切换同时重启。

手动修改日间/夜间时间

默认北京时间06:00进入日间完整模式，19:00进入夜间仅上传模式。现场修改时使用systemd drop-in，不要改单元文件名。例如改为07:30开始、20:15结束：

sudo systemctl edit smart-cam-daily-start.timer

填入：

[Timer]
OnCalendar=
OnCalendar=*-*-* 07:30:00

再执行：

sudo systemctl edit smart-cam-daily-stop.timer

填入：

[Timer]
OnCalendar=
OnCalendar=*-*-* 20:15:00

最后重载、重启定时器并立即按当前北京时间对齐一次模式：

sudo systemctl daemon-reload
sudo systemctl restart smart-cam-daily-start.timer smart-cam-daily-stop.timer
sudo systemctl start smart-cam-mode-restore.service
systemctl list-timers --all 'smart-cam-daily-*'

drop-in中第一行空的OnCalendar=必须保留，它用于清除原时间，避免新旧两个时间同时触发。要恢复包内默认时间，执行sudo systemctl revert smart-cam-daily-start.timer smart-cam-daily-stop.timer，然后再执行上述重载和重启命令。

升级、失败和回退原则

• 部署脚本不会删除已有smart-cam容器。
• 旧容器会重命名为smart-cam-before-20261013-日期时间。
• 新旧容器共享的/userdata/data是持久化业务数据，不能通过删除容器回滚数据内容。
• 如果部署在停止旧容器前失败，旧服务不受影响。
• 如果停止旧容器后失败，终端会打印旧容器备份名称，便于人工检查和回退。
• 已存在的smart-cam专用直播FRP配置在修改前会备份；其他FRP配置和服务完全不动。

部署成功判定

日间部署时，脚本要求以下项目全部成功：

• smart-cam.service处于active。
• 扫描/巡航控制接口健康。
• 自动追踪接口健康。
• 盒子内部直播控制接口健康。
• 自动清理timer处于active。

夜间19:00至次日06:00部署时，脚本遵循仅上传设计，不要求扫描、追踪和直播接口启动，而是验证上传进程存在。

更换目标检测模型

• detection.model_path指向新的RKNN，detection.labels_path必须指向该模型实际类别文件；标签一行一类，数量和顺序必须与模型输出一致。
• 输入宽高不需要写进config.json。程序在初始化时读取RKNN输入张量，按该尺寸创建RGA预处理并依据输出特征图自动计算stride；原始YOLOv5输入宽高应能被最大检测stride整除。
• 原始输出YOLOv5支持3个或4个检测头、每个检测头3组任意正数anchors。所有YOLOv5统一读取/smart-cam/models/yolov5_anchor.txt，文件内容按从小stride到大stride的检测头顺序排列；模型名称变化时无需改anchor文件。
• raw-head RKNN文件本身通常不保留可可靠读取的anchors，端侧不能从输出张量反推出训练anchors。只有新模型的训练anchors确实变化时，才需要替换全局yolov5_anchor.txt。交付包提供scripts/export-yolov5-metadata.py，可在x86的YOLOv5训练/导出环境中从可信.pt生成该文件和模型同名标签：

python3 scripts/export-yolov5-metadata.py \
  --weights /path/to/best.pt \
  --rknn /path/to/bird.rknn

• YOLOv8是一输出合并布局或九输出分离布局时为anchor-free，程序不会读取yolov5_anchor.txt。

config.json完整参数说明

以下说明对应镜像内/smart-cam/config/config.json。相对路径均以/smart-cam为基准； 布尔值必须使用JSON的true/false。同一设备的摄像头连接信息只有video.source一个来源， 芯片平台不写入本文件，而由部署脚本自动识别并选择模型。

设备、输入和检测

参数	当前默认值	实际作用
system.name	Smart Camera System	配置所属系统的名称标记；当前业务逻辑不读取，但必须保留用于识别配置来源。
system.version	1.2.0	config.json结构版本标记；当前业务逻辑不读取，但后续配置迁移以它为依据。
device.id	V200202608100000	Kafka消息的sensor.id、上传远端目录和设备身份。部署时用回答的设备编号覆盖。
video.source	海康主码流RTSP URL	唯一的摄像头IP、RTSP端口、账号、密码来源；启动脚本据此派生所选厂商的SDK和HTTP连接。
video.width / video.height	1920 / 1080	解码后供检测、绘制、识别后直播和标注录像共同使用的唯一处理/输出分辨率。可按资源提高到2560/1440；3840/2160只适合需要真4K且资源足够的设备。都设为0才按输入流原始分辨率处理。
video.frame_skip	1	每隔多少个采集帧送一次后续链路；1表示不主动跳过。实时源仍会丢弃已经过期的队列帧来保持低延迟。
detection.model_path	当前平台YOLOv5 RKNN	直播检测、扫图小图检测、巡航点生成和自动追踪共同使用的目标检测模型。部署时自动改为RK3576或RK3588版本。
detection.labels_path	当前检测模型标签TXT	检测类别名称，一行一个，数量和顺序必须与RKNN输出完全一致；目标类别ID和画面框名称均以此文件为准。
detection.confidence_threshold	0.5	检测结果进入跟踪、分类、绘制等主链路的最低置信度。
detection.nms_threshold	0.3	检测后处理NMS的IoU阈值。
detection.target_classes	[0]	只保留指定检测类别ID；当前鸟类检测模型的鸟类ID为0。

YOLOv5 anchors不属于运行策略配置，固定读取/smart-cam/models/yolov5_anchor.txt。启动时一次性 校验检测头数量乘每头3对anchors所需的全部正数；更换文件名或使用相同anchors的新模型时无需 改它。RKNN原始检测头中通常没有足够信息可靠反推出训练anchors，所以真正更换anchors时仍需 从训练权重导出并覆盖该文件。YOLOv8输出布局被识别后完全跳过此文件，不产生每帧额外开销。

跟踪、直播输出和坐标输出

参数	当前默认值	实际作用
tracking.enabled	true	是否运行ByteTrack并给检测目标分配稳定ID。自动追踪依赖目标ID。
tracking.max_age	10	目标短暂未匹配时保留轨迹的最大处理帧数。
tracking.iou_threshold	0.15	检测框与已有轨迹匹配的最低IoU。
tracking.ghost_max_age	0	0禁用跟踪幽灵框和光流预测；显示层按目标ID分别保留最近一次真实检测，并从推理结果实际到达绘制线程的时刻开始动态保留450～700ms。画面和目标基本静止时，还会对框中心及宽高做小死区、有限幅低通，消除框上下拉伸；目标或镜头明显移动时立即使用新框。该显示稳定不回写检测结果，不参与自动追踪、录像或业务判定。
tracking.ghost_solid_style	false	启用幽灵框时，true用普通实线，false用半透明虚线。
rtsp_output.enabled	1	是否提供叠加识别结果后的RTSP直播。
rtsp_output.url	rtsp://0.0.0.0:8554/live	容器内RTSP监听地址、端口和路径。
rtsp_output.bitrate	0	识别后直播H.264码率（kbps）。0为自动：常用1440p/15fps约9600kbps、1080p/15fps约7200kbps、4K/15fps约14400kbps；正数表示强制码率。直播分辨率直接使用video.width/height，没有独立输出宽高参数。
coord_output.enabled	true	是否通过UDP发布检测框坐标，供已有外部坐标消费者使用。
coord_output.port	9000	坐标UDP目标端口。
coord_output.dest_ip	255.255.255.255	坐标UDP目标IP或域名；当前为局域网广播。
coord_output.normalize	false	true输出0到1归一化坐标，false输出像素坐标。

标签、录像和上传

参数	当前默认值	实际作用
voc_labels.enabled	true	是否为触发的标注录像生成对应VOC XML。
voc_labels.output_dir	data/annotations	XML目录。实际宿主持久化位置为/userdata/data/annotations。
voc_labels.database_name	BirdDetection	写入XML <database>的来源名称。
recording.enabled	1	是否生成识别后标注录像并触发独立原始码流录像。
recording.save_raw_video	1	是否同时保存摄像头原始码流片段。
recording.output_dir	data/videos	标注录像目录；原始录像使用其同级data/videos_raw。
recording.codec	h264	标注录像硬编码不可用时的软件编码回退格式；正常路径使用MPP H.264。
recording.min_detection_confidence	0.3	录像事件候选的最低检测置信度。
recording.segment_seconds	15	本地视频文件作为输入时的分段时长；摄像头RTSP触发录像由record_seconds控制。
recording.record_seconds	30	RTSP检测事件每段录像的墙钟时长。
recording.detection_confirm_window	25	录像确认滑动窗口大小，单位为处理帧。
recording.detection_confirm_min_frames	15	上述窗口内至少多少帧有目标才确认录像事件。该门槛不再阻塞自动追踪。
upload.videos.enabled	false	是否SFTP上传标注视频。关闭时本地仍会生成标注视频。
upload.videos.kafka_topic	deepstream_e2c_cam	标注视频组启用时投递的Kafka topic。与主topic相同只投递一次。
upload.videos.storage_namespace	smart_cam	标注视频远端路径中的存储命名空间。
upload.videos.root_dir	/storage2/file/remote_sync	标注视频组的SFTP根目录。
upload.videos_raw	true	是否SFTP上传原始视频。
upload.annotations	true	是否SFTP上传VOC XML。
upload.kafka_topic	deepstream_e2c_cam	原始视频/XML组完成SFTP后投递的Kafka topic。
upload.storage_namespace	smart_cam	原始视频/XML远端路径中的存储命名空间。
upload.server.host	60.10.24.48	SSH/SFTP/Kafka部署侧使用的后台主机。
upload.server.port	60013	后台SSH/SFTP端口。
upload.server.username	user	后台SSH/SFTP用户名。认证使用部署登记的私钥，不在JSON保存后台密码。
upload.root_dir	/storage2/file/remote_sync	原始视频/XML的SFTP根目录。

每个三件套先等待XML及启用上传的文件稳定，再完成全部SFTP上传，最后发送Kafka并等待broker确认。 Kafka的@timestamp来自文件名video_YYYYMMDD_HHMMSS_mmm中的录像开始墙钟时间，直接格式化为原消费者兼容的ISO-8601 ...Z字符串，不再做北京时间到UTC的8小时偏移； 消息字段、topic、key和其他内容不变。旧文件名无法解析时才回退到XML时间或文件修改时间。

可视化、分类和密度估计

参数	当前默认值	实际作用
visualization.font_path	fonts/NotoSerifCJK-Regular.ttc	中文类别、数量等叠加文字字体。
visualization.logo_path	src/blank.png	右上角Logo图片；空白图表示不显示可见Logo。
visualization.logo_width	100	Logo目标宽度，像素。
visualization.logo_height	0	Logo目标高度；0按原图宽高比自动计算。
visualization.logo_x / visualization.logo_y	1170 / 10	以1920x1080为基准的Logo左上角坐标，其他处理分辨率按比例缩放。
classification.enabled	true	是否对检测框执行鸟种分类。
classification.model_path	当前平台分类RKNN	分类模型；部署时自动选择对应芯片版本。
classification.labels_path	当前平台标签TXT	分类类别名称，行号必须与模型输出类别顺序一致。
classification.taxonomy_path	空字符串	可选分类学映射文件；为空时直接采用模型标签。
classification.catalog_enabled	false	是否把分类概率限制在保护区物种名录内；启用时必须同时提供taxonomy。
classification.catalog_path	config/reserve_species.txt	保护区候选物种名录文件。
classification.confidence_threshold	0.3	单次分类结果进入加权投票的最低置信度；低于此值视为弃权。
classification.immediate_display_confidence	0.55	新目标第一次分类达到该值时立即显示临时物种标签；未达到时，两次一致且票权占比至少70%也会提前显示。最终稳定标签仍需三次加权投票中至少两票一致。
classification.min_catalog_probability_mass	0.1	启用名录约束时，原始概率落入名录内的最低总概率；不足则不强行给具体物种。
classification.debug	false	是否输出分类张量和概率调试日志。
classification.stabilize_window	20	每个跟踪ID保留的独立ConvNeXt分类结果数量，不是视频帧数。
classification.track_confirm_frames	20	一个跟踪ID用于录像去重和物种覆盖判定前所需的YOLO观测数；不阻塞直播中的首次物种显示。
classification.relabel_report.enabled	false	是否记录名录约束前后标签变化统计。
classification.relabel_report.interval_minutes	1440	重标统计汇总输出周期，分钟。
classification.relabel_report.output_file	data/logs/species_relabel_report.log	重标统计日志路径。
classification.relabel_report.max_file_size_kb	1024	重标统计日志轮转阈值，KiB。
classification.coarse_fallback_map	{"bird":"鸟"}	分类未得到可靠细类时，检测粗类到中文显示名的映射。
density.enabled	true	是否运行密度估计模型并叠加热力图和总数。
density.model_path	当前平台密度RKNN	密度估计模型；部署时自动选择对应芯片版本。
density.infer_interval	100	每多少个处理帧更新一次密度估计，其余帧复用最近结果。
density.debug	false	是否输出密度模型张量和推理调试日志。
density.heatmap_scale	0.25	右下角热力图宽高相对当前画面的比例。

自动追踪

参数	当前默认值	实际作用
auto_tracking.enabled	true	自动追踪总开关。
auto_tracking.event_host / event_port	127.0.0.1 / 19001	C++检测主链路向追踪控制器发布最新目标集合的本机UDP地址。
auto_tracking.publish_interval_ms	100	检测目标集合最短发布间隔，毫秒。
auto_tracking.scan_http_url	http://127.0.0.1:18080	追踪控制器读取巡航状态并发送PTZ动作的扫描服务地址。
auto_tracking.interval_seconds	0.09	中档追踪控制轮询周期，秒；低/高档为0.12/0.07秒。轮询本身不增加模型推理频率。
auto_tracking.aggregation_window_seconds	0.18	每一步计算只聚合该时间窗内、且晚于上次PTZ动作的新检测样本。
auto_tracking.minimum_samples	1	严格清空旧帧并按采集时间拒绝移动前画面后，首个新检测样本即可参与计算，缩短巡航画面刚切换时的启动时间。
auto_tracking.confidence_threshold	0.55	自动追踪独立置信度门槛。检测绘框门槛当前为0.5；降至0.55后缩小“已有框但未追踪”的区间，同时保留少量余量过滤临界误检。目标达到该值即进入自动追踪，不等待录像确认窗口。
auto_tracking.post_move_frame_delay_seconds	0.02	中档PTZ指令完成后的额外画面保护时间；高档为0，旧帧仍由采集时间戳强制拒绝。
auto_tracking.motion_feedback_timeout_seconds	0.4	云台坐标粒度过粗且画面尚未体现位移时，等待可见反馈的最长时间；低/高档为0.55/0.30秒。
auto_tracking.driver_settle_ms	140	中档自动追踪专用的动作制动回读等待；低/高档为220/100ms，不改变人工控制、巡航和扫图的完整到位等待。
auto_tracking.post_motion_identity_grace_seconds	1.2	自己完成一次PTZ动作后的目标ID重关联窗口。同数量目标在窗口内整体换ID不重置两分钟追踪预算；目标数量增加仍按新鸟处理。
auto_tracking.center_deadzone_ratio	0.07	画面中心基础缓冲区比例；控制器还会根据当前zoom和实测最小步长动态扩大。
auto_tracking.max_target_jump_ratio	0.3	相邻新画面中目标联合框中心允许的最大跳变，用于过滤错误关联。
auto_tracking.stable_windows	1	新会话启动前需要连续有效的聚合窗口数。
auto_tracking.max_follow_distance_deg	45	一次追踪会话相对巡航锚点允许移动的最大角距离。
patrol.tracking_range_ratio（追踪距离百分比）	0.3	将本次巡航路线的水平、垂直总范围各乘30%得到当前点位允许偏移，再与max_follow_distance_deg取更严格的限制；这就是“只能追踪整个巡航范围百分之多少”的参数。
auto_tracking.max_follow_seconds	120	画面目标ID集合没有新增ID时的连续追踪上限；出现新ID立即重置，上限不延长巡航点5分钟总倒计时。
auto_tracking.lost_grace_seconds	10	目标暂时消失后继续等待的宽限时间。
auto_tracking.rearm_absence_seconds	15	达到时间/距离上限后，同批目标需连续消失多久才允许重新建立会话。新ID不受此等待限制。
auto_tracking.speed_profile	medium	当前追踪速度档：low、medium或high；使用运维命令切换后会持久化。
auto_tracking.speed_profiles.*	见下文	三档完整参数组。当前档位会覆盖下面的平移/俯仰和变倍基准参数；需要微调某一档时修改对应参数组。
auto_tracking.pan_tilt.speed	7	中档平移/俯仰的最高速度档，不是每一步固定使用的速度；控制器会按误差和zoom动态选择。
auto_tracking.pan_tilt.min_speed	1	动态选档的最低速度。提高到2会整体加快远目标追踪，但高zoom和近中心时更容易过冲。
auto_tracking.pan_tilt.zoom_speed_weight	0.55	zoom对速度上限和选档的抑制权重，范围0～1；低/高档为0.75/0.40。倍率越高，允许的最高齿轮越低，避免高倍焦短促猛冲。
auto_tracking.pan_tilt.response_gain / response_curve	1.95 / 0.65	从目标中心误差映射到速度档位的比例增益和曲线；高档更快捕获，但仍受zoom封顶和单步硬制动约束。
auto_tracking.pan_tilt.far_error_ratio / far_min_speed	0.14 / 6	中档目标中心偏差达到0.14时请求至少6档，高档偏差0.10以上请求7档；最终齿轮仍受当前zoom自动封顶。
auto_tracking.pan_tilt.approach_ratio	0.60	每一步计划消除的位置误差比例，范围0.2～1；还会受下面两个防越界硬上限约束。
auto_tracking.pan_tilt.no_cross_step_ratio	0.73	单步最多消耗“当前中心误差减缓冲区”中的73%；低/高档为68%/76%。它保证动作不越过剩余中心误差。
auto_tracking.pan_tilt.response_safety_ratio	1.18	对在线实测云台响应再加18%制动余量；低/高档均为20%。目标自身运动导致一次响应估计偏小时，不会据此发出长脉冲。
auto_tracking.pan_tilt.max_screen_step_ratio	0.13	中档一次动作最多计划移动整幅画面的13%；低/高档为10%/16%。它与no_cross_step_ratio取更严格者。
auto_tracking.pan_tilt.min_duration_ms / max_duration_ms	60 / 480	中档配置脉冲范围。程序还按齿轮设置平滑最小持续时间：低齿轮用更长的连续移动代替高齿轮短促启停；若仍可能越过中心则继续降档或保持不动。
auto_tracking.pan_tilt.settle_seconds	0.03	中档平移/俯仰后等待下一次闭环计算的最短时间。
auto_tracking.pan_tilt.reversal_deadzone_ratio	0.145	方向反转的加宽缓冲区；低/高档为0.14/0.15，避免刚越过中心就反向。
auto_tracking.pan_tilt.reversal_confirm_cycles	2	反向偏差必须在连续新画面中出现的次数，防止单帧检测跳动触发震荡。
auto_tracking.pan_tilt.crossing_hold_seconds	1.25	确认跨越中心后的反向制动保护时间；低/高档为1.15/1.35秒。
auto_tracking.pan_tilt.invert_pan / invert_tilt	false / false	仅当摄像机安装/图像旋转造成控制方向相反时，分别反转水平或垂直屏幕方向。
auto_tracking.zoom.enabled	true	是否允许自动变倍。
auto_tracking.zoom.single_target_area_ratio	0.3	单目标最终框面积占整幅画面的目标比例。
auto_tracking.zoom.multiple_target_area_ratio	0.5	多目标最左/右/上/下边界组成的联合框目标面积比例。
auto_tracking.zoom.hysteresis_ratio	0.05	面积目标的基础滞回带；反向变倍还使用更宽的持久Schmitt带，防止放大/缩小震荡。
auto_tracking.zoom.min_zoom / max_zoom	100 / 4000	允许的绝对zoom范围；仍受相机实际能力和每个巡航点学习边界约束。
auto_tracking.zoom.speed / min_speed	6 / 1	中档变倍最高/最低速度。控制器按目标面积误差和当前zoom动态选档，接近目标面积或高倍焦时自动降档。
auto_tracking.zoom.zoom_speed_weight	0.60	当前光学倍率对变倍齿轮上限的抑制权重；低/高档为0.80/0.45。
auto_tracking.zoom.response_gain / response_curve	1.6 / 0.68	面积误差映射到变倍档位的比例增益和曲线。
auto_tracking.zoom.min_duration_ms / duration_ms	220 / 520	中档在1×附近的最小和最大/基准变倍脉冲；倍率升高后程序按比例缩短（不低于120ms）。
auto_tracking.zoom.approach_ratio	0.52	学到镜头变倍响应后，每一步计划消除的zoom误差比例。
auto_tracking.zoom.min_target_size_px	24	缩小时保护最小单框宽高，避免小目标因继续缩小而丢失。
auto_tracking.zoom.stable_cycles	2	普通同方向变倍连续确认周期数。
auto_tracking.zoom.centered_cycles	2	放大前目标联合框必须连续居中的严格新画面数；缩小保护画面边界不受此项阻塞。
auto_tracking.zoom.after_pan_observe_seconds	0.20	平移/俯仰后至少观察多久才允许放大，避免边移动边盲目放大。低/高档为0.30/0.12秒。
auto_tracking.zoom.max_zoom_in_step_ratio	0.21	1×时单次放大倍率增量上限；高倍焦还会继续按倍率衰减。低/高档为0.18/0.24。
auto_tracking.zoom.max_zoom_out_step_ratio	0.16	普通单次缩小倍率比例上限；低/高档为0.14/0.18，高倍焦继续衰减。
auto_tracking.zoom.urgent_max_zoom_out_step_ratio	0.28	目标触碰5%安全边界时允许的紧急单步缩小上限；低/高档为0.24/0.30。
auto_tracking.zoom.reverse_confirm_cycles	3	变倍反转必须连续出现的严格新画面数；高档为4，边界保护型缩小也不能绕过。
auto_tracking.zoom.reverse_observe_seconds	0.9	上一次变倍后允许反向前的最短观察时间；高档为1.0秒。
auto_tracking.zoom.reversal_area_ratio	0.145	反向变倍使用的加宽面积滞回带；低/高档为0.14/0.15，框面积小幅波动不会触发放大/缩小反复切换。
auto_tracking.zoom.reversal_lock_seconds	4.5	完成一次变倍反转后禁止再次反转的时间；高档为4秒。联合框确实大到画面放不下时仍可立即缩小保护边界。
auto_tracking.zoom.area_smoothing_alpha	0.4	新画面框面积进入变倍控制值的权重；高档为0.45。首次目标立即采用真实面积，后续单帧框大小跳变不会直接触发反向。
auto_tracking.zoom.settle_seconds	0.8	普通变倍后等待下一次变倍的时间，期间仍可平移追踪；该静止窗口让摄像头自动对焦完成。低/高档为1.0/0.65秒。
auto_tracking.zoom.edge_settle_seconds	0.35	为保护画面边缘而紧急缩小时的最短稳定等待；低/高档为0.5/0.28秒。
auto_tracking.control.manual_override_seconds	300	平台HTTP人工PTZ接管的滑动保护时间，秒；每条平台PTZ请求都会重新开始5分钟计时。
auto_tracking.http.host / http.port	0.0.0.0 / 18081	自动追踪健康、状态和控制接口监听地址。

所有有效目标先组成一个联合框。每次最多发一条对角平移/俯仰指令或一条变倍指令， 动作后丢弃旧检测帧，再依据移动后的新画面重新计算。框边界距离画面四边至少5%是程序固定安全约束， 不是可调JSON项；当“居中”和“5%边界”冲突时先缩小保证边界，再继续居中。

自动追踪速度组合调节

无需手改多项参数，直接在低、中、高档之间任意切换：

docker exec smart-cam smart-camctl tracking speed low
docker exec smart-cam smart-camctl tracking speed medium
docker exec smart-cam smart-camctl tracking speed high

不是只能向上逐档切换，三条命令可从当前任意档直接切到指定档。tracking status会显示当前档位，切换结果写入config.json，容器重启后保持。三档实际组合：

三档会同时改变两类速度：一类是控制轮询、动作后等待、反馈超时等“取得下一次追踪决策”的速度；另一类是PTZ齿轮、单步脉冲和单步画面位移上限等“执行本次移动”的速度。因而切换档位不是只改变摄像头电机速度。

档位	平移/俯仰组合	变倍组合	适用场景
低档 low	最高5档；40×附近自动封顶约2档；单步画面上限10%	最高5档；单步放大/缩小基准上限18%/14%；变倍后观察1秒	近目标或机械响应很猛的摄像头，稳定优先。
中档 medium	最高7档；40×附近自动封顶约3档；单步画面上限13%	最高6档；单步放大/缩小基准上限21%/16%；变倍后观察0.8秒	默认档，兼顾野外移动目标和观感。
高档 high	最高7档；40×附近自动封顶约4档；单步画面上限16%	最高7档；单步放大/缩小基准上限24%/18%；变倍后观察0.65秒	野外游禽、跑动鹬类等较快目标；速度更高但仍不允许一步跨越中心。

高档远离中心时会请求高齿轮，但最终齿轮必须经过当前zoom封顶；40×附近不再使用7档短脉冲。每一步同时受“剩余中心误差比例”和“整幅画面位移比例”限制，首次动作还使用保守相机响应先验，在线学到真实响应后继续按更严格值制动。低齿轮使用较长连续脉冲，减少短促启停造成的一撮一撮观感。平移/俯仰反转仍必须在连续两个严格新画面中成立；确认跨越中心后还会扩大反向缓冲并短时制动。变倍只有在目标连续居中后才开始，每次只推进一小段，随后保留自动对焦观察时间，再从严格新画面重算。受检测漏检、遮挡、网络帧延迟和云台机械极限影响，软件不能承诺任何现场目标绝对不丢失。

程序还会按“水平/垂直轴 × 速度档”学习最小有效脉冲。如果一次短脉冲的PTZ回读和新画面都确认没有移动，下次自动增加该档最小脉冲；增加后可能越过中心则保持该轴不动。相邻两步不是固定定时发送：每轮必须完成当前脉冲、SDK回读、丢弃旧帧和取得严格新检测结果。新版本压缩了无效反馈超时，因此大多数轮次更接近，但机械动作时长、RTSP延迟和目标检测结果决定它不会成为完全相同的固定间隔。

pan_tilt.speed和zoom.speed只是速度上限。整体响应速度还由单步脉冲、zoom抑制、动作后等待和新画面确认共同决定。如需在预设档基础上继续针对某个点位微调，请修改当前档位对应的auto_tracking.speed_profiles.<档位>，不要只改外层基准值：

目标	建议组合	代价/注意事项
野外远目标快速追踪	先使用默认medium；快速游动仍跟不上再切high	新中档已接近旧高档；防越界上限始终生效，不建议单独放大最长脉冲。
摄像头低档位过慢	提高response_gain或降低response_curve；确有需要再提高min_speed	前两项主要加快中远距离，较少影响近中心制动。
小鸟需要尽快放大	使用high档；仍慢时小幅提高该档zoom.response_gain或duration_ms	若放大过头，先降低response_gain、duration_ms或approach_ratio。
近距离/办公室减少震荡	min_speed=1、zoom_speed_weight=0.6～1.0、approach_ratio=0.55～0.7，适当提高center_deadzone_ratio和zoom.hysteresis_ratio	更稳但追踪移动目标会变慢。
缩短两步之间等待	优先选择更高速度档；不要继续降低driver_settle_ms、motion_feedback_timeout_seconds或post_move_frame_delay_seconds	默认值已按现场压缩。两步仍需依次等待脉冲执行、SDK回读和严格新画面，因此不会是绝对固定间隔。

程序在每次动作后清空检测队列，并按视频帧采集时间拒绝动作前旧帧，因此minimum_samples=1不会复用旧画面。变倍后即使SDK倍率坐标已经改变，也要等新画面面积出现预期变化（或达到短反馈超时）才计算下一步，避免在RTSP内容尚未更新时连续发命令。检测模型实际推理速度、摄像头机械响应和RTSP延迟仍是现场速度上限。

巡航、扫图和直播会话

参数	当前默认值	实际作用
patrol.enabled	true	是否运行自动巡航。
patrol.max_points	20	从扫图结果选取的最大巡航点数量；永久人工点另外合并。
patrol.dwell_seconds	300	每个巡航点到位后立即开始的总驻留倒计时，秒；自动追踪不会暂停该倒计时。
patrol.preview_hold_seconds	120	执行smart-camctl patrol preview后的预览倒计时，秒；再次查看下一点会重新计时并中断当时的录像。倒计时内禁止自动触发录像，但允许手动录像和自动追踪；到期后从当前画面开始一个且仅一个完整巡航驻留周期。
patrol.tracking_range_ratio	0.3	追踪相对当前巡航点可用角度范围占整个扫图/巡航范围的比例；自动追踪章节也列出了其与绝对角度上限的共同作用。
patrol.manual_resume_seconds	300	从最后一条平台HTTP人工PTZ指令到返回原巡航点/扫图点的保护时间；期间全部自动PTZ让权。厂商客户端移动不会触发。
patrol.zoom_search_after_seconds	120	到点后连续多久未发现目标才开始通过变倍搜索，秒。
patrol.zoom_search_interval_seconds	10	无目标变倍搜索两步之间的间隔，秒。
camera.vendor	hikvision	摄像头厂商唯一开关，只允许hikvision或tiandy。
scan.enabled	true	扫图和扫图计划总开关。
scan.pan_start / pan_end / pan_step	11590 / 20280 / 1738	水平方向扫描起点、终点和步长，使用厂商适配层统一后的PTZ整数单位。
scan.tilt_start / tilt_end / tilt_step	180 / 2122 / 971	垂直方向扫描起点、终点和步长。
scan.zoom	340	扫图使用的绝对zoom值。
scan.move_wait	0.5	发出绝对定位后开始检查前的等待时间，秒。
scan.capture_wait	1.0	到位后截图前等待画面稳定的时间，秒。
scan.focus_wait	1.0	触发聚焦后等待完成的时间，秒。
scan.move_timeout	35	单个点位移动的总超时，秒。
scan.pan_tolerance / tilt_tolerance / zoom_tolerance	70 / 45 / 20	判定已到位的P/T/Z允许误差。
scan.stable_checks	2	连续多少次坐标落入容差才判定稳定到位。
scan.stable_wait_ms	300	到位稳定检查间隔，毫秒。
scan.output_dir	/smart-cam/data/scan	扫图图片、批次元数据和状态输出目录。
scan.schedule.enabled	true	是否启用每日定时扫图。
scan.schedule.check_interval_seconds	30	定时器检查计划的间隔，秒。
scan.schedule.catch_up_window_minutes	30	计划时刻错过或被占用后的补扫窗口，分钟。
scan.schedule.retry_interval_seconds	60	补扫窗口内启动失败后的重试间隔，秒。
scan.schedule.times	["09:00","16:00"]	每日扫图时间列表，使用设备本地时区。
scan.image.width / scan.image.height	1280 / 720	每个扫图点保存及送入同一检测模型的小图尺寸。
scan.image.timeout	20	单张摄像头抓图请求超时，秒。
scan.http.host / scan.http.port	0.0.0.0 / 18080	扫图、巡航和摄像头PTZ控制接口监听地址。
live_stream.enabled	true	是否启用按需公网/网页直播控制服务。
live_stream.viewer_max_seconds	300	每个观看者各自一次播放会话允许的最长时间，秒；从该观看者首次请求实际播放清单开始计时，请求分片不会续期，到期返回终止清单并断开该会话，重新打开直播才生成新的独立倒计时。
live_stream.idle_shutdown_seconds	300	最后一个观看者离开后，按需直播转码链路延迟关闭的时间，秒。