LightOnOCR-2-1B生产环境部署：systemd服务管理+日志轮转+健康检查-平芜编程栈

LightOnOCR-2-1B生产环境部署：systemd服务管理+日志轮转+健康检查

1. 为什么需要生产级部署

LightOnOCR-2-1B 是一个 1B 参数的多语言 OCR 模型，支持 11 种语言（中英日法德西意荷葡瑞丹）。它不是玩具模型，而是真正能投入业务使用的工具——能识别表格、收据、表单甚至数学公式，对图片分辨率最长边 1540px 的适配效果最佳，GPU 内存占用约 16GB。但光有功能还不够，如果你打算把它用在公司内部文档处理系统、客户自助扫描平台或者自动化票据审核流程里，那“手动启动”“Ctrl+C停止”“日志堆满磁盘”这些操作就完全不可接受。

真实场景下，你需要的是：服务崩溃后自动拉起、日志按天压缩归档不占满硬盘、API 响应超时能被及时发现、升级时平滑重启不中断请求。这些都不是靠bash start.sh能解决的。本文就带你把 LightOnOCR-2-1B 从“能跑起来”变成“稳稳在线”，用最标准的 Linux 生产实践完成三件事：用 systemd 实现服务化管理、用 logrotate 做日志轮转、用 curl + systemd timer 做轻量健康检查。

整个过程不依赖 Docker，不改一行模型代码，所有配置都基于你已有的目录结构和运行方式，实测在 Ubuntu 22.04/CentOS 7 环境下均可直接复用。

2. systemd 服务化：让服务真正“托管”起来

2.1 创建服务单元文件

Linux 下的服务管理核心就是 systemd。我们要为 LightOnOCR-2-1B 创建两个独立服务：一个管 Gradio 前端（端口 7860），一个管 vLLM 后端 API（端口 8000）。这样既能分别启停，又能设置不同资源限制和依赖关系。

先创建前端服务文件：

sudo tee /etc/systemd/system/lightonocr-frontend.service << 'EOF' [Unit] Description=LightOnOCR-2-1B Gradio Frontend After=network.target StartLimitIntervalSec=0 [Service] Type=simple User=root WorkingDirectory=/root/LightOnOCR-2-1B ExecStart=/usr/bin/python3 /root/LightOnOCR-2-1B/app.py Restart=always RestartSec=10 Environment=PYTHONUNBUFFERED=1 Environment=GRADIO_SERVER_PORT=7860 Environment=GRADIO_SERVER_NAME=0.0.0.0 StandardOutput=append:/var/log/lightonocr/frontend.log StandardError=append:/var/log/lightonocr/frontend.log SyslogIdentifier=lightonocr-frontend LimitNOFILE=65536 [Install] WantedBy=multi-user.target EOF

再创建后端服务文件（注意路径与模型参数）：

sudo tee /etc/systemd/system/lightonocr-backend.service << 'EOF' [Unit] Description=LightOnOCR-2-1B vLLM Backend API After=network.target lightonocr-frontend.service StartLimitIntervalSec=0 [Service] Type=simple User=root WorkingDirectory=/root/ai-models/lightonai/LightOnOCR-2-1B ExecStart=/usr/bin/vllm serve \ --model /root/ai-models/lightonai/LightOnOCR-2-1B \ --host 0.0.0.0 \ --port 8000 \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.95 \ --max-num-seqs 8 \ --max-model-len 4096 Restart=always RestartSec=15 Environment=PYTHONUNBUFFERED=1 StandardOutput=append:/var/log/lightonocr/backend.log StandardError=append:/var/log/lightonocr/backend.log SyslogIdentifier=lightonocr-backend LimitNOFILE=65536 MemoryLimit=18G [Install] WantedBy=multi-user.target EOF

关键点说明：

Restart=always确保进程意外退出后自动重启，RestartSec=10/15避免高频重启；
MemoryLimit=18G是硬性内存上限，防止 GPU 显存爆掉拖垮整机；
After=... frontend.service表示后端启动依赖前端就绪，避免 API 先跑而界面还没加载完的错乱；
所有日志统一写入/var/log/lightonocr/目录，为后续轮转打基础。

2.2 启用并验证服务状态

创建完服务文件后，刷新配置并启用：

sudo systemctl daemon-reload sudo systemctl enable lightonocr-frontend.service sudo systemctl enable lightonocr-backend.service sudo systemctl start lightonocr-frontend.service sudo systemctl start lightonocr-backend.service

