企业官网建设流程全解析

搞本地AI搜索的朋友，应该都经历过这种场景：模型跑得挺好，OpenWebUI也装完了，想着给它配个联网搜索，翻文档装上SearXNG，结果搜索一开就报错，要么502，要么403，要么搜出来一片空白。这套OpenWebUI+SearXNG的组合我前后重装部署不下十次，踩过的坑基本都集中在几个固定的配置点上。这篇文章就把最常见的5个配置错误，连带着排查思路和解决命令一起整理出来。

这套方案适合谁？主要是本地部署过大模型（Ollama、LM Studio、vLLM都算），又想让对话机器人具备实时搜索能力的朋友。OpenWebUI负责聊天界面和API网关，SearXNG负责把Google、Bing这些搜索引擎的搜索结果聚合起来，让模型在回答时能引用最新信息。下面这些坑如果你正好遇到，别急着重装，按顺序排查基本都能救回来。

1. 整体架构：为什么OpenWebUI要和SearXNG组队

先把这个架构讲明白，后面排查的时候思路才会清晰。OpenWebUI本身不承担搜索功能，它只是一个前端界面加API转发层。你问它“今天北京天气怎么样”，模型如果只凭训练数据回答，通常不准确，这时候就需要一个搜索模块把实时信息捞回来，再拼接到系统提示词里，让模型基于这些搜索结果生成回答。

SearXNG就是那个搜索模块。它是一个元搜索引擎，自己没索引，但可以把用户的查询同时转发给多个搜索引擎（Google、Bing、Brave、DuckDuckGo等），然后把各家结果去重、合并后统一返回。好处有两个：一是自托管，不需要花钱买搜索API；二是有统一的JSON输出格式，方便程序消费。OpenWebUI就是通过HTTP请求调用SearXNG的JSON接口，拿到搜索结果后塞进上下文，模型再根据这些上下文输出回答。

整个链路大致是这样：用户在OpenWebUI对话框输入问题，OpenWebUI根据配置把问题拼成一个搜索请求发给SearXNG，SearXNG去请求上游搜索引擎，拿到结果后返回JSON给OpenWebUI，OpenWebUI把JSON里的标题、链接、摘要整理成上下文，最后连同用户问题一起发给本地模型。模型基于上下文生成回答。所以任何一个环节出问题，表现都是“联网搜索不可用”。

搞清楚这个链路之后，就能理解为什么很多看似不相干的配置错误会导致同一类症状。下面这5个错误，每一个都能让上面这条链路断在某个位置。

2. 错误一：SearXNG返回403/502，联网搜索直接不可用

2.1 症状和分析

SearXNG容器正常启动，网页版搜索也能正常打开，但在OpenWebUI里一开联网搜索就报错。界面提示一般是“Failed to fetch search results”或者直接502 Bad Gateway，打开SearXNG的容器日志，能看到一堆403 Forbidden。这个问题的经典程度，几乎每个第一次把OpenWebUI和SearXNG接起来的人都遇到过。

为什么网页版能打开、OpenWebUI不能用？根子在于SearXNG默认配置只允许HTML页面访问，没开放JSON格式输出。OpenWebUI请求的是/search?q=xxx&format=json这个接口，SearXNG一看format=json，直接拒绝。搜索引擎为了防止程序滥用，也是同样的逻辑：JSON接口一旦开放，等于任何人可以用你的服务做无限次聚合查询，所以SearXNG默认把这个口子关得很严。

2.2 解决方法

修改SearXNG的settings.yml，在search段落下把formats列表里加上json。这个文件通常在/etc/searxng/settings.yml，如果用Docker挂载，一般在宿主机./searxng/settings.yml这个位置。

search: formats: - html - json

改完重启SearXNG容器，再到OpenWebUI里搜索一次。这一步做完，大部分403问题就消失了。改完后用curl验证一下，这个动作在后续排查中的复现价值很高，先记住：

curl "http://localhost:8080/search?q=test&format=json"

如果返回一段包含results字段的JSON，说明JSON格式已经通了。

2.3 一个容易忽略的隐藏坑

SearXNG新版本默认开启了limiter，这是一层基于IP请求频率的限流保护。如果是刚部署完就测试，触发限流的概率不大，但如果你用同一个IP频繁调用搜索接口，SearXNG会主动拒绝后续请求，表现也是403。我在测试脚本时经常连续发几十条搜索请求，然后突然就开始报错，一开始还以为是SearXNG坏了，后来才发现是限流器在起作用。

