lite-avatar形象库部署教程：supervisorctl配置文件详解与自定义钩子编写-深圳市維司達科技有限公司

lite-avatar形象库部署教程：supervisorctl配置文件详解与自定义钩子编写

1. 引言：为什么需要管理服务？

想象一下，你刚把lite-avatar形象库部署好，看着150多个精美的数字人形象，准备大展身手。突然，服务因为某个未知原因崩溃了，或者你想在服务启动时自动加载一些配置，又或者需要监控服务的运行状态。这时候，一个可靠的服务管理工具就显得至关重要。

Supervisor就是这样一个“服务管家”。它能在后台默默守护你的应用，一旦服务意外停止，它会自动重启；你可以随时查看服务状态、日志；还能在服务启动前后执行自定义脚本。今天，我们就来深入探讨如何为lite-avatar配置supervisor，并编写实用的自定义钩子，让你的数字人服务坚如磐石。

2. 环境准备与supervisor安装

在开始配置之前，确保你的系统已经准备好。我们假设你使用的是基于Debian/Ubuntu的Linux系统。

2.1 安装supervisor

打开终端，执行以下命令：

# 更新包列表 sudo apt update # 安装supervisor sudo apt install supervisor -y # 验证安装 supervisord --version

安装完成后，supervisor会自动启动。你可以通过以下命令检查它的状态：

# 检查supervisor服务状态 sudo systemctl status supervisor # 如果没运行，启动它 sudo systemctl start supervisor # 设置开机自启 sudo systemctl enable supervisor

2.2 了解supervisor目录结构

安装完成后，supervisor的主要配置文件和工作目录如下：

/etc/supervisor/ ├── supervisord.conf # 主配置文件 └── conf.d/ # 程序配置文件目录（我们主要在这里操作） /var/log/supervisor/ # supervisor自身日志目录

重要提示：我们通常不会直接修改主配置文件supervisord.conf，而是在/etc/supervisor/conf.d/目录下为每个服务创建独立的配置文件。这样管理起来更清晰，也避免破坏默认配置。

3. 为lite-avatar创建supervisor配置

现在，我们来为lite-avatar形象库服务创建一个专属的supervisor配置文件。

3.1 创建配置文件

在终端中执行：

# 切换到配置目录 cd /etc/supervisor/conf.d/ # 创建lite-avatar的配置文件 sudo nano liteavatar.conf

3.2 基础配置详解

将以下配置内容复制到文件中，我会逐段解释每个参数的作用：

[program:liteavatar] ; 程序名称，用于supervisorctl管理时使用 command=/usr/bin/python3 /root/workspace/liteavatar/app.py ; 启动命令：指定Python解释器和主程序路径 directory=/root/workspace/liteavatar ; 工作目录：命令执行时所在的目录 user=root ; 运行用户：根据你的安全需求设置，生产环境建议使用非root用户 autostart=true ; 自动启动：supervisor启动时自动启动该程序 autorestart=true ; 自动重启：程序退出时自动重启 startretries=3 ; 启动重试次数：如果启动失败，重试3次 startsecs=10 ; 启动等待时间：程序启动后等待10秒，确认是否启动成功 stopwaitsecs=10 ; 停止等待时间：发送停止信号后等待10秒，如果还没停止就强制终止 stdout_logfile=/root/workspace/liteavatar.log ; 标准输出日志文件 stdout_logfile_maxbytes=10MB ; 单个日志文件最大大小 stdout_logfile_backups=5 ; 保留的日志文件备份数量 stderr_logfile=/root/workspace/liteavatar_error.log ; 标准错误日志文件（错误信息单独记录） stderr_logfile_maxbytes=10MB ; 错误日志文件最大大小 stderr_logfile_backups=3 ; 错误日志备份数量 environment=PYTHONPATH="/root/workspace/liteavatar",PORT="7860" ; 环境变量：可以在这里设置程序需要的环境变量

3.3 配置参数深度解析

为了让配置更贴合实际需求，我们来详细看看几个关键参数：

