项目地址

https://github.com/bytedance/deer-flow

整体架构概览

如何debug这个项目？

项目好是好，但是项目太大，不好调试，不清楚里面的流程，想要清楚里面的流程，要如何在 pycharm 中配置可以调试呢？

官方启动命令

让我们首先看下官方是怎么启动的。官方是通过将nginx, gateway, langgraph, nodejs通过 make 命令的方式启动的。make 可以将多项复杂配置和具有依赖关系的配置给你捋清楚，简化项目的配置。

Make命令学习占坑 TODO

---

那如何在 pycharm 中，以 Debug 的方式调试呢？
其实还是需要看 make 命令启动了那些内容：
无非也是后端（langGraph）、前端（nodejs）、网关（gateway）、nginx。 所以我们也需要将这些统统配置到 pycharm 中。

# Start all services
dev:
	@echo "Stopping existing services if any..."
	@-pkill -f "langgraph dev" 2>/dev/null || true
	@-pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true
	@-pkill -f "next dev" 2>/dev/null || true
	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
	@sleep 1
	@-pkill -9 nginx 2>/dev/null || true
	@-./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true
	@sleep 1
	@echo ""
	@echo "=========================================="
	@echo "  Starting DeerFlow Development Server"
	@echo "=========================================="
	@echo ""
	@echo "Services starting up..."
	@echo "  → Backend: LangGraph + Gateway"
	@echo "  → Frontend: Next.js"
	@echo "  → Nginx: Reverse Proxy"
	@echo ""
	@if ! { \
			[ -n "$$DEER_FLOW_CONFIG_PATH" ] && [ -f "$$DEER_FLOW_CONFIG_PATH" ] || \
			[ -f backend/config.yaml ] || \
			[ -f config.yaml ]; \
		}; then \
		echo "✗ No DeerFlow config file found."; \
		echo "  Checked these locations:"; \
		echo "    - $$DEER_FLOW_CONFIG_PATH (when DEER_FLOW_CONFIG_PATH is set)"; \
		echo "    - backend/config.yaml"; \
		echo "    - ./config.yaml"; \
		echo ""; \
		echo "  Run 'make config' from the repo root to generate ./config.yaml, then set required model API keys in .env or your config file."; \
		exit 1; \
	fi
	@cleanup() { \
		trap - INT TERM; \
		echo ""; \
		echo "Shutting down services..."; \
		pkill -f "langgraph dev" 2>/dev/null || true; \
		pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true; \
		pkill -f "next dev" 2>/dev/null || true; \
		nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true; \
		sleep 1; \
		pkill -9 nginx 2>/dev/null || true; \
		echo "Cleaning up sandbox containers..."; \
		./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true; \
		echo "✓ All services stopped"; \
		exit 0; \
	}; \
	trap cleanup INT TERM; \
	mkdir -p logs; \
	echo "Starting LangGraph server..."; \	# 启动langGraph
	cd backend && NO_COLOR=1 uv run langgraph dev --no-browser --allow-blocking --no-reload > ../logs/langgraph.log 2>&1 & \
	sleep 3; \
	echo "✓ LangGraph server started on localhost:2024"; \
	echo "Starting Gateway API..."; \	# 启动Gateway
	cd backend && uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001 > ../logs/gateway.log 2>&1 & \
	sleep 3; \
	if ! lsof -i :8001 -sTCP:LISTEN -t >/dev/null 2>&1; then \
		echo "✗ Gateway API failed to start. Last log output:"; \
		tail -60 logs/gateway.log; \
		echo ""; \
		echo "Likely configuration errors:"; \
		grep -E "Failed to load configuration|Environment variable .* not found|config\.yaml.*not found" logs/gateway.log | tail -5 || true; \
		cleanup; \
	fi; \
	echo "✓ Gateway API started on localhost:8001"; \
	echo "Starting Frontend..."; \		# 启动前端
	cd frontend && pnpm run dev > ../logs/frontend.log 2>&1 & \
	sleep 3; \
	echo "✓ Frontend started on localhost:3000"; \
	echo "Starting Nginx reverse proxy..."; \
	mkdir -p logs && nginx -g 'daemon off;' -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) > logs/nginx.log 2>&1 & \
	sleep 2; \
	echo "✓ Nginx started on localhost:2026"; \
	echo ""; \
	echo "=========================================="; \
	echo "  DeerFlow is ready!"; \
	echo "=========================================="; \
	echo ""; \
	echo "  🌐 Application: http://localhost:2026"; \
	echo "  📡 API Gateway: http://localhost:2026/api/*"; \
	echo "  🤖 LangGraph:   http://localhost:2026/api/langgraph/*"; \
	echo ""; \
	echo "  📋 Logs:"; \
	echo "     - LangGraph: logs/langgraph.log"; \
	echo "     - Gateway:   logs/gateway.log"; \
	echo "     - Frontend:  logs/frontend.log"; \
	echo "     - Nginx:     logs/nginx.log"; \
	echo ""; \
	echo "Press Ctrl+C to stop all services"; \
	echo ""; \
	wait

在pycharm中配置

配置nginx：

点击 配置-》编辑

点击加号-》Shell Script-》脚本文件，然后输入图中配置，然后点击确定

nginx -g 'daemon off;' -c /Users/bytedance/workspace/deer-flow/docker/nginx/nginx.local.conf -p /Users/bytedance/workspace/deer-flow

注意这里的位置要配置成自己项目的位置

前端配置

点击加号-》Shell Script-》脚本文件，然后输入图中配置，然后点击确定

pnpm run dev

GateWay配置

点击加号-》python-》module 选择uvicorn，然后输入图中配置，然后点击确定

src.gateway.app:app --host 0.0.0.0 --port 8001

LangGraph配置

点击加号-》python-》选择script，然后输入图中配置，然后点击确定

scripts：注意这里是你的虚拟环境里的 langGraph 路径
/Users/bytedance/workspace/deer-flow/backend/.venv/bin/langgraph

dev --no-browser --allow-blocking --no-reload

启动服务

依次启动 Nginx、Gateway、langGraph、frontend，即可正常 debug：