解决Bisheng最常见故障：从启动失败到工作流异常的全流程修复指南

【免费下载链接】bisheng Bisheng is an open LLM devops platform for next generation AI applications. 项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng

你是否曾遇到Bisheng部署后无法访问？工作流执行到一半突然卡住？文档解析始终失败？本文将针对企业用户最常遇到的8类技术问题，提供基于官方源码和配置文件的解决方案，让你在15分钟内恢复服务。

部署启动类故障

Docker容器启动失败

症状：执行docker compose up -d后部分容器状态异常，使用docker ps查看发现backend或frontend容器反复重启。

解决方案：

1. 检查容器日志定位具体错误：

docker logs bisheng-backend  # 查看后端服务日志
docker logs bisheng-frontend  # 查看前端服务日志

2. 验证MySQL连接配置是否正确： 配置文件路径：docker/bisheng/config/config.yaml

database_url: "mysql+pymysql://root:gAAAAABlp4b4c59FeVGF_OQRVf6NOUIGdxq8246EBD-b0hdK_jVKRs1x4PoAn0A6C5S6IiFKmWn0Nm5eBUWu-7jxcqw6TiVjQA==@mysql:3306/bisheng?charset=utf8mb4"

注意：默认加密密码为1234，如需修改请参考官方文档中的密码加密方法

3. 确认系统资源是否满足最低要求：

• CPU ≥ 4核
• 内存 ≥ 16GB
• 磁盘空间 ≥ 50GB

服务端口冲突

症状：Nginx启动失败，日志显示"bind() to 0.0.0.0:3001 failed (98: Address already in use)"

解决方案：修改Nginx配置文件中的端口映射： 配置文件路径：docker/nginx/conf.d/default.conf

server {
    listen 3002;  # 将冲突的3001端口改为其他可用端口
    server_name localhost;
    ...
}

同时更新docker-compose.yml中的端口映射：docker/docker-compose.yml

services:
  frontend:
    ports:
      - "3002:3001"  # 左侧主机端口改为3002

数据库连接故障

MySQL连接超时

症状：Backend日志出现"OperationalError: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server on 'mysql' ([Errno 111] Connection refused)")"

解决方案：

1. 检查MySQL容器健康状态：

docker inspect -f '{{.State.Health.Status}}' bisheng-mysql

2. 验证MySQL服务是否正常启动： 配置文件路径：docker/mysql/conf/my.cnf 确认以下关键配置：

[mysqld]
port = 3306
max_connections = 1000
wait_timeout = 600
interactive_timeout = 600

3. 重启MySQL服务：

docker restart bisheng-mysql

Redis缓存连接失败

症状：应用启动时报错"Redis connection error: Connection refused"

解决方案：检查Redis配置： 配置文件路径：docker/redis/redis.conf 确保以下配置正确：

bind 0.0.0.0
port 6379
timeout 300

应用配置文件中的Redis连接字符串：docker/bisheng/config/config.yaml

redis_url: "redis://redis:6379/1"

工作流执行异常

工作流执行到一半停止

症状：工作流执行过程中突然停止，无错误提示，状态停留在"运行中"。

解决方案：

1. 检查Celery Worker日志：

docker logs bisheng-backend-worker

2. 查看任务执行状态： 工作流任务管理代码：src/backend/bisheng/chat/manager.py 关键代码片段：

async def close_client(self, client_key: str, code: int, reason: str):
    if chat_client := self.active_clients.get(client_key):
        try:
            self.clear_client(client_key)
            await chat_client.close()
            await chat_client.websocket.close(code=code, reason=reason)
        except RuntimeError as exc:
            if 'after sending' in str(exc):
                logger.error(exc)

3. 增加工作流超时配置： 修改Celery配置：src/backend/bisheng/core/celeryconfig.py

task_time_limit = 3600  # 设置任务超时时间为1小时
task_soft_time_limit = 300  # 设置任务软超时时间为5分钟

