VideoAgentTrek-ScreenFilter代码实例：Supervisor自启服务管理实战

本文介绍了如何在星图GPU平台上自动化部署VideoAgentTrek-ScreenFilter镜像，实现基于YOLO的视频/图片屏幕内容检测服务。通过配置Supervisor守护进程，该应用可升级为具备自动重启和状态监控能力的生产级服务，确保检测任务稳定运行。

ThunderstormDragon65

893人浏览 · 2026-04-03 04:12:11

ThunderstormDragon65 · 2026-04-03 04:12:11 发布

VideoAgentTrek-ScreenFilter代码实例：Supervisor自启服务管理实战

1. 引言：从手动启动到自动化服务

想象一下这个场景：你部署了一个基于YOLO的视频目标检测应用，每次服务器重启，都需要手动登录、激活环境、启动服务。如果半夜服务器宕机，第二天早上才发现服务挂了，业务中断了几个小时，这无疑是一场运维噩梦。

今天，我们就来解决这个问题。本文将手把手带你，将一个基于 VideoAgentTrek-ScreenFilter 模型的视频/图片检测应用，从手动启动的“玩具”，升级为具备 Supervisor守护、自动重启、状态监控 的“生产级”服务。

你将学到什么？

如何为你的AI应用配置Supervisor守护进程
如何实现服务崩溃后自动恢复
如何通过命令行轻松管理服务状态
如何查看实时日志，快速定位问题

为什么选择Supervisor？ Supervisor是一个用Python写的进程管理工具，它能把一个普通的命令行程序，变成在后台运行的守护进程。它最大的好处是：服务挂了能自动重启，再也不用担心半夜宕机没人管了。

2. 项目背景与核心功能

在深入服务管理之前，我们先快速了解一下 VideoAgentTrek-ScreenFilter 这个应用是做什么的。

2.1 应用核心能力

这是一个基于Ultralytics YOLO框架的目标检测模型，专门用于识别视频和图片中的屏幕类内容（比如电脑显示器、手机屏幕、电视等）。它提供了两种使用模式：

图片检测模式：上传一张图片，它能识别出图中的屏幕，并返回两个结果：
- 可视化图片：在原图上用框标出检测到的屏幕
- JSON明细：包含每个检测框的类别、置信度、坐标位置
视频检测模式：上传一段视频，它会逐帧分析，并返回：
- 带检测框的视频：每一帧都标出了屏幕位置
- JSON统计报告：汇总了整个视频的检测情况（如总共发现了多少个屏幕，每一类出现了多少次）

2.2 技术栈与部署现状

这个应用通常部署在CSDN星图这样的GPU云平台上，提供了一个开箱即用的Web界面（运行在7860端口）。用户通过浏览器上传文件、调整参数、查看结果，非常方便。

但这里有个问题：这个Web服务是通过一个Python脚本启动的。如果这个脚本进程因为任何原因退出了（比如代码异常、服务器重启、内存不足），服务就停止了，用户也就无法访问了。

我们的目标，就是让Supervisor来接管这个进程的生命周期管理。

3. Supervisor配置实战：从零到守护进程

下面，我们一步步来配置Supervisor，让你能清晰看到每个文件、每条命令的作用。

3.1 第一步：创建Supervisor配置文件

Supervisor的配置文件通常放在 /etc/supervisor/conf.d/ 目录下。我们为视频检测服务创建一个专属的配置文件。

# 切换到配置目录
cd /etc/supervisor/conf.d/

# 创建配置文件（需要sudo权限）
sudo nano videoagent-screenfilter.conf

将以下配置内容粘贴到文件中：

[program:videoagent-screenfilter]
# 启动命令（这里就是原来你手动执行的命令）
command=/usr/bin/python /root/workspace/app.py

# 程序运行目录
directory=/root/workspace

# 自动启动（当Supervisor启动时，这个程序也自动启动）
autostart=true

# 自动重启（程序退出后自动重启）
autorestart=true

