企业官网建设流程全解析

15-部署与二次开发：从demo到产品化的完整路径

1. 开篇：十四篇铺垫，最后一脚

回头看整个系列，像看一场施工直播：

• 第 1~5 篇：把"识别钓鱼漂相"这个想法拆成四类漂相（下顿、顶漂、黑漂、点漂），设计了系统骨架——安卓推流 + Python 识别，纯局域网。
• 第 6~7 篇：目标跟踪。用 2D 恒速卡尔曼滤波平滑轨迹，用 ByteTrack 风格两级 IoU 匹配跟踪目标。
• 第 8~11 篇：漂相识别。三通道 EMA 平滑信号、四态状态机、波浪幅度估计抗风浪、事件化输出。
• 第 12 篇：合成视频生成器，让系统在没有真鱼塘的日子里也能自测。
• 第 13 篇：量化评估体系，查全率/查准率 + 事件匹配，用压测报告给系统"称重"。
• 第 14 篇：检测器无缝切换，HSV 规则和 YOLO 深度学习后端并存，一行配置切换。

这一整套，检测→跟踪→识别→抗风浪→服务→安卓→测试→评估，全链路闭环。今天的收尾篇就干三件事：

1. 怎么部署：三个命令把系统跑起来。
2. 怎么调：一张参数速查表，看懂全部可调旋钮。
3. 怎么二次开发 + 产品化：五大扩展点、FAQ 排查、从 demo 到产品的路怎么走。

先说好，本篇不是"到此结束"，而是"从这里开始"——部署和二次开发，才是系统真正开始被使用、被打磨的起点。看完这篇，你应该能把项目跑起来、把参数调顺手、知道往哪个方向扩展，并且心里有一张"产品化还要补哪些课"的清单。

2. 环境要求：轻得令人发指

先说最低门槛，这可能是你见过的对机器最友好的 CV 项目之一：

服务端（PC）

• Python 3.9+
• 识别核心零第三方算法依赖，只需要 OpenCV + numpy 两个包
• 内存 4GB 够用，CPU 即可（不强制 GPU）

pipinstallopencv-python numpy

就这两行。没有 CUDA、没有 CUDA Toolkit、没有深度学习全家桶。识别核心零第三方依赖这句话，从第 1 篇说到第 15 篇，含金量体现在这里——你真去 pip 装一遍就知道多省事。

安卓端（手机）

• Android 8.0+（CameraX 的最低系统要求）
• 支持 CameraX 的主流机型即可，不需要旗舰

网络

• 纯局域网：手机和 PC 连同一个 WiFi，数据全程不出这个网络。不上云、不联网、不经过任何第三方服务器。

3. 快速开始：三个命令跑通全系统

3.1 第一步：装依赖

cdauto-fishing python-mvenv .venv# 建议建虚拟环境，隔离依赖# Windows: .venv\Scripts\activate Linux/Mac: source .venv/bin/activatepipinstallopencv-python numpy

3.2 第二步：一行命令自检

装完先别急着连手机，跑一个内置自检——用第 12 篇的合成视频把全流程（检测→跟踪→识别→评估）走一遍：

python main.py demo--wavemedium--seed0

这条命令会：生成一段 60 秒合成钓鱼视频 → 跑完整识别管线 → 自动匹配事件 → 输出评估报告。看到类似下面这种输出，说明核心链路是通的：

漂相类型 | TP | FP | FN | 查全率 | 查准率 ---------|----|----|----|--------|-------- 下顿 | 8 | 0 | 0 | 1.00 | 1.00 顶漂 | 5 | 0 | 0 | 1.00 | 1.00 ...

顺带把项目的三种演示方式一次列全，不同阶段总有对应的一条路：

1. 零素材演示：python main.py demo—— 自动生成含四种漂相的合成钓鱼视频，识别并输出评估报告，一分钟内跑通全流程，不需要任何素材；
2. 实时演示：电脑跑python main.py server，手机装 App 后同一 Wi-Fi 连上即可，摄像头对准水面浮漂，语音播报实时响起；
3. 压力演示：python tools/stress_test.py—— 4 档波浪 × 多场景，直观展示抗风浪能力。

3.3 第三步：启动服务端

python main.py server--port8888--bind0.0.0.0

服务端监听所有网卡，等手机来推流。启动后看到[INFO] server listening on 0.0.0.0:8888就绪。

3.4 第四步：安卓端

1. 用 Android Studio 打开android/FloatDetectApp目录（首次会下载 Gradle 依赖，喝杯茶）。
2. 改一个配置：MainActivity.kt或local.properties里把服务端 IP 填成 PC 的局域网 IP（Settings → MainActivity里有专门入口，下文 FAQ 会讲怎么找 IP）。
3. USB 连手机或无线调试，点 Run。App 起来后对准浮漂，漂相识别结果就出现在服务端日志和手机上。

IP 怎么找？PC 上打开命令行：

• Windows：ipconfig，找"无线局域网适配器 WLAN"里的 IPv4 地址，形如192.168.x.x；
• Mac/Linux：ifconfig，找en0里的inet地址。

填进 App 的服务器设置，确认手机和 PC 前缀一致（都是192.168.x）才说明在同一个局域网。填完先用手机浏览器访问http://PC的IP:8888/ping，能看到{"status":"ok"}之类的应答，说明网络链路通了，再开 App 推流——这一步能帮你把"网络问题"和"App 问题"一刀切开。

从零到跑通，核心命令就两条（pip install和python main.py server），其余全是图形界面点按钮。

4. 网络拓扑：一张图看懂数据流

┌──────────────────────┐ WiFi 局域网 ┌──────────────────────┐ │ 手机（安卓） │ ────────────────────────▶ │ PC（服务端） │ │ FloatDetectApp │ MJPEG/H.264 视频推流 │ Python 识别核心 │ │ │ │ │ │ · CameraX 采集 │ ◀──────────────────────── │ · 检测(HSV/YOLO) │ │ · 实时预览漂相 │ JSON 识别结果回调 │ · 卡尔曼平滑 │ │ · 报警提示/声音 │ (漂相类型/时间/置信度) │ · 跟踪(IoU匹配) │ │ │ │ · 状态机识别 │ │ IP: 192.168.1.100 │ │ · 事件输出/日志 │ └──────────────────────┘ │ IP: 192.168.1.50 │ └──────────────────────┘

数据流只有两段，全部在局域网内：

1. 上行：手机把摄像头画面压缩后推给 PC（30fps，640×480 起步）。
2. 下行：PC 识别出漂相后，把事件结果（{kind: "down", time: 12.3, conf: 0.92}）回传手机，手机弹报警。

没有任何一段经过公网。这是本项目最硬的隐私卖点，后面产品化章节还会展开讲。

5. 配置总览：一张参数调优速查表，二次开发的地图

config.py是全部旋钮的集中地，分六个区。新手拿到手最该做的事，就是把这张表存下来，改参数时对着查。

5.1 参数速查表

5.2 新手调参三板斧（先记住这三组）

第一板斧：识别没反应 → 先查 DETECTOR.HSV 的阈值和 MIN_AREA。大概率是漂色没框住（调RED_LOW/HIGH）或漂太小被面积过滤了（调小MIN_AREA）。

第二板斧：误报多 → 调高DOWN_THRES等判定阈值 + 调大COOLDOWN。判定阈值越高越"挑"，冷却时间越长越不容易连发。

第三板斧：画面卡 → 调低FPS/分辨率 + 调低JPEG_QUALITY+ 调小FRAME_SIZE。卡顿十有八九是网络或算力瓶颈，先降码率再动别的。

原则就一句话：一次只改一个参数，改完跑一遍压测（python stress_test.py）看指标。第 13 篇的评估体系就是为这个准备的——调参不再是玄学。

一个完整的调参小剧场，感受一下这套流程怎么用：

场景：钓友反馈"小浪天气误报变多，但漏报不严重"。

第一步，明确目标：压查准率，允许查全率小幅下降（宁可漏报不可误报，第 13 篇的产品原则）。

第二步，改一个参数：把DOWN_THRES从 3.5 调到 4.0（判定更苛刻，弱信号更难触发下顿）。

第三步，跑压测对比：python stress_test.py，看小浪档位的查准率是否回到 100%，同时记下查全率掉了几个点。

第四步，判断是否接受：如果查全率只掉 2~3 个点、查准率拉满，这个参数就定下来；如果查全率暴跌，说明调过头，退回到 3.7 再试。

看到没，整个流程没有一个字靠"感觉"，全是数据和对比。这就是第 13 篇评估体系在运维侧的日常用法——它不仅是上线前的一张体检单，更是上线后每一次调参的裁判。

6. 五大扩展点：二次开发的完整地图

系统当前是一套"闭环最小可用"的实现。想加功能？别推倒重来，架构上已经留好了口子。以下是五条最顺的扩展路径。

扩展点一：换检测器（backend 切换 YOLO）

上一整篇都在讲这个。接口不变、下游零改动，config.py里BACKEND="yolo"就切过去了。适合场景：要覆盖多种漂型、夜光漂、复杂背景。

扩展点二：加漂相类型（改识别状态机）

现在识别四类：下顿、顶漂、黑漂、点漂。想加"截口"（浮漂下沉途中被截停）？思路很清晰：

• 在识别器里新增一个状态枚举；
• 在状态机转移逻辑里，加一条"轨迹先匀速下降、突然急停"的转移条件；
• 在事件输出处加对应的事件类型；
• 在合成视频生成器和压测评估里补上新类型的 GT 样本。

难点不在代码，在"这个漂相的物理特征怎么定义成可计算的信号"——这正是第 8~11 篇讲的状态机思想的延伸。

扩展点三：多目标播报（识别器并行化）

当前逻辑一般只对"画面里最可信的一个目标"输出报警。多支漂同时盯：

• 跟踪模块本来就支持多目标（ByteTrack 风格匹配，第 6~7 篇），主目标选择只是一个"选谁播报"的策略；
• 把识别器改成每个跟踪目标各跑一个状态机实例（状态机本身是独立于目标的数据结构），并行判定；
• 事件回调带上目标 ID，安卓端可以区分"第 1 支漂报警 / 第 2 支漂报警"。

这里有个新手容易漏的细节：状态机实例必须按目标 ID 隔离，不能共用。如果两个目标共用一个状态机，漂 1 的顿口信号会把漂 2 的状态也带跑，结果就是两只漂互相"串报警"。实现上，用一个dict[id -> StateMachine]，目标删除时把对应实例一并回收，思路就清晰了。多目标从"算法"变成了"数据结构管理"，难度比想象低。

扩展点四：接入语音/微信推送（改事件回调）

现在报警是"安卓 App 弹提示"。想接更多渠道？事件输出处是一个统一的回调函数，做成"通知分发器"即可：

# notify.py - 扩展点示例：事件分发器defnotify(event):"""收到一个识别事件，分发给所有已注册的通知渠道"""forchannelinCHANNELS:# CHANNELS 可注册：log/app/wechat/tts...channel.send(event)

想加微信推送就写一个WeChatChannel（用企业微信 webhook 或自建机器人），注册进CHANNELS，不用动识别核心一行代码。

扩展点五：数据上云（从纯本地到可选的联网）

当前设计是 YAGNI 纯本地，数据不出局域网。但将来想远程看钓鱼画面、异地收报警？加一层可选的 MQTT 桥（消息队列遥测传输，轻量级物联网协议）：

• 服务端订阅识别事件，桥接到 MQTT broker；
• 手机/PC/网页端订阅同一主题，实现远程播报；
• 数据走你自己部署的 broker，仍然不经过第三方，隐私红利不丢。

一个克制的好习惯：给"上云"留开关，而不是默认全开。config.py加一项CLOUD.ENABLED=False，默认保持纯本地；用户需要时自己打开并配置 broker 地址。这样既保留了升级路径，又守住了"数据不出本地"的产品底线——功能可以增加，默认值要保守。

顺带一提：上云之后，第 13 篇的压测脚本依然要跑——远程播报再多，识别不准一切都白搭。评估闭环是任何扩展的地基。

7. 常见问题排查表（FAQ）：报错先翻这页

把这几篇以来用户踩过的坑汇总成表，八成问题都能对号入座。

最后教你一套定位大法：问题在哪个环节？系统是四段链路（推流→检测→跟踪→识别），出问题先判断在哪一段，别瞎调：

第一步：服务端日志有没有 "frame received" 之类的字样？ ├─ 没有 → 网络/推流问题，回到 FAQ 第一、二行排查 └─ 有 → 推流通了，继续 第二步：日志里 detect 有没有输出框？ ├─ 没有 → 检测环节问题，查 HSV 阈值/MIN_AREA（或 YOLO 置信度） └─ 有 → 检测通了，继续 第三步：日志里有没有 "target updated / 轨迹更新"？ ├─ 没有 → 跟踪环节问题，查 IOU_THRES、LOST_FRAMES └─ 有 → 跟踪通了，继续 第四步：没有报警事件 → 识别环节问题 └─ 查判定阈值、EMA 系数、冷却时间、抗浪阈值

