百川 2-13B-Chat-4bits WebUI 部署：Supervisor 配置文件 baichuan-webui.conf 详解

关键点说明：

• exitcodes=0,2：定义哪些退出码被认为是'正常退出'。0 通常表示成功退出，2 可能表示某种预期的终止。只有当程序以这些代码退出时，Supervisor 才不会自动重启它。
• stopsignal=TERM：停止程序时发送 TERM 信号（优雅终止）。这给了程序清理资源的机会，而不是粗暴地直接杀死。
• stopwaitsecs=10：发送停止信号后等待 10 秒，如果程序还在运行，就强制终止。这是为了防止某些程序'赖着不走'。
• stopasgroup=true 和 killasgroup=true：这两个设置确保当停止程序时，它创建的所有子进程也会被一起停止。这对于 Python Web 服务特别重要，因为它可能会创建多个工作进程。

2.3 日志管理配置

stdout_logfile=/root/baichuan2-13b-webui/logs/supervisord.log stdout_logfile_maxbytes=10MB stdout_logfile_backups=10 stdout_capture_maxbytes=1MB stdout_events_enabled=false stderr_logfile=/root/baichuan2-13b-webui/logs/supervisord_err.log stderr_logfile_maxbytes=10MB stderr_logfile_backups=10 stderr_capture_maxbytes=1MB stderr_events_enabled=false 

日志配置的重要性：

日志是排查问题的'眼睛'。这个配置做了几件重要的事：

1. 日志轮转：每个日志文件最大 10MB，保留最近 10 个文件。这意味着你的日志不会无限增长占满磁盘空间。当 supervisord.log 达到 10MB 时，它会自动重命名为 supervisord.log.1，然后创建新的 supervisord.log，依此类推，最多保留 10 个历史文件。
2. 标准输出和错误分离：stdout_logfile 记录正常输出，stderr_logfile 记录错误信息。这样在排查问题时，你可以快速定位是普通信息还是错误信息。
3. 日志位置集中：所有日志都放在 /root/baichuan2-13b-webui/logs/ 目录下，与 WebUI 的访问日志、错误日志放在一起，方便统一管理。

实际查看日志的命令：

# 查看最近的日志
tail -f /root/baichuan2-13b-webui/logs/supervisord.log
# 查看错误日志
tail -f /root/baichuan2-13b-webui/logs/supervisord_err.log
# 查看所有日志文件
ls -lh /root/baichuan2-13b-webui/logs/

2.4 环境与资源限制

environment=PYTHONPATH="/root/baichuan2-13b-webui",PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" priority=999 

环境变量设置：

• PYTHONPATH：告诉 Python 解释器在哪里寻找模块。这里设置为项目根目录，确保 Python 能正确导入项目中的自定义模块。
• PATH：设置命令搜索路径。虽然这里设置的是系统默认路径，但在某些定制环境中，可能需要添加其他路径。
• priority=999：进程启动优先级。数字越小优先级越高（-20 最高，19 最低）。999 实际上是一个相对较低的优先级，确保系统关键服务先启动。

3. 配置文件的实际应用场景

理解了配置文件的每个部分后，我们来看看在实际使用中，这些配置如何发挥作用。

3.1 服务状态监控实战

当你运行 supervisorctl status baichuan-webui 时，看到的输出背后发生了什么？

# 实际执行这个命令时
supervisorctl status baichuan-webui
# 可能的输出
baichuan-webui RUNNING pid 28765, uptime 1 day, 2:30:15 

这个状态信息是 Supervisor 根据配置文件监控得到的：

• RUNNING：表示程序正在正常运行（autorestart=true 在起作用）
• pid 28765：进程 ID，如果服务异常，你可以用 kill -9 28765 强制终止
• uptime：运行时间，帮助你了解服务稳定性

3.2 服务管理命令详解

基于这个配置文件，你可以执行各种管理操作：

# 启动服务（如果配置文件中的 autostart=false，就需要手动启动）
supervisorctl start baichuan-webui
# 停止服务（会发送 TERM 信号，等待 10 秒后强制停止）
supervisorctl stop baichuan-webui
# 重启服务（先停止再启动）
supervisorctl restart baichuan-webui
# 重新加载配置文件（修改 conf 文件后需要执行）
supervisorctl update baichuan-webui
# 查看所有被 Supervisor 管理的服务
supervisorctl status all

3.3 开机自启动机制

很多人好奇为什么服务器重启后服务能自动恢复。这其实是多个配置共同作用的结果：

1. 程序配置中的 autostart=true：当 Supervisor 启动时，会自动启动所有 autostart=true 的程序。

完整的启动链条：

服务器启动 → systemd 启动 Supervisor → Supervisor 读取配置文件 → 启动 baichuan-webui → 执行 start.sh → 启动 WebUI 服务 

Supervisor 服务本身开机启动：

# 查看 Supervisor 是否开机自启
systemctl is-enabled supervisor
# 输出：enabled 表示已启用 

你可以通过这个命令验证整个启动过程：

# 查看 Supervisor 的启动日志
journalctl -u supervisor.service --since "1 hour ago"
# 查看具体的启动时间线
systemctl status supervisor.service

4. 常见问题排查指南

当 WebUI 服务出现问题时，这个配置文件和你对它的理解就能派上用场了。

4.1 服务启动失败

症状：supervisorctl status 显示 FATAL 或 BACKOFF

排查步骤：

手动测试启动脚本：

# 切换到项目目录
cd /root/baichuan2-13b-webui
# 手动执行启动脚本，看是否有错误
./start.sh 

检查启动脚本权限：

