记录一些我自己遇到的问题

安装与升级RAGFlow的过程，均查阅了官网手册Quickstart | RAGFlow，下面是遇到的一些问题：

注：配置文件截图中的行数，取自v0.26.2版本RAGFlow，截图附带这个行数也是为了进一步方便大家定位要修改字段的位置，如果后续新版本造成配置文件格式或配置文件内容发生了增减变化，图中的行数未必准确，需要通过搜索相关字段来重新确定修改的位置

问题1

运行entrypoint.sh时报错：cat: /ragflow/VERSION: No such file or directory

解决1

在ragflow根目录下创建一个VERSION文件，内容只写一行版本号，比如v0.26.2，再次执行entrypoint.sh启动脚本

如仍然报错，把/ragflow/VERSION更换为绝对路径（具体可用pwd查一下），后面如有其它的类似/ragflow开头的找不到文件的错误，也一并更换为绝对路径（这个路径问题应该也能通过设置环境变量的方式解决）

问题2

运行entrypoint.sh时报错：cp: /etc/nginx/conf.d/ragflow.conf.python: No such file or directory

解决2

注释掉Nginx相关字样

将entrypoint.sh从Select Nginx Configuration based on API_PROXY_SCHEME到# Function(s)中间的内容全部注释掉

然后将Starting nginx下面的/usr/sbin/nginx也注释掉（这一项/usr/sbin/nginx需要注释的问题，官方手册也提到过）

再次执行entrypoint.sh启动脚本

问题3

运行entrypoint.sh时报错：ModuleNotFoundError: No module named 'infinity.rag_tokenizer'

解决3

未处在venv虚拟环境里执行启动脚本，具体是看CLI前面的(ragflow)提示符（如下图），如果没有(ragflow)提示符的话，执行source .venv/bin/activate进入虚拟环境，再次执行entrypoint.sh启动脚本

因为官方手册步骤是在vnev虚拟环境里安装的RAGFlow依赖前置组件，如果打开新终端窗口后未处在虚拟环境，缺少前置组件，就会报上述错误

问题4

执行启动脚本后，出现MySQL连接报错 （2003, "Can't connect to MySQL server on 'mysql' ([Errno 61] Connection refused)"）

解决4

修改下列端口配置：

①ragflow/docker/.env文件的ES_PORT字段的9200修改为1200

②ragflow/docker/.env文件的MYSQL_PORT字段、EXPOSE_MYSQL_PORT字段的3306均修改为5455

③ragflow/docker/service_conf.yaml.template的es部分hosts: 'http://${ES_HOST:-es01}:9200'的9200修改为1200，mysql部分MYSQL_PORT字段的3306修改为5455（与上面的端口号同步，这里修改mysql字段端口号时不要删除端口号前的横线）

然后用docker-compose重启一下RAGFlow相关的容器，应用上述配置：

docker compose -f docker/docker-compose-macos.yml down

docker compose -f docker/docker-compose-macos.yml up -d

再次执行启动脚本

问题5

终端窗口使用command+c“停止”RAGFlow后端服务后，窗口仍反复滚动输出日志

解决5

关闭这个终端窗口，重新打开一次（也需要重新激活虚拟环境），但要注意command+c并没有真正停止掉RAGFlow后端服务，真正停止方法是pkill -f "docker/entrypoint.sh"或pkill -f "ragflow_server.py"（具体用哪一种取决于你用哪种方法启动的服务，如通过ragflow_server.py启动服务，则只需pkill -f "ragflow_server.py"，如通过enterpoint.sh启动服务，则两个pkill地方都要做）

当然也可以通过查询进程与kill的方法停止服务，下为过程：

ps -ef|grep ragflow，查一下是不是RAGFlow进程还在后台运行，其中vite那个是前端web进程，ragflow_server.py那个是后端进程，如果有发现这个进程存在，则kill -9 PID（图中是31674）

不论用entrypoint.sh启动还是用ragflow_server.py启动，后端进程都是ragflow_server.py，因为entrypoint.sh最终也调用ragflow_server.py）

问题6

执行python api/ragflow_server.py后报错[Errno 48] Address already in use

解决6

注释掉docker-compose-macos.yml里的- ${SVR_HTTP_PORT}:9380这一行，再次执行启动脚本

再不行的话通过解决5里的方式终止后端服务，再次执行脚本

注：如果是用entrypoint.sh启动服务，表象可能会启动成功，但是进入RAGFlow页面会反复报500错误，此时往前翻一下启动日志，如存在类似上述端口冲突报错的话，也用同样方法解决（不过目前官方手册已经建议直接用ragflow_server.py启动服务了）

问题7

RAGFlow在模型提供商页面，通过Ollama添加本地模型时，验证模型报Fail to access model(Ollama/xxx:xb) using this api key.No valid response received

解决7

