RagflowPlus v0.2.1 版本更新教程

RagflowPlus v0.2.1 版本带来了重要的功能升级与体验优化，本次更新共修复了 6 个关键问题，并新增了 用户密码重置功能。本教程将逐一详解每个修复内容、新增特性及相关注意事项，帮助您快速完成升级并充分利用新版功能。

修复的 6 个关键问题

1. 图片不显示问题

部分场景下，图片无法正常显示，仅呈现一串无意义字符串。经排查，根本原因在于 Minio 存储中图片缺少公共访问权限。

修复方法：调整 Minio 图像文件的权限策略，对图片存储文件夹下所有文件设置为公开访问。具体配置如下：

"Resource": [f"arn:aws:s3:::{kb_id}/images/*"]

小提示：如果您在部署后遇到图片异常，请优先检查 Minio 存储桶的权限策略，确保 images/* 路径已开放公共读取权限。

常见问题：为什么修改权限后图片仍然不显示？请确认镜像或容器中的 Minio 配置是否已同步更新；若使用持久化卷，需重启容器使新权限策略生效。

2. 嵌入模型连接错误问题

在后台知识库管理菜单中检测嵌入模型状态时，可能遇到以下三种错误：

• 模型名称查询错误：查询时错误地填充了 Chat 模型信息。修复方式：在 talent_llm 表中增加模型类型过滤条件。
• 模型配置信息更新错误：之前直接读取最早的模型配置，导致更换模型后信息不同步。修复方式：查询用户最新使用的 embedding 模型配置，确保前后台同步一致。
• 非 vLLM 模型配置信息错误：vLLM 镜像的接口地址末尾包含 v1，与其他标准接口不兼容。修复方式：后台验证时对 API 地址进行鲁棒性填充，以兼容不同模型类型。

提示：为减少前后台配置冲突，后台嵌入模型配置现已禁止用户直接编辑。如需修改，请在前台操作，后台将自动保持一致。

常见问题：为何后台不允许修改嵌入模型？因为后台与前台共用同一张 MySQL 数据表，若后台开放修改权限，易导致前后台模型信息不一致，影响知识库解析效果。

3. 上传 >1M 文件时报 413 错误

当上传文件超过 1MB 时，系统会返回 413 错误。这是因为 Nginx 默认限制了文件大小为 1MB。

修复方法：v0.2.1 版本将 Nginx 配置文件改为外部挂载，您可以通过修改 dockernginxmanagement_nginx.conf 文件中的 client_max_body_size 参数来动态调整文件大小限制，默认值已提升至 500MB。

常见问题：修改后仍然报 413 错误怎么办？请确认已修改正确的配置文件，并重启 Nginx 容器；若使用 Docker Compose，可能需要执行重新加载配置操作。

4. 解析块回溯不对应问题

在前台知识库查看 PDF 文件的解析块时，原本的位置可能发生错位。

修复方法：重新优化了匹配逻辑，并进一步增强了对表格解析块的支持。现在解析块能准确定位原文位置，表格内容也可正常显示。

提示：如果您发现部分复杂文档（如含表格的 PDF）解析后仍有轻微偏移，建议尝试重新上传并再次解析。

5. 解析失败原因显示问题

在后台知识库解析文件时，若出现错误，此前会固定显示“请先安装 LibreOffice”提示，而实际错误原因可能不同。根本原因是源码部署需手动安装 LibreOffice，而 Docker 镜像已内置该环境。

修复方法：v0.2.1 版本优化了错误显示逻辑，现在前端将收到真实的解析失败原因（例如内存不足、文件损坏等）。

常见问题：如果仍然看到“请先安装 LibreOffice”提示怎么办？请检查您是否仍在使用旧版本，或者源码部署环境中缺少 LibreOffice。Docker 部署用户无需担忧此问题。

6. 解析块显示为 0 问题

上传 txt、excel 等类型文件时，虽然已正常解析，但显示的解析块数量为 0。原因是 MinerU 解析引擎仅支持 word、ppt、pdf 三种格式，对其他格式未做异常判断和错误反馈。

修复方法：v0.2.1 版本增加了对不支持文件类型的检测，并给出明确的错误提示，避免解析块显示为 0 带来的困惑。

小提示：如需解析 txt 或 excel 文件，建议先将其转换为支持的格式（如 PDF）后再上传。

新增功能：用户密码重置

原系统用户密码采用加密存储，管理员无法查看明文。当用户忘记密码时，无法自助找回。为此，v0.2.1 版本在后台用户管理模块中新增了 用户密码重置 按钮。管理员可通过该按钮为指定用户重置密码，重置后的密码将以明文形式显示，便于管理员转交给用户。

常见问题：重置密码后，用户需要重新登录吗？是的，用户需使用新密码登录。建议提醒用户尽快修改密码。

其他改进

RagflowPlus v0.2.1 的前台系统基于 v0.17.2-slim 打包，移除了内置模型，使镜像体积大幅缩小。注意：不推荐使用内置模型，因为在 GPU 环境下无法有效控制显存占用和显卡分布。

建议：推荐使用独立部署的模型服务（如 vLLM、Ollama）与 RagflowPlus 配合，以便更灵活地分配资源。

以上是 RagflowPlus v0.2.1 版本的完整更新内容。如果您在升级过程中遇到任何问题，请参考本教程中的常见问题解答，或查阅官方文档。祝您使用愉快！