对话即部署：用DeepSeek+Skills+MCP构建可编程知识库

1. 项目概述：当“对话”成为部署指令的那一刻

我第一次在终端里敲下curl -X POST http://localhost:8000/v1/chat/completions，看着返回的 JSON 里嵌着一行完整的 Docker Compose YAML，手是抖的。不是因为紧张，而是因为——这行文本真的被自动执行了，容器起来了，API 服务跑通了，整个过程没碰一次编辑器、没切一次终端标签页、没手动改过一个环境变量。这就是标题里说的“对话即部署”：你不需要写 CI/CD 脚本，不用配 GitHub Actions，甚至不用打开 VS Code，只要在聊天框里说一句“把 RAGFlow 接入本地 DeepSeek-R1 模型，用 PostgreSQL 当向量库，暴露 8080 端口”，背后整套基础设施就完成了编排、拉取、配置、启动、健康检查和日志路由。它不是概念演示，不是 Demo 视频，而是我在过去三个月里每天真实使用的开发流——用自然语言驱动 DevOps 全链路。

核心关键词DeepSeek、Skills、MCP、知识库，不是并列关系，而是四层咬合的齿轮：DeepSeek 是推理引擎，是那个能听懂“我要搭一个支持中文 PDF 解析的私有知识库”的大脑；Skills 是它的“肌肉记忆”，比如docker_run、git_clone、pg_restore这些原子能力，不是 API 封装，而是带上下文感知、错误恢复、权限沙箱的真实操作函数；MCP（Model Control Protocol）是神经系统，定义了模型如何安全、可审计、可中断地调用 Skills，它不依赖特定框架，而是一套轻量通信契约，让模型输出不再只是文本，而是结构化动作指令；知识库则是整个系统的“记忆外挂”，但不是传统 RAG 的静态 embedding 库，而是动态可编程的语义空间——你能用自然语言问“上个月销售报告里提到的三个风险点，哪些在 Q3 复盘会上被否决了？”，系统会自动拆解问题、跨文档溯源、比对会议纪要时间戳、调用 SQL 查询数据库、再把结果喂回模型生成摘要。这套组合拳解决的不是“能不能跑大模型”的问题，而是“怎么让大模型真正接管日常工程任务”的问题——它把部署从“运维人员的专项技能”，降维成“每个工程师都能用母语发起的协作请求”。

适合谁看？如果你是后端工程师，正被重复的环境搭建、服务联调、配置同步折磨得想辞职；如果你是 AI 工程师，天天在 Dify / RAGFlow / LlamaIndex 的 UI 和 config.yaml 之间反复横跳，却离“让模型自己修 bug”越来越远；如果你是技术负责人，团队里一半时间花在“教新人怎么起本地知识库”，另一半时间在救火“为什么测试环境的 embedding 模型版本和线上不一致”——那这篇就是为你写的。它不讲原理图，不画架构框，只告诉你：哪几行代码必须改，哪个端口必须开，为什么mcp-server一定要用--no-sandbox启动，以及当你在 Obsidian 里右键选中一段文字说“把这个加进知识库并打上#客户反馈标签”时，背后到底发生了什么。

2. 整体设计思路：为什么是这四块拼图，而不是别的？

2.1 不选 LangChain / LlamaIndex 做编排层：它们太“重”，也太“软”

很多人第一反应是：“用 LangChain 编排 DeepSeek，调用工具不就行了？”我试过。用 LangChain 的 Tool Calling 机制封装docker run命令，表面看没问题，但实际一跑就崩。原因很实在：LangChain 的工具调用是纯 Python 函数调用，它假设所有工具都在当前进程内存里，而docker run这种操作需要 root 权限、网络命名空间隔离、cgroup 资源限制——这些 LangChain 根本不感知。更致命的是错误处理：当docker run因端口冲突失败时，LangChain 只能拿到一个CalledProcessError异常，它不知道该重试、该换端口、还是该删掉旧容器。它没有“上下文状态”，只有“函数返回值”。而 Skills 的设计哲学是：每个 Skill 必须自带状态机。比如docker_runSkill 内部会先docker ps -q --filter "expose=8080"查端口占用，再决定是--port 8081还是docker stop $(...)，这个决策逻辑是硬编码在 Skill 里的，不是靠模型 prompt 提示出来的。LangChain 把“决策权”全交给模型，而 Skills 把“决策权”按能力边界切分——模型负责“想做什么”，Skill 负责“怎么做才安全”。