出现这个报错的话，其实在第一次配置完Ollama的实例名称和基础Url，展开模型列表准备配置模型时，右上角就已经弹出102 Internal server error的错误了

原因是http://host.docker.internal:11434这个地址DNS解析没成功（之前我都用这个地址，不知为何这次解析不了了，直接浏览器输入http://host.docker.internal:11434也报DNS找不到的错误）

解决方法是不用http://host.docker.internal:11434，改用http://localhost:11434

验证成功后，按确认键即可添加上模型

问题8

RAGFlow部分页面打不开，报类似图中的Something went wrong

解决8

这个时候web服务的那个终端窗口，通常也会有报错信息的，根据具体报错信息确定如何解决

①报The service is no longer running的错误

此时在该窗口按command+c，或是从另一个终端窗口pkill npm，停止web服务，再次npm run dev启动服务

如果web服务中有类似下图的警告信息，还可能要配合警告信息里的npx update-browserslist-db@latest命令解决问题，有关这个命令的作用见其他作者写的这篇文章npx update-browserslist-db@latest 这个命令是做什么的，为什么要执行这个命令。-CSDN博客

②报Failed to resolve import xxx from xxx. Does the file exist?的错误

这种错误是尝试导入该页面功能必需模块时，未找到模块（通常是未安装，比如图中的remark-breaks和@extend-ai/react-docx），通过npm安装一下缺失模块，再次刷新页面，如果刷新页面后仍然报Something went wrong，说明仍有必需模块未满足，再次返回日志窗口查看缺失的模块名称并安装

问题9

输入localhost:9222（或其它内网电脑登录ip:9222）进入RAGFlow页面时，前端Web服务终端窗口频繁报[vite] 开头的/api接口错误 Error: connect ECONNREFUSED 127.0.0.1:9384，同时网页报循环报500:undefined与Something went wrong TypeError: Cannot read properties of undefined (reading 'chats')错误，任何页面都打不开（Something went wrong）或无数据，并且右上一直弹500

解决9

升级v0.27.1后，vite.config.ts配置文件的server.proxy配置默认是空的了，要手动配置一下Vite Proxy地址

具体操作如下（把标蓝的部分改一下，注意括号匹配别弄乱了）：

原配置项：

    server: {
      port: Number(env.PORT) || 9222,
      strictPort: false,
      hmr: {
        overlay: false,
      },
      proxy,
    },

修改后的配置项：

    server: {
      port: Number(env.PORT) || 9222,
      strictPort: false,
      hmr: {
        overlay: false,
      },
      proxy: {
       '/api': {
        target: 'http://127.0.0.1:9380',
        },
     },
    }, 

保存修改后，如果配置正确且括号、逗号等语法没有错误，Web服务终端窗口会自动重启服务并恢复正常，此时回到RAGFlow Web页面，就正常使用了

如果还保存着先前版本能用的vite.config.ts，也可以套用过来里边的proxy部分配置试一下

有关Vite Proxy的配置问题，这篇文章有详细讲解（话说我也没怎么仔细读，就是把里边的配置格式拿走调试一下能用为止）Vite Proxy配置全解析：从原理到避坑指南（vite.config.ts详解）-CSDN博客

问题10

Docker RAGFlow镜像Build完成以后，仍为AMD64架构，Docker Desktop的ragflow镜像位置能看到鲜明的黄色AMD64叹号

解决10

之前可能有残留的涉及x86_64（amd64）错误配置或错误依赖文件，删除ragflow_deps镜像和其它错误构建为x86_64架构的RAGFlow相关镜像，检查是否有其它没改过来的错误配置或执行的其它错误操作（比如docker-compose-macos.yml里的services.ragflow.platform项是否修改成了linux/arm64，是否是用的docker-compose-macos.yml起的服务而非不带macos后缀的yml起的服务等），然后从uv run python3 download_deps.py开始，重新下载并构建依赖镜像，并重新正确构建RAGFlow镜像，正确的效果是Docker Desktop不要有任何AMD64标志

小结

上面是我目前遇到的一些报错和解决方法，其中有些跟升级相关的报错，本身是官方手册里是写过的，初次安装会规避，但是一旦升级RAGFlow版本后，原来一些配置文件被新版配置文件覆盖，于是再次出现了上述报错

还有那个VERSION文件，升级版本后重新修改一下里边的版本号，如果重新开了一个全新的ragflow目录，这个VERSION文件因为原版是没有的，需要重新创建一下

随着RAGFlow的不断更新，上述步骤、脚本内容、界面都可能会发生变化，也可能会有新的模块依赖关系（比图remark-breaks和@extend-ai/react-docx这两个模块缺失，是发生在聊天对话界面的，我在早期版本没遇到过这个问题，也能正常打开界面进行对话，v0.26.2再次打开聊天页面就报这个错误了）

上述为我遇到的部分问题及处理过程，如后续有新问题，还会继续更新