# 启动重试次数
startretries=3

# 运行用户（根据你的实际情况调整）
user=root

# 重定向标准输出到日志文件
stdout_logfile=/root/workspace/videoagent-screenfilter.log
stdout_logfile_maxbytes=10MB
stdout_logfile_backups=5

# 重定向标准错误到日志文件
stderr_logfile=/root/workspace/videoagent-screenfilter-error.log
stderr_logfile_maxbytes=10MB
stderr_logfile_backups=5

# 环境变量（如果有需要的话）
environment=PYTHONPATH="/root/workspace",MAX_VIDEO_SECONDS="60"

配置参数解读：

[program:videoagent-screenfilter]：定义了一个名为 videoagent-screenfilter 的程序
command：最重要的参数，指定要运行的具体命令
autorestart=true：这是“自动恢复”魔法的关键！程序异常退出后会自动重新启动
stdout_logfile 和 stderr_logfile：把程序输出的日志保存到文件，方便后续排查问题

3.2 第二步：让Supervisor加载新配置

创建好配置文件后，需要告诉Supervisor重新加载配置，这样它才能识别我们这个新服务。

# 重新读取所有配置文件
sudo supervisorctl reread

# 更新配置（让新配置生效）
sudo supervisorctl update

执行完这两条命令后，你应该能看到类似这样的输出：

videoagent-screenfilter: available

这表示Supervisor已经识别到了我们的新服务配置。

3.3 第三步：启动并验证服务

现在，让我们启动这个服务，并检查它是否正常运行。

# 启动服务
sudo supervisorctl start videoagent-screenfilter

# 查看服务状态
sudo supervisorctl status videoagent-screenfilter

如果一切正常，你会看到类似这样的输出：

videoagent-screenfilter RUNNING pid 12345, uptime 0:00:30

恭喜！ 你的视频检测服务现在已经由Supervisor托管，具备了自动重启的能力。

4. 日常运维：服务管理命令大全

配置好之后，日常运维就变得非常简单。下面这些命令，是你需要经常用到的。

4.1 服务状态管理

# 查看所有由Supervisor管理的服务状态
sudo supervisorctl status

# 查看指定服务的详细状态
sudo supervisorctl status videoagent-screenfilter

# 启动服务
sudo supervisorctl start videoagent-screenfilter

# 停止服务
sudo supervisorctl stop videoagent-screenfilter

# 重启服务（先停止再启动）
sudo supervisorctl restart videoagent-screenfilter

4.2 日志查看与监控

日志是排查问题的关键。Supervisor帮我们把日志都保存到了指定文件。

# 查看实时日志（最常用）
tail -f /root/workspace/videoagent-screenfilter.log

# 查看最近100行日志
tail -100 /root/workspace/videoagent-screenfilter.log

# 查看错误日志
tail -50 /root/workspace/videoagent-screenfilter-error.log

# 搜索日志中的特定信息（比如错误）
grep -i "error" /root/workspace/videoagent-screenfilter.log

4.3 网络与进程检查

有时候，服务状态显示是RUNNING，但实际端口没监听，这时候需要进一步检查。

# 检查7860端口是否在监听
sudo netstat -tlnp | grep 7860
# 或者使用ss命令（更现代）
sudo ss -ltnp | grep 7860

# 查看具体的Python进程
ps aux | grep "app.py"
ps aux | grep "videoagent"

# 检查GPU是否被使用（如果用了GPU）
nvidia-smi

5. 故障排查：常见问题与解决方案

即使有了Supervisor，服务运行中也可能遇到各种问题。下面是一些常见问题的排查思路。

5.1 服务启动失败

现象：sudo supervisorctl status 显示服务状态为 FATAL 或不断重启。

排查步骤：