提示：不要把 Skills 理解为“API 封装”。它是带策略的执行体。比如git_cloneSkill 会自动检测目标目录是否存在、是否为 git 仓库、是否有未提交更改，再决定是git pull、git clone --depth 1还是报错提示用户确认。这种判断逻辑，绝不能丢给大模型实时生成。

2.2 为什么 MCP 是不可替代的“神经中枢”？

MCP（Model Control Protocol）这个词最近被炒得很热，但很多人没抓住它的本质。它不是又一个 RPC 协议，而是一个意图-动作-反馈的标准化管道。举个具体例子：当模型输出{"action": "run_docker", "params": {"image": "ragflow/ragflow", "port": 8080}}，MCP Server 干了三件事：第一，校验这个 action 是否在白名单里（run_docker是允许的，rm -rf /是直接拦截的）；第二，把 params 传给对应的 Skill 执行，并捕获 stdout/stderr/exit_code；第三，把执行结果结构化打包成{"status": "success", "output": "Container started on port 8080", "logs_tail": "..."}返回给模型。这个闭环里，最关键的是“校验”和“结构化反馈”。没有 MCP，模型输出的 JSON 可能是{"cmd": "sh", "args": ["-c", "curl http://localhost:8000/shutdown"]}——这已经不是部署，是自杀。MCP 的白名单机制强制所有动作显式声明、最小权限，这是生产环境的底线。而结构化反馈让模型能真正“理解”执行结果：它看到"status": "failed"就知道要重试或换方案，看到"logs_tail"里有Connection refused就明白是依赖服务没起来，而不是笼统地“执行失败”。我们实测过，去掉 MCP 直接走 raw function call，模型在 7 次调用后就会开始幻觉出不存在的容器 ID 并尝试docker exec，而加上 MCP 的严格 schema 校验，这个数字是 237 次——稳定性差了两个数量级。

2.3 知识库为什么必须是“可编程”的，而不是“只读”的？

标题里写的是“知识库”，但搜索热词里高频出现的是ragflow知识库搭建全流程、dify本地部署教程、obsidian知识库搭建——这说明绝大多数人还在把知识库当成“文档存档柜”。真正的瓶颈从来不是“怎么存”，而是“怎么用”。比如销售同事问：“张三客户上周提的需求，技术评估结论是什么？”传统 RAG 会从所有文档里找“张三”+“需求”+“技术评估”，但很可能返回 5 份不同日期的会议纪要，模型得自己判断哪份最新。而我们的知识库是“可编程”的：它内置了query_sales_requirement(customer: str, week: str)这个 Skill，这个 Skill 会自动连接 CRM 数据库查张三的工单号，再用工单号去 Jira 查关联的技术任务，最后聚合 Jira 评论里带@tech标签的回复。这个过程完全透明，用户只看到结果，但背后是知识库与业务系统深度耦合。Obsidian 插件之所以能实现“右键加标签”，是因为它把 Obsidian 的vaultAPI 封装成了obsidian_add_tagSkill，而这个 Skill 的参数校验规则里，tag字段必须匹配预设的#客户反馈|#技术债|#待验证正则——这保证了知识库标签体系不会被随意污染。知识库不是终点，而是 Skills 的数据源，是 MCP 的调度对象，是 DeepSeek 的思考原料。三者缺一不可。

2.4 DeepSeek-R1 为什么是当前最优解，而不是 Claude 或 GPT？

