当前位置：首页 > news >正文

cv_resnet18_ocr-detection启动失败？服务排查步骤详解

news 2026/4/4 16:27:12

cv_resnet18_ocr-detection启动失败？服务排查步骤详解

1. 问题背景与常见现象

你是不是也遇到过这样的情况：刚部署完cv_resnet18_ocr-detectionOCR文字检测模型，满怀期待地运行bash start_app.sh，结果服务没起来，浏览器打不开页面，连日志都看不到几行有效信息？

别急，这几乎是每个初次使用该模型的人都会踩的坑。本文将带你一步步排查cv_resnet18_ocr-detection 启动失败的各种可能原因，并提供可落地的解决方案。

这个由“科哥”开发并二次封装的 WebUI 版 OCR 检测工具，基于 ResNet18 架构实现高效文字定位，在证件识别、文档数字化等场景中表现不错。但它的部署过程对环境依赖较强，一旦某个环节出错，就可能导致服务无法正常启动。

我们先来看一个典型的失败表现：

执行start_app.sh后无任何输出或直接退出
提示端口被占用但查不到进程
浏览器访问http://IP:7860显示连接拒绝或超时
Python 报错 ImportError、ModuleNotFoundError 或 CUDA 相关异常

下面我们就从最基础的环境准备开始，逐层深入排查。

2. 环境检查与依赖验证

2.1 确认系统与硬件支持

首先确保你的运行环境满足基本要求：

项目	推荐配置
操作系统	Ubuntu 18.04 / 20.04 / 22.04（推荐）
CPU	至少 2 核
内存	≥ 8GB（若用 GPU 可适当降低）
显卡	NVIDIA GPU（支持 CUDA，显存 ≥ 4GB）
存储空间	≥ 10GB 可用空间

如果你是在云服务器上部署，请确认是否已安装 NVIDIA 驱动和 CUDA 工具包。

执行以下命令检查 GPU 支持情况：

nvidia-smi

如果提示command not found，说明驱动未安装；如果显示设备信息但无 CUDA 版本，则需补装 CUDA。

2.2 检查 Python 环境与依赖包

进入项目目录后，先查看是否存在requirements.txt文件：

ls /root/cv_resnet18_ocr-detection/requirements.txt

如果有，建议创建独立虚拟环境安装依赖：

python3 -m venv ocr_env source ocr_env/bin/activate pip install --upgrade pip pip install -r requirements.txt

如果没有requirements.txt，可以参考常见依赖手动安装：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 pip install flask opencv-python numpy pillow onnx onnxruntime-gpu

注意：请根据你的 CUDA 版本选择合适的 PyTorch 安装方式。例如 CUDA 11.8 使用cu118，CUDA 12.1 使用cu121。

安装完成后，测试关键模块能否导入：

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"

如果返回False，说明 CUDA 不可用，可能是驱动、PyTorch 或 cuDNN 版本不匹配。

3. 启动脚本分析与调试技巧

3.1 查看 start_app.sh 脚本内容

很多问题其实藏在start_app.sh里。我们先看看它到底做了什么：

cat start_app.sh

典型内容如下：

#!/bin/bash export FLASK_APP=app.py export FLASK_ENV=development flask run --host=0.0.0.0 --port=7860

或者更复杂的版本：

nohup python app.py > logs/start.log 2>&1 &

如果是前者，可以直接在终端运行，便于观察实时输出：

flask run --host=0.0.0.0 --port=7860

如果是后者，记得去logs/start.log查看错误日志：

tail -f logs/start.log

3.2 常见脚本级错误及修复

❌ 错误1：权限不足

bash: ./start_app.sh: Permission denied

解决方法：添加执行权限

chmod +x start_app.sh

❌ 错误2：Python 解释器路径错误

脚本中写死了/usr/bin/python，但实际是python3

修改脚本第一行：

#!/usr/bin/env python3

❌ 错误3：端口被占用

提示Address already in use

查看占用进程：

lsof -ti:7860 kill $(lsof -ti:7860)

或更换端口：

flask run --host=0.0.0.0 --port=7861

然后访问http://IP:7861

4. 应用代码层面的问题排查

4.1 检查主程序入口文件

通常为app.py或main.py，确认是否存在：

ls app.py

打开文件，检查是否有明显的语法错误或模块导入失败。

重点关注以下几行：

from flask import Flask, request, jsonify import cv2 import torch from models.detector import OCRDetector # 注意路径是否正确

如果报错No module named 'models'，说明 Python 包结构有问题，需要添加__init__.py或调整 sys.path。

临时修复方法：

import sys sys.path.append('/root/cv_resnet18_ocr-detection')

4.2 模型权重文件缺失

ResNet18 OCR 检测模型通常需要预训练权重文件，如resnet18_ocr.pth。

检查模型加载部分：

model = OCRDetector(weights='weights/resnet18_ocr.pth')

确认权重文件是否存在：

ls weights/

若不存在，需从原作者提供的渠道下载，或重新训练生成。

4.3 图像预处理逻辑异常

有时模型能加载，但在第一次推理时报错，比如：

RuntimeError: expected scalar type Float but found Double

这是由于输入数据未归一化导致的。检查预处理代码：

image = image.astype(np.float32) / 255.0 # 必须除以 255 tensor = torch.from_numpy(image).permute(2, 0, 1).unsqueeze(0)

确保所有输入张量都是float32类型且范围在 [0,1]。

5. WebUI 服务运行状态监控

5.1 使用 ps 与 netstat 检查进程

服务看似启动了却无法访问？先确认进程是否存在：

ps aux | grep python

查找类似：

root 12345 0.0 10.2 1234567 89012 ? Sl 10:30 0:05 python app.py

再检查端口监听状态：

netstat -tulnp | grep 7860

或使用更简洁的命令：

lsof -i :7860

如果没有输出，说明服务根本没起来。

5.2 日志文件定位核心错误

大多数 WebUI 应用都会输出日志。查找以下位置：

find . -name "*.log" | xargs ls -lt

重点查看：

logs/start.log
workdirs/train.log
outputs/output.log

常见致命错误包括：

OSError: [Errno 2] No such file or directory: 'weights/...'
AssertionError: Torch not compiled with CUDA enabled
ImportError: cannot import name 'xxx' from 'yyy'

这些都能直接指向问题根源。

6. 实战案例：一次完整排错记录

故障描述

用户反馈：执行bash start_app.sh后没有任何反应，ps查不到进程，lsof也没看到端口。

排查流程

检查脚本权限
```
ls -l start_app.sh
```
发现权限为-rw-r--r--，缺少执行位。
修复：
```
chmod +x start_app.sh
```
手动运行脚本查看输出
```
./start_app.sh
```
输出：
```
/usr/bin/env: ‘python\r’: No such file or directory
```
这是典型的 Windows 换行符问题（\r\n导致\r被当作文件名）。
转换换行符格式
使用dos2unix工具：
```
dos2unix start_app.sh
```
若未安装：
```
apt install dos2unix
```

再次运行

./start_app.sh

此时出现新错误：

ModuleNotFoundError: No module named 'flask'

安装缺失依赖
```
pip install flask
```
继续运行仍报错
```
RuntimeError: CUDA out of memory.
```
切换为 CPU 模式
修改app.py中的设备设置：
```
device = torch.device('cpu') # 原为 'cuda'
```
最终成功启动
```
* Running on http://0.0.0.0:7860
```
浏览器顺利打开 WebUI 页面。