DAMO-YOLO部署教程：bash /root/build/start.sh 启动原理与日志排查

DAMO-YOLO部署教程：bash /root/build/start.sh 启动原理与日志排查

1. 为什么需要理解 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 动画。只要你能看懂终端输出、会查文件路径、愿意多看两眼日志里的括号和冒号——这篇就是为你写的。

2./root/build/start.sh全流程拆解：从敲下回车开始

2.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.0, port=5000, debug=False）

这个链条里，每一步失败都会在终端留下独特痕迹。关键不是记住所有步骤，而是学会“听日志说话”。

2.2 实际日志对照：看懂每一行在说什么

下面是你执行bash /root/build/start.sh后，终端最可能出现的几类输出。我们逐行解释它们的真实含义：

正常启动日志（健康信号）

> Checking Python version... OK (3.10.12) > 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.0:5000) > * Running on http://127.0.0.1:5000 > Press CTRL+C to quit

• Checking Python version... OK：说明脚本成功识别了 Python 环境，版本符合要求（3.10+）
• CUDA available: True：GPU 已就绪，这是毫秒级推理的前提
• Model path ... exists.：模型文件夹存在，避免了首次运行时漫长的自动下载
• Loading model ... Done.：模型已成功加载进显存，此时 GPU 显存占用会明显上升（可用nvidia-smi验证）
• Running on http://127.0.0.1:5000：Flask 服务已监听，这是最关键的健康标志

警告类日志（可运行但有隐患）

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 'modelscope'

• Port 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:则服务可能跑起来了，但功能不完整。

3. 三步精准日志排查法：不再盲目重启

当你发现http://localhost:5000打不开，或界面加载一半卡住，别急着Ctrl+C再试一次。按以下顺序检查，90% 的问题能在 3 分钟内定位：

3.1 第一步：确认服务进程是否真在运行

执行命令：

ps aux | grep "flask\|python" | grep -v grep

• 如果返回空：说明start.sh根本没启动成功，或启动后立即崩溃。回到上一节，重点看终端最后几行 ERROR 日志。
• 如果返回类似：

  root 12345 0.1 3.2 1234567 89012 ? Sl 10:20 0:05 /usr/bin/python3 /root/app.py

  说明 Flask 进程在运行，问题出在网络访问层或前端层。

3.2 第二步：验证端口监听与本地连通性

即使进程在跑，也可能没正确绑定端口。执行：

netstat -tuln | grep :5000 # 或更简洁的 ss -tuln | grep :5000

• 期望输出：

  tcp6 0 0 :::5000 :::* LISTEN

  表示服务正在监听所有 IPv6 地址（也兼容 IPv4）。
• 如果无输出：Flask 启动时指定了host=127.0.0.1（只监听本地），需修改启动命令为host=0.0.0.0。
• 如果显示127.0.0.1:5000：只能本机访问，外部设备（如手机、另一台电脑）无法连接。

再测试本地能否通：

curl -I http://127.0.0.1:5000

• 返回HTTP/1.0 200 OK：后端正常，问题在浏览器或网络。
• 返回curl: (7) Failed to connect：端口未监听，或 Flask 未启动成功。

3.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 标签页）。

4. 常见故障速查表与修复命令

重要提醒：所有修复操作后，不要直接再次运行start.sh。先确保旧进程已终止：

pkill -f "flask\|python.*app.py" # 再启动 bash /root/build/start.sh

5. 进阶建议：让部署更稳、排查更快

5.1 给 start.sh 加个“健康检查”钩子

你可以在start.sh末尾追加一段简单检查，让它启动后自动验证关键环节：

# 在 start.sh 最后加入 echo " Health check starting..." sleep 3 if curl -s http://127.0.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

这样，脚本要么成功告诉你地址，要么明确报错退出，省去人工判断。

5.2 用 journalctl 管理长期运行日志（适合生产）

如果将 DAMO-YOLO 作为后台服务长期运行，推荐用 systemd 管理，并用journalctl查日志：

# 创建服务文件 sudo tee /etc/systemd/system/damo-yolo.service << 'EOF' [Unit] Description=DAMO-YOLO Visual Detection Service After=network.target [Service] Type=simple User=root WorkingDirectory=/root ExecStart=/bin/bash /root/build/start.sh Restart=always RestartSec=10 [Install] WantedBy=multi-user.target EOF sudo systemctl daemon-reload sudo systemctl enable damo-yolo sudo systemctl start damo-yolo # 查看实时日志（比终端滚动更清晰） sudo journalctl -u damo-yolo -f

5.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。这一次，别只盯着浏览器，也看看那一屏滚动的文字——它们正等着你去听懂。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。