server: limiter: false

如果不希望被限流干扰调试，可以临时在server段把limiter设为false。生产环境建议开启，然后配合redis做更细粒度的限流，但这套配置对个人自用来说有点重，按需开启就好。

3. 错误二：Docker网络配错，容器之间互访失败

3.1 症状和分析

OpenWebUI和SearXNG都用Docker部署，两个容器各自都跑起来了，但在OpenWebUI的搜索设置里填http://localhost:8080，怎么试都连不上。在OpenWebUI容器内部执行curl http://localhost:8080也是拒绝连接。这个报错特别容易让人误判成“SearXNG没起来”，于是反复重启SearXNG，折腾半天毫无进展。

问题本质在于Docker的网络隔离机制。每个容器有自己的网络命名空间，容器内的localhost是容器自身而非宿主机。OpenWebUI容器里的localhost:8080指向OpenWebUI容器自己，而这个容器里根本没有服务监听8080端口。同理，SearXNG容器里的localhost也指向SearXNG自己。两个容器之间要通信，必须走Docker网络，而不是宿主机的回环地址。

3.2 解决方法

推荐做法是把两个服务放在同一个自定义桥接网络里，然后用服务名作为主机名互相访问。下面这段docker-compose.yml是整理过的可用版本：

version: "3.8" services: searxng: image: searxng/searxng:latest container_name: searxng networks: - ai-network ports: - "8080:8080" volumes: - ./searxng:/etc/searxng environment: - SEARXNG_BASE_URL=http://searxng:8080/ open-webui: image: ghcr.io/open-webui/open-webui:main container_name: open-webui networks: - ai-network ports: - "3000:8080" environment: - SEARXNG_QUERY_URL=http://searxng:8080/search?q= extra_hosts: - "host.docker.internal:host-gateway" volumes: - ./open-webui:/app/backend/data networks: ai-network: driver: bridge

这里关键点有三个：一是两个服务必须在同一个networks条目下；二是OpenWebUI里的SEARXNG_QUERY_URL必须写http://searxng:8080/search?q=，而不是localhost；三是容器名要能解析，searxng这个服务名在自定义网络里能直接解析成容器IP。如果你的OpenWebUI是用network_mode: host模式跑的，那才可以用localhost，这种情况属于例外。

验证网络是否连通，在宿主机上执行：

docker exec open-webui curl -s "http://searxng:8080/search?q=test&format=json"

如果返回JSON数据，说明网络层面的问题已经解决。

3.3 为什么不用host网络模式

有人图省事，直接把两个容器都设成network_mode: host，这样所有服务共享宿主机网络，localhost确实能通。但host模式会让每个服务都占用宿主机的端口，时间一长端口冲突、环境变量污染的问题都来了。我自己的经验是，自定义桥接网络更干净，服务名解析也更好管。多花两分钟写网络配置，后面排查问题能省几个小时。

4. 错误三：环境变量和代理配置互相“打架”

4.1 症状和分析

这个坑比前两个更隐蔽，因为表面上看配置都对了。SEARXNG_QUERY_URL填的是http://searxng:8080/search?q=，网络也能通，但在OpenWebUI日志里能看到搜索请求发出去后超时，或者请求的URL很奇怪，明显被某个环节改写过。还有人的情况是SearXNG日志里压根收不到请求，OpenWebUI直接报连接超时。

常见原因有两个。第一，环境变量被覆盖。OpenWebUI的配置文件里可能同时存在SEARXNG_QUERY_URL和OPENAI_API_BASE_URL两处定义，某些版本在读取配置时有优先级差异，导致最终生效的是一个拼接错误的地址。第二，代理设置的“殃及池鱼”。如果你的宿主机或容器环境配了HTTP_PROXY/HTTPS_PROXY，OpenWebUI发出的搜索请求也会走代理，而代理本身不可用或没有放行到SearXNG容器的流量，请求就卡住了。

4.2 解决方法

先梳理环境变量来源。建议把OpenWebUI和SearXNG的配置彻底分开管理，不要图省事写在一个全局env文件里。OpenWebUI的关键环境变量建议固定如下：

SEARXNG_QUERY_URL=http://searxng:8080/search?q= ENABLE_RAG_WEB_SEARCH=True

