Troubleshooting SpiderFoot setup and first scanSpiderFoot 安装和首次扫描故障排查

Common issues when setting up SpiderFoot on macOS, Linux or Docker — and how to fix them.在 macOS、Linux 或 Docker 上安装 SpiderFoot 时的常见问题和解决方法。

Installation issues安装问题

pip install fails with dependency errorpip install 报依赖错误

Use a virtual environment: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt. On macOS check that python3 points to Homebrew Python, not the system one.使用虚拟环境：python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt。macOS 上确认 python3 指向 Homebrew Python 而非系统自带。

Docker container starts but port not accessibleDocker 容器启动但端口无法访问

Make sure you publish the port: docker run -p 5001:5001 spiderfoot. If another service uses port 5001, change the host side: docker run -p 5002:5001 spiderfoot, then open http://127.0.0.1:5002.确认发布了端口：docker run -p 5001:5001 spiderfoot。如果端口 5001 被其他服务占用，改宿主机侧：docker run -p 5002:5001 spiderfoot，然后访问 http://127.0.0.1:5002。

Kali: spiderfoot command not foundKali: spiderfoot 命令找不到

Try: sudo apt update && sudo apt install spiderfoot. If that fails, clone the GitHub repo and run from source.尝试：sudo apt update && sudo apt install spiderfoot。如果不行，clone GitHub 仓库后从源码运行。

First scan issues首次扫描问题

Scan returns no results扫描无结果

A narrow scope with passive-only modules on a low-profile domain can legitimately return few findings. Increase modules gradually, not the scope first.对低调域名做窄范围纯被动模块扫描，结果少是正常的。先逐步增加模块，不要急着扩大范围。

Web UI shows connection refusedWeb UI 显示连接被拒绝

Check that sf.py is listening on 127.0.0.1 (localhost), not 0.0.0.0, for a local-only safe run. Use -l 127.0.0.1:5001.确认 sf.py 监听在 127.0.0.1（localhost），不是 0.0.0.0，以保持本地安全运行。使用 -l 127.0.0.1:5001。

Scan takes too long扫描时间太长

Stop the scan early. A first run should be a learning exercise, not a full inventory. Review partial results and tune modules.提前停止扫描。第一次运行是学习，不是完整盘点。复核部分结果后调整模块。