DeerFlow 2.0 本地化部署与排坑实战指南

[Hical61]

Summary

Add a practical deployment guide for Windows + Docker Desktop environments, covering real-world issues encountered during local setup.

What's included

• Pre-requisites: Docker Desktop configuration for corporate-managed Windows endpoints (IP-Guard, WSL restrictions, Hyper-V fallback)
• 5 critical config fixes before first launch:
  1. Root .env setup (BETTER_AUTH, API keys)
  2. config.yaml model configuration
  3. Removing sensitive volume mounts that crash Docker on managed endpoints
  4. next.config.js patch to bypass TypeScript/ESLint build errors
  5. frontend/.env and extensions_config.json initialization to prevent 500 errors
• BuildKit manifest list issue (root cause analysis + fix): docker compose up fails with No such image because BuildKit stores OCI manifest lists in its own cache instead of the Docker daemon's image store — workaround using docker build + --pull never
• Docker context isolation on Windows (default vs desktop-linux)
• Quick-reference redeployment commands

Environment tested

• OS: Windows 10 Enterprise LTSC (corporate managed)
• Docker Desktop: 4.37.1
• Docker Compose: v2.31.0-desktop.2
• BuildKit: v0.17.3

[CLAassistant]

All committers have signed the CLA.

[Hical61]

Hi, I've updated the troubleshooting guide with an additional fix.

New section added: "502 Bad Gateway — gateway startup failure"

Root cause: The .env file contains Windows-style paths (e.g., D:\hical\deer-flow\config.yaml) for DEER_FLOW_CONFIG_PATH and DEER_FLOW_EXTENSIONS_CONFIG_PATH. These are passed into the container via env_file, but the Linux process inside the container cannot resolve Windows paths, causing the gateway to fail at startup and nginx to return 502.

Fix: Explicitly override these two variables with container-internal paths in the docker-compose.yaml gateway environment block, which takes precedence over env_file.

This is a common pitfall for Windows users deploying with Docker Desktop. The updated doc now includes the full diagnosis steps and fix.