autorestart的几种模式：

true：意外退出时自动重启（推荐）
false：不自动重启
unexpected：只有意外退出时才重启（退出码不为0或2）
exitcodes：指定哪些退出码时重启

日志轮转策略：上面的配置使用了按大小轮转，你也可以按时间轮转：

stdout_logfile=/root/workspace/liteavatar_%(year)s%(month)s%(day)s.log stdout_logfile_maxbytes=0 ; 0表示不按大小轮转 stdout_logfile_backups=30 ; 保留30天的日志

资源限制（可选，防止程序占用过多资源）：

priority=999 ; 进程优先级（数字越小优先级越高） process_name=%(program_name)s_%(process_num)02d ; 进程名格式 numprocs=1 ; 进程数量 numprocs_start=0 ; 进程号起始值 ; 资源限制 rlimit_core=0 ; core文件大小限制（0表示不限制） rlimit_nofile=65535 ; 文件描述符限制 rlimit_nproc=65535 ; 进程数限制

4. 应用配置并管理服务

配置文件写好了，接下来让它生效。

4.1 加载新配置

# 重新加载supervisor配置（不会重启正在运行的程序） sudo supervisorctl reread # 更新配置（新程序会被启动，配置有变化的程序会重启） sudo supervisorctl update # 或者两步合并 sudo supervisorctl update all

4.2 常用管理命令

现在你可以使用supervisorctl来管理lite-avatar服务了：

# 查看所有程序状态 sudo supervisorctl status # 查看lite-avatar状态 sudo supervisorctl status liteavatar # 启动服务 sudo supervisorctl start liteavatar # 停止服务 sudo supervisorctl stop liteavatar # 重启服务 sudo supervisorctl restart liteavatar # 查看实时日志 sudo supervisorctl tail -f liteavatar # 查看错误日志 sudo supervisorctl tail -f liteavatar stderr # 进入交互模式（可以连续执行多个命令） sudo supervisorctl

4.3 查看服务日志

除了通过supervisorctl查看日志，你也可以直接查看日志文件：

# 查看最新100行日志 tail -100 /root/workspace/liteavatar.log # 实时查看日志更新 tail -f /root/workspace/liteavatar.log # 查看包含错误的关键日志 grep -i error /root/workspace/liteavatar_error.log # 查看特定时间段的日志 sed -n '/2024-01-15 10:00:00/,/2024-01-15 11:00:00/p' /root/workspace/liteavatar.log

5. 编写自定义钩子脚本

钩子脚本（hook scripts）是supervisor的一个强大功能，允许你在服务状态变化时执行自定义操作。比如：服务启动前检查依赖、启动后发送通知、停止时清理临时文件等。

5.1 钩子脚本存放位置

创建一个专门的目录来存放钩子脚本：

# 创建钩子脚本目录 mkdir -p /root/workspace/liteavatar/hooks # 设置执行权限 chmod +x /root/workspace/liteavatar/hooks/

5.2 启动前检查钩子

创建一个在服务启动前执行的脚本，检查必要的依赖和配置：

sudo nano /root/workspace/liteavatar/hooks/before_start.sh

脚本内容：