验证是否正常运行：

sudo systemctl status lightonocr-frontend.service lightonocr-backend.service

你应该看到两行active (running)，且没有红色错误提示。再用ss -tlnp | grep -E "7860|8000"确认端口监听正常。此时你已经告别了pkill -f和手敲命令——服务开机自启、崩溃自愈、资源受控，这才是生产该有的样子。

3. 日志轮转：告别磁盘告警和日志爆炸

3.1 创建日志目录与权限

默认日志会不断追加到单个文件，几天下来就几个 GB。我们用系统自带的 logrotate 工具来管理：

sudo mkdir -p /var/log/lightonocr sudo chown root:root /var/log/lightonocr sudo chmod 755 /var/log/lightonocr

3.2 配置 logrotate 规则

创建专属配置文件：

sudo tee /etc/logrotate.d/lightonocr << 'EOF' /var/log/lightonocr/*.log { daily missingok rotate 30 compress delaycompress notifempty create 644 root root sharedscripts postrotate systemctl kill --signal=SIGHUP lightonocr-frontend.service lightonocr-backend.service > /dev/null 2>&1 || true endscript } EOF

这段配置的意思是：

每天轮转一次/var/log/lightonocr/下所有.log文件；
保留最近 30 天的日志（rotate 30），超出的自动删除；
压缩旧日志（.log.1.gz），但昨天的日志先不压（delaycompress），方便排查问题；
postrotate里发送SIGHUP信号给服务，让它们重新打开新日志文件（Gradio 和 vLLM 都支持此信号）；
notifempty防止空日志也生成压缩包。

测试配置是否语法正确：

sudo logrotate -d /etc/logrotate.d/lightonocr

看到reading config file和compressing log with gzip就说明没问题。明天同一时间，logrotate 会自动执行；你也可以手动触发一次：

sudo logrotate -f /etc/logrotate.d/lightonocr

执行后检查：ls -lh /var/log/lightonocr/应该能看到frontend.log.1和backend.log.1，原文件变为空。

4. 健康检查：让系统自己“体检”

4.1 编写健康检查脚本

光靠 systemd 的Restart=always还不够——如果服务进程还在，但 API 返回 500 或卡死，systemd 是不会重启的。我们需要主动探测。

创建检查脚本：

sudo tee /usr/local/bin/check-lightonocr-health.sh << 'EOF' #!/bin/bash # 检查 LightOnOCR 前后端健康状态 SERVER_IP="127.0.0.1" FRONTEND_PORT="7860" BACKEND_PORT="8000" # 检查前端是否响应 HTTP 200 FRONTEND_OK=$(curl -s -o /dev/null -w "%{http_code}" http://$SERVER_IP:$FRONTEND_PORT/health 2>/dev/null) # 检查后端是否返回模型信息（vLLM 标准健康端点） BACKEND_OK=$(curl -s -o /dev/null -w "%{http_code}" http://$SERVER_IP:$BACKEND_PORT/health 2>/dev/null) if [ "$FRONTEND_OK" = "200" ] && [ "$BACKEND_OK" = "200" ]; then echo "$(date): OK - Both frontend and backend are healthy" >> /var/log/lightonocr/health.log exit 0 else echo "$(date): ERROR - Frontend=$FRONTEND_OK, Backend=$BACKEND_OK" >> /var/log/lightonocr/health.log # 记录错误后尝试重启服务 systemctl restart lightonocr-frontend.service lightonocr-backend.service 2>/dev/null exit 1 fi EOF sudo chmod +x /usr/local/bin/check-lightonocr-health.sh

注意：Gradio 默认没有/health路由，我们需要在app.py开头加一行（就在import后面）：

# 在 app.py 最顶部 import 下方添加 from gradio.routes import mount_gradio_app import gradio as gr # 添加健康检查路由（放在 demo.launch() 之前） def health_check(): return "OK" with gr.Blocks() as demo: gr.Markdown("## LightOnOCR-2-1B") # ... 原有 UI 代码保持不变 ... # 启动前挂载健康路由 app = gr.routes.App.create_app(demo) app.add_api_route("/health", lambda: {"status": "ok"}, methods=["GET"])

vLLM 的/health端点是内置的，无需修改。

4.2 设置定时任务执行检查

用 systemd timer 替代 crontab，更统一、更可控：

sudo tee /etc/systemd/system/lightonocr-healthcheck.service << 'EOF' [Unit] Description=LightOnOCR Health Check After=network.target [Service] Type=oneshot ExecStart=/usr/local/bin/check-lightonocr-health.sh RemainAfterExit=yes [Install] WantedBy=multi-user.target EOF sudo tee /etc/systemd/system/lightonocr-healthcheck.timer << 'EOF' [Unit] Description=Run LightOnOCR Health Check Every 2 Minutes Requires=lightonocr-healthcheck.service [Timer] OnBootSec=5min OnUnitActiveSec=2min Persistent=true [Install] WantedBy=timers.target EOF sudo systemctl daemon-reload sudo systemctl enable lightonocr-healthcheck.timer sudo systemctl start lightonocr-healthcheck.timer

现在，系统每 2 分钟就会调用一次检查脚本：成功则记录 OK，失败则自动重启两个服务，并记入health.log。你可以随时查看：

sudo tail -n 20 /var/log/lightonocr/health.log

5. 实用技巧与避坑指南

5.1 GPU 内存优化：别让显存成为瓶颈

LightOnOCR-2-1B 占用约 16GB 显存，但实际使用中可能因 batch size 或图像尺寸波动。我们在lightonocr-backend.service中已设--gpu-memory-utilization 0.95，这是关键安全阀。如果你用的是 A10/A100 等大显存卡，可微调至0.98提升吞吐；如果是 24GB 卡，建议保守设为0.92，留足余量给系统和其他进程。

另外，vLLM 的--max-num-seqs 8控制并发请求数。实测中，8 是平衡速度与稳定性的甜点值——超过 10 容易触发 OOM；低于 4 则吞吐不足。如需更高并发，优先考虑横向扩展（多台机器部署），而非强行提参。

5.2 图片上传限制：前端也要守规矩

Gradio 默认不限制上传大小，但大图（>10MB）会导致前端卡顿甚至崩溃。在app.py的gr.Interface初始化处，加上参数：

gr.Interface( fn=extract_text, inputs=gr.Image(type="pil", label="上传图片（PNG/JPEG，≤10MB）"), outputs=gr.Textbox(label="识别结果"), title="LightOnOCR-2-1B 多语言文字识别", allow_flagging="never", examples=[...], # 新增限制 css=".gradio-container {max-width: 100% !important;}", ).launch( server_name="0.0.0.0", server_port=7860, share=False, favicon_path=None, # 关键：限制上传大小为 10MB max_file_size="10mb" )

这样用户上传超限文件时，前端会直接报错，避免后端无谓等待。

5.3 快速诊断三板斧

当服务异常时，别急着重启，先用这三条命令快速定位：

看日志最新 20 行：

sudo tail -n 20 /var/log/lightonocr/backend.log

查 GPU 显存实时占用：

nvidia-smi --query-compute-apps=pid,used_memory --format=csv,noheader,nounits

测试 API 是否通（用一张小图 base64）：
```
curl -s http://127.0.0.1:8000/health | jq .
```

如果health返回 200 但业务接口失败，大概率是模型加载异常或输入格式问题；如果health都不通，优先检查 vLLM 进程是否存活、端口是否被占。

6. 总结：从能用到好用的跨越

我们完成了 LightOnOCR-2-1B 的生产就绪改造：

服务化：通过两个 systemd service 文件，实现进程托管、开机自启、崩溃自愈、资源隔离；
日志治理：用 logrotate 实现日志按天轮转、自动压缩、30 天留存，彻底告别磁盘爆满；
主动监控：自定义健康检查脚本 + systemd timer，每 2 分钟自动探测，异常即重启，把“等用户反馈故障”变成“系统自己修复”；
细节加固：GPU 显存安全阀、前端上传限制、快速诊断指令，让运维不再靠猜。

这套方案不依赖容器编排，不引入额外组件，所有配置都是 Linux 通用标准，你可以直接复制粘贴到任何一台有 root 权限的服务器上。它不会让你的 OCR 识别得更快，但会让你的系统更稳、更省心、更像一个真正上线的产品。

下一步，你可以基于这个稳定底座，轻松对接企业微信机器人自动推送识别结果，或接入 Nginx 做 HTTPS 反向代理对外提供服务，甚至用 Prometheus + Grafana 把 GPU 利用率、API 延迟、错误率都可视化出来——而这一切，都建立在今天打下的坚实基础上。

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

LightOnOCR-2-1B生产环境部署：systemd服务管理+日志轮转+健康检查