gpt-researcher Docker 快速部署指南docker-compose 与 Docker CLI 完整实战【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher本文围绕 gpt-researcher 官方 Docker 快速启动流程展开完整讲解从安装 Docker Desktop、配置.env环境变量到通过docker-compose up --build一键拉起后端 Python 服务localhost:8000与 React 前端localhost:3000的完整链路并深入仓库源码解析docker-compose.yml服务编排、Dockerfile多阶段构建原理以及 Docker CLI 直接运行与本地文档挂载方案。读完本文你将掌握 gpt-researcher 在 Docker 环境下的标准化启动、服务裁剪与排障能力。一、准备工作安装并启动 Docker DesktopDocker 快速部署的第一步是安装 Docker Desktop。gpt-researcher 的后端基于 Python 3.12仓库根目录 Dockerfile 使用python:3.12-slim-bookworm基础镜像前端为 Next.js二者均被打包为独立镜像因此本机只需具备 Docker 运行时即可无需手动安装 Python 或 Node.js 环境。安装完成后请确认 Docker 守护进程正常运行且你的 Docker 版本同时支持 Compose V2新版 Docker Desktop 默认内置docker compose子命令旧版则使用带连字符的docker-compose独立命令这也是文档中两种写法并存的原因。提示Windows/macOS 用户安装 Docker Desktop 后请保持其在后台运行Linux 用户建议将当前用户加入docker用户组避免每次执行都需要sudo。二、配置环境变量从.env.example到.env启动前需要为容器注入 API Key。官方推荐的流程是将仓库根目录的.env.example文件复制为.env填入密钥后保存。仓库中的 .env.example 提供了完整的环境变量模板核心条目如下OPENAI_API_KEY TAVILY_API_KEY BRAVE_API_KEY XQUIK_API_KEY GETXAPI_API_KEY DOC_PATH./my-docsOPENAI_API_KEYLLM 提供方密钥。gpt-researcher 支持任意 LLM Provider默认以 OpenAI 兼容接口接入若使用自定义 OpenAI 兼容端点本地模型、其他云厂商还需在.env中补充OPENAI_BASE_URL对应 docker-compose.yml 中注入容器的同名变量。TAVILY_API_KEY默认的 Web 搜索 API 密钥Tavily Search。项目同样支持brave、xquik、getxapi、google、bing、searx等检索器相关密钥可一并填入。DOC_PATH本地文档目录路径默认./my-docs用于基于本地文档研究场景详见第六节。此外.env.example中还包含大量可选的性能与可观测性配置例如# 并发抓取与限速Firecrawl Free 仅允许 2 个并发浏览器 #MAX_SCRAPER_WORKERS15 #SCRAPER_RATE_LIMIT_DELAY0.0 # LangSmith 链路追踪 # LANGCHAIN_TRACING_V2true # LANGCHAIN_API_KEY # LANGCHAIN_PROJECTgpt-researcher # 各阶段 LLM 输出 Token 上限FAST3000 / SMART6000 / STRATEGIC4000 # SMART_TOKEN_LIMIT16000这些变量被 gpt_researcher/config/config.py 读取优先取环境变量缺省时回落到 gpt_researcher/config/variables/default.py 中的DEFAULT_CONFIG如DOC_PATH缺省即为./my-docs。关于原文档中在requirements.txt中添加所选 LLM 对应的 langchain 包这一步骤仓库根目录 requirements.txt 已随项目维护固定依赖集合该提示主要用于自定义 LLM 接入场景。若你使用非内置的 langchain 集成如langchain-deepseek、langchain_mistralai等可在构建前将其追加到该文件镜像构建阶段会自动通过pip install -r requirements.txt安装见 Dockerfile。若你完全使用默认的 OpenAI 兼容配置则无需改动此文件。三、一键启动docker-compose up --build环境变量就绪后在仓库根目录执行docker-compose up --build如果你的 Docker 版本使用 Compose V2去掉连字符的现代写法请改用它docker compose up --build--build会在启动前重新构建镜像确保代码与依赖为最新状态。构建完成后默认会同时启动两个服务Python 后端服务FastAPI Uvicorn监听localhost:8000React 前端服务Next.js监听localhost:3000打开浏览器访问localhost:3000即可开始使用 gpt-researcher 发起研究任务。排障提示若docker-compose up首次启动因拉取/构建超时失败可先单独执行docker compose build查看构建日志再执行docker compose up -d以分离模式后台运行通过docker compose logs -f跟踪输出。四、源码级解析docker-compose.yml 中的服务编排仓库根目录的 docker-compose.yml 定义了默认的两个核心服务另有测试与 Discord 机器人两个可选服务。4.1 gpt-researcher后端gpt-researcher: pull_policy: build image: gptresearcher/gpt-researcher build: ./ environment: OPENAI_API_KEY: ${OPENAI_API_KEY} OPENAI_BASE_URL: ${OPENAI_BASE_URL} TAVILY_API_KEY: ${TAVILY_API_KEY} LANGCHAIN_API_KEY: ${LANGCHAIN_API_KEY} LOGGING_LEVEL: INFO # 图片生成可选用于在报告中内嵌图片 GOOGLE_API_KEY: ${GOOGLE_API_KEY} IMAGE_GENERATION_ENABLED: ${IMAGE_GENERATION_ENABLED:-false} IMAGE_GENERATION_MODEL: ${IMAGE_GENERATION_MODEL:-gemini-2.0-flash-preview-image-generation} IMAGE_GENERATION_MAX_IMAGES: ${IMAGE_GENERATION_MAX_IMAGES:-3} volumes: - ${PWD}/my-docs:/usr/src/app/my-docs:rw - ${PWD}/outputs:/usr/src/app/outputs:rw - ${PWD}/logs:/usr/src/app/logs:rw user: root restart: always ports: - 8000:8000关键点说明pull_policy: build优先从本地构建镜像未命中时再考虑拉取gptresearcher/gpt-researcher远端镜像。环境变量全部通过${VAR}从你的.env文件注入带:-默认值的变量图片生成相关即使.env未配置也能以安全默认值启动。三个挂载卷使容器与宿主机共享数据my-docs本地文档库、outputs报告输出、logs应用日志。后端入口 main.py 通过load_dotenv()加载环境变量并以uvicorn.run(app, host0.0.0.0, port8000)启动 FastAPI 应用应用本体在 backend/server/app.py。restart: always容器异常退出后自动重启适合长期运行。4.2 gptr-nextjs前端gptr-nextjs: image: gptresearcher/gptr-nextjs stdin_open: true environment: CHOKIDAR_USEPOLLING: true LOGGING_LEVEL: INFO NEXT_PUBLIC_GA_MEASUREMENT_ID: ${NEXT_PUBLIC_GA_MEASUREMENT_ID} NEXT_PUBLIC_GPTR_API_URL: ${NEXT_PUBLIC_GPTR_API_URL} build: dockerfile: Dockerfile.dev context: frontend/nextjs volumes: - /app/node_modules - ./frontend/nextjs:/app - ./frontend/nextjs/.next:/app/.next - ./outputs:/app/outputs ports: - 3000:3000使用 frontend/nextjs/Dockerfile.dev 以开发模式构建支持热重载CHOKIDAR_USEPOLLING: true是为容器内文件监听所做的兼容配置。NEXT_PUBLIC_GPTR_API_URL控制前端调用的后端地址缺省时前端默认指向localhost:8000。前端通过 WebSocket 与后端实时交互研究进度相关实现见 frontend/nextjs/hooks/useWebSocket.ts因此两个容器需要同时运行。4.3 可选服务测试与 Discord 机器人docker-compose.yml中还有两个通过profiles隔离的可选服务默认不启动gpt-researcher-testsprofiles: [test]构建后自动安装pytest、pytest-asyncio、faiss-cpu并运行tests/report-types.py与tests/vector-store.py两组测试适合 CI 或本地回归验证。discord-botprofiles: [discord]基于 docs/discord-bot 构建的 Discord 研究机器人需要DISCORD_BOT_TOKEN与DISCORD_CLIENT_ID监听3001:3000。按需启动的方式# 仅启动核心服务后端 前端 docker compose up --build # 额外启动测试服务 docker compose --profile test up --build # 额外启动 Discord 机器人 docker compose --profile discord up --build不需要某个服务时也可直接在docker-compose.yml中注释掉对应服务块正如仓库 README 的 Run with Docker 章节README.md所提示的那样。五、镜像构建原理Dockerfile 与 Dockerfile.fullstack5.1 标准镜像Dockerfile的三阶段构建仓库根目录 Dockerfile 采用多阶段构建Stage 1install-browser基于python:3.12-slim-bookworm安装 Chromium、Chromedriver、Firefox、Geckodriver 及编译工具链。这些浏览器是 gpt-researcher 网页抓取与 PDF 渲染能力的基础对应 gpt_researcher/scraper/browser 模块。Stage 2gpt-researcher-install复制根目录 requirements.txt 与 multi_agents/requirements.txt一次性安装全部 Python 依赖含多智能体扩展。Stage 3gpt-researcher最终镜像创建非 root 用户gpt-researcher预建并授权outputs目录最后以CMD uvicorn main:app --host ${HOST} --port ${PORT} --workers ${WORKERS}启动服务。默认HOST0.0.0.0、PORT8000、WORKERS1均可用构建参数覆盖。多阶段构建的好处是浏览器与 Python 依赖层的缓存可复用且最终镜像不包含构建期临时文件减小体积。5.2 全栈单镜像Dockerfile.fullstack仓库还提供 Dockerfile.fullstack将前后端合并为单个镜像Stage 1用node:slim构建 Next.js 前端npm run buildStage 2复用上述浏览器安装逻辑arm64 平台直接 apt 安装 Chromiumamd64 走 Google Chrome 官方源Stage 3安装 Python 依赖Stage 4 最终镜像安装 Node.js、nginx、supervisord将前端构建产物复制进镜像由 supervisord 同时拉起三个进程——Uvicorn 后端main:app、npm run start前端内部 3001 端口、nginx监听 3000负责将/outputs、/reports、/ws代理到后端 8000其余流量转发到前端 3001。如果你希望一个镜像跑全栈、单端口对外可参考该 Dockerfile 自行构建仓库未提供对应的 compose 服务需要手动docker build -f Dockerfile.fullstack -t gptr-fullstack .。六、Docker CLI 直接运行与本地文档挂载不依赖 docker-compose 时可用docker run直接启动后端容器docker run -it --name gpt-researcher -p 8000:8000 --env-file .env \ -v /absolute/path/to/gptr_docs:/my-docs gpt-researcher命令参数逐一说明--env-file .env将仓库根目录的.env文件整体注入容器环境变量效果等同于 compose 中的${VAR}注入。-p 8000:8000将容器 8000 端口映射到宿主机供前端或浏览器访问。-v /absolute/path/to/gptr_docs:/my-docs将宿主机上的文档目录挂载到容器内/my-docs供 GPTR API Server 分析。注意/absolute/path/to/gptr_docs必须替换为你的文档目录绝对路径。--name gpt-researcher为容器命名便于docker start/stop/logs管理。该模式仅启动后端如需完整 Web UI仍需通过docker-compose up gptr-nextjs单独启动前端或直接访问localhost:8000使用后端自带的交互页面。本地文档研究模式无论使用哪种启动方式只需将待研究的 PDF、TXT、CSV、Excel、Markdown、PPT、Word 等文件放入挂载目录如./my-docs确保环境变量DOC_PATH指向该目录compose 中即为./my-docs挂载点export DOC_PATH./my-docs然后在 Web 界面的 Report Source 下拉框中选择My Documents即可让 gpt-researcher 基于你的本地文档而非 Web 搜索开展研究。这一行为由 gpt_researcher/config/config.py 的DOC_PATH配置驱动本地文档加载实现见 gpt_researcher/document/document.py。七、验证与常见问题验证部署是否成功# 查看两个核心服务状态 docker compose ps # 跟踪后端日志确认 Uvicorn 与 API Key 加载正常 docker compose logs -f gpt-researcher # 直接调用后端健康检查 curl http://localhost:8000常见问题与对策现象可能原因与对策docker-compose命令不存在使用 Compose V2 语法docker compose up --build或升级 Docker Desktop构建过程下载 Chromium 超时网络受限时更换镜像源或改用gptresearcher/gpt-researcher预构建镜像设置pull_policy后直接docker compose up前端打开但研究无响应确认TAVILY_API_KEY、OPENAI_API_KEY已正确写入.env并检查后端日志中的鉴权报错本地文档识别不到确认DOC_PATH与挂载路径一致且文件已放入./my-docs目录端口被占用修改 docker-compose.yml 中的8000:8000或3000:3000映射为其他宿主机端口八、总结gpt-researcher 的 Docker 化部署将复杂的环境依赖Python 3.12、Chromium 浏览器、Node.js、多智能体扩展全部封装进镜像使用者只需三件事安装 Docker、配置.env、执行docker compose up --build。默认拉起后端8000与前端3000两个服务需要时可通过--profile启用测试或 Discord 机器人服务单容器场景则使用docker run --env-file .env -v ...配合本地文档挂载。理解 docker-compose.yml、Dockerfile 与 Dockerfile.fullstack 的编排与构建逻辑能帮助你在实际部署中自由裁剪服务、自定义镜像与快速排障。进一步阅读可参考仓库中的 getting-started.md本地直装方式与 linux-deployment.mdLinux 生产部署。【免费下载链接】gpt-researcherAn autonomous agent that conducts deep research on any data using any LLM providers项目地址: https://gitcode.com/GitHub_Trending/gp/gpt-researcher创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考