#!/bin/bash # lite-avatar服务启动前检查脚本 # 文件名：before_start.sh echo "=========================================" echo "$(date) - 开始执行lite-avatar启动前检查" echo "=========================================" # 检查Python环境 if ! command -v python3 &> /dev/null; then echo "错误：未找到python3，请先安装Python3" exit 1 fi PYTHON_VERSION=$(python3 --version | awk '{print $2}') echo "Python版本：$PYTHON_VERSION" # 检查必要Python包 REQUIRED_PACKAGES=("torch" "numpy" "pillow" "flask") for package in "${REQUIRED_PACKAGES[@]}"; do if ! python3 -c "import $package" 2>/dev/null; then echo "警告：未找到Python包 - $package" echo "尝试安装：pip3 install $package" pip3 install $package --quiet else echo "已安装：$package" fi done # 检查模型文件是否存在 MODEL_DIR="/root/workspace/liteavatar/models" if [ ! -d "$MODEL_DIR" ]; then echo "错误：模型目录不存在 - $MODEL_DIR" echo "请先下载模型文件" exit 1 fi # 检查端口是否被占用 PORT=7860 if lsof -i:$PORT > /dev/null 2>&1; then echo "警告：端口 $PORT 已被占用" PID=$(lsof -ti:$PORT) echo "占用进程PID：$PID" # 可以选择杀死占用进程（谨慎操作） # kill -9 $PID fi # 清理旧的临时文件 TEMP_DIR="/tmp/liteavatar" if [ -d "$TEMP_DIR" ]; then echo "清理临时目录：$TEMP_DIR" rm -rf "$TEMP_DIR"/* fi # 创建必要的目录 mkdir -p "$TEMP_DIR" mkdir -p "/root/workspace/liteavatar/logs" echo "=========================================" echo "$(date) - 启动前检查完成" echo "=========================================" exit 0

记得给脚本添加执行权限：

chmod +x /root/workspace/liteavatar/hooks/before_start.sh

5.3 启动后通知钩子

创建一个服务启动成功后发送通知的脚本：

sudo nano /root/workspace/liteavatar/hooks/after_start.sh

脚本内容：

#!/bin/bash # lite-avatar服务启动后通知脚本 # 文件名：after_start.sh echo "=========================================" echo "$(date) - lite-avatar服务启动成功" echo "=========================================" # 获取服务信息 SERVICE_NAME="liteavatar" START_TIME=$(date '+%Y-%m-%d %H:%M:%S') HOSTNAME=$(hostname) IP_ADDRESS=$(hostname -I | awk '{print $1}') PORT=7860 # 检查服务是否真的在运行 sleep 3 # 等待服务完全启动 if curl -s http://localhost:$PORT/health > /dev/null 2>&1; then STATUS="运行正常" HEALTH_CHECK="通过" else STATUS="运行异常" HEALTH_CHECK="失败" fi # 记录到日志文件 LOG_FILE="/root/workspace/liteavatar/logs/startup.log" { echo "服务启动时间：$START_TIME" echo "服务名称：$SERVICE_NAME" echo "主机名：$HOSTNAME" echo "IP地址：$IP_ADDRESS" echo "服务端口：$PORT" echo "健康检查：$HEALTH_CHECK" echo "服务状态：$STATUS" echo "访问地址：http://$IP_ADDRESS:$PORT" echo "" } >> "$LOG_FILE" # 发送通知（这里以写入文件为例，实际可以替换为邮件、钉钉、微信等） NOTIFICATION_FILE="/root/workspace/liteavatar/logs/notifications.log" { echo "[$(date)] 服务启动通知" echo "服务：lite-avatar形象库" echo "状态：已启动" echo "地址：http://$IP_ADDRESS:$PORT" echo "健康状态：$HEALTH_CHECK" echo "---" } >> "$NOTIFICATION_FILE" # 如果是生产环境，可以在这里添加实际的通知逻辑 # 例如发送邮件： # echo "lite-avatar服务已启动" | mail -s "服务启动通知" admin@example.com # 或者调用Webhook： # curl -X POST -H "Content-Type: application/json" \ # -d '{"text":"lite-avatar服务已启动"}' \ # https://your-webhook-url echo "启动信息已记录到：$LOG_FILE" echo "通知已发送到：$NOTIFICATION_FILE" exit 0

添加执行权限：

chmod +x /root/workspace/liteavatar/hooks/after_start.sh

5.4 停止时清理钩子

创建一个在服务停止时清理资源的脚本：

sudo nano /root/workspace/liteavatar/hooks/on_stop.sh

脚本内容：