搜索热词里claude code skills、gpt-4o deployment出现频率很高，但我们坚持用 DeepSeek-R1，理由很务实：可控性、确定性、成本。Claude 的 tool calling 在长上下文（>100K tokens）时会出现参数截断，我们测试过，当知识库 chunk 达到 200 个时，Claude 3.5 会把{"port": 8080}里的0丢掉，变成{"port": 808}，然后docker run报错。GPT-4o 的响应速度虽快，但它的 function call 输出格式不稳定——有时是{"name": "run_docker", "arguments": "{...}"}，有时是{"tool_calls": [{"function": {"name": "...", "arguments": "..."}}]}，解析层要写两套逻辑。而 DeepSeek-R1 的deepseek-coder系列模型，在tool_choice="required"模式下，输出 JSON Schema 的合规率是 99.7%，我们用 500 条真实部署指令压测过，只有 1 条因输入里混入了 emoji 导致解析失败（已加前置清洗）。更重要的是成本：DeepSeek-R1-16B 本地部署，A10 显卡上 128 token/s，单次部署指令（平均 320 tokens）耗时 2.5 秒，电费不到 0.001 元；而调用 GPT-4o API，同样指令平均 1.8 秒，但费用是 0.023 元——差了 23 倍。对于每天执行 200+ 次部署的团队，一个月就是 138 元 vs 13800 元。这不是技术情怀，是财务报表上的真实数字。

3. 核心细节解析：Skills 设计、MCP 配置、知识库接入的硬核要点

3.1 Skills 开发：不是写函数，是设计“可信赖的数字员工”

Skills 的核心不是功能多，而是可预测、可审计、可降级。我们定义了一个 Skills 开发铁律：每个 Skill 必须通过三道关卡才能上线。

第一关：输入强校验。以docker_run为例，它的 Pydantic Model 定义如下：

class DockerRunParams(BaseModel): image: str = Field(..., pattern=r'^[a-z0-9]+(?:[._-][a-z0-9]+)*\/[a-z0-9]+(?:[._-][a-z0-9]+)*:[a-z0-9.-]+$') port: int = Field(..., ge=1024, le=65535) env: Dict[str, str] = Field(default_factory=dict) volume: Optional[str] = Field(default=None, pattern=r'^/[^:]+:[^:]+:ro?$')

注意pattern里的正则：强制镜像名必须是registry/repo:tag格式，禁止latest标签（避免不可重现），port限制在非特权端口范围，volume路径必须是绝对路径且不含..。这些不是为了防黑客，而是防自己手滑。我们吃过亏：有次在 prompt 里写了run ragflow with latest tag，模型真就输出了{"image": "ragflow/ragflow:latest"}，结果新版本有 breaking change，整个知识库服务挂了 3 小时。

第二关：执行沙箱化。所有 Skills 运行在独立的subprocess.Popen中，且强制设置：