查看错误日志：这是第一步，也是最重要的一步。
```
tail -100 /root/workspace/videoagent-screenfilter-error.log
```
常见错误原因：
- Python依赖缺失：错误日志中可能有 ModuleNotFoundError
- 端口被占用：7860端口已经被其他程序使用
- 权限问题：程序没有权限访问某些文件或目录
- 路径错误：command 中指定的Python路径或脚本路径不正确
手动测试命令：在命令行中手动执行配置文件中 command 指定的命令，看是否能正常运行。
```
cd /root/workspace
/usr/bin/python app.py
```

5.2 服务运行中异常退出

现象：服务运行一段时间后自动重启，状态在 RUNNING 和 STARTING 之间切换。

排查步骤：

查看退出前的日志：

# 查看日志最后部分，寻找异常信息
tail -200 /root/workspace/videoagent-screenfilter.log

可能的原因：
- 内存不足：处理大视频时内存耗尽
- GPU显存不足：模型加载或推理时显存不够
- 代码异常：程序中有未捕获的异常
- 外部依赖服务不可用

资源监控：在服务运行期间监控系统资源。

# 监控内存使用
free -h

# 监控GPU显存（如果使用GPU）
watch -n 1 nvidia-smi

5.3 Web界面无法访问

现象：服务状态显示 RUNNING，但浏览器无法打开页面。

排查步骤：

检查端口监听：

# 确认7860端口确实在监听
sudo netstat -tlnp | grep 7860

检查防火墙：

# 查看防火墙规则（根据系统不同）
sudo ufw status  # Ubuntu
sudo firewall-cmd --list-all  # CentOS

检查应用日志：查看应用是否正常启动了Web服务。

grep -i "running on" /root/workspace/videoagent-screenfilter.log
grep -i "7860" /root/workspace/videoagent-screenfilter.log

6. 高级技巧：让服务更健壮

基本的Supervisor配置已经能解决大部分问题，但如果你想让服务更加稳定，可以考虑下面这些进阶配置。

6.1 添加健康检查

可以在Supervisor配置中添加一个简单的健康检查脚本，定期检查服务是否真的可用，而不仅仅是进程是否存在。

首先，创建一个健康检查脚本：

# 创建健康检查脚本
nano /root/workspace/health_check.py

脚本内容：

#!/usr/bin/env python3
import requests
import sys

try:
    # 尝试访问服务的健康检查端点或首页
    response = requests.get('http://localhost:7860/', timeout=5)
    if response.status_code == 200:
        print("Service is healthy")
        sys.exit(0)  # 退出码0表示健康
    else:
        print(f"Service returned status code: {response.status_code}")
        sys.exit(1)  # 退出码非0表示不健康
except Exception as e:
    print(f"Health check failed: {str(e)}")
    sys.exit(1)

然后修改Supervisor配置，添加健康检查：

# 在原有的[program]配置下方添加
[program:videoagent-healthcheck]
command=/usr/bin/python /root/workspace/health_check.py
autostart=true
autorestart=true
startretries=3
user=root
stdout_logfile=/root/workspace/healthcheck.log
stderr_logfile=/root/workspace/healthcheck-error.log

6.2 资源限制与监控

如果你的服务器资源有限，可以给服务设置资源限制，防止单个服务耗尽所有资源。

# 在原有的videoagent-screenfilter配置中添加
[program:videoagent-screenfilter]
# ... 原有配置 ...

# 内存限制（超过限制会被重启）
memory_limit=2GB

# 进程数限制
process_name=%(program_name)s_%(process_num)02d
numprocs=1

# 停止信号和超时时间
stopsignal=INT
stopwaitsecs=30

6.3 日志轮转与清理

随着服务运行，日志文件会越来越大。可以配置日志轮转，自动清理旧日志。

# 在原有的stdout_logfile配置后添加
stdout_logfile_maxbytes=50MB  # 单个日志文件最大50MB
stdout_logfile_backups=10     # 保留10个备份文件
stdout_logfile_keep_days=30   # 保留30天的日志

stderr_logfile_maxbytes=20MB
stderr_logfile_backups=5
stderr_logfile_keep_days=7