#!/bin/bash # lite-avatar服务停止时清理脚本 # 文件名：on_stop.sh echo "=========================================" echo "$(date) - 执行lite-avatar停止清理" echo "=========================================" # 记录停止时间 STOP_TIME=$(date '+%Y-%m-%d %H:%M:%S') LOG_FILE="/root/workspace/liteavatar/logs/shutdown.log" # 清理临时文件 TEMP_DIRS=( "/tmp/liteavatar" "/root/workspace/liteavatar/temp" "/root/workspace/liteavatar/cache" ) for dir in "${TEMP_DIRS[@]}"; do if [ -d "$dir" ]; then echo "清理目录：$dir" find "$dir" -type f -mtime +1 -delete # 删除1天前的文件 find "$dir" -type d -empty -delete # 删除空目录 fi done # 清理旧的日志文件（保留最近7天） LOG_DIR="/root/workspace/liteavatar/logs" if [ -d "$LOG_DIR" ]; then echo "清理旧日志文件" find "$LOG_DIR" -name "*.log" -type f -mtime +7 -delete fi # 释放GPU内存（如果使用了GPU） if command -v nvidia-smi &> /dev/null; then echo "检查GPU进程..." # 查找可能残留的Python进程 GPU_PROCESSES=$(nvidia-smi --query-compute-apps=pid --format=csv,noheader) if [ -n "$GPU_PROCESSES" ]; then echo "发现GPU进程：$GPU_PROCESSES" # 谨慎操作：这里只是示例，实际应根据需要处理 # for pid in $GPU_PROCESSES; do # kill -9 $pid 2>/dev/null # done fi fi # 记录停止信息 { echo "服务停止时间：$STOP_TIME" echo "清理操作完成" echo "临时文件已清理" echo "旧日志已删除（保留7天内）" echo "" } >> "$LOG_FILE" echo "清理完成，记录已保存到：$LOG_FILE" exit 0

添加执行权限：

chmod +x /root/workspace/liteavatar/hooks/on_stop.sh

6. 在supervisor配置中集成钩子

现在，我们需要修改之前的supervisor配置，让它在适当的时候执行我们的钩子脚本。

6.1 更新配置文件

编辑之前的配置文件：

sudo nano /etc/supervisor/conf.d/liteavatar.conf

在原有配置基础上添加钩子配置：

[program:liteavatar] command=/usr/bin/python3 /root/workspace/liteavatar/app.py directory=/root/workspace/liteavatar user=root autostart=true autorestart=true startretries=3 startsecs=10 stopwaitsecs=10 stdout_logfile=/root/workspace/liteavatar.log stdout_logfile_maxbytes=10MB stdout_logfile_backups=5 stderr_logfile=/root/workspace/liteavatar_error.log stderr_logfile_maxbytes=10MB stderr_logfile_backups=3 environment=PYTHONPATH="/root/workspace/liteavatar",PORT="7860" ; ========== 钩子配置 ========== ; 启动前执行检查脚本 startsecs=15 ; 增加启动等待时间，给钩子脚本执行时间 ; 启动前钩子（非supervisor原生支持，通过包装脚本实现） ; 我们将修改command来集成启动前检查 ; 停止时钩子 stopsignal=TERM ; 停止信号类型 stopwaitsecs=30 ; 增加停止等待时间，给清理脚本时间 ; 退出码映射 exitcodes=0,2 ; 0和2表示正常退出

6.2 创建包装启动脚本

由于supervisor没有直接的"启动前钩子"配置，我们可以创建一个包装脚本来实现：

sudo nano /root/workspace/liteavatar/start_wrapper.sh

脚本内容：

#!/bin/bash # lite-avatar启动包装脚本 # 文件名：start_wrapper.sh # 执行启动前检查 echo "执行启动前检查..." /root/workspace/liteavatar/hooks/before_start.sh # 检查前一个命令的退出状态 if [ $? -ne 0 ]; then echo "启动前检查失败，终止启动" exit 1 fi echo "启动前检查通过，开始启动主程序..." # 执行启动后通知（在后台执行，不阻塞主程序） (/root/workspace/liteavatar/hooks/after_start.sh) & # 启动主程序 exec /usr/bin/python3 /root/workspace/liteavatar/app.py "$@"

添加执行权限：