LLM模型调用失败

症状：工作流中调用LLM模型时出现"LLMExecutionError"错误。

解决方案：

1. 检查模型配置：src/backend/bisheng/chat/config.py

2. 验证API密钥是否正确配置：

# 模型API密钥配置示例
LLM_API_KEYS = {
    "openai": os.environ.get("OPENAI_API_KEY", ""),
    "chatglm": os.environ.get("CHATGLM_API_KEY", ""),
    # 其他模型密钥...
}

3. 检查网络连接是否正常，确保服务器能访问模型API端点：

curl -I https://api.openai.com/v1/models  # 测试OpenAI API连接

文档处理故障

文档解析失败

症状：上传文档后解析失败，显示"DocumentParseError"错误。

解决方案：

1. 检查支持的文件格式：docker/bisheng/config/config.yaml

environment:
  uns_support: ['png','jpg','jpeg','bmp','doc', 'docx', 'ppt', 'pptx', 'xls', 'xlsx', 'txt', 'md', 'html', 'pdf', 'csv', 'tiff']

2. 验证文档解析服务是否正常运行： 文档解析代码：src/backend/bisheng/pptx2md/parser.py

3. 对于大型文档（>50MB），增加解析超时配置：

# 修改文档解析超时设置
def parse_document(file_path, timeout=300):  # 设置超时为5分钟
    with timeout_context(timeout):
        # 解析文档的代码...

日志排查指南

日志文件位置

Bisheng系统默认日志路径：

• 应用日志：/app/data/bisheng.log（容器内路径）
• 统计日志：/app/data/statistic.log（容器内路径）

宿主机映射路径：docker/bisheng/config/config.yaml

logger_conf:
  handlers:
    - sink: "/app/data/bisheng.log"
      level: INFO
      format: '<level>[{time:YYYY-MM-DD HH:mm:ss.SSSSSS}] [{level.name} process-{process.id}-{thread.id} {name}:{line}]</level> - <level>trace={extra[trace_id]} {message}</level>'
      rotation: "00:00"
      retention: "3 Days"
      enqueue: true

常见错误日志分析

数据库连接错误：

OperationalError: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server on 'mysql' ([Errno 111] Connection refused)")

解决：检查MySQL容器是否运行，网络是否通畅

权限错误：

PermissionError: [Errno 13] Permission denied: '/app/data/uploads/test.docx'

解决：调整数据目录权限：

chmod -R 777 docker/data/bisheng

性能优化建议

系统资源优化

针对内存不足问题，可调整JVM参数：docker/bisheng/entrypoint.sh

# 调整Java虚拟机内存设置
export JAVA_OPTS="-Xms512m -Xmx2g"  # 根据服务器内存调整

数据库性能优化

修改MySQL配置：docker/mysql/conf/my.cnf

[mysqld]
max_connections = 500
innodb_buffer_pool_size = 2G  # 设置为服务器内存的50%左右
query_cache_size = 64M

总结与预防措施

1. 定期备份配置文件：

   • docker/bisheng/config/config.yaml
   • docker/docker-compose.yml

2. 监控关键服务状态：

   • 后端API健康检查：curl http://localhost:7860/health
   • 数据库连接测试：docker exec -it bisheng-mysql mysql -uroot -p1234

3. 建立日志轮转机制： 配置文件：docker/bisheng/config/config.yaml中的logger_conf部分

通过以上方法，你可以解决Bisheng在企业环境中90%的常见故障。如果遇到复杂问题，建议先查看详细日志，定位错误发生的模块，再对照本文提供的解决方案进行修复。定期维护和监控可以有效减少故障发生的概率，确保AI应用平台稳定运行。

提示：所有配置修改后需重启相应服务才能生效，重要修改建议在测试环境验证后再应用到生产环境。

【免费下载链接】bisheng Bisheng is an open LLM devops platform for next generation AI applications. 项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng