DeerFlow部署教程：Nginx反向代理配置WebUI访问与HTTPS支持-深圳市維司達科技有限公司

DeerFlow部署教程：Nginx反向代理配置WebUI访问与HTTPS支持

1. DeerFlow是什么：你的个人深度研究助理

DeerFlow不是另一个简单的聊天机器人，而是一个能真正帮你做深度研究的智能助手。它像一位随时待命的研究搭档——当你想了解比特币价格波动背后的宏观逻辑，它能自动检索最新财经报道、链上数据和机构研报；当你需要撰写一份医疗AI技术趋势报告，它会调用多个搜索引擎比对信息源，执行Python代码分析公开数据集，再整合成结构清晰的文档；甚至还能把这份报告转成自然流畅的播客脚本，用接近真人语调的声音为你朗读。

它不依赖单一模型“硬算”，而是通过协调多个专业角色协同工作：有负责整体规划的“协调器”，有专注信息检索的“研究员”，有擅长代码执行的“编码员”，还有专精内容组织的“报告员”。这种多智能体协作方式，让DeerFlow在处理复杂、长链条的研究任务时，表现得更像一个有分工、有流程的专业研究团队。

2. 为什么需要Nginx反向代理与HTTPS

DeerFlow默认启动后，WebUI服务监听在本地http://127.0.0.1:8000，这带来两个现实问题：

无法远程访问：你在家里的电脑上部署了DeerFlow，却只能在服务器本机打开浏览器访问，手机、公司电脑、平板全都连不上；
安全性不足：HTTP协议传输的数据是明文的，登录凭证、研究提问、生成的报告内容都可能被截获，尤其当你处理的是敏感行业信息或内部资料时，风险更高。

Nginx反向代理就是解决这两个问题的“桥梁”——它对外暴露一个安全、易记的地址（比如https://research.yourdomain.com），接收所有来自互联网的请求，再把它们悄悄转发给DeerFlow的本地服务；而HTTPS则在这座桥上加了一层加密隧道，确保所有数据在传输过程中都被牢牢锁住。

这不是可有可无的“高级配置”，而是让DeerFlow从一个本地实验工具，真正变成你日常研究工作流中可靠一环的关键一步。

3. 环境准备与前置检查

在开始配置Nginx之前，请先确认DeerFlow核心服务已稳定运行。这一步看似简单，却是后续所有操作的基础。

3.1 验证vLLM大模型服务状态

DeerFlow依赖vLLM提供高性能的Qwen3-4B-Instruct-2507模型推理能力。如果它没起来，WebUI打开后将无法响应任何提问。

请执行以下命令查看日志：

cat /root/workspace/llm.log

正常情况下，你应该能看到类似这样的关键输出行：

INFO 01-26 10:23:45 [engine.py:292] Started engine with config: model='Qwen3-4B-Instruct-2507', tensor_parallel_size=1, dtype=bfloat16 INFO 01-26 10:23:47 [http_server.py:123] HTTP server started on http://0.0.0.0:8001

重点看最后两行：Started engine表示模型加载成功，HTTP server started表示vLLM的API服务已监听在0.0.0.0:8001。如果日志里出现ERROR或长时间卡在Loading model...，请先排查GPU显存、模型路径或CUDA版本问题。

3.2 验证DeerFlow主服务状态

接下来确认DeerFlow自身的协调与Web服务是否就绪：

cat /root/workspace/bootstrap.log

理想日志应包含：

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit) INFO: Application startup complete.

这表示DeerFlow的WebUI后端已成功启动，并监听在0.0.0.0:8000。此时，你可以在服务器上用curl http://localhost:8000测试，返回HTML内容即为正常。

小贴士：如果你发现两个服务都启动了，但浏览器访问http://服务器IP:8000仍失败，请检查云服务器的安全组规则，确保8000和8001端口已对你的IP开放（仅用于临时验证，正式环境切勿长期开放）。

4. Nginx安装与基础反向代理配置

现在，我们来搭建那座安全的“桥梁”。

4.1 安装Nginx

在Ubuntu/Debian系统上，执行：

sudo apt update sudo apt install nginx -y sudo systemctl enable nginx sudo systemctl start nginx

安装完成后，在浏览器中输入你的服务器公网IP，应该能看到Nginx默认欢迎页。这说明Nginx已正确运行。

4.2 创建DeerFlow专属配置文件

Nginx的配置文件通常放在/etc/nginx/sites-available/目录下。我们为DeerFlow创建一个独立配置，便于管理：

sudo nano /etc/nginx/sites-available/deerflow

将以下内容粘贴进去（请务必将your-domain.com替换为你自己的域名，例如research.mycompany.com）：