chmod +x /root/workspace/liteavatar/start_wrapper.sh

6.3 更新supervisor配置使用包装脚本

修改supervisor配置中的command：

[program:liteavatar] ; 使用包装脚本启动 command=/root/workspace/liteavatar/start_wrapper.sh ; 其他配置保持不变...

6.4 创建停止包装脚本

同样，我们可以创建一个停止包装脚本：

sudo nano /root/workspace/liteavatar/stop_wrapper.sh

脚本内容：

#!/bin/bash # lite-avatar停止包装脚本 # 文件名：stop_wrapper.sh # 首先停止主程序 echo "停止主程序..." pkill -f "python3 /root/workspace/liteavatar/app.py" # 等待主程序停止 sleep 5 # 执行停止清理 echo "执行停止清理..." /root/workspace/liteavatar/hooks/on_stop.sh echo "服务停止完成"

添加执行权限：

chmod +x /root/workspace/liteavatar/stop_wrapper.sh

7. 高级配置与监控

7.1 配置Web管理界面

Supervisor提供了一个Web管理界面，可以方便地查看和管理所有服务。

编辑主配置文件：

sudo nano /etc/supervisor/supervisord.conf

找到[inet_http_server]部分，取消注释并修改：

[inet_http_server] port=0.0.0.0:9001 ; 监听所有IP的9001端口 username=admin ; 用户名 password=your_password ; 密码（请修改为强密码）

重启supervisor使配置生效：

sudo systemctl restart supervisor

现在你可以通过浏览器访问http://你的服务器IP:9001来管理服务了。

7.2 配置日志轮转

除了supervisor自带的日志管理，我们还可以使用系统的logrotate来管理日志：

创建logrotate配置：

sudo nano /etc/logrotate.d/liteavatar

内容：

