Ubuntu 部署 PaddleOCR 完整指南
🖥️ 系统要求
硬件要求
推荐配置
-
CPU: 4 核心 2.5GHz 以上（支持 AVX 指令集）
-
内存: 8GB RAM 或更多
-
存储: 20GB 可用空间（SSD 推荐）
软件要求
-
操作系统: Ubuntu 22.04 LTS
-
Python: 3.8 - 3.11（推荐 3.9）
-
pip: 最新版本
🔧 环境准备
1. 系统更新
# 更新系统包列表
sudo apt update && sudo apt upgrade -y
# 安装基础工具
sudo apt install -y curl wget git vim
2. 安装系统依赖
# 安装编译工具和依赖库
sudo apt install -y \build-essential \python3-dev \python3-pip \libgomp1 \libgfortran5 \libblas3 \liblapack3 \libopencv-dev \pkg-config
# 安装 Python 相关依赖
sudo apt install -y \python3-venv \python3-setuptools \python3-wheel
3. 配置 Python 环境
# 检查 Python 版本
python3 --version
# 升级 pip
python3 -m pip install --upgrade pip
# 创建虚拟环境（推荐）
python3 -m venv paddleocr-env
source paddleocr-env/bin/activate
# 或者全局安装（不推荐生产环境）
📦 安装步骤
1. 安装 PaddlePaddle 框架
CPU 版本
# 使用阿里云镜像加速安装
python3 -m pip install paddlepaddle -i https://mirrors.aliyun.com/pypi/simple/
2. 安装 PaddleOCR
# 安装 PaddleOCR
python3 -m pip install paddleocr -i https://mirrors.aliyun.com/pypi/simple/
3. 安装 PaddleX
# 安装 PaddleX 基础版本
pip install "paddlex[base]" -i https://mirrors.aliyun.com/pypi/simple/
4. 处理依赖问题
安装核心依赖
# 如果遇到依赖问题，手动安装核心依赖
pip install numpy opencv-python pillow PyYAML packaging -i https://mirrors.aliyun.com/pypi/simple/
解决 tokenizers 编译问题
# 如果 tokenizers 依赖报错，先安装预编译版本
pip install tokenizers==0.19.1 -i https://mirrors.aliyun.com/pypi/simple/
# 或者跳过 tokenizers 相关功能
pip install paddleocr --no-deps -i https://mirrors.aliyun.com/pypi/simple/
5. 安装服务化部署插件
# 安装 PaddleX 服务化部署插件
paddlex --install serving
⚙️ 服务配置
1. 基本服务启动
# 启动 OCR 服务（默认端口 8080）
paddlex --serve --pipeline OCR
# 指定端口启动
paddlex --serve --pipeline OCR --port 8082
# 指定设备启动
paddlex --serve --pipeline OCR --device cpu
paddlex --serve --pipeline OCR --device gpu
2. 服务参数说明
| 参数 | 说明 | 默认值 |
|---|---|---|
| –pipeline | PaddleX 产线注册名或配置文件路径 | 必需 |
| –device | 部署设备（cpu/gpu） | 自动检测 |
| –host | 服务器绑定地址 | 0.0.0.0 |
| –port | 服务监听端口 | 8080 |
| –use_hpip | 启用高性能推理 | false |
| –hpi_config | 高性能推理配置文件 | - |
3. 配置 systemd 服务
创建服务文件
sudo nano /etc/systemd/system/paddlex-ocr.service
服务配置内容
[Unit]
Description=PaddleX OCR Service - Maximum Performance
Documentation=https://github.com/PaddlePaddle/PaddleX
After=network.target
Wants=network.target
[Service]
Type=simple
User=root
Group=root
WorkingDirectory=/tmp
Environment=PATH=/usr/local/bin:/usr/bin:/bin
Environment=PADDLEX_HOME=/tmp/.paddlex
Environment=HOME=/tmp
Environment=OMP_NUM_THREADS=0
Environment=OPENBLAS_NUM_THREADS=0
Environment=MKL_NUM_THREADS=0
Environment=NUMEXPR_MAX_THREADS=0
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/local/bin/paddlex --serve --pipeline OCR --port 8082 --host 0.0.0.0
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=paddlex-ocr
# 无资源限制以获得最大性能
LimitNOFILE=infinity
LimitNPROC=infinity
LimitCORE=infinity
# 最小安全限制以获得最大性能
NoNewPrivileges=false
ProtectSystem=false
ProtectHome=false
ReadWritePaths=/
[Install]
WantedBy=multi-user.target
创建必要目录
# 创建 PaddleX 缓存目录
sudo mkdir -p /tmp/.paddlex
sudo mkdir -p /tmp/.paddlex/temp
sudo mkdir -p /tmp/.paddlex/official_models
sudo chown -R root:root /tmp/.paddlex
sudo chmod -R 755 /tmp/.paddlex
🚀 部署管理
1. 服务管理命令
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start paddlex-ocr
# 停止服务
sudo systemctl stop paddlex-ocr
# 重启服务
sudo systemctl restart paddlex-ocr
# 查看服务状态
sudo systemctl status paddlex-ocr
# 设置开机自启
sudo systemctl enable paddlex-ocr
# 禁用开机自启
sudo systemctl disable paddlex-ocr
2. 日志管理
# 实时查看日志
sudo journalctl -u paddlex-ocr -f
# 查看最近的日志
sudo journalctl -u paddlex-ocr --since "1 hour ago"
# 查看详细日志
sudo journalctl -u paddlex-ocr -f --no-pager
# 清理日志
sudo journalctl --vacuum-time=7d
3. 进程管理
# 查看 PaddleX 进程
ps aux | grep paddlex
# 查看端口占用
sudo netstat -tlnp | grep :8082
sudo lsof -i :8082
# 强制终止进程（谨慎使用）
sudo pkill -f paddlex
🔍 测试验证
1. 服务测试
# 检查服务是否正常运行
curl -X GET http://localhost:8082/health
# 测试 OCR API（需要准备测试图片）
curl -X POST "http://localhost:8082/ocr" \-H "Content-Type: multipart/form-data" \-F "file=@test_image.jpg"
🔧 故障排除
1. 常见安装问题
问题：pip3 命令不存在
# 解决方案：安装 pip3
sudo apt update
sudo apt install -y python3-pip
问题：libgomp.so.1 缺失
# 解决方案：安装 OpenMP 库
sudo apt install -y libgomp1 gcc g++ libomp-dev
问题：tokenizers 编译失败
# 解决方案1：安装预编译版本
pip install tokenizers==0.19.1 -i https://mirrors.aliyun.com/pypi/simple/
# 解决方案2：跳过 tokenizers
pip install paddleocr --no-deps -i https://mirrors.aliyun.com/pypi/simple/
pip install numpy opencv-python pillow PyYAML packaging -i https://mirrors.aliyun.com/pypi/simple/
2. 服务启动问题
问题：端口被占用
# 查看占用端口的进程
sudo lsof -i :8080
# 使用其他端口
paddlex --serve --pipeline OCR --port 8082
📊 监控和维护
1. 系统监控
# 监控系统资源
htop
iostat -x 1
vmstat 1# 监控网络连接
ss -tuln | grep :8082
2. 日志分析
# 分析错误日志
sudo journalctl -u paddlex-ocr | grep ERROR# 统计请求量
sudo journalctl -u paddlex-ocr | grep "POST /ocr" | wc -l
📚 参考资源
-
PaddleOCR 官方文档
-
PaddleX 官方文档
-
PaddlePaddle 官方文档