ENABLE_RAG_WEB_SEARCH这个变量容易被漏掉。有些版本里，即使设置了SEARXNG_QUERY_URL，如果没开RAG Web Search的总开关，搜索链路也不会真正启用。这个变量名在不同版本里有细微差异，检查的时候先确认你安装的OpenWebUI版本对应的文档。

代理的问题，用NO_PROXY变量把内网地址排除掉。如果OpenWebUI容器确实需要走代理访问外部资源（比如拉取模型），那就在环境变量里明确排除到SearXNG的流量：

NO_PROXY=searxng,localhost,127.0.0.1,192.168.0.0/16 HTTP_PROXY=http://your-proxy:port HTTPS_PROXY=http://your-proxy:port

另外一个和代理相似的坑是防火墙出站规则。不少Windows用户是在本机直接跑Docker，Windows Defender或第三方安全软件如果拦截了Docker容器虚拟网卡的出站流量，SearXNG的搜索请求就发不出去。排查方法是临时关掉安全软件再测一次搜索，如果恢复正常，说明是防火墙拦截，给Docker相关进程加一条出站放行规则就好。

4.3 日志排查顺序很重要

遇到这种“配置看着对、实际不工作”的情况，别在界面上反复试，打开日志看请求的实际走向。OpenWebUI的日志里会记录搜索请求的完整URL，SearXNG的访问日志会记录收到的请求。两边都看一遍，就能定位到请求是在哪个环节断的。日志不会骗人，你的眼睛会。

5. 错误四：搜索引擎被限流/验证码拦截，SearXNG有结果但搜不到

5.1 症状和分析

这个问题的表现很磨人：SearXNG网页版搜索完全正常，单独请求JSON接口也能返回结果，但OpenWebUI集成后搜索出来的结果经常是空白的，或者偶尔有结果、大部分时间报错。打开SearXNG日志，能看到大量429 Too Many Requests、CAPTCHA之类的错误。

根因在于SearXNG本身不产生数据，它依赖上游搜索引擎。Google、Bing这些搜索引擎对数据中心IP、机房IP有非常严格的频率限制。你用自己的家用宽带访问Google可能没什么问题，但一旦经过SearXNG循环请求，短时间内的请求量就会触发风控。再加上默认配置里几十个搜索引擎全部开启，每个引擎都在请求，上限很快就被拉爆了。

5.2 解决方法

动手改之前先明确一点：不求搜索引擎数量，求稳定可用。很多人的第一反应是去settings.yml里把遗漏的搜索引擎全部打开，这完全是反方向操作。正确的做法是只保留几个稳定、不容易触发验证码的引擎，把其余的全关掉。

一个相对稳定的组合是Bing + DuckDuckGo + Qwant + Startpage。在settings.yml的engines段里，把不需要的引擎的disabled字段设为true，保留的引擎保持默认启用。同时调大超时时间，SearXNG默认的timeout是3秒，对慢速网络环境太短了，改成5到10秒能明显提高成功率：

outgoing: request_timeout: 10 max_request_timeout: 15

如果搜索结果的质量还是不满意，可以考虑给SearXNG配置代理。注意这里是给SearXNG配置它访问上游搜索引擎的代理，不是上面OpenWebUI的那个代理。在settings.yml的outgoing段加上：

outgoing: proxies: http: - http://proxy-address:port https: - http://proxy-address:port

配置代理后，SearXNG的请求会从代理出口发出，相对不容易被搜索引擎风控限制。但个人使用场景如果网络环境本身不差，先不加代理，用精简引擎方案试几天，大概率够用。

5.3 观察引擎的“健康度”

SearXNG有个很有用的页面，路径是/config，在网页管理界面里能看到每个引擎的响应时间、失败次数、被限流次数。这个页面是判断引擎状态的直接依据。我一般隔一周打开看一下，哪个引擎的失败率飙高就临时把它禁用，等风控缓解了再重新打开。这个操作比改代码管用得多。

6. 错误五：界面开关开了但实际没有生效

6.1 症状和分析

这个坑最迷惑人。OpenWebUI的设置页面里，你明明把“Enable Web Search”打开了，也填好了SEARXNG_QUERY_URL，开始新对话的时候也特意勾选了联网搜索选项。结果模型回答的内容还是纯粹依赖训练数据，完全没有体现出它“看到了”搜索结果。有人甚至怀疑模型不行，换了好几个模型都一样。

