完整改动清单问题 1数据库迁移失败 ——alembic_cfg变量未定义现象容器启动日志报迁移过程出错: name alembic_cfg is not defined。根因[start.sh](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/start.sh) 中alembic_cfg Config(alembic.ini)原本只写在if not table_exists:分支内。非首次部署时该分支被跳过后面无条件执行的command.upgrade(alembic_cfg, head)就引用了未定义的变量。修复把alembic_cfg Config(alembic.ini)移到if判断外面[第20行](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/start.sh#L20)无论是否首次部署都会初始化。调整执行顺序先在with engine.connect()块内查表块退出连接关闭后再执行 stamp/upgrade避免连接占用。重建容器后日志出现数据库迁移完成!。问题 2PDF 解析失败 —— XGBoost 旧模型格式被新版库移除上传 0 切片的真正根源现象上传 PDF 后解析阶段报错Failed to load model: …/deepdoc/updown_concat_xgb.model The binary format has been deprecated in 1.6 and removed in 3.1文档解析出 0 个切片后续无内容可入库。根因PDF 解析依赖的 deepdoc 模块使用 XGBoost 旧二进制格式的模型文件而重新构建镜像时 pip 拉到了 XGBoost 3.1该版本彻底移除了旧格式读取支持。修复在 [requirements.txt:9](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/requirements.txt#L9) 锁定xgboost2.1.42.x 仍兼容旧二进制格式重新构建镜像后模型正常加载、PDF 正常切片。问题 3前端添加按钮是死的功能未实现现象点添加无弹窗、无请求、无报错。文件改动[contracts.tsx](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/component/contracts.tsx#L129)按钮原本连onClick都没有。补全点击 → 弹 Modal → 调api.repository.list()拉知识库文件 → Checkbox 多选 → 已添加项置灰防重复 → 确认走onAdd回调搜索框补onChange本地过滤[contracts.module.scss](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/component/contracts.module.scss)新增弹窗文件列表样式[chat/index.tsx](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/frontend/src/pages/chat/index.tsx#L359)传onAdd回调按document_name去重合并进documentsstate问题 4上传假成功 ES 向量索引结构错误现象前端提示上传成功但提问检索不到任何内容。文件改动[es_conn.py](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/utils/es_conn.py#L137-L150)原代码加载了mapping.jsonq_1024_vec定义为dense_vector却从不使用ES 自动建索引把向量当普通数组kNN 失效。新增createIdx()insert()前先用正确 mapping 建索引[file_parse.py](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/file_parse.py#L137-L151)解析/embedding/ES 插入失败原本只print不抛异常导致假成功三处均改为raise Exception[chat_rt.py](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/router/chat_rt.py#L437)新增POST /recreate_index重建接口检索异常日志改为logger.exception()打完整堆栈[第182行](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/router/chat_rt.py#L182)配套操作删除旧索引后重新上传文件。问题 5检索链路连环崩溃命中了文档但引文为空现象ES 有 25 条文档、向量检索命中引文始终为空。文件改动[search_v2.py](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L375-L384)① DashScope rerank API 返回 NoneKey 无权限会炸穿整个检索加 try/except自动降级为本地混合排序② 降级路径里question_tks入库时是[]而非字符串.split()崩溃[第298-305行](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/search_v2.py#L298-L305)加 list/str 类型兼容[query.py](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/app/service/core/rag/nlp/query.py#L200-L211)hybrid_similarity依赖 sklearn 但镜像和 requirements 里都没有改用 numpy 手写 cosine零新增依赖问题 6Docker 挂载路径错误所有后端修改不生效的总开关现象代码反复确认改对、容器里也能查到新代码但运行行为和报错完全不变。根因[docker-compose.yml](file:///d:/保研资料/wangzhe/第六周RAG%20(Part%202)RAG工业级项目实战/FinInsRAG-V3/swxy(1)/swxy/backend/docker-compose.yml#L24) 的挂载./app:/app/app把宿主机代码挂到了容器/app/app/嵌套子目录而 Dockerfile 是WORKDIR /appCOPY . /app服务实际运行镜像里/app/下的旧代码新代码从未被加载。修复-./app:/app# 原 ./app:/app/app挂载变更需docker compose up -d --force-recreate swxy_api重建容器普通 restart 不重读挂载。故障链总览容器启动期 问题1 迁移脚本变量作用域错误 问题2 XGBoost 版本过新导致 PDF 无法切片上传内容为空的源头 使用期 问题3 前端添加按钮未实现 问题4 ES 缺向量 mapping 失败静默 → 假成功 问题5 rerank 403 → 类型错误 → sklearn 缺失三连崩 环境层 问题6 volume 挂错目录以上后端修复一度全部不生效需要的话我可以把这份完整说明写进项目 README 或单独的排查文档。