核心内容摘要
某大厂提示工程架构师分享：提示系统集成测试的秘诀
DAMO-YOLO部署教程bash /root/build/start.sh 启动原理与日志排查
为什么需要理解 start.sh 的启动逻辑你刚下载完 DAMO-YOLO 镜像执行了bash /root/build/start.sh浏览器打开http://localhost:5000界面酷炫、检测飞快——一切看起来都很顺利。
但当某天页面打不开、上传图片没反应、或者识别框突然全变灰色时你点开终端只看到一串滚动的日志却不知道该看哪一行、该改什么配置、甚至不确定服务到底有没有真正跑起来。
这不是玄学是工程落地中最常遇到的“黑盒时刻”。
本教程不讲模型怎么训练、不讲 TinyNAS 原理也不堆砌参数调优技巧。
我们聚焦一个最实际的问题/root/build/start.sh这行命令背后到底发生了什么它如何把 Python 模型、Flask 服务、前端资源和 UI 动效串成一个可运行的整体当它出问题时日志里哪些信息才是真正有用的线索你会学到start.sh的完整执行链条从 shell 解析到 Flask 启动每个关键步骤对应的日志特征一眼识别卡在哪一步3 类高频故障的精准定位方法端口冲突、模型加载失败、静态资源路径错误一套可复用的日志排查流程不用重启、不用重装5 分钟内定位根因不需要你懂 NAS 搜索也不需要会写 CSS 动画。
只要你能看懂终端输出、会查文件路径、愿意多看两眼日志里的括号和冒号——这篇就是为你写的。
/root/build/start.sh全流程拆解从敲下回车开始
1 脚本结构总览不依赖源码也能推理虽然你手头可能没有start.sh的源码但通过观察系统结构、日志输出和常见部署模式我们可以反向还原它的核心逻辑。
它不是一段神秘代码而是一条清晰的“启动流水线”[Shell 层] bash /root/build/start.sh ↓ [环境检查层] 检查 Python 版本、CUDA 可用性、模型路径是否存在 ↓ [依赖准备层] 激活虚拟环境如有、安装缺失的 pip 包如 opencv-python-headless ↓ [服务准备层] 复制或链接前端静态资源到 Flask 默认目录static/ ↓ [模型加载层] 预加载 DAMO-YOLO 模型ModelScope 下载 PyTorch 加载 ↓ [Web 服务层] 启动 Flask 应用指定 host
0.
0.
0, port5000, debugFalse这个链条里每一步失败都会在终端留下独特痕迹。
关键不是记住所有步骤而是学会“听日志说话”。
2 实际日志对照看懂每一行在说什么下面是你执行bash /root/build/start.sh后终端最可能出现的几类输出。
我们逐行解释它们的真实含义正常启动日志健康信号 Checking Python version... OK (
3.
10.
CUDA available: True, Device: cuda:0 Model path /root/ai-models/iic/cv_tinynas_object-detection_damoyolo/ exists. Loading model from ModelScope hub... Done. * Serving Flask app app:app * Debug mode: off * Running on all addresses (
0.
0.
0:
* Running on http://
127.
0.
1:5000 Press CTRLC to quitChecking Python version... OK说明脚本成功识别了 Python 环境版本符合要求
10CUDA available: TrueGPU 已就绪这是毫秒级推理的前提Model path ... exists.模型文件夹存在避免了首次运行时漫长的自动下载Loading model ... Done.模型已成功加载进显存此时 GPU 显存占用会明显上升可用nvidia-smi验证Running on http://
127.
0.
1:5000Flask 服务已监听这是最关键的健康标志警告类日志可运行但有隐患WARNING: No .env file found. Using default config. WARNING: Static assets not found in /root/build/dist. Falling back to /root/webui/.这类日志不会导致服务崩溃但暗示配置或资源路径非标准。
比如Static assets警告意味着前端 HTML/CSS/JS 文件没放在预期位置可能导致界面错乱、按钮无响应、霓虹绿边框不显示——但后端检测依然正常。
❌ 错误类日志服务无法启动ERROR: Port 5000 is already in use. Try lsof -i :5000 or change port. OSError: [Errno 2] No such file or directory: /root/ai-models/iic/cv_tinynas_object-detection_damoyolo/ ModuleNotFoundError: No module named modelscopePort 5000 is already in use最常见原因另一个进程可能是上次没关干净的 Flask或是 Jupyter占用了端口。
No such file or directory模型路径不存在。
注意不是模型文件损坏而是整个文件夹缺失。
DAMO-YOLO 不会自动创建该路径。
No module named modelscope核心依赖未安装。
start.sh可能跳过了 pip install 步骤或虚拟环境未激活。
关键提示日志中出现ERROR:或Traceback开头的行基本等于启动失败出现WARNING:则服务可能跑起来了但功能不完整。
三步精准日志排查法不再盲目重启当你发现http://localhost:5000打不开或界面加载一半卡住别急着CtrlC再试一次。
按以下顺序检查90% 的问题能在 3 分钟内定位
1 第一步确认服务进程是否真在运行执行命令ps aux | grep flask\|python | grep -v grep如果返回空说明start.sh根本没启动成功或启动后立即崩溃。
回到上一节重点看终端最后几行 ERROR 日志。
如果返回类似root 12345
1
2 1234567 89012 ? Sl 10:20 0:05 /usr/bin/python3 /root/app.py说明 Flask 进程在运行问题出在网络访问层或前端层。
2 第二步验证端口监听与本地连通性即使进程在跑也可能没正确绑定端口。
执行netstat -tuln | grep :5000 # 或更简洁的 ss -tuln | grep :5000期望输出tcp6 0 0 :::5000 :::* LISTEN表示服务正在监听所有 IPv6 地址也兼容 IPv4。
如果无输出Flask 启动时指定了host
127.
0.
1只监听本地需修改启动命令为host
0.
0.
0。
如果显示
127.
0.
1:5000只能本机访问外部设备如手机、另一台电脑无法连接。
再测试本地能否通curl -I http://
127.
0.
1:5000返回HTTP/
0 200 OK后端正常问题在浏览器或网络。
返回curl: (
Failed to connect端口未监听或 Flask 未启动成功。
3 第三步检查模型加载与静态资源路径这是 UI 出现“白屏”、“无识别框”、“滑块不响应”的根本原因。
检查模型路径真实性ls -l /root/ai-models/iic/cv_tinynas_object-detection_damoyolo/必须看到configuration.json、pytorch_model.bin、preprocessor_config.json等文件。
如果只有空文件夹说明模型未下载需手动执行modelscope download --model iic/cv_tinynas_object-detection_damoyolo --local_dir /root/ai-models/iic/cv_tinynas_object-detection_damoyolo/检查前端资源是否就位ls -l /root/build/dist/ # 或 /root/webui/至少应包含index.html、static/css/、static/js/。
若缺失可临时软链ln -sf /root/webui /root/build/dist经验
总结UI 白屏 前端资源找不到识别框不出现 模型未加载或加载失败滑块拖不动 JavaScript 报错查看浏览器 F12 → Console 标签页。
常见故障速查表与修复命令现象最可能原因一行定位命令修复方案终端一闪而过无任何输出start.sh权限不足ls -l /root/build/start.shchmod x /root/build/start.sh页面显示This site can’t be reached端口被占用lsof -i :5000 | grep LISTENkill -9 $(lsof -t -i :
页面打开但全是文字无样式、无按钮前端静态资源路径错误ls /root/build/dist/index.htmlln -sf /root/webui /root/build/dist上传图片后无反应控制台报500 Internal Server Error模型加载失败CUDA 内存不足nvidia-smi查看显存关闭其他 GPU 进程或添加--no-cuda启动参数降级为 CPU 模式滑块调节后无效果检测结果不变前端 JS 未正确连接后端 API浏览器按F12→ Network → 查看/api/detect请求状态检查app.py中CORS(app)是否启用或 Nginx 反向代理配置重要提醒所有修复操作后不要直接再次运行start.sh。
先确保旧进程已终止pkill -f flask\|python.*app.py # 再启动 bash /root/build/start.sh
进阶建议让部署更稳、排查更快
1 给 start.sh 加个“健康检查”钩子你可以在start.sh末尾追加一段简单检查让它启动后自动验证关键环节# 在 start.sh 最后加入 echo Health check starting... sleep 3 if curl -s http://
127.
0.
1:5000 | grep -q Visual Brain; then echo Service is live at http://localhost:5000 else echo ❌ Service failed to respond. Check logs above. exit 1 fi这样脚本要么成功告诉你地址要么明确报错退出省去人工判断。
2 用 journalctl 管理长期运行日志适合生产如果将 DAMO-YOLO 作为后台服务长期运行推荐用 systemd 管理并用journalctl查日志# 创建服务文件 sudo tee /etc/systemd/system/damo-yolo.service EOF [Unit] DescriptionDAMO-YOLO Visual Detection Service Afternetwork.target [Service] Typesimple Userroot WorkingDirectory/root ExecStart/bin/bash /root/build/start.sh Restartalways RestartSec10 [Install] WantedBymulti-user.target EOF sudo systemctl daemon-reload sudo systemctl enable damo-yolo sudo systemctl start damo-yolo # 查看实时日志比终端滚动更清晰 sudo journalctl -u damo-yolo -f
3 保留一份最小可运行快照部署稳定后执行# 打包当前有效状态不含大模型文件 tar -czf damo-yolo-deploy-snapshot-$(date %Y%m%d).tar.gz \ /root/build/start.sh \ /root/app.py \ /root/webui/ \ /root/.bashrc # 如果修改过环境变量下次环境异常时无需重装解压即用。
6.
总结启动不是魔法日志就是说明书bash /root/build/start.sh从来不是一句“黑箱咒语”。
它是一份精心编排的自动化清单串联起环境、依赖、模型、服务和界面。
而终端里滚动的文字不是噪音是系统发出的、最诚实的状态报告。
你不需要成为 Shell 专家也能读懂OK是通行证ERROR是路障WARNING是减速带Port in use提醒你清理旧进程No such file告诉你补全路径curl是你的第一把探针ps和netstat是你的双目镜。
真正的部署能力不在于一次成功而在于失败时你能比别人快 3 分钟找到那行关键日志。
现在打开你的终端再执行一次bash /root/build/start.sh。
这一次别只盯着浏览器也看看那一屏滚动的文字——它们正等着你去听懂。