build_notes_simengweb/assets/index.html-qQq622U8.js

import{_ as i,c as a,a as e,o as l}from"./app-DTJ1dk4L.js";const h={};function n(t,s){return l(),a("div",null,[...s[0]||(s[0]=[e(`<p>这是一份按本次真实部署过程重新整理的操作文档～</p><p>我会尽量把每一步都写得温柔一点、清楚一点，让你以后自己回看的时候，不需要再从聊天记录里一点一点翻找啦。</p><p>这份文档适用于：</p><ul><li>Windows 11</li><li>Docker Desktop</li><li>WSL2</li><li>PowerShell</li><li>本地通过 Docker 部署 RAGFlow</li><li>在 Cursor 中通过 MCP 访问本地知识库</li></ul><h2 id="_1-最终落地状态" tabindex="-1"><a class="header-anchor" href="#_1-最终落地状态"><span>1. 最终落地状态</span></a></h2><p>本次实际部署目录：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次实际使用版本：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">infiniflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow:v0.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">23.1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次实际对外端口如下：</p><table><thead><tr><th>服务</th><th style="text-align:right;">主机端口</th><th style="text-align:right;">容器端口</th><th>说明</th></tr></thead><tbody><tr><td>RAGFlow Web UI</td><td style="text-align:right;">38180</td><td style="text-align:right;">80</td><td>浏览器主入口</td></tr><tr><td>RAGFlow HTTPS</td><td style="text-align:right;">38443</td><td style="text-align:right;">443</td><td>HTTPS 入口</td></tr><tr><td>RAGFlow API</td><td style="text-align:right;">39380</td><td style="text-align:right;">9380</td><td>主 API</td></tr><tr><td>RAGFlow Admin API</td><td style="text-align:right;">39381</td><td style="text-align:right;">9381</td><td>管理端接口</td></tr><tr><td>RAGFlow MCP</td><td style="text-align:right;">39382</td><td style="text-align:right;">9382</td><td>Cursor 连接的 MCP</td></tr><tr><td>Elasticsearch</td><td style="text-align:right;">31200</td><td style="text-align:right;">9200</td><td>向量检索底层</td></tr><tr><td>MySQL</td><td style="text-align:right;">35455</td><td style="text-align:right;">3306</td><td>元数据数据库</td></tr><tr><td>Redis</td><td style="text-align:right;">36379</td><td style="text-align:right;">6379</td><td>缓存</td></tr><tr><td>MinIO API</td><td style="text-align:right;">39010</td><td style="text-align:right;">9000</td><td>对象存储</td></tr><tr><td>MinIO Console</td><td style="text-align:right;">39011</td><td style="text-align:right;">9001</td><td>MinIO 控制台</td></tr><tr><td>OpenSearch</td><td style="text-align:right;">31201</td><td style="text-align:right;">9200</td><td>可选组件</td></tr><tr><td>Kibana</td><td style="text-align:right;">36601</td><td style="text-align:right;">5601</td><td>可选组件</td></tr><tr><td>Infinity Thrift</td><td style="text-align:right;">33817</td><td style="text-align:right;">23817</td><td>可选组件</td></tr><tr><td>Infinity HTTP</td><td style="text-align:right;">33820</td><td style="text-align:right;">23820</td><td>可选组件</td></tr><tr><td>Infinity PostgreSQL</td><td style="text-align:right;">35432</td><td style="text-align:right;">5432</td><td>可选组件</td></tr><tr><td>OceanBase</td><td style="text-align:right;">32881</td><td style="text-align:right;">2881</td><td>可选组件</td></tr><tr><td>TEI</td><td style="text-align:right;">36380</td><td style="text-align:right;">80</td><td>可选嵌入服务</td></tr></tbody></table><p>本次 Compose 项目名：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>因此容器名会类似：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mysql</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">minio</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>这样做的好处是，容器、网络、卷都不会以默认的 <code>docker-</code> 前缀出现，更容易识别～</p><h2 id="_2-这次实际改动过的关键文件" tabindex="-1"><a class="header-anchor" href="#_2-这次实际改动过的关键文件"><span>2. 这次实际改动过的关键文件</span></a></h2><p>下面这些文件，是这次部署和修复里真正动过的：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\.env</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\docker</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">compose.yml</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\mcp\\server\\server.py</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">C:\\Users\\~\\.cursor\\mcp.json</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>它们分别负责：</p><ul><li><p><code>docker\\.env</code></p><ul><li>统一管理端口</li><li>指定镜像版本</li><li>指定 Compose 项目名</li><li>配置 MCP 的 host、port、base URL、mode、host API key</li></ul></li><li><p><code>docker\\docker-compose.yml</code></p><ul><li>让 <code>ragflow-cpu</code> 或 <code>ragflow-gpu</code> 真正带着 MCP 参数启动</li><li>将主机上的 <code>mcp/server/server.py</code> 挂载到容器里</li></ul></li><li><p><code>mcp\\server\\server.py</code></p><ul><li>修复空知识库导致 MCP 无限刷日志的问题</li></ul></li><li><p><code>C:\\Users\\~\\.cursor\\mcp.json</code></p><ul><li>把 Cursor 指向本机 <code>http://127.0.0.1:39382/mcp/</code></li></ul></li></ul><h2 id="_3-为什么这次使用-v0-23-1" tabindex="-1"><a class="header-anchor" href="#_3-为什么这次使用-v0-23-1"><span>3. 为什么这次使用 v0.23.1</span></a></h2><p>官方文档页面可能会展示更新的开发文档内容，但本次实际部署的时候，选择的是更稳妥的稳定版本：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">infiniflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow:v0.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">23.1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>这样做的原因很简单：</p><ul><li>稳定版更适合本地长期使用</li><li>与当前 Docker Compose 配置兼容性更稳定</li><li>便于把问题范围收敛到部署和配置，而不是开发版变更</li></ul><p>如果你后续要升级版本，建议先备份：</p><ul><li><code>docker\\.env</code></li><li><code>docker\\docker-compose.yml</code></li><li>自己修补过的 <code>mcp\\server\\server.py</code></li></ul><h2 id="_4-windows-11-上从零部署-ragflow-的完整步骤" tabindex="-1"><a class="header-anchor" href="#_4-windows-11-上从零部署-ragflow-的完整步骤"><span>4. Windows 11 上从零部署 RAGFlow 的完整步骤</span></a></h2><h3 id="_4-1-准备环境" tabindex="-1"><a class="header-anchor" href="#_4-1-准备环境"><span>4.1 准备环境</span></a></h3><p>请先确认下面这些基础组件已经装好：</p><ul><li>Windows 11</li><li>WSL2</li><li>Docker Desktop</li><li>Git</li><li>PowerShell 7 或 Windows PowerShell</li><li><code>curl.exe</code></li></ul><p>可以先简单检查：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">version</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose version</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">git </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">version</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">wsl </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">l </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">v</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">version</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="_4-2-创建部署目录" tabindex="-1"><a class="header-anchor" href="#_4-2-创建部署目录"><span>4.2 创建部署目录</span></a></h3><p>如果 <code>D:\\Project</code> 不存在，先创建：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">New-Item</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ItemType Directory </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">Path </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">Force</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>进入目录并克隆官方仓库：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">git clone https:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">github.com</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">infiniflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow.git</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>如果已经有仓库目录，可以直接进入：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="_4-3-设置-wsl-内核参数-vm-max-map-count" tabindex="-1"><a class="header-anchor" href="#_4-3-设置-wsl-内核参数-vm-max-map-count"><span>4.3 设置 WSL 内核参数 <code>vm.max_map_count</code></span></a></h3><p>这是 Elasticsearch 常见的要求。如果不设置，RAGFlow 依赖的 ES 组件很容易启动失败。</p><p>本次实际使用的是临时设置方式：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">wsl </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d docker</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">desktop </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">u root </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> sysctl </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">w vm.max_map_count</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">262144</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>如果输出类似下面这样，就表示成功：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">vm.max_map_count </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 262144</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>这一步非常重要。</p><p>如果 Docker Desktop 重启过，这个值有可能需要重新执行一次。</p><h3 id="_4-4-修改-docker-env" tabindex="-1"><a class="header-anchor" href="#_4-4-修改-docker-env"><span>4.4 修改 <code>docker\\.env</code></span></a></h3><p>打开：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\.env</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次实际关键配置如下：</p><div class="language-dotenv line-numbers-mode" data-highlighter="shiki" data-ext="dotenv" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-dotenv"><span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">COMPOSE_PROJECT_NAME</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">simeng-ragflow</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">ES_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">31200</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">OS_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">31201</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">KIBANA_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">36601</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">INFINITY_THRIFT_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">33817</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">INFINITY_HTTP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">33820</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">INFINITY_PSQL_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">35432</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">OCEANBASE_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">32881</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">MYSQL_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">35455</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">MINIO_CONSOLE_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">39011</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">MINIO_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">39010</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">REDIS_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">36379</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">SVR_WEB_HTTP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">38180</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">SVR_WEB_HTTPS_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">38443</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">SVR_HTTP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">39380</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">ADMIN_SVR_HTTP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">39381</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">SVR_MCP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">39382</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TEI_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">36380</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_HOST</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">0.0.0.0</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">9382</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_BASE_URL</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">http://127.0.0.1:9380</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_MODE</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">self-host</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_HOST_API_KEY</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">ragflow-请替换为你自己的值</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_IMAGE</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">infiniflow/ragflow:v0.23.1</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TZ</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Asia/Shanghai</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>请注意：</p><ul><li><code>RAGFLOW_MCP_BASE_URL</code> 这里写的是容器内 MCP 访问容器内 RAGFlow API 的地址，所以是 <code>http://127.0.0.1:9380</code></li><li><code>SVR_MCP_PORT=39382</code> 是主机暴露出来给 Cursor 用的外部端口</li><li><code>RAGFLOW_MCP_HOST_API_KEY</code> 不要直接公开写在文档、截图或聊天记录里</li></ul><p>本机当前已经有一个可用的真实 key 存在于本地 <code>.env</code> 里。如果你是重新部署，请自行生成并填入～</p><h3 id="_4-5-修改-docker-docker-compose-yml" tabindex="-1"><a class="header-anchor" href="#_4-5-修改-docker-docker-compose-yml"><span>4.5 修改 <code>docker\\docker-compose.yml</code></span></a></h3><p>打开：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\docker</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">compose.yml</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>需要让 <code>ragflow-cpu</code> 或 <code>ragflow-gpu</code> 真正带着 MCP 参数启动。</p><p>本次 <code>ragflow-cpu</code> 实际结构如下：</p><div class="language-yaml line-numbers-mode" data-highlighter="shiki" data-ext="yaml" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-yaml"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">ragflow-cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  depends_on</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">    mysql</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">      condition</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> service_healthy</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  profiles</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> cpu</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  image</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${RAGFLOW_IMAGE}</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --enable-mcpserver</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host=\${RAGFLOW_MCP_HOST}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-port=\${RAGFLOW_MCP_PORT}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-base-url=\${RAGFLOW_MCP_BASE_URL}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-script-path=/ragflow/mcp/server/server.py</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-mode=\${RAGFLOW_MCP_MODE}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host-api-key=\${RAGFLOW_MCP_HOST_API_KEY}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --enable-adminserver</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  ports</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${SVR_WEB_HTTP_PORT}:80</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${SVR_WEB_HTTPS_PORT}:443</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${SVR_HTTP_PORT}:9380</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${ADMIN_SVR_HTTP_PORT}:9381</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> \${SVR_MCP_PORT}:9382</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  volumes</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./ragflow-logs:/ragflow/logs</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./nginx/ragflow.conf:/etc/nginx/conf.d/ragflow.conf</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./nginx/proxy.conf:/etc/nginx/proxy.conf</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./nginx/nginx.conf:/etc/nginx/nginx.conf</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ../history_data_agent:/ragflow/history_data_agent</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ../mcp/server/server.py:/ragflow/mcp/server/server.py</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./service_conf.yaml.template:/ragflow/conf/service_conf.yaml.template</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ./entrypoint.sh:/ragflow/entrypoint.sh</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  env_file</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> .env</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  networks</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ragflow</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  restart</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> unless-stopped</span></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">  extra_hosts</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    -</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">host.docker.internal:host-gateway</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>如果你使用 GPU 版，也要把 <code>ragflow-gpu</code> 一起改掉，保持一致。</p><p>这里最重要的有三点：</p><ol><li><p><code>--enable-mcpserver</code></p><ul><li>这是让 MCP 真正启动的开关</li></ul></li><li><p><code>--mcp-host-api-key=\${RAGFLOW_MCP_HOST_API_KEY}</code></p><ul><li>这是给容器内 MCP 进程访问 RAGFlow API 用的，不是给 Cursor 客户端用的</li></ul></li><li><p><code>- ../mcp/server/server.py:/ragflow/mcp/server/server.py</code></p><ul><li>这是为了让本地修补过的 <code>server.py</code> 真正进入容器</li></ul></li></ol><h3 id="_4-6-启动服务" tabindex="-1"><a class="header-anchor" href="#_4-6-启动服务"><span>4.6 启动服务</span></a></h3><p>进入 <code>docker</code> 目录：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow\\docker</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>首次启动：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose up </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>查看状态：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose ps</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>也可以直接看全局容器：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker ps </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">format </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">table {{.Names}}\\t{{.Status}}\\t{{.Ports}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次正常容器应至少包括：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mysql</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">minio</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">redis</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">es01</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="_5-首次启动后的验证" tabindex="-1"><a class="header-anchor" href="#_5-首次启动后的验证"><span>5. 首次启动后的验证</span></a></h2><h3 id="_5-1-检查-web-ui" tabindex="-1"><a class="header-anchor" href="#_5-1-检查-web-ui"><span>5.1 检查 Web UI</span></a></h3><p>浏览器访问：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">38180</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>如果能打开前端页面，说明 Web 层已经起来啦～</p><h3 id="_5-2-检查健康接口" tabindex="-1"><a class="header-anchor" href="#_5-2-检查健康接口"><span>5.2 检查健康接口</span></a></h3><p>运行：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39380</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">v1</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">system</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">healthz</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次正常返回示例：</p><div class="language-json line-numbers-mode" data-highlighter="shiki" data-ext="json" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-json"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">{</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">db</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ok</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">doc_engine</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ok</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">redis</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ok</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">status</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ok</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">storage</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ok</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>只要这里全部是 <code>ok</code>，就说明主链路正常。</p><h2 id="_6-默认账号与登录说明" tabindex="-1"><a class="header-anchor" href="#_6-默认账号与登录说明"><span>6. 默认账号与登录说明</span></a></h2><p>RAGFlow 默认管理员账号来自官方文档：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>admin@ragflow.io</span></span>
<span class="line"><span>admin</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><p>访问地址：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">38180</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">admin</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>请特别注意：</p><ul><li>这个默认管理员账号只能登录 <code>/admin</code></li><li>不能登录普通前台</li><li>如果你拿它去登录普通前台，会收到类似：</li></ul><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>Default admin account cannot be used to login normal services!</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>这不是密码错，而是 RAGFlow 本身就这样设计。</p><p>普通使用方式是：</p><ul><li>管理后台：<code>/admin</code></li><li>普通用户前台：<code>/</code></li><li>普通用户需要注册新账号，或者由管理员创建</li></ul><h2 id="_7-这次实际遇到的问题与解决方案" tabindex="-1"><a class="header-anchor" href="#_7-这次实际遇到的问题与解决方案"><span>7. 这次实际遇到的问题与解决方案</span></a></h2><p>这一节很重要，因为这里不是&quot;理论问题&quot;，而是这次在 Windows 11 本机部署时真实踩到的坑。</p><h3 id="_7-1-问题一-minio-缺少-bucket-健康检查返回-500" tabindex="-1"><a class="header-anchor" href="#_7-1-问题一-minio-缺少-bucket-健康检查返回-500"><span>7.1 问题一：MinIO 缺少 bucket，健康检查返回 500</span></a></h3><h4 id="现象" tabindex="-1"><a class="header-anchor" href="#现象"><span>现象</span></a></h4><p>初次启动后，RAGFlow 的健康检查可能失败，日志里会出现类似 <code>NoSuchBucket</code>，接口返回 500。</p><h4 id="根因" tabindex="-1"><a class="header-anchor" href="#根因"><span>根因</span></a></h4><p>MinIO 服务起来了，但 <code>ragflow-bucket</code> 没有自动建立。</p><h4 id="解决方案" tabindex="-1"><a class="header-anchor" href="#解决方案"><span>解决方案</span></a></h4><p>进入一个能运行 Python 的 RAGFlow 容器，手工创建 bucket：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker exec simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> python </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">c </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">from minio import Minio; c=Minio(&#39;minio:9000&#39;, access_key=&#39;rag_flow&#39;, secret_key=&#39;infini_rag_flow&#39;, secure=False); b=&#39;ragflow-bucket&#39;; print(&#39;exists_before=&#39; + str(c.bucket_exists(b))); (None if c.bucket_exists(b) else c.make_bucket(b)); print(&#39;exists_after=&#39; + str(c.bucket_exists(b)))</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>创建成功后，再次检查：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39380</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">v1</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">system</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">healthz</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>如果返回全 <code>ok</code>，说明已经恢复正常。</p><h3 id="_7-2-问题二-mcp-端口明明映射了-但-cursor-还是连不上" tabindex="-1"><a class="header-anchor" href="#_7-2-问题二-mcp-端口明明映射了-但-cursor-还是连不上"><span>7.2 问题二：MCP 端口明明映射了，但 Cursor 还是连不上</span></a></h3><h4 id="现象-1" tabindex="-1"><a class="header-anchor" href="#现象-1"><span>现象</span></a></h4><p>宿主机上看到已经有：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 9382</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>但 Cursor 仍然不可用，或者访问时表现异常。</p><h4 id="根因-1" tabindex="-1"><a class="header-anchor" href="#根因-1"><span>根因</span></a></h4><p>仅仅暴露端口并不等于 MCP 真的启动了。</p><p>之前的问题就是：</p><ul><li>Docker 做了 <code>39382 -&gt; 9382</code> 的端口映射</li><li>但容器内其实没有 MCP 进程监听 <code>9382</code></li></ul><p>所以表现会像：</p><ul><li><code>/sse</code> 访问空响应</li><li>或容器里 <code>127.0.0.1:9382</code> 直接 <code>Connection refused</code></li></ul><h4 id="解决方案-1" tabindex="-1"><a class="header-anchor" href="#解决方案-1"><span>解决方案</span></a></h4><p>必须在 <code>docker-compose.yml</code> 里显式增加：</p><div class="language-yaml line-numbers-mode" data-highlighter="shiki" data-ext="yaml" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-yaml"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --enable-mcpserver</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host=\${RAGFLOW_MCP_HOST}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-port=\${RAGFLOW_MCP_PORT}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-base-url=\${RAGFLOW_MCP_BASE_URL}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-script-path=/ragflow/mcp/server/server.py</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-mode=\${RAGFLOW_MCP_MODE}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host-api-key=\${RAGFLOW_MCP_HOST_API_KEY}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>然后重建容器：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow\\docker</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose up </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">force</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">recreate ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="_7-3-问题三-cursor-配置写成-mcp-实际应该写-mcp" tabindex="-1"><a class="header-anchor" href="#_7-3-问题三-cursor-配置写成-mcp-实际应该写-mcp"><span>7.3 问题三：Cursor 配置写成 <code>/mcp</code>，实际应该写 <code>/mcp/</code></span></a></h3><h4 id="现象-2" tabindex="-1"><a class="header-anchor" href="#现象-2"><span>现象</span></a></h4><p>MCP 有时看起来能通，有时又初始化失败，行为不稳定。</p><h4 id="根因-2" tabindex="-1"><a class="header-anchor" href="#根因-2"><span>根因</span></a></h4><p><code>/mcp</code> 会发生 <code>307</code> 重定向到 <code>/mcp/</code>。</p><p>有些 MCP 客户端对这个跳转处理得不够稳定，所以最好直接写最终地址。</p><h4 id="解决方案-2" tabindex="-1"><a class="header-anchor" href="#解决方案-2"><span>解决方案</span></a></h4><p>Cursor 配置使用：</p><div class="language-json line-numbers-mode" data-highlighter="shiki" data-ext="json" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-json"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">mcpServers</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">    &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">RAGFlow</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">      &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">url</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">http://127.0.0.1:39382/mcp/</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>不要写成：</p><div class="language-json line-numbers-mode" data-highlighter="shiki" data-ext="json" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-json"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">mcpServers</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">    &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">RAGFlow</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">      &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">url</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">http://127.0.0.1:39382/mcp</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="_7-4-问题四-mcp-查询一发起-容器日志疯狂刷屏" tabindex="-1"><a class="header-anchor" href="#_7-4-问题四-mcp-查询一发起-容器日志疯狂刷屏"><span>7.4 问题四：MCP 查询一发起，容器日志疯狂刷屏</span></a></h3><h4 id="现象-3" tabindex="-1"><a class="header-anchor" href="#现象-3"><span>现象</span></a></h4><p>在容器 <code>simeng-ragflow-ragflow-cpu-1</code> 中，MCP 发起检索后，日志不断重复请求：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>GET /api/v1/datasets/&lt;dataset_id&gt;/documents?page=1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>几乎像死循环一样不停输出。</p><h4 id="本次触发问题的请求示例" tabindex="-1"><a class="header-anchor" href="#本次触发问题的请求示例"><span>本次触发问题的请求示例</span></a></h4><div class="language-json line-numbers-mode" data-highlighter="shiki" data-ext="json" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-json"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">question</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">vuepress-theme-plume 博客文章 frontmatter tags 标签配置</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">page_size</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 8</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">similarity_threshold</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 0.2</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="根因-3" tabindex="-1"><a class="header-anchor" href="#根因-3"><span>根因</span></a></h4><p><code>mcp/server/server.py</code> 中有一段逻辑会在补齐 <code>document_metadata</code> 时遍历知识库文档分页。</p><p>如果某个知识库是空的，也就是：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>docs = []</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>原来的代码既没有翻页，也没有退出循环，于是它会一直打同一个：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>/documents?page=1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>这次实际触发该问题的原因是：</p><ul><li>查询时没有传 <code>dataset_ids</code></li><li>MCP 会自动遍历所有可用知识库</li><li>其中正好包含一个空知识库</li><li>空知识库触发了分页死循环</li></ul><h4 id="修复方式" tabindex="-1"><a class="header-anchor" href="#修复方式"><span>修复方式</span></a></h4><p>已在：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\mcp\\server\\server.py</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>中补上保护逻辑。核心思路是：</p><ul><li>请求失败就退出</li><li><code>docs</code> 为空就退出</li><li><code>code != 0</code> 就退出</li><li>当 <code>page * page_size &gt;= total</code> 时退出</li></ul><p>本次修补后的关键逻辑可以概括为：</p><div class="language-python line-numbers-mode" data-highlighter="shiki" data-ext="python" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-python"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docs_res </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;"> self</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">_get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">f</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">&quot;/datasets/</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">{</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">dataset_id</span><span style="--shiki-light:#A65E2B;--shiki-dark:#C99076;">}</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">/documents&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">page</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> page</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">page_size</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> page_size</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">})</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">if</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> not</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_res </span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">or</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_res</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">status_code </span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">!=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 200</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">    break</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docs_data </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_res</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">json</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">()</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">page_docs </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">data</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {}).</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">docs</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> or</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> []</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">total </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">data</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {}).</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">total</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">,</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 0</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> or</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 0</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">if</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> docs_data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">.</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">get</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">(</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">code</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> !=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;"> 0</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> or</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> not</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> page_docs</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">    break</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">if</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> page </span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">*</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> page_size </span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">&gt;=</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> total</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">    break</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="为什么还要挂载-server-py" tabindex="-1"><a class="header-anchor" href="#为什么还要挂载-server-py"><span>为什么还要挂载 <code>server.py</code></span></a></h4><p>因为容器内部默认使用镜像里自带的 <code>server.py</code>。</p><p>如果你只是改了主机文件，但没有在 Compose 里加：</p><div class="language-yaml line-numbers-mode" data-highlighter="shiki" data-ext="yaml" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-yaml"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> ../mcp/server/server.py:/ragflow/mcp/server/server.py</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>那容器里运行的仍然是旧代码，问题不会真正消失。</p><h3 id="_7-5-问题五-powershell-里发中文-json-mcp-返回-utf-8-decode-错误" tabindex="-1"><a class="header-anchor" href="#_7-5-问题五-powershell-里发中文-json-mcp-返回-utf-8-decode-错误"><span>7.5 问题五：PowerShell 里发中文 JSON，MCP 返回 <code>utf-8 decode</code> 错误</span></a></h3><h4 id="现象-4" tabindex="-1"><a class="header-anchor" href="#现象-4"><span>现象</span></a></h4><p>通过 PowerShell 把中文问题写进 JSON，再用 <code>curl</code> 提交时，MCP 返回类似编码错误。</p><h4 id="根因-4" tabindex="-1"><a class="header-anchor" href="#根因-4"><span>根因</span></a></h4><p>Windows 下某些写文件方式默认带 BOM，或者不是严格的 UTF-8 无 BOM，服务端解析时会异常。</p><h4 id="解决方案-3" tabindex="-1"><a class="header-anchor" href="#解决方案-3"><span>解决方案</span></a></h4><p>用 UTF-8 无 BOM 明确写文件：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> Join-Path</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">env:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TEMP</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ragflow_mcp_test.json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:1,&quot;method&quot;:&quot;tools/call&quot;,&quot;params&quot;:{&quot;name&quot;:&quot;ragflow_retrieval&quot;,&quot;arguments&quot;:{&quot;question&quot;:&quot;vuepress-theme-plume 博客文章 frontmatter tags 标签配置&quot;,&quot;page_size&quot;:8,&quot;similarity_threshold&quot;:0.2}}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> New-Object</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> System.Text.UTF8Encoding</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">false</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">[</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">System.IO.File</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">]</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">::WriteAllText</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>然后再请求：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Accept: application/json, text/event-stream</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Content-Type: application/json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">binary </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">@</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">tmp</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mcp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="_7-6-问题六-刚重建容器后-mcp-短时间内-connection-refused" tabindex="-1"><a class="header-anchor" href="#_7-6-问题六-刚重建容器后-mcp-短时间内-connection-refused"><span>7.6 问题六：刚重建容器后，MCP 短时间内 <code>Connection refused</code></span></a></h3><h4 id="现象-5" tabindex="-1"><a class="header-anchor" href="#现象-5"><span>现象</span></a></h4><p>你刚执行完重建，立刻测试 <code>/mcp/</code> 或 <code>/sse</code>，可能会看到连接失败。</p><h4 id="根因-5" tabindex="-1"><a class="header-anchor" href="#根因-5"><span>根因</span></a></h4><p>MCP 进程已经在起，但主 API <code>9380</code> 还没完全 ready，服务存在启动顺序窗口期。</p><h4 id="解决方案-4" tabindex="-1"><a class="header-anchor" href="#解决方案-4"><span>解决方案</span></a></h4><p>先等健康检查恢复为 <code>ok</code>，再测：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39380</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">v1</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">system</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">healthz</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>只要主 API 健康了，再去测 MCP，通常就会稳定。</p><h3 id="_7-7-问题七-mcp-能连上-但检索报-ollama-连接错误" tabindex="-1"><a class="header-anchor" href="#_7-7-问题七-mcp-能连上-但检索报-ollama-连接错误"><span>7.7 问题七：MCP 能连上，但检索报 Ollama 连接错误</span></a></h3><h4 id="现象-6" tabindex="-1"><a class="header-anchor" href="#现象-6"><span>现象</span></a></h4><p>MCP 初始化正常，但真正执行检索或召回时，返回类似：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>Failed to connect to Ollama. Please check that Ollama is downloaded, running and accessible.</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h4 id="根因-6" tabindex="-1"><a class="header-anchor" href="#根因-6"><span>根因</span></a></h4><p>这通常不是 MCP 网络层的问题，而是 RAGFlow 当前所绑定的模型服务不可用。</p><p>也就是说：</p><ul><li>MCP 通了</li><li>RAGFlow 主服务也通了</li><li>但 RAGFlow 检索链路依赖的模型服务没有通</li></ul><h4 id="解决方案-5" tabindex="-1"><a class="header-anchor" href="#解决方案-5"><span>解决方案</span></a></h4><p>检查你在 RAGFlow 后台配置的模型是否真的可用：</p><ul><li>如果使用 Ollama，确认 Ollama 进程在运行</li><li>如果使用 OpenAI 兼容接口，确认 API 地址和 key 正确</li><li>如果使用本地代理，确认代理服务本身是正常的</li></ul><p>这个问题和 &quot;Cursor 的 MCP 配置&quot; 不是同一层，排障时不要混在一起看。</p><h2 id="_8-如何配置-mcp" tabindex="-1"><a class="header-anchor" href="#_8-如何配置-mcp"><span>8. 如何配置 MCP</span></a></h2><p>这一节分成两部分：</p><ul><li>RAGFlow 服务端如何启用 MCP</li><li>Cursor 客户端如何接入 MCP</li></ul><h3 id="_8-1-服务端-mcp-配置" tabindex="-1"><a class="header-anchor" href="#_8-1-服务端-mcp-配置"><span>8.1 服务端 MCP 配置</span></a></h3><p>服务端的关键不在 Cursor，而在 RAGFlow 的容器启动参数。</p><h4 id="env-中的-mcp-相关配置" tabindex="-1"><a class="header-anchor" href="#env-中的-mcp-相关配置"><span><code>.env</code> 中的 MCP 相关配置</span></a></h4><div class="language-dotenv line-numbers-mode" data-highlighter="shiki" data-ext="dotenv" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-dotenv"><span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_HOST</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">0.0.0.0</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_PORT</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">9382</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_BASE_URL</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">http://127.0.0.1:9380</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_MODE</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">self-host</span></span>
<span class="line"><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">RAGFLOW_MCP_HOST_API_KEY</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">ragflow-请替换为你自己的值</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h4 id="docker-compose-yml-中必须有的参数" tabindex="-1"><a class="header-anchor" href="#docker-compose-yml-中必须有的参数"><span><code>docker-compose.yml</code> 中必须有的参数</span></a></h4><div class="language-yaml line-numbers-mode" data-highlighter="shiki" data-ext="yaml" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-yaml"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">command</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --enable-mcpserver</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host=\${RAGFLOW_MCP_HOST}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-port=\${RAGFLOW_MCP_PORT}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-base-url=\${RAGFLOW_MCP_BASE_URL}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-script-path=/ragflow/mcp/server/server.py</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-mode=\${RAGFLOW_MCP_MODE}</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;"> --mcp-host-api-key=\${RAGFLOW_MCP_HOST_API_KEY}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>这里最容易混淆的一点是：</p><ul><li><code>RAGFLOW_MCP_HOST_API_KEY</code> 是给服务端 MCP 自己去访问 RAGFlow API 用的</li><li>不是说 Cursor 一定要把这个 key 带出去</li></ul><p>本次实际验证下，Cursor 侧可以不配置 API key，仍可通过 <code>http://127.0.0.1:39382/mcp/</code> 正常工作。</p><h3 id="_8-2-cursor-侧-mcp-配置" tabindex="-1"><a class="header-anchor" href="#_8-2-cursor-侧-mcp-配置"><span>8.2 Cursor 侧 MCP 配置</span></a></h3><p>Cursor 全局配置文件位置：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">C:\\Users\\~\\.cursor\\mcp.json</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>本次最终可用配置如下：</p><div class="language-json line-numbers-mode" data-highlighter="shiki" data-ext="json" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-json"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">{</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">  &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">mcpServers</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">    &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">RAGFlow</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> {</span></span>
<span class="line"><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">      &quot;</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">url</span><span style="--shiki-light:#99841877;--shiki-dark:#B8A96577;">&quot;</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">:</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">http://127.0.0.1:39382/mcp/</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">    }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  }</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">}</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>请注意两个细节：</p><ol><li>使用 <code>127.0.0.1</code>，不要混用 <code>localhost</code></li><li>使用 <code>/mcp/</code>，不要写成 <code>/mcp</code></li></ol><p>如果你已经改好配置，但 Cursor 面板没有刷新出来，可以：</p><ul><li>重启 Cursor</li><li>或重新打开 MCP 面板</li></ul><h2 id="_9-如何验证-mcp-是否正常" tabindex="-1"><a class="header-anchor" href="#_9-如何验证-mcp-是否正常"><span>9. 如何验证 MCP 是否正常</span></a></h2><p>这一节给出的是 Windows 11 下可以直接运行的 PowerShell 命令。</p><h3 id="_9-1-验证-sse" tabindex="-1"><a class="header-anchor" href="#_9-1-验证-sse"><span>9.1 验证 <code>/sse</code></span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">i </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">max</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">time </span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">3</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">sse</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>正常时会看到类似：</p><div class="language-text line-numbers-mode" data-highlighter="shiki" data-ext="text" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-text"><span class="line"><span>HTTP/1.1 200 OK</span></span>
<span class="line"><span>content-type: text/event-stream; charset=utf-8</span></span>
<span class="line"><span></span></span>
<span class="line"><span>event: endpoint</span></span>
<span class="line"><span>data: /messages/?session_id=xxxx</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>这里超时是正常的，因为 SSE 本来就是长连接。</p><p>只要能看到 <code>HTTP/1.1 200 OK</code> 和 <code>event: endpoint</code>，就说明监听已经在了。</p><h3 id="_9-2-验证-mcp-initialize" tabindex="-1"><a class="header-anchor" href="#_9-2-验证-mcp-initialize"><span>9.2 验证 <code>/mcp/ initialize</code></span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> Join-Path</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">env:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TEMP</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ragflow_mcp_init.json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:1,&quot;method&quot;:&quot;initialize&quot;,&quot;params&quot;:{&quot;protocolVersion&quot;:&quot;2024-11-05&quot;,&quot;capabilities&quot;:{},&quot;clientInfo&quot;:{&quot;name&quot;:&quot;local-test&quot;,&quot;version&quot;:&quot;1.0.0&quot;}}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> New-Object</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> System.Text.UTF8Encoding</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">false</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">[</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">System.IO.File</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">]</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">::WriteAllText</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">i </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Accept: application/json, text/event-stream</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Content-Type: application/json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">binary </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">@</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">tmp</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">  http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mcp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>正常时会返回 <code>200 OK</code>，并带上 <code>serverInfo</code>。</p><h3 id="_9-3-验证-tools-list" tabindex="-1"><a class="header-anchor" href="#_9-3-验证-tools-list"><span>9.3 验证 <code>tools/list</code></span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> Join-Path</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">env:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TEMP</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ragflow_mcp_tools_list.json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:2,&quot;method&quot;:&quot;tools/list&quot;,&quot;params&quot;:{}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> New-Object</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> System.Text.UTF8Encoding</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">false</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">[</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">System.IO.File</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">]</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">::WriteAllText</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Accept: application/json, text/event-stream</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Content-Type: application/json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">binary </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">@</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">tmp</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">  http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mcp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>正常时你会看到 <code>ragflow_retrieval</code> 这个工具，以及当前可用知识库列表。</p><h3 id="_9-4-验证-tools-call" tabindex="-1"><a class="header-anchor" href="#_9-4-验证-tools-call"><span>9.4 验证 <code>tools/call</code></span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> Join-Path</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">env:</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">TEMP</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">ragflow_mcp_tool_call.json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;id&quot;:3,&quot;method&quot;:&quot;tools/call&quot;,&quot;params&quot;:{&quot;name&quot;:&quot;ragflow_retrieval&quot;,&quot;arguments&quot;:{&quot;question&quot;:&quot;vuepress-theme-plume 博客文章 frontmatter tags 标签配置&quot;,&quot;page_size&quot;:8,&quot;similarity_threshold&quot;:0.2}}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> =</span><span style="--shiki-light:#998418;--shiki-dark:#B8A965;"> New-Object</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> System.Text.UTF8Encoding</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#1E754F;--shiki-dark:#4D9375;">false</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">[</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">System.IO.File</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">]</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">::WriteAllText</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">($</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">tmp</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">body</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">,</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> $</span><span style="--shiki-light:#B07D48;--shiki-dark:#BD976A;">utf8NoBom</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">)</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Accept: application/json, text/event-stream</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">H </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">Content-Type: application/json</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#999999;--shiki-dark:#666666;">  --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">data</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">binary </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">@</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">$</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">tmp</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;"> \`</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">  http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">mcp</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>如果返回真正的 chunk 内容，说明 MCP 与知识库已经打通。</p><p>如果返回模型错误，而不是网络错误，说明：</p><ul><li>MCP 已通</li><li>但 RAGFlow 内部模型服务仍需单独检查</li></ul><h2 id="_10-ragflow-日常启动、停止、重建命令" tabindex="-1"><a class="header-anchor" href="#_10-ragflow-日常启动、停止、重建命令"><span>10. RAGFlow 日常启动、停止、重建命令</span></a></h2><h3 id="启动前先设置内核参数" tabindex="-1"><a class="header-anchor" href="#启动前先设置内核参数"><span>启动前先设置内核参数</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">wsl </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d docker</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">desktop </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">u root </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> sysctl </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">w vm.max_map_count</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">=</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">262144</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="启动" tabindex="-1"><a class="header-anchor" href="#启动"><span>启动</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow\\docker</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose up </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="停止" tabindex="-1"><a class="header-anchor" href="#停止"><span>停止</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow\\docker</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose down</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="只重建-ragflow-主容器" tabindex="-1"><a class="header-anchor" href="#只重建-ragflow-主容器"><span>只重建 RAGFlow 主容器</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">Set-Location</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;"> &#39;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">D:\\Project\\ragflow\\docker</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&#39;</span></span>
<span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose up </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">d </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">force</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">recreate ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h3 id="查看日志" tabindex="-1"><a class="header-anchor" href="#查看日志"><span>查看日志</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker logs </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">tail </span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">200</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>持续跟踪：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker logs </span><span style="--shiki-light:#AB5959;--shiki-dark:#CB7676;">-f</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> simeng</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">ragflow</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">cpu</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">1</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="查看容器" tabindex="-1"><a class="header-anchor" href="#查看容器"><span>查看容器</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker ps </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">format </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">table {{.Names}}\\t{{.Status}}\\t{{.Ports}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h2 id="_11-不建议直接做的事情" tabindex="-1"><a class="header-anchor" href="#_11-不建议直接做的事情"><span>11. 不建议直接做的事情</span></a></h2><h3 id="_11-1-不要轻易执行-docker-compose-down-v" tabindex="-1"><a class="header-anchor" href="#_11-1-不要轻易执行-docker-compose-down-v"><span>11.1 不要轻易执行 <code>docker compose down -v</code></span></a></h3><p>这个命令会把卷一起删掉。</p><p>如果你没有明确打算重置数据，尽量不要这样做。</p><p>推荐只用：</p><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker compose down</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="_11-2-不要把默认管理员密码长期保留在对外环境中" tabindex="-1"><a class="header-anchor" href="#_11-2-不要把默认管理员密码长期保留在对外环境中"><span>11.2 不要把默认管理员密码长期保留在对外环境中</span></a></h3><p>默认管理员账号只适合本地测试。</p><p>如果要用于局域网或公网，建议尽快处理：</p><ul><li>修改管理员密码</li><li>关闭不必要的注册入口</li><li>修改 <code>.env</code> 中的默认弱口令</li></ul><h3 id="_11-3-不要把真实的-mcp-host-api-key-写进文档或发给别人" tabindex="-1"><a class="header-anchor" href="#_11-3-不要把真实的-mcp-host-api-key-写进文档或发给别人"><span>11.3 不要把真实的 MCP host API key 写进文档或发给别人</span></a></h3><p>这类 key 应只保存在：</p><ul><li>本地 <code>.env</code></li><li>安全的密码管理工具</li></ul><p>这份文档里只保留占位符，是为了避免后续二次泄露。</p><h2 id="_12-推荐的排障顺序" tabindex="-1"><a class="header-anchor" href="#_12-推荐的排障顺序"><span>12. 推荐的排障顺序</span></a></h2><p>如果以后再出现问题，建议按这个顺序排：</p><ol><li>先看容器在不在</li></ol><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">docker ps </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">format </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">table {{.Names}}\\t{{.Status}}\\t{{.Ports}}</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><ol start="2"><li>再看主服务健康不健康</li></ol><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">s </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39380</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">v1</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">system</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">healthz</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><ol start="3"><li>再看 MCP 端口是否在监听</li></ol><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#998418;--shiki-dark:#B8A965;">curl.exe</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> -</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">i </span><span style="--shiki-light:#999999;--shiki-dark:#666666;">--</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">max</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">time </span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">3</span><span style="--shiki-light:#999999;--shiki-dark:#666666;"> --</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">noproxy </span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#B56959;--shiki-dark:#C98A7D;">*</span><span style="--shiki-light:#B5695977;--shiki-dark:#C98A7D77;">&quot;</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;"> http:</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">//</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">127.0</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">.</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">0.1</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">:</span><span style="--shiki-light:#2F798A;--shiki-dark:#4C9A91;">39382</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">/</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">sse</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><ol start="4"><li><p>再测 <code>/mcp/</code> 初始化</p></li><li><p>最后才去看 Cursor 配置</p></li></ol><p>这样排会比较稳，不容易把&quot;模型问题&quot;&quot;服务问题&quot;&quot;客户端配置问题&quot;混在一起。</p><h2 id="_13-一份最小可用检查清单" tabindex="-1"><a class="header-anchor" href="#_13-一份最小可用检查清单"><span>13. 一份最小可用检查清单</span></a></h2><p>如果你只想快速确认现在能不能用，可以看这一小节。</p><h3 id="ragflow-是否正常" tabindex="-1"><a class="header-anchor" href="#ragflow-是否正常"><span>RAGFlow 是否正常</span></a></h3><ul class="task-list-container"><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-0" disabled="disabled"><label class="task-list-item-label" for="task-item-0"><code>http://127.0.0.1:38180</code> 能打开</label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-1" disabled="disabled"><label class="task-list-item-label" for="task-item-1"><code>http://127.0.0.1:38180/admin</code> 能打开</label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-2" disabled="disabled"><label class="task-list-item-label" for="task-item-2"><code>http://127.0.0.1:39380/v1/system/healthz</code> 返回全 <code>ok</code></label></li></ul><h3 id="mcp-是否正常" tabindex="-1"><a class="header-anchor" href="#mcp-是否正常"><span>MCP 是否正常</span></a></h3><ul class="task-list-container"><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-3" disabled="disabled"><label class="task-list-item-label" for="task-item-3"><code>http://127.0.0.1:39382/sse</code> 能返回 <code>event: endpoint</code></label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-4" disabled="disabled"><label class="task-list-item-label" for="task-item-4"><code>initialize</code> 返回 <code>200</code></label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-5" disabled="disabled"><label class="task-list-item-label" for="task-item-5"><code>tools/list</code> 能列出 <code>ragflow_retrieval</code></label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-6" disabled="disabled"><label class="task-list-item-label" for="task-item-6"><code>tools/call</code> 能返回知识库内容，或者至少返回模型层错误而不是网络层错误</label></li></ul><h3 id="cursor-是否配置正确" tabindex="-1"><a class="header-anchor" href="#cursor-是否配置正确"><span>Cursor 是否配置正确</span></a></h3><ul class="task-list-container"><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-7" disabled="disabled"><label class="task-list-item-label" for="task-item-7"><code>C:\\Users\\~\\.cursor\\mcp.json</code> 已写入 <code>http://127.0.0.1:39382/mcp/</code></label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-8" disabled="disabled"><label class="task-list-item-label" for="task-item-8"> 地址使用了 <code>/mcp/</code></label></li><li class="task-list-item"><input type="checkbox" class="task-list-item-checkbox" id="task-item-9" disabled="disabled"><label class="task-list-item-label" for="task-item-9"> 改完后已重启 Cursor</label></li></ul><h2 id="_14-本次部署中可直接参考的文件路径总表" tabindex="-1"><a class="header-anchor" href="#_14-本次部署中可直接参考的文件路径总表"><span>14. 本次部署中可直接参考的文件路径总表</span></a></h2><h3 id="部署目录" tabindex="-1"><a class="header-anchor" href="#部署目录"><span>部署目录</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="环境变量" tabindex="-1"><a class="header-anchor" href="#环境变量"><span>环境变量</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\.env</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="compose-文件" tabindex="-1"><a class="header-anchor" href="#compose-文件"><span>Compose 文件</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docker\\docker</span><span style="--shiki-light:#999999;--shiki-dark:#666666;">-</span><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">compose.yml</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="mcp-服务端实现" tabindex="-1"><a class="header-anchor" href="#mcp-服务端实现"><span>MCP 服务端实现</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\mcp\\server\\server.py</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="cursor-mcp-配置" tabindex="-1"><a class="header-anchor" href="#cursor-mcp-配置"><span>Cursor MCP 配置</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">C:\\Users\\~\\.cursor\\mcp.json</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="官方管理员文档" tabindex="-1"><a class="header-anchor" href="#官方管理员文档"><span>官方管理员文档</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\docs\\guides\\accessing_admin_ui.md</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="普通登录限制代码" tabindex="-1"><a class="header-anchor" href="#普通登录限制代码"><span>普通登录限制代码</span></a></h3><div class="language-powershell line-numbers-mode" data-highlighter="shiki" data-ext="powershell" style="--shiki-light:#393a34;--shiki-dark:#dbd7caee;--shiki-light-bg:#ffffff;--shiki-dark-bg:#121212;"><pre class="shiki shiki-themes vitesse-light vitesse-dark vp-code"><code class="language-powershell"><span class="line"><span style="--shiki-light:#393A34;--shiki-dark:#DBD7CAEE;">D:\\Project\\ragflow\\api\\apps\\user_app.py</span></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h2 id="_15-一点温柔的提醒" tabindex="-1"><a class="header-anchor" href="#_15-一点温柔的提醒"><span>15. 一点温柔的提醒</span></a></h2><p>这套链路表面上看只是 &quot;把 RAGFlow 跑起来，再在 Cursor 里配个 MCP&quot;。</p><p>但实际踩下来，你会发现它至少包含四层：</p><ul><li>Docker 层</li><li>RAGFlow 服务层</li><li>MCP 服务层</li><li>Cursor 客户端层</li></ul><p>任何一层不通，都会表现成 &quot;好像 MCP 有问题&quot;。</p><p>所以以后遇到异常时，别急，也别怀疑自己哪里全都弄错了。</p><p>多数时候只是某一层状态没有对齐。</p><p>按这份文档一层一层检查，通常就能很快找到问题点。</p><h2 id="_16-参考链接" tabindex="-1"><a class="header-anchor" href="#_16-参考链接"><span>16. 参考链接</span></a></h2><ul><li>官方文档：<a href="https://ragflow.io/docs" target="_blank" rel="noopener noreferrer">https://ragflow.io/docs</a></li><li>官方仓库：<a href="https://github.com/infiniflow/ragflow" target="_blank" rel="noopener noreferrer">https://github.com/infiniflow/ragflow</a></li><li>官方 Releases：<a href="https://github.com/infiniflow/ragflow/releases" target="_blank" rel="noopener noreferrer">https://github.com/infiniflow/ragflow/releases</a></li></ul><h2 id="_17-本次文档重建说明" tabindex="-1"><a class="header-anchor" href="#_17-本次文档重建说明"><span>17. 本次文档重建说明</span></a></h2><p>这份文档是根据本次实际部署、修复、验证过程重新整理的。</p><p>它特别保留了这次真实发生过的关键问题：</p><ul><li>MinIO bucket 缺失</li><li>默认管理员账号不能登录普通前台</li><li>MCP 端口映射了但实际没有启动</li><li>Cursor <code>/mcp</code> 与 <code>/mcp/</code> 的差异</li><li>空知识库导致 MCP 日志无限刷屏</li><li>PowerShell 中文 JSON 编码问题</li><li>模型服务异常与 MCP 异常的区分</li></ul><p>如果以后你继续调整：</p><ul><li>模型配置</li><li>Docker 端口</li><li>MCP 参数</li><li><code>server.py</code> 修补逻辑</li></ul><p>建议同步更新这份文档，这样后面你自己维护会轻松很多。</p>`,316)])])}const p=i(h,[["render",n]]),d=JSON.parse('{"path":"/article/windows11-ragflow-deployment-mcp/","title":"Windows 11 本地部署 RAGFlow 与 Cursor MCP 完整记录 | 模型","lang":"zh-CN","frontmatter":{"title":"Windows 11 本地部署 RAGFlow 与 Cursor MCP 完整记录","createTime":"2026/03/29 18:00:00","permalink":"/article/windows11-ragflow-deployment-mcp/","sidebar":"/ai/","description":"这是一份按本次真实部署过程重新整理的操作文档～ 我会尽量把每一步都写得温柔一点、清楚一点，让你以后自己回看的时候，不需要再从聊天记录里一点一点翻找啦。 这份文档适用于： Windows 11 Docker Desktop WSL2 PowerShell 本地通过 Docker 部署 RAGFlow 在 Cursor 中通过 MCP 访问本地知识库 1....","head":[["script",{"type":"application/ld+json"},"{\\"@context\\":\\"https://schema.org\\",\\"@type\\":\\"Article\\",\\"headline\\":\\"Windows 11 本地部署 RAGFlow 与 Cursor MCP 完整记录\\",\\"image\\":[\\"\\"],\\"dateModified\\":\\"2026-03-29T05:21:46.000Z\\",\\"author\\":[]}"],["meta",{"property":"og:url","content":"https://www.simengweb.com/article/windows11-ragflow-deployment-mcp/"}],["meta",{"property":"og:site_name","content":"仲夏夜之梦"}],["meta",{"property":"og:title","content":"Windows 11 本地部署 RAGFlow 与 Cursor MCP 完整记录"}],["meta",{"property":"og:description","content":"这是一份按本次真实部署过程重新整理的操作文档～ 我会尽量把每一步都写得温柔一点、清楚一点，让你以后自己回看的时候，不需要再从聊天记录里一点一点翻找啦。 这份文档适用于： Windows 11 Docker Desktop WSL2 PowerShell 本地通过 Docker 部署 RAGFlow 在 Cursor 中通过 MCP 访问本地知识库 1...."}],["meta",{"property":"og:type","content":"article"}],["meta",{"property":"og:locale","content":"zh-CN"}],["meta",{"property":"og:updated_time","content":"2026-03-29T05:21:46.000Z"}],["meta",{"property":"article:modified_time","content":"2026-03-29T05:21:46.000Z"}]]},"readingTime":{"minutes":15.7,"words":4710},"git":{"createdTime":1774761706000,"updatedTime":1774761706000,"contributors":[{"name":"祀梦","username":"","email":"3501646051@qq.com","commits":1,"avatar":"https://gravatar.com/avatar/6406a81eeddc359cf3d3ce018797689fc6d014ff06215c27d0210b42e8f5a8ab?d=retro"}]},"autoDesc":true,"filePathRelative":"notes/ai/ragflow-windows11-mcp.md","headers":[]}');export{p as comp,d as data};