/root/workspace/liteavatar.log /root/workspace/liteavatar_error.log /root/workspace/liteavatar/logs/*.log { daily # 每天轮转 missingok # 如果日志文件丢失，不报错 rotate 30 # 保留30天的日志 compress # 压缩旧日志 delaycompress # 延迟压缩（下次轮转时压缩） notifempty # 如果日志为空，不轮转 create 644 root root # 创建新日志文件的权限 sharedscripts # 所有日志处理完后执行脚本 postrotate # 通知supervisor重新打开日志文件 supervisorctl signal liteavatar SIGUSR2 endscript }

7.3 监控服务健康状态

我们可以创建一个健康检查脚本，定期检查服务状态：

sudo nano /root/workspace/liteavatar/hooks/health_check.sh

脚本内容：

#!/bin/bash # lite-avatar健康检查脚本 # 文件名：health_check.sh PORT=7860 HEALTH_URL="http://localhost:$PORT/health" STATUS_FILE="/tmp/liteavatar_health.status" MAX_FAILURES=3 FAILURE_COUNT_FILE="/tmp/liteavatar_failure.count" # 检查服务健康状态 check_health() { if curl -s --max-time 5 "$HEALTH_URL" | grep -q "healthy"; then echo "OK" return 0 else echo "ERROR" return 1 fi } # 记录状态 record_status() { local status=$1 local timestamp=$(date '+%Y-%m-%d %H:%M:%S') echo "$timestamp - $status" >> "$STATUS_FILE" # 只保留最近100条记录 tail -100 "$STATUS_FILE" > "${STATUS_FILE}.tmp" && mv "${STATUS_FILE}.tmp" "$STATUS_FILE" } # 主逻辑 if check_health; then echo "$(date) - 服务健康检查通过" record_status "HEALTHY" # 重置失败计数 echo "0" > "$FAILURE_COUNT_FILE" else echo "$(date) - 服务健康检查失败" record_status "UNHEALTHY" # 增加失败计数 if [ -f "$FAILURE_COUNT_FILE" ]; then failures=$(cat "$FAILURE_COUNT_FILE") failures=$((failures + 1)) else failures=1 fi echo "$failures" > "$FAILURE_COUNT_FILE" # 如果连续失败超过阈值，尝试重启 if [ "$failures" -ge "$MAX_FAILURES" ]; then echo "$(date) - 连续失败 $failures 次，尝试重启服务" record_status "RESTARTING" sudo supervisorctl restart liteavatar # 重置失败计数 echo "0" > "$FAILURE_COUNT_FILE" record_status "RESTARTED" fi fi

添加执行权限并设置定时任务：

chmod +x /root/workspace/liteavatar/hooks/health_check.sh # 添加到crontab，每分钟检查一次 (crontab -l 2>/dev/null; echo "* * * * * /root/workspace/liteavatar/hooks/health_check.sh >> /root/workspace/liteavatar/logs/health_check.log 2>&1") | crontab -

8. 故障排查与常见问题

8.1 supervisorctl常见问题

问题1：配置更新后服务没启动

# 查看配置是否有语法错误 sudo supervisorctl reread # 查看详细错误信息 sudo supervisorctl update sudo tail -f /var/log/supervisor/supervisord.log

问题2：服务启动后立即退出

# 查看服务的退出码 sudo supervisorctl status liteavatar # 查看详细日志 sudo supervisorctl tail -f liteavatar stderr # 手动测试启动命令 cd /root/workspace/liteavatar /usr/bin/python3 app.py

问题3：权限问题

# 检查文件权限 ls -la /root/workspace/liteavatar/ # 检查脚本是否有执行权限 ls -la /root/workspace/liteavatar/hooks/*.sh # 如果使用非root用户，确保用户有权限 sudo chown -R username:username /root/workspace/liteavatar

8.2 钩子脚本调试技巧

查看钩子脚本执行日志：

# 手动测试钩子脚本 /root/workspace/liteavatar/hooks/before_start.sh # 查看supervisor执行日志 sudo tail -f /var/log/supervisor/supervisord.log | grep liteavatar # 查看包装脚本输出 sudo supervisorctl tail -f liteavatar

在钩子脚本中添加调试信息：

# 在脚本开头添加 set -x # 开启调试模式，显示执行的每一行命令 # 或者在关键位置添加日志 echo "DEBUG: 当前目录是 $(pwd)" >> /tmp/debug.log echo "DEBUG: 环境变量 PATH=$PATH" >> /tmp/debug.log

8.3 性能监控

监控服务资源使用：

# 查看服务进程ID sudo supervisorctl pid liteavatar # 查看进程资源使用 top -p $(sudo supervisorctl pid liteavatar) # 查看内存使用 ps -p $(sudo supervisorctl pid liteavatar) -o pid,rss,vsz,cmd # 如果是GPU服务，查看GPU使用 nvidia-smi | grep -A5 "Processes"

9. 总结

通过本文的详细讲解，你应该已经掌握了：

Supervisor的安装与基础配置：学会了如何安装supervisor，并为lite-avatar创建专属的配置文件
服务管理命令：熟练使用supervisorctl来启动、停止、重启和监控服务
自定义钩子脚本编写：创建了启动前检查、启动后通知、停止时清理等实用钩子
高级监控与管理：配置了Web管理界面、日志轮转和健康检查
故障排查技巧：掌握了常见问题的解决方法

关键要点回顾：

Supervisor配置文件要放在/etc/supervisor/conf.d/目录下
钩子脚本可以极大增强服务的可靠性和可维护性
定期检查日志是预防问题的好习惯
健康检查脚本能自动恢复异常服务

下一步建议：

根据你的实际需求，调整钩子脚本的具体逻辑
考虑将通知功能集成到你的监控系统（如Prometheus、Grafana）
编写更多的维护脚本，如备份脚本、数据清理脚本等
考虑使用Docker容器来进一步隔离和管理服务

记住，一个好的服务管理配置不仅能减少运维工作量，还能大大提高服务的稳定性。现在你的lite-avatar形象库已经有了一个可靠的"守护者"，可以更专注于数字人应用的开发了。

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

lite-avatar形象库部署教程：supervisorctl配置文件详解与自定义钩子编写