upstream deerflow_backend { server 127.0.0.1:8000; } server { listen 80; server_name your-domain.com; location / { proxy_pass http://deerflow_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_redirect off; } # 静态资源缓存优化 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 1y; add_header Cache-Control "public, immutable"; } }

这个配置做了几件关键事：

upstream定义了一个名为deerflow_backend的后端服务组，指向DeerFlow的8000端口；
server块监听80端口，当有人访问your-domain.com时，Nginx会接管请求；
location /是核心，它把所有请求（包括WebSocket连接，这对DeerFlow的实时交互至关重要）原封不动地转发给后端；
proxy_set_header系列指令确保DeerFlow能正确识别用户的真实IP和访问协议，避免出现“无法连接”或“登录失效”的问题。

4.3 启用配置并测试HTTP访问

配置好后，需要创建软链接启用它：

sudo ln -sf /etc/nginx/sites-available/deerflow /etc/nginx/sites-enabled/ sudo nginx -t

nginx -t命令会检查语法是否正确。如果看到syntax is ok和test is successful，就可以重载Nginx使配置生效：

sudo systemctl reload nginx

现在，打开你的浏览器，访问http://your-domain.com（注意是http，不是https）。你应该能看到DeerFlow熟悉的WebUI界面，和直接访问http://服务器IP:8000完全一致。这意味着反向代理的第一步——HTTP访问——已经成功。

5. 配置HTTPS：获取SSL证书并启用加密

HTTP只是第一步，HTTPS才是生产环境的标配。我们将使用免费、自动化且广受信任的Let’s Encrypt服务来获取SSL证书。

5.1 安装Certbot并获取证书

Certbot是Let’s Encrypt官方推荐的证书管理工具。安装命令如下：

sudo apt install certbot python3-certbot-nginx -y

然后，执行以下命令一键获取并安装证书（同样请替换your-domain.com）：

sudo certbot --nginx -d your-domain.com

执行过程中，Certbot会：

自动检测Nginx配置中定义的域名；
引导你输入邮箱（用于证书到期提醒）；
询问是否将HTTP自动重定向到HTTPS（强烈建议选择“2: Redirect”）；
自动修改/etc/nginx/sites-available/deerflow文件，添加HTTPS监听和重定向规则。

整个过程无需手动编辑证书文件，Certbot会把证书存放在/etc/letsencrypt/live/your-domain.com/目录下，并自动配置Nginx使用它们。

5.2 验证HTTPS与自动续期

完成Certbot后，再次访问https://your-domain.com。浏览器地址栏应显示绿色的锁形图标，点击它可以查看证书详情，确认颁发者是“Let’s Encrypt”。

Let’s Encrypt证书有效期为90天，但Certbot已为你配置了自动续期任务。你可以手动测试续期是否有效：

sudo certbot renew --dry-run

如果看到Congratulations, all simulated renewals succeeded，就说明一切安好。系统会在证书到期前30天自动尝试更新，你完全无需操心。

6. WebUI使用与常见问题排查

现在，你的DeerFlow已经拥有了一个安全、专业的访问入口。让我们快速走一遍使用流程，并解决几个新手最常遇到的“卡点”。

6.1 标准使用流程

打开前端：在浏览器中输入https://your-domain.com，进入DeerFlow WebUI；
启动研究：点击页面中央醒目的红色按钮（如你提供的截图2.5.2所示），它通常标有“Start Research”或“New Session”；
提出问题：在输入框中写下你的研究需求，例如：“对比分析2024年Q1全球主流AI芯片（H100, MI300X, A100）的FP16算力、功耗与市场价格”；
等待结果：DeerFlow会显示清晰的执行步骤（搜索、编码、分析、报告），最终生成一份图文并茂的PDF报告或可直接收听的播客。

6.2 三个高频问题与解决方案

问题1：页面空白或显示“Connection refused”
原因：Nginx配置中的proxy_pass地址错误，或DeerFlow服务意外停止。
解决：先执行sudo systemctl status nginx确认Nginx运行；再执行cat /root/workspace/bootstrap.log | tail -20查看DeerFlow最新日志，确认其仍在监听8000端口。
问题2：能打开首页，但点击“Start Research”后无反应或报错
原因：WebSocket连接被阻断，通常是Nginx配置中缺少Upgrade和Connection头部。
解决：检查/etc/nginx/sites-available/deerflow文件，确保location /块内包含了proxy_set_header Upgrade $http_upgrade;和proxy_set_header Connection "upgrade";这两行。
问题3：HTTPS访问正常，但报告中的图片链接仍是HTTP，导致浏览器拦截混合内容
原因：DeerFlow生成的内容里硬编码了HTTP地址。
解决：在DeerFlow的配置文件（通常是.env或config.yaml）中，查找BASE_URL或WEBUI_URL类似字段，将其值改为https://your-domain.com，然后重启DeerFlow服务。