# 确保 start.sh 有执行权限
ls -l /root/baichuan2-13b-webui/start.sh
# 应该显示：-rwxr-xr-x
# 如果没有执行权限，添加权限
chmod +x /root/baichuan2-13b-webui/start.sh 

查看详细错误信息：

# 查看 Supervisor 的错误日志
cat /root/baichuan2-13b-webui/logs/supervisord_err.log
# 查看启动脚本的输出
supervisorctl tail -f baichuan-webui stdout 

4.2 服务频繁重启

症状：服务运行几分钟后就重启，uptime 时间很短

可能原因和解决：

配置错误：

# 检查配置文件语法
supervisorctl reread
supervisorctl update
# 如果有语法错误，会在这里显示 

端口冲突：

# 检查 7860 端口是否被占用
netstat -tulpn | grep :7860
# 如果被占用，可以修改 WebUI 的端口
# 需要修改 start.sh 和配置文件中的端口设置 

内存不足：

# 检查系统内存
free -h
# 检查 GPU 显存
nvidia-smi
# 如果显存不足，考虑调整模型加载参数
# 修改 start.sh 中的相关参数 

4.3 日志文件过大

症状：磁盘空间不足，发现日志文件很大

解决方案：

调整日志配置（修改 baichuan-webui.conf）：

# 减小单个日志文件大小
stdout_logfile_maxbytes=5MB
stderr_logfile_maxbytes=5MB
# 减少保留的文件数量
stdout_logfile_backups=5
stderr_logfile_backups=5 

修改后需要重新加载配置：

supervisorctl update baichuan-webui 

临时清理：

# 清空当前日志文件（服务运行时也可以执行）
> /root/baichuan2-13b-webui/logs/supervisord.log
> /root/baichuan2-13b-webui/logs/supervisord_err.log 

5. 高级配置与优化建议

如果你对服务的稳定性有更高要求，或者有特殊需求，可以考虑以下优化。

5.1 资源限制配置

为了防止服务占用过多资源影响系统，可以添加资源限制：

; 添加到 baichuan-webui.conf 中
process_name=%(program_name)s
numprocs=1
numprocs_start=0
; 内存限制（100MB 软限制，200MB 硬限制）
memory_limit=100MB
memory_limit_max=200MB
; CPU 限制（最多使用 2 个核心）
cpu_limit=200
cpu_limit_max=400 

参数说明：

• memory_limit：内存软限制，超过会收到警告
• memory_limit_max：内存硬限制，超过会被终止
• cpu_limit：CPU 使用率限制（百分比）

5.2 多实例部署

如果你的服务器配置足够高，可以运行多个实例提高并发能力：

; 修改进程名称模板
process_name=%(program_name)s_%(process_num)02d
; 启动 3 个实例
numprocs=3
numprocs_start=0
; 每个实例使用不同的端口
environment=PORT=786%(process_num)d,PYTHONPATH="/root/baichuan2-13b-webui" 

这样会启动三个实例，分别监听 7860、7861、7862 端口。你可以在前面加一个负载均衡器（如 Nginx）来分发请求。

5.3 健康检查配置

添加健康检查，确保服务真正可用而不仅仅是进程存在：

; 健康检查配置
[eventlistener:baichuan-healthcheck]
command=/root/baichuan2-13b-webui/healthcheck.sh
events=TICK_60
autostart=true
autorestart=true 

创建健康检查脚本 healthcheck.sh：

#!/bin/bash
# 健康检查脚本
if curl -s http://localhost:7860 > /dev/null; then
    exit 0 # 健康
else
    exit 1 # 不健康
fi 

6. 配置文件备份与恢复

配置文件一旦损坏，服务就无法正常管理。做好备份很重要。

6.1 备份配置文件

# 备份当前配置
cp /etc/supervisor/conf.d/baichuan-webui.conf /root/baichuan2-13b-webui/backup/baichuan-webui.conf.backup.$(date +%Y%m%d)
# 备份整个 Supervisor 配置目录
tar -czf /root/supervisor-backup-$(date +%Y%m%d).tar.gz /etc/supervisor/ 

6.2 恢复配置文件

# 如果配置文件损坏，从备份恢复
cp /root/baichuan2-13b-webui/backup/baichuan-webui.conf.backup.20240101 /etc/supervisor/conf.d/baichuan-webui.conf
# 重新加载配置
supervisorctl update baichuan-webui 

6.3 配置版本管理

如果你经常修改配置，建议使用版本控制：

# 初始化 Git 仓库（如果还没有）
cd /root/baichuan2-13b-webui
git init
# 添加配置文件
git add /etc/supervisor/conf.d/baichuan-webui.conf
# 提交更改
git commit -m "更新 Supervisor 配置"
# 查看配置历史
git log --oneline /etc/supervisor/conf.d/baichuan-webui.conf 

7. 总结

通过今天的详细解析，你现在应该对 baichuan-webui.conf 这个配置文件有了全面的理解。它不仅仅是几行配置文本，而是确保你的百川 AI 服务稳定运行的基石。

关键要点回顾：

1. 自动恢复能力：autostart 和 autorestart 设置确保了服务的高可用性
2. 日志管理：合理的日志配置帮助你在出现问题时快速定位
3. 进程管理：Supervisor 提供了完善的管理接口，让你可以轻松控制服务状态
4. 灵活扩展：配置文件支持各种高级设置，满足不同场景的需求

实用建议：

• 定期检查日志文件，了解服务运行状况
• 修改配置前做好备份
• 使用 supervisorctl 命令管理服务，而不是直接操作进程
• 遇到问题时，先看日志，再查配置，最后考虑修改

这个配置文件的设计考虑到了大多数使用场景，对于一般用户来说，默认配置已经足够稳定可靠。只有当你有特殊需求时，才需要调整其中的参数。