问题出在OpenWebUI的功能设计上。新版本的“Web Search”开关分了好几层：第一层是全局设置里的总开关，第二层是每个模型自己的功能开关，第三层是会话层面的对话入口开关。很多人在第一层开了总开关，但第二层某个具体模型的功能开关没开，那这个模型发起的所有对话都不会走联网搜索。如果用的是外部接入的API模型，有些还需要在模型配置里额外确认“Tools”权限，因为联网搜索在OpenWebUI内部是作为一个工具来执行的。

6.2 解决方法

按下面这个顺序逐项检查，基本不会漏：

• 全局设置里确认Enable Web Search打开，SEARXNG_QUERY_URL填了有效地址。
• 打开“模型管理”，找到当前使用的模型，确认Web Search或Tools功能没有被关闭。
• 开始新对话时，注意对话输入框上方有没有联网搜索的图标或开关，确保它在启用状态。

如果你是把OpenWebUI当作纯API服务器用，通过/api/chat接口调用，那还得多一步：请求参数里要显式传web_search: true，OpenWebUI不会替你默认开启。这一点特别容易被忽略，很多写脚本调API的人在这栽过跟头。

6.3 区分Web Search、Tools和RAG

这三者的边界很多新手容易混淆。简单说：RAG是把本地知识库的文档切片后做向量检索，是“搜你已有的资料”；Web Search是去互联网搜索，是“搜世界上的公开信息”；Tools是OpenWebUI开放给模型的外部工具调用入口，Web Search在集成后也是以Tool的形式挂载的。如果你在界面上看到“Knowledge”选项但没看到“Web Search”选项，说明Web Search功能压根没被加载，检查重点应该是模型配置和工具开关，而不是搜索URL。

7. 配置完成后的验证方法与效果调优

7.1 一次完整的链路验证

配置全部完成之后，别急着用，先按步骤做一次端到端验证。第一步验证SearXNG本身，第二步验证OpenWebUI到SearXNG的通路，第三步验证模型有没有真正拿到搜索结果。

第一步，直接请求SearXNG的JSON接口：

curl -s "http://localhost:8080/search?q=OpenWebUI%20SearXNG&format=json" | head -c 500

正常情况会返回包含results字段的JSON，里面至少有标题、链接、摘要。

第二步，进OpenWebUI容器里请求SearXNG服务名：

docker exec open-webui curl -s "http://searxng:8080/search?q=test&format=json"

如果这一步能通，说明容器网络和环境变量都没问题。

第三步，在OpenWebUI界面发起一次对话，问题里带上需要实时信息的内容，比如“今天有什么重要的科技新闻”。模型回答后，点开回答下方的引用来源或者详情，检查是否存在搜索结果的引用。如果你的模型支持显示来源，这一步最直观。

7.2 搜索结果质量调优

基础链路通了之后，还可以做几个小优化。SEARXNG_QUERY_URL后面可以追加一些参数，比如指定搜索结果的返回语言：

SEARXNG_QUERY_URL=http://searxng:8080/search?q=&language=zh-CN

如果想要更实时的结果，不需要挖太旧的网页，可以加时间范围限制：

SEARXNG_QUERY_URL=http://searxng:8080/search?q=&time_range=year

time_range的取值有day、week、month、year，按需求选一个。这几个参数都是SearXNG原生支持的，OpenWebUI会原样拼接过去，不需要额外开发。

7.3 搜不到时先怀疑哪一层

我自己排查这套组合故障时，有个固定的排查顺序：先看SearXNG日志，确认有没有收到OpenWebUI的请求；再看SearXNG有没有成功拿到上游搜索引擎的结果；最后检查OpenWebUI有没有把结果正确传给模型。这个顺序从数据流的下游向上游走，每层都能很快定位。实际用下来，70%的故障集中在第2章和第5章那两个错误上，一个是不开JSON格式，一个是上游搜索引擎被限流。

这套OpenWebUI+SearXNG的组合，配置难度真心不高，出问题的点也很集中。把这5个坑提前避开，后面用起来基本就是“一次配置，长期稳定”的状态。最后分享一个小偏方：如果你经常用脚本批量测试搜索，给SearXNG单独留一个API Key或者用代理IP池轮换，能有效降低被限流的概率。希望这份避坑指南能让你少走几个小时的弯路。