proc = subprocess.Popen( cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=300, # 5分钟硬超时 cwd="/tmp/skills-workspace", # 强制工作目录 env={"PATH": "/usr/bin:/bin"} # 最小化 PATH )

timeout=300是生命线。曾经有个git_cloneSkill 因网络波动卡在Cloning into 'xxx'...17 分钟，导致整个 MCP Server 线程阻塞。现在超时后自动 kill，返回{"status": "timeout", "message": "Command timed out after 300s"}，模型立刻知道要换镜像源或重试。

第三关：输出结构化归一。无论底层是docker run还是psql -c，所有 Skills 的返回都必须是统一的SkillResult：

class SkillResult(BaseModel): status: Literal["success", "failed", "timeout", "permission_denied"] output: str # 标准输出内容 error: str # 错误输出内容（仅 status=="failed" 时有值） logs_tail: str # 截取最后 200 字符，用于快速诊断 metadata: Dict[str, Any] # 技术元数据，如 container_id, commit_hash

这个 schema 是 MCP Server 解析的唯一依据。模型看到status=="failed"且error包含port is already allocated，就能自主决定port=8081重试；看到metadata.container_id就能后续调用docker_logsSkill 查日志。没有这个归一，模型就是盲人摸象。

注意：Skills 的metadata字段是黄金字段。我们在docker_run里存container_id，在git_clone里存commit_hash，在pg_backup里存backup_file_size。这些不是日志，而是模型下一步行动的“路标”。别省略。

3.2 MCP Server 配置：安全与性能的平衡点在哪里？

MCP Server 不是开箱即用的。我们基于开源mcp-server-python改造，关键配置项有三个：

1. 白名单策略（security_policy.json）

{ "allowed_actions": [ "docker_run", "docker_stop", "git_clone", "obsidian_add_tag", "pg_query" ], "rate_limit": { "window_seconds": 300, "max_calls": 10 }, "sandbox": { "allowed_dirs": ["/tmp/skills-workspace", "/home/user/kb"], "blocked_commands": ["rm -rf", "dd if=", "mkfs"] } }

重点是blocked_commands：它不是正则匹配，而是精确字符串前缀拦截。rm -rf被拦，但rm file.txt可以——因为 Skills 里rm操作只允许删除/tmp/skills-workspace下的临时文件。这个粒度控制，比 Linux capability 更细。

2. 日志审计开关（audit_log_enabled: true）每条 Skill 调用都会写入/var/log/mcp-audit.log，格式为：

2024-06-15T08:23:41Z | user:alice | action:docker_run | input:{"image":"ragflow/ragflow:0.12.3","port":8080} | status:success | metadata:{"container_id":"abc123"}

这个日志是事后追责的唯一依据。我们把它接入 ELK，设置告警：当status:failed且input.port < 1024时，立即 Slack 通知运维。审计不是为了监控人，而是为了确认系统没被绕过。

3. 性能调优（concurrency: 4）MCP Server 默认是单线程，但 Skills 里大量 IO 操作（Docker API、PostgreSQL 查询）是阻塞的。我们把concurrency设为 4，意味着最多 4 个 Skills 并发执行。实测发现，超过 4 个并发，A10 显卡的 VRAM 就会因 DeepSeek 模型推理和 Skills 进程争抢而 OOM。这个数字不是理论值，是我们在 32GB VRAM 机器上用stress-ng --vm 2 --vm-bytes 16G压测出来的临界点。

3.3 知识库接入：RAGFlow + PostgreSQL 的“非标准”用法

RAGFlow 官方推荐用 ChromaDB，但我们强制切换到 PostgreSQL，原因只有一个：事务一致性。ChromaDB 的add_documents是异步的，你调用完立刻查，可能查不到；而 PostgreSQL 的INSERT ... RETURNING id是原子的，插入成功就一定能查到。这对“对话即部署”至关重要——当用户说“把这份合同加入知识库”，系统必须确保：1）文件解析完成；2）chunk 存入 DB；3）embedding 向量写入pgvector表；4）返回document_id给模型。四个步骤必须在一个 DB 事务里。

具体改造点有三处：

1. 修改 RAGFlow 的document_service.py

# 原来用 chroma.add() # 改为： with get_db_session() as session: doc = Document(name=file_name, type="pdf", status="parsing") session.add(doc) session.flush() # 获取自增 id # 解析 PDF，生成 chunks chunks = parse_pdf(file_path) for i, chunk in enumerate(chunks): # 计算 embedding（用 sentence-transformers） emb = embed_model.encode(chunk.text).tolist() # 写入 pgvector 表 session.execute( text("INSERT INTO embeddings (doc_id, chunk_idx, content, embedding) VALUES (:doc_id, :idx, :content, :emb)"), {"doc_id": doc.id, "idx": i, "content": chunk.text, "emb": emb} ) session.commit() # 事务提交，全部成功或全部失败

2. PostgreSQL 配置优化在postgresql.conf里必须开启：

shared_preload_libraries = 'vector' work_mem = '64MB' # 提升 ORDER BY vector <-> ... 的排序性能 maintenance_work_mem = '512MB' # 加速 CREATE INDEX CONCURRENTLY

vector扩展是 pgvector 的核心，不加载它，<->操作符根本不存在。work_mem太小会导致相似度查询超时，我们实测 32GB 内存服务器，64MB是最佳平衡点——再大，其他查询会内存不足；再小，top-k 查询延迟从 120ms 涨到 850ms。

3. RAGFlow Web UI 的“隐藏开关”RAGFlow 前端默认禁用 PostgreSQL 选项。要启用，需在web/src/config.js里修改：

export const SUPPORTED_VECTOR_STORES = ['pgvector', 'chroma']; // 原来只有 chroma // 并在登录后 URL 加 ?vector_store=pgvector 强制激活

这个开关藏得深，但它是让知识库真正“可编程”的前提——只有 PG 才支持SELECT * FROM documents WHERE tags @> ARRAY['#客户反馈']这样的高级查询，而 ChromaDB 只能做 flat search。

4. 实操全流程：从零搭建“对话即部署”系统（含避坑清单）

4.1 环境准备：硬件、系统、依赖的硬性门槛

这不是一个“npm install 就能跑”的玩具项目。我们用的是生产级配置，所有步骤均在 Ubuntu 22.04 LTS 上实测通过。

硬件要求（最低）：

• CPU：Intel i7-8700K 或 AMD Ryzen 5 3600（6 核 12 线程）
• 内存：32GB DDR4（RAGFlow + PostgreSQL + DeepSeek-R1-16B 吃内存）
• 显卡：NVIDIA A10（24GB VRAM）或 RTX 4090（24GB）——A10 是性价比之选，FP16 推理吞吐稳定在 128 token/s
• 硬盘：1TB NVMe SSD（知识库索引和 Docker 镜像占空间极大）

系统级依赖（必须一次性装齐）：

# 1. NVIDIA 驱动（A10 需要 525+ 版本） sudo apt install nvidia-driver-535 # 2. Docker CE（24.0.5+，老版本不支持 --cgroup-parent） curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER # 3. PostgreSQL 15（不是 16，RAGFlow 适配 15） sudo apt install postgresql-15 postgresql-client-15 sudo -u postgres psql -c "CREATE EXTENSION vector;" # 4. Python 3.10（DeepSeek 官方支持版本） sudo apt install python3.10-venv python3.10-dev

注意：不要用apt install python3，Ubuntu 22.04 自带的是 3.10.6，但python3-dev包名是python3.10-dev。漏掉-dev，后续编译pgvector会报Python.h not found。

Docker 配置关键项（/etc/docker/daemon.json）：

{ "default-runtime": "runc", "runtimes": { "nvidia": { "path": "nvidia-container-runtime", "runtimeArgs": [] } }, "default-ulimits": { "nofile": { "Name": "nofile", "Hard": 65536, "Soft": 65536 } } }

ulimits.nofile必须设为 65536。RAGFlow 启动时会打开数百个文件描述符（PDF 解析、向量计算、日志轮转），默认 1024 不够，会报OSError: Too many open files。这个坑我们踩了两天，strace -e trace=openat docker run ...才定位到。

4.2 DeepSeek-R1 模型部署：量化、服务化、API 对齐

我们不推荐 HuggingFace Transformers 原生加载，因为generate()方法无法满足 MCP 的低延迟要求。必须用 vLLM（0.4.2）+ AWQ 量化。

步骤 1：下载并量化模型

# 从 HuggingFace 下载原始权重（约 32GB） huggingface-cli download deepseek-ai/deepseek-coder-33b-instruct --local-dir ./deepseek-33b # 用 awq quantize（需 4x A10，量化耗时 47 分钟） pip install autoawq python -m awq.entry --model_path ./deepseek-33b \ --w_bit 4 --q_group_size 128 \ --output_path ./deepseek-33b-awq

AWQ 量化后模型体积从 32GB 降到 9.2GB，推理速度提升 2.3 倍，精度损失 <0.8%（在 HumanEval 测试集上）。q_group_size=128是关键，太小（32）精度掉太多，太大（256）速度没提升。

步骤 2：vLLM 启动服务

# 注意：必须指定 --enable-chunked-prefill，否则长上下文（>32K）会 OOM python -m vllm.entrypoints.api_server \ --model ./deepseek-33b-awq \ --tensor-parallel-size 4 \ --dtype half \ --gpu-memory-utilization 0.9 \ --enable-chunked-prefill \ --max-num-seqs 256 \ --port 8000

--gpu-memory-utilization 0.9是精髓。A10 24GB 显存，vLLM 默认用满，但 Skills 进程也要吃显存（Docker API 调用、PG 向量计算），留 10% 给系统，避免CUDA out of memory。我们实测，0.95 时每 3 次部署就有 1 次 OOM，0.9 则 100 次无一失败。

步骤 3：API 兼容层（对接 MCP）vLLM 的/v1/chat/completions返回格式是 OpenAI 风格，但 MCP 要求tool_calls字段必须是数组，而 vLLM 默认是单对象。需加一层 FastAPI 代理：

@app.post("/mcp/chat/completions") async def mcp_chat_completions(request: Request): body = await request.json() # 强制添加 tool_choice body["tool_choice"] = "required" # 调用 vLLM async with httpx.AsyncClient() as client: resp = await client.post("http://localhost:8000/v1/chat/completions", json=body) data = resp.json() # 修复 tool_calls 格式 if "tool_calls" in data["choices"][0]["message"]: tc = data["choices"][0]["message"]["tool_calls"] if isinstance(tc, dict): # vLLM 返回 dict data["choices"][0]["message"]["tool_calls"] = [tc] return data

这个代理层是必须的。没有它，MCP Server 解析tool_calls会失败。

4.3 MCP Server 与 Skills 的集成：让模型真正“动手”

安装与配置：

git clone https://github.com/axelife/mcp-server-python cd mcp-server-python pip install -e . # 复制我们定制的安全策略 cp /path/to/security_policy.json ./config/ # 启动（注意 --no-sandbox！） mcp-server --host 0.0.0.0 --port 8001 --config ./config/security_policy.json --no-sandbox

--no-sandbox是关键。MCP Server 默认用 Chromium sandbox，但它会拦截docker命令的fork()系统调用，导致 Skills 无法启动子进程。--no-sandbox关闭它，但代价是必须依赖security_policy.json的白名单做防护——这是安全与可用性的明确取舍。

Skills 注册（mcp-server-python 的 plugin 机制）：在./plugins/下创建docker_skills.py：

from mcp.server.stdio import stdio_server from mcp.types import ToolResult def docker_run(image: str, port: int, env: dict = None) -> ToolResult: # ... 执行逻辑（见 3.1 节） return ToolResult(status="success", output="...", metadata={"container_id": cid}) # 注册为 MCP Tool tools = [ Tool( name="docker_run", description="Run a docker container with specified image and port", input_schema=DockerRunParams.model_json_schema(), implementation=docker_run ) ] # 启动 server stdio_server(tools)

注册后，MCP Server 启动时会自动加载./plugins/下所有.py文件。我们约定：每个 Skill 一个文件，文件名即tool_name，这样便于团队协作管理。

DeepSeek 与 MCP 的联动测试：用 curl 发送一条“部署指令”：

curl -X POST http://localhost:8001/mcp/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "deepseek-r1", "messages": [{"role": "user", "content": "Deploy RAGFlow with PostgreSQL backend on port 8080"}], "tools": [{"type": "function", "function": {"name": "docker_run"}}] }'

如果返回{"status": "success", "metadata": {"container_id": "abc123"}}，且docker ps | grep abc123确实存在，说明链路打通。这是最关键的验收点，必须亲手验证。

4.4 知识库与 Skills 的双向绑定：让“对话”有记忆、有上下文

知识库不是被动被查的，它要主动参与 Skills 的决策。我们实现了两个关键绑定：

1. Obsidian 插件：右键即入库在 Obsidian 的main.js里注入：

this.registerEvent( this.app.workspace.on("editor-menu", (menu, editor) => { const selected = editor.getSelection(); if (selected.length > 10) { menu.addItem((item) => { item.setTitle("Add to Knowledge Base") .setIcon("book") .onClick(async () => { // 调用 MCP 的 obsidian_add_tag Skill const resp = await fetch("http://localhost:8001/mcp/skill", { method: "POST", body: JSON.stringify({ "tool": "obsidian_add_tag", "params": { "vault_path": this.app.vault.adapter.basePath, "file_path": editor.file.path, "tag": "#obsidian-import" } }) }); new Notice("Added to KB!"); }); }); } }) );

这个插件让知识库采集从“手动复制粘贴”变成“右键点击”，采集效率提升 5 倍。关键是tag字段强制为#obsidian-import，这样后续query_kb(tag="#obsidian-import")就能精准召回所有 Obsidian 来源内容。

2. RAGFlow 的“反向触发”：知识库变更自动更新 SkillsRAGFlow 的document_service.py里，在session.commit()后加：

# 文档入库成功，触发 MCP 更新缓存 import requests requests.post("http://localhost:8001/mcp/skill", json={ "tool": "kb_cache_refresh", "params": {"doc_id": doc.id} })

kb_cache_refreshSkill 会清空 Redis 里对应doc_id的缓存，并重新加载 chunk 到内存。这样，当用户在 RAGFlow Web UI 里删掉一个文档，Skills 层立刻感知，不会再用到已删除的内容。这是“对话即部署”的闭环：部署行为改变知识库，知识库变化又影响下一次部署决策。

5. 常见问题与排查技巧实录：那些没写在文档里的坑

5.1 模型“装死”：输出 JSON 但 Skills 不执行

现象：DeepSeek 返回了{"action": "docker_run", "params": {...}}，但docker ps看不到容器，MCP Server 日志里也没有docker_run调用记录。

排查路径：

1. 检查 MCP Server 的--no-sandbox是否生效
   ps aux | grep mcp-server，看启动命令里有没有--no-sandbox。没有？重启服务。
2. 检查 Skills 文件权限
   ls -l ./plugins/docker_skills.py，确保是rw-r--r--。如果权限是600（只有 owner 可读），MCP Server 会静默跳过加载，日志里只有一行INFO: Skipping plugin ... (permission denied)。
3. 检查tool_choice是否强制
   用 curl 测试时，"tool_choice": "required"必须显式传入。漏掉这一行，模型会返回普通文本，而不是 JSON tool call。

终极验证法：
直接调用 Skills 的 Python 函数：

from plugins.docker_skills import docker_run result = docker_run(image="nginx:alpine", port=8080) print(result) # 如果这里报错，问题在 Skills 层；如果成功，问题在 MCP 或模型层

5.2 PostgreSQL 向量查询慢：10 秒才返回结果

现象：用户问“合同里关于违约金的条款”，RAGFlow 响应超时，Nginx 返回 504。

根因分析：
pgvector的CREATE INDEX没建好。默认CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops)是无效的，必须指定lists参数：

-- 删除错误索引 DROP INDEX IF EXISTS idx_embeddings_embedding; -- 创建正确索引（lists = 100 是经验值） CREATE INDEX ON embeddings USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);

lists参数决定聚类数。太小（10）查得快但精度低；太大（1000）精度高但慢。我们用 10 万条合同 chunk 测试，lists=100时 P95 延迟 120ms，lists=1000时是 890ms。100是黄金值。

验证命令：

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM embeddings ORDER BY embedding <=> '[0.1,0.2,...]' LIMIT 5;

看Execution Time和Buffers。如果Buffers里Shared Hit< 90%，说明索引没生效，缓存没命中。

5.3 MCP Server 启动报错 “Address already in use”

现象：mcp-server --port 8001报错OSError: [Errno 98] Address already in use。

不是端口被占那么简单。
MCP