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

优质文章学习记录

08 Apr 2026 — 12 min read

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

1. 项目简介与部署价值

如果你已经成功部署了百川2-13B-Chat-4bits的WebUI，并且通过check.sh脚本看到服务运行正常，那么恭喜你，最复杂的部分已经完成了。但你可能会有这样的疑问：这个服务是怎么在后台稳定运行的？为什么服务器重启后它还能自动启动？今天，我们就来深入聊聊这个幕后的“守护者”——Supervisor配置文件。

简单来说，baichuan-webui.conf这个文件就像是给你的AI服务请了一个24小时在线的管家。它负责监控服务的运行状态，如果服务意外崩溃了，它会自动重启；如果服务器重启了，它会自动把服务拉起来。没有它，你的WebUI服务就像没有安全绳的高空作业，随时可能因为各种意外而中断。

这个配置文件虽然看起来只是一些文本设置，但它决定了你的AI服务能否稳定、可靠地长期运行。理解它，不仅能让你在遇到问题时快速定位，还能让你根据自己的需求进行定制化调整。

2. Supervisor配置文件结构解析

让我们打开位于/etc/supervisor/conf.d/目录下的baichuan-webui.conf文件，看看里面到底写了什么。我会逐段解释每个配置项的作用，让你彻底明白这个“管家”的工作方式。

2.1 基础配置部分

[program:baichuan-webui] command=/root/baichuan2-13b-webui/start.sh directory=/root/baichuan2-13b-webui user=root autostart=true autorestart=true startsecs=10 startretries=3

逐行解读：

[program:baichuan-webui]：这是定义一个Supervisor管理程序的开始。baichuan-webui是这个程序的唯一标识符，你在执行supervisorctl status baichuan-webui时看到的正是这个名字。
command=/root/baichuan2-13b-webui/start.sh：这是最重要的配置，告诉Supervisor要运行什么命令。这里指向的是项目目录下的start.sh启动脚本。为什么不直接运行Python命令？因为start.sh脚本里封装了环境激活、参数设置等复杂操作，让启动过程更可靠。
directory=/root/baichuan2-13b-webui：设置工作目录。这意味着所有相对路径的操作（比如读取配置文件、写入日志）都会基于这个目录进行。
user=root：以root用户身份运行程序。这确保了服务有足够的权限访问系统资源。在实际生产环境中，出于安全考虑，可能会使用专门的用户来运行。
autostart=true：当Supervisor启动时，自动启动这个程序。这就是为什么服务器重启后你的WebUI能自动恢复的关键设置。
autorestart=true：程序意外退出时自动重启。想象一下，如果因为某个临时错误导致服务崩溃，这个设置会让它在几秒钟内自动恢复，用户甚至感觉不到中断。
startsecs=10：程序启动后需要稳定运行10秒才被认为是启动成功。这避免了程序刚启动就崩溃的情况被误判为成功。
startretries=3：如果启动失败，最多重试3次。超过3次后，Supervisor会放弃并标记为失败状态。

2.2 进程管理配置

exitcodes=0,2 stopsignal=TERM stopwaitsecs=10 stopasgroup=true killasgroup=true

关键点说明：

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

日志配置的重要性：

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

日志轮转：每个日志文件最大10MB，保留最近10个文件。这意味着你的日志不会无限增长占满磁盘空间。当supervisord.log达到10MB时，它会自动重命名为supervisord.log.1，然后创建新的supervisord.log，依此类推，最多保留10个历史文件。
标准输出和错误分离：stdout_logfile记录正常输出，stderr_logfile记录错误信息。这样在排查问题时，你可以快速定位是普通信息还是错误信息。
日志位置集中：所有日志都放在/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 开机自启动机制

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

程序配置中的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服务稳定运行的基石。

关键要点回顾：

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

实用建议：

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

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

获取更多AI镜像

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

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

优质文章学习记录