每一段都有日志输出，按段逐层排查，90% 的问题五分钟内能定位到具体模块。这也是本系统把"可观测性"内置进日志设计的原因——排障靠日志，不靠玄学。

8. 产品化路径思考：从"自己能用的 demo"到"能卖的产品的最后一公里"

系统在你自己手里已经能跑了。但"自己能跑"和"别人能用"之间，隔着整整一个产品化的鸿沟。列一下这条路上一道道要过的坎：

第一道坎：设备与加固

软件跑通了，硬件还是"手机 + 笔记本 + 充电宝"的实验室组合。产品化要解决：防水外壳（钓箱是水边场景，设备要能淋雨）、支架固定（怎么把手机稳定架在钓箱上、角度怎么可调）、供电（一块电池撑一整天）。

第二道坎：稳定性

demo 时代崩了重启就行，产品时代不行。三件事必做：

• 看门狗：服务端定期自检，识别进程挂掉自动拉起；
• 断线重连：手机 WiFi 抖动是常态，推流断线要自动重连，服务端对"半截帧"要能容错；
• 日志：统一日志格式、按天滚动，出问题能查"昨天下午 3 点那会儿为什么没报警"。

第三道坎：多用户与运维

从"我的一台机器"变成"很多钓友各一台"：参数怎么远程下发（每支漂不同，用户要能自己调阈值）、固件/模型怎么远程升级（第 14 篇的 ONNX 换模型正好是这个通道）、出问题怎么远程排查。运维能力是产品化的隐形门槛，比功能开发更磨人。

这里给新手一个反直觉的建议：别一上来就造"完整产品"，先做"付费能用的窄门"。比如第一版只卖"Android 8 以上 + 指定两台手机型号 + 固定参数 + 远程不调参"的闭门方案——用户少、问题可控、你周末改得过来。等真实用户把 bug 和需求喂出来，再逐步放开。产品化的过程不是"把 demo 做完"，而是"把不确定性问题一个个锁死"：多少个机型会崩、多少种光线会漏、多少种网络会断，这些都是上线后才知道的，而每一类问题都需要一个版本去解决。

第四道坎：合规与隐私（我们的大招）

最后这道坎，本项目的架构设计居然天然占便宜：数据不出本地。画面在局域网内处理，不经过任何云端。在"AI 产品隐私合规"越来越严的当下，这既是合规优势，更是实打实的营销卖点——“您的钓鱼画面永不离开您的 WiFi”，一句话甩出去，比一百页隐私协议都有说服力。

把这个卖点完整展开就是：不依赖云端——纯局域网部署，数据不出本地，无订阅费用、无隐私风险。三句话对应三种焦虑：画面不上传（隐私）、不交月费（成本）、不依赖服务器在线（可靠性）。对一个要长期架在水边、风吹日晒的设备来说，"随时可用、画面私有"是用户听得懂也听得进的价值——这也是 demo 版从第一天就坚持纯局域网架构的原因：隐私不是产品化之后补的课，是地基里就打好的桩。

9. 宣传收尾：这套系统凭什么值得抄作业

到了收尾，把最拿得出手的三件事再摆一遍：

第一，抗风浪效果是打出来的。

压力测试 4 档数据明明白白：平静水面查全率/查准率 100%/100%，小浪 92%/100%，中浪 100%/100%，大浪 76%/76%。尤其注意查准率——前三档全部 100%，一个误报都没有。钓鱼场景里，"宁可漏报不可误报"是最懂用户的产品决策：误报摧毁信任，漏报最多错过一竿。这套取舍逻辑，体现在信号处理（波浪幅度估计 + 自适应阈值）的每一行设计里。

第二，数据不出本地是硬隐私卖点。

全链路纯局域网，识别核心零第三方依赖（只有 OpenCV + numpy）。在"AI 都要上云"的大环境下，"不上云"本身成了稀缺价值——对隐私敏感的用户，这句话就是购买理由。

第三，全流程开源是工程示范。

从合成数据生成、量化评估闭环、参数速查表，到双后端可切换的检测器架构——这不是一个"只负责识别"的黑盒 demo，而是一套完整可运行的工程范本。新手照着走一遍，学会的不是"抄代码"，而是"一个 CV 项目该有的工程骨架长什么样"。

这套系统的适用场景，也远不止"帮自己盯漂"这一种：

• 台钓/竞技钓：代替人工盯漂，抓顿口、抓送漂；
• 教学演示：向新手展示什么是下顿/顶漂/黑漂/点漂，比嘴上描述直观一百倍；
• 技术验证：目标检测+跟踪+时序状态机+抗噪的完整示例工程；
• 产品化起点：识别核心可对接后台 Spring Boot 等，升级 YOLO 模型提升复杂场景鲁棒性。

获取方式：本项目为 demo 版本，源码、文档、安卓工程完整开放——README 快速开始、二次开发文档、部署文档一应俱全。想跑起来，本篇第 3 节的快速开始就够；想改起来，第 6 节五大扩展点就是地图；想产品化，第 8 节的四道坎就是清单。从 clone 到跑通第一条评估报告，一个下午足矣。

10. 给新手的最终启发：炫技不是终点，闭环才是

最后一篇，说点整个系列最想让你带走的东西。

这个项目里，你见过多少"炫技"？说实话，不多。检测用的是最朴素的 HSV 颜色阈值（第 14 篇才给了 YOLO 选项），跟踪是经典的卡尔曼 + IoU 匹配，识别是四个状态的状态机，评估是加减乘除的指标公式。没有一个是"别人不会的高深算法"。

那它凭什么值得做成一个系列？因为它的价值不在任何单个算法，而在工程闭环：

• 能用：安卓推流 + 服务端识别，真鱼塘里跑得起来；
• 可测：合成视频 + 压测脚本，随时能给自己"称重"；
• 可调：一张参数速查表，每个旋钮都知道动了会怎样；
• 可扩：检测器接口、事件分发、状态机结构，都给扩展留好了门。

这八个字，“能用、可测、可调、可扩”，是一个完整 CV 项目区别于"课程大作业"的分水岭。课程大作业交上去就结束了，工程系统做完还要被人用、被改、被调、被骂——所有让你难受的地方，都是闭环要补的功课。

最后给一条可执行的学习路线，把这个系列的价值最大化：① 先把仓库跑起来（这篇的快速开始）；② 跑压测脚本，亲手复现 100%/100% 和 76%/76% 这两组数字；③ 改一个参数，再跑压测，体会"参数如何影响指标"；④ 挑一个扩展点（推荐先做"加漂相类型"），带着这 15 篇的上下文动手改代码。做完这四步，这套系统的工程骨架就真正长在你脑子里了——换一个项目、换一个领域，这套"检测→跟踪→识别→评估→部署"的闭环方法论照样能搬过去用。这才是本系列最想交给你的东西：不是一支会识别的浮漂，而是一套做 CV 系统的思维方式。

把这篇看完，把系统跑起来，把压测跑一遍，把参数调一调——你会发现自己不知不觉已经完成了从"会写代码"到"会做系统"的转变。

收工。去钓一竿吧。

钓鱼漂相识别 —— 让每一次咬口都不被错过。

🎣 关于 Auto-Fishing 项目

钓鱼漂相识别 —— 让每一次咬口都不被错过

一句话介绍：台钓/野钓时，盯漂是最累也最关键的环节——下顿、顶漂、黑漂、点漂四种真实漂相稍纵即逝，大风大浪时更难判读，很多钓友因此错过提竿时机。Auto-Fishing 用计算机视觉自动识别这四种漂相，并在第一时间给出语音提醒，把钓友从"死盯漂"中解放出来。

核心特性

识别效果（合成演示视频，5 组随机场景）

关于大浪一档的解读：16px 波浪 vs 10~26px 咬口信号，已接近物理可分极限，该浪况下肉眼同样难以判读；系统优先保证不误报（宁缺毋滥），在中小浪况下表现优异。

三种演示方式

1. 零素材演示：python main.py demo—— 自动生成含四种漂相的合成钓鱼视频，识别并输出评估报告，一分钟内跑通全流程
2. 实时演示：电脑跑python main.py server，手机装 App 后同一 Wi-Fi 连上即可，摄像头对准水面浮漂，语音播报实时响起
3. 压力演示：python tools/stress_test.py—— 4 档波浪 × 多场景，直观展示抗风浪能力

适用场景

• 台钓/竞技钓：代替人工盯漂，抓顿口、抓送漂
• 教学演示：向新手展示什么是下顿/顶漂/黑漂/点漂
• 技术验证：目标检测+跟踪+时序状态机+抗噪的完整示例工程
• 产品化起点：识别核心可对接后台 Spring Boot 等，升级 YOLO 模型提升复杂场景鲁棒性

获取方式

本项目为 demo 版本，源码、文档、安卓工程完整开放（README 快速开始 / 二次开发文档 / 部署文档）。