前言欢迎来到 AutoHunter 部署与使用指南本文旨在为安全研究人员和开发者提供一份详尽的 AutoHunter 系统部署手册。AutoHunter 是一个自动化 SRC 漏洞挖掘系统集成了 FOFA 资产测绘与 LLM 多 worker 自主挖掘/审核/情报沉淀功能能够显著提升漏洞挖掘效率。无论你是安全新手还是经验丰富的渗透测试人员本指南都将帮助你快速搭建并运行 AutoHunter 系统。我们将从最基础的 Docker 部署开始逐步深入到本地源码部署、环境变量配置、常见问题排查等各个环节确保你能够顺利启动并使用这个强大的自动化工具。在开始之前请确保你已经准备好以下资源一个可用的 FOFA 账号或 Hunter 等其他网络空间测绘引擎的 API KeyAI 大模型的 API Key如 DeepSeek、通义千问等基本的命令行操作知识Python 3.9 和 Node.js 16 环境如果选择本地源码部署让我们开始吧下载资源GitHub - StanleyNull/AutoHunter: 自动化 SRC 漏洞挖掘系统FOFA 资产测绘 LLM 多 worker 自主挖掘/审核/情报沉淀。Powered By StanleyNull · GitHub如何部署要将AutoHunter部署到本地电脑推荐优先使用Docker 方式最省心环境隔离好其次是本地源码运行。以下是具体步骤一、Docker 部署推荐项目根目录包含Dockerfile说明支持容器化部署这是最简单的方式。安装 Docker DesktopWindows/Mac前往官网下载并安装 Docker Desktop。Linux使用包管理器安装docker.io和docker-compose。克隆项目代码git clone https://github.com/StanleyNull/AutoHunter.git cd AutoHunter配置环境变量复制.env.example为.envcp .env.example .env编辑.env文件填入你的 API Key、数据库地址、FOFA Token 等必要配置。构建并启动容器docker compose up --build -d若无docker-compose.yml可手动构建镜像并运行docker build -t autohunter . docker run -d --name autohunter -p 8000:8000 --env-file .env autohunter访问服务前端页面http://localhost:8000端口根据实际配置调整后端 API通常在http://localhost:8000/api或类似路径二、本地源码部署适合开发者调试安装依赖环境Python ≥ 3.9项目语言占比76%Node.js ≥ 16前端 Vue 项目PostgreSQL / MySQL根据.env配置选择数据库克隆并进入项目git clone https://github.com/StanleyNull/AutoHunter.git cd AutoHunter安装 Python 依赖pip install -r requirements.txt安装前端依赖并构建cd frontend npm install npm run build cd ..配置环境变量同 Docker 部署步骤复制并编辑.env文件。这步不清楚的可以看翻到后面我写了两种方法初始化数据库解释这条命令会自动检测数据库变化并更新表结构。如果看到类似 INFO [alembic.runtime.migration] Context impl SQLiteImpl 或 Running upgrade 的字样且没有报错就说明成功了。若有报错可往后翻有详细解决办法python manage.py migrate # Django 项目 # 或 alembic upgrade head # Flask SQLAlchemy 项目启动服务AutoHunter 是前后端分离的架构你需要分别启动后端和前端。请打开两个终端窗口或者在一个终端里分步操作1. 启动后端 (核心服务)这一步负责调用 AI 和 FOFA 接口。若报错往后翻有详细解决方法确保终端路径在E:\desktop\AutoHunter(项目根目录)。输入以下命令并回车uvicorn main:app --reload成功标志看到类似Uvicorn running on http://127.0.0.1:8000的绿色字样且没有红色报错。2. 启动前端 (网页界面)这一步让你能通过浏览器访问工具。现在打开浏览器访问前端终端里显示的那个地址通常是http://localhost:5173你应该就能看到 AutoHunter 的登录或主界面了 开始使用不要关闭上面的后端终端新开一个终端窗口。先进入前端文件夹cd frontend启动开发服务器npm run dev成功标志看到Local: http://localhost:5173/(端口号可能是 5173 或 3000)。✅ 你现在可以做的下一步操作点击顶栏「新建」按钮截图中右上角“任务”按钮旁边应该有个“”或“新建”入口我上面那个夜间模式的截图是还没认证的要在令牌输入一开始.env文件中设置的密码认证了才会显示若存在疑问可以往后翻有详细解决步骤尝试创建第一个漏洞挖掘任务。观察控制台按F12打开浏览器开发者工具 → 切换到Network网络标签页 → 点击“新建”或任何按钮时看是否有请求发送到http://127.0.0.1:8001。如果看到 200 状态码 → 前后端通信正常如果看到红色报错如 CORS、404、500→ 别慌往后翻我帮你定位问题。#问题原因解决1看不到「新建任务」按钮未认证authRoleRef ! full输入令牌登录2FOFA 报「不符合规范」FOFA 账号是注册用户无 API 配额0/0换用 Hunter 等其他免费引擎3API 请求 404Vite 代理端口写错8000且该端口上跑的是别的程序改用 18800 端口4API 请求 500后端跑在 8000Vite 代理指向 18800空端口统一端口为 18800测试后端接口打开http://127.0.0.1:8001/docs看看 FastAPI 自动生成的 Swagger 文档里有没有/tasks或/create之类的接口可以手动点“Try it out”测试一下。 小提醒若你右上角显示“未认证”说明系统可能有登录/权限机制。如果点击“新建”没反应或提示需要登录你可能需要先注册或登录一个账号看有没有“登录”或“注册”按钮。如果“新建”按钮点不动也可能是前端还没绑定事件或者后端接口还没写好——这时候就要看控制台报错了。第二种本地源码方式如何部署环境变量复制并编辑 .env 文件听起来很专业其实操作非常简单。你可以把它理解为给软件填写“账号密码”和“设置”的过程。因为项目作者不能把他的私人密钥公开所以他提供了一个模板文件.env.example。你需要把这个模板复制一份改个名字然后填入你自己的信息程序才能跑起来。以下是针对 Windows 和 Mac 用户的“保姆级”操作教程第一步找到文件在你克隆下来的AutoHunter文件夹里你会看到两个长得很像的文件.env.example这是模板不要直接改它.gitignore等其它文件第二步复制并重命名二选一方法 A使用命令行最快推荐如果你已经打开了终端Terminal / CMD / PowerShell并且停留在项目目录下直接运行这一行命令Windows (PowerShell):copy .env.example .envMac / Linux:cp .env.example .env运行完后文件夹里会多出一个叫.env的新文件。方法 B手动操作鼠标流在文件夹里右键点击.env.example。选择“复制”。在空白处右键“粘贴”。把新生成的文件重命名为.env注意Windows 可能会提示你“如果改变文件扩展名可能会导致文件不可用”点击是如果看不见.example后缀请确保文件名就是.env而不是.env.txt。第三步编辑内容填空打开文件右键点击刚才生成的.env文件选择用记事本Windows或文本编辑Mac打开。推荐用 VS Code 打开会有颜色高亮看着不累。填写信息你会看到类似下面的内容怎么填这个.env文件虽然看起来很长但其实你只需要关注最前面的几个核心配置后面的大部分参数保持默认即可。根据文件开头的注释提示我为你整理了“三步极简配置法”第一步配置 AI 大模型必填这是整个系统的大脑不填这个程序无法运行。找到文件开头的【必填】AI / LLM 通道区域默认已经帮你选好了 DeepSeek你只需要填入你的 API Key我是用的阿里云的api操作步骤网站上写的很详细了我就不多说了 提示如果你没有 Key可以去 DeepSeek 开放平台注册获取。如果你用的是其他模型如通义、Kimi请修改对应的 BASE_URL 和 MODEL。第二步配置 FOFA 测绘 Key强烈推荐这个工具是用来自动搜集目标资产的如果不填你只能手动录入目标会失去很多自动化功能。找到【推荐】FOFA 网络空间测绘 Key区域# 【在这里填入你的 FOFA Key】 FOFA_KEY你的FOFA_Key 下面的保持留空即可 FOFA_BASE_URL FOFA_ALLOWED_HOSTS 提示去 FOFA 官网 (fofa.info) 登录个人中心或者直接访问网络空间测绘网络空间安全搜索引擎网络空间搜索引擎安全态势感知 - FOFA网络空间测绘系统复制你的 API Key 填进去。第三步配置访问控制令牌保护你的控制台为了防止别人偷偷访问你的本地服务强烈建议设置一个访问密码。找到【强烈建议】访问控制令牌区域# 【在这里填入一个足够长的随机字符串作为密码】 AUTOHUNTER_API_TOKENMySuperSecretPassword123! 下面两个只读和观摩权限本地自己用可以留空 AUTOHUNTER_READ_TOKEN AUTOHUNTER_OBSERVER_TOKEN 剩下的需要改吗完全不需要文件里剩下的服务监听、内置应用层 WAF、Worker 挖掘预算、并发与线程池等几百行参数作者已经为你调好了默认值直接保持原样千万不要去动它们。第四步保存填好后直接按Ctrl S(Windows) 或Command S(Mac) 保存然后关掉文件。确保文件名是.env不要变成.env.txt。确认无误后你就可以回到上面打开终端执行python manage.py migrate开始启动啦初始化数据库常见问题问题1这个错误是因为 Alembic 找不到迁移脚本的配置路径通常发生在项目结构不完整或配置文件缺失时。1. 检查项目根目录是否存在alembic.ini文件打开你的 AutoHunter 项目文件夹就是E:\desktop\AutoHunter。确认根目录下有一个名为alembic.ini的文件。如果没有说明项目初始化不完整需要从源码重新拉取或手动创建。2. 检查alembic文件夹是否存在在根目录下应该有一个名为alembic的文件夹注意不是alembic.ini。这个文件夹里必须包含env.py和versions/子文件夹。如果缺少说明迁移环境未初始化。✅ 修复方法如果上述文件缺失你需要重新初始化 Alembic 环境# 在项目根目录执行 alembic init alembic这会创建alembic.ini和alembic/文件夹。然后再次运行alembic upgrade head⚠️ 特别注意不要手动删除alembic文件夹它包含数据库版本历史删了会导致数据丢失。如果项目是克隆的 Git 仓库检查.gitignore是否误忽略了alembic/versions/导致迁移文件未下载。Windows 路径问题确保项目路径中没有中文或特殊字符如E:\desktop\AutoHunter是安全的但E:\桌面\AutoHunter可能出问题。完成以上步骤后数据库初始化就能正常进行了。问题2这个错误是因为 Alembic 在尝试连接数据库时找不到你配置的数据库驱动dialect。从报错sqlalchemy.exc.NoSuchModuleError: Cant load plugin: sqlalchemy.dialects:driver来看问题出在alembic.ini文件里的数据库连接字符串配置不正确。按上述步骤还是报错问题原因Alembic 依赖 SQLAlchemy 来连接数据库。SQLAlchemy 需要知道你要连的是什么数据库比如 SQLite、MySQL、PostgreSQL以及用什么驱动去连。你的配置里写的是driver这不是一个真实的数据库类型所以 SQLAlchemy 找不到对应的“方言包”来翻译指令。解决方法你需要打开项目根目录下的alembic.ini文件找到sqlalchemy.url这一行把它改成正确的数据库连接地址。如果你用的是 SQLite推荐新手使用若不知道自己用的是什么那大概率就是这个这是最简单的方案不需要安装额外的数据库软件。把sqlalchemy.url改成sqlalchemy.url sqlite:///./app.db这会在你当前目录下创建一个名为app.db的 SQLite 数据库文件。如果你用的是 MySQL你需要先安装 MySQL 驱动pip install pymysql然后把sqlalchemy.url改成sqlalchemy.url mysqlpymysql://用户名:密码localhost:3306/数据库名如果你用的是 PostgreSQL你需要先安装 PostgreSQL 驱动pip install psycopg2-binary然后把sqlalchemy.url改成sqlalchemy.url postgresqlpsycopg2://用户名:密码localhost:5432/数据库名修改后再次执行保存alembic.ini文件后回到终端重新运行alembic upgrade head如果配置正确这次就不会报错了数据库表结构会自动创建成功。启动服务常见问题后端问题1这个错误Could not import module main意思是Uvicorn 在当前目录下找不到名为main.py的文件。这通常是因为你运行命令的目录不对或者项目的主入口文件名字不叫main.py。请按以下步骤排查确认主入口文件名打开你的项目文件夹E:\desktop\AutoHunter。仔细看一眼根目录下的文件列表。找找看有没有叫main.py的文件如果没有找找有没有叫app.py、server.py或者run.py的文件如果有把启动命令里的main换成那个文件名例如uvicorn app:app --reload。如果有请继续看下一步。确认当前终端路径虽然你的截图显示路径是E:\desktop\AutoHunter但有时候终端的“视觉路径”和“实际工作目录”不一致。请在当前终端输入以下命令并回车强制刷新一下路径cd E:\desktop\AutoHunter然后再重新运行启动命令uvicorn main:app --reload检查文件是否被隐藏或后缀名错误有时候 Windows 会隐藏已知文件类型的扩展名。你可能看到了一个叫main的文件但它实际可能是main.txt或者main.py.txt。解决方法在文件夹上方的菜单栏点击“查看”勾选“文件扩展名”确保那个文件确实叫main.py。若找不到.py文件如图所示根目录下确实没有main.py但是有一个app文件夹。最后发现在app文件夹里有现在请回到你的终端PowerShell输入下面这个绝对正确的命令uvicorn app.main:app --reload 命令解析app(第一个)代表项目根目录下的app文件夹。main代表文件夹里的main.py文件。:app(第二个)代表代码里定义的那个 FastAPI 实例变量名通常都叫 app。执行后观察如果看到绿色的Uvicorn running on http://127.0.0.1:8000就说明后端启动成功了后端问题2若还是报错端口被占用和模块导入路径错误。 第一步解决 WinError 10013端口被占这个错误以一种访问权限不允许的方式做了一个访问套接字的尝试99% 的情况是因为8000 端口被其他程序占用了比如之前的 Uvicorn 进程没关干净或者微信、其他开发工具占了。✅ 解决方法换一个端口启动在终端里输入以下命令把端口从 8000 改成 8001uvicorn app.main:app --reload --port 8001如果 8001 也被占了就换 8002、8080 等直到成功为止。️ 进阶找出并杀掉占用端口的进程可选如果你想彻底解决可以查一下谁占了 8000 端口netstat -ano | findstr :8000你会看到一个 PID比如 12345然后用任务管理器或命令杀掉它taskkill /PID 12345 /F 第二步解决 Attribute app not found模块导入错误这个错误Error loading ASGI app. Attribute app not found in module app说明你运行的命令uvicorn app:app --reload是错的——它试图把整个app文件夹当作一个模块但里面没有直接定义一个叫app的变量。✅ 正确命令再次强调你必须指定到具体的文件uvicorn app.main:app --reloadapp.main→ 进入app文件夹找到main.py:app→ 在main.py里找那个叫app的 FastAPI 实例 最终推荐启动命令一步到位结合上面两点最稳妥的启动方式是uvicorn app.main:app --reload --port 8001执行后如果看到绿色的Uvicorn running on http://127.0.0.1:8001就说明后端成功了认证令牌常见问题问题一看不到「新建任务」和「设置」按钮现象页面显示「还没有任务」顶部导航栏没有「新建」按钮。根本原因前端有访问控制App.vue:175-178代码中写了router-link v-ifauthRoleRef full to/create ... span新建/span /router-link只有当用户的认证角色为full时这两个按钮才会渲染。没有令牌 未认证 角色为null 按钮被隐藏。解决在顶部导航栏点击「令牌」按钮输入 .env文件自己设置的密码即可。问题二FOFA 报「不符合规范」现象在任务中使用 FOFA 引擎搜索时返回错误提示。根本原因FOFA 账号类型为「注册用户」免费账号API 配额为0/0。FOFA 当前政策是注册账号仅能通过 Web 界面使用API 接口需要付费会员或单独购买 API 点数。截图显示身份权限: 注册用户 API查询次数余额: 0/0 API数据返回额度: 0/0这不是账号密码错误是账号类型本身就没有 API 调用权限。解决改用其他免费有 API 的引擎。已在.env第 65 行配置了 Hunter奇安信的 KeyHUNTER_KEYff.。。。。自己的API。创建任务时把引擎选为「Hunter」即可。问题三修改.env后令牌仍然无效现象修改了AUTOHUNTER_API_TOKEN为。。。.env文件自己设置的的密码前端输入后提示令牌无效。根本原因有两个叠加问题后端进程在启动时通过app/config.py:10-24的_load_dotenv()加载.env文件到os.environ之后每次令牌校验app/security.py:48-49都是从内存的环境变量读取。修改文件后必须重启后端进程才能生效光刷新浏览器没用。浏览器本地还缓存了旧令牌之前访问过的令牌被存储在localStorage和cookie (ah_api_token)中每次请求都会自动带上旧令牌导致即使.env正确请求中发出去的还是旧令牌。解决后端重启 浏览器清缓存localStorage.clear() 删除 cookie。问题四API 请求返回 404{detail:Not Found}现象所有/api/*请求/api/auth/status、/api/tasks、/api/settings等均返回 404。根本原因vite.config.js:13中 Vite 代理配置的端口写错了/api: { target: http://localhost:8000, ... }端口 8000 上运行的不是 AutoHunter 后端而是一个Acunetix 漏洞扫描系统。访问http://localhost:8000/docs可以看到那是一个完全不同的 Swagger 文档路由是/api/v1/configuration、/api/v1/plugins等。所以 Vite 把前端请求转发到了 Acunetix 的后端Acunetix 不认识 AutoHunter 的/api/auth/status等路由返回 404。解决将 Vite 代理端口改为 AutoHunter 实际运行的端口18800。但最初改好后又出现了问题五。问题五API 请求返回 500Internal Server Error现象把 Vite 代理改到 18800 后请求返回空的 500 错误响应体为空Content-Type 为text/plain。根本原因之前为了修复问题四临时把 Vite 代理从 8000 改成了 18800但后端仍然跑在 8000 端口uvicorn app.main:app --reload --port 8000。所以请求被转发到了 18800 端口而那个端口上没有任何服务在监听 → 空连接 → 500 错误。解决将后端也改为 18800 端口启动uvicorn app.main:app --reload --port 18800同时 Vite 代理保持 18800。前后端端口统一后问题消失。若F12之后点击「响应」标签在「标题」旁边里面的内容错误堆栈是空的说明后端在返回响应之前就崩溃了。这不是令牌问题是后端本身的问题。1. 确认后端是否在运行curl -s http://localhost:18800/health或在powershel里curl.exe -s http://localhost:18800/health如果返回{ok: true}— 后端在跑如果连接失败 — 后端根本没启动也在浏览器里测试一下访问http://localhost:8000/docsFastAPI 自带的 Swagger 文档看看能不能打开。这样能确认后端是否真的正常启动了。若浏览器访问显示则localhost:8000上跑的根本不是 AutoHunter 的后端而是另一个 Acunetix 漏洞扫描系统的后端看/docs里的路由/api/v1/configuration、/api/v1/plugins这些。所以你现在有两个选择方案一让 AutoHunter 跑在别的端口推荐在 AutoHunter 后端的终端里先按CtrlC停掉当前的 uvicorn然后用一个不同的端口重新启动cd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800然后把 Vite 代理也改成 18800但这样你就需要停掉现在跑在 8000 端口的东西。你可以先看看netstat -ano | findstr :8000然后把 Vite 代理改回 8000确保前端代理到正确的后端。第一步停掉当前后端改用 18800 端口启动在后端终端跑uvicorn的那个按CtrlC停掉然后执行cd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800第二步重启 Vite 前端在前端终端跑npm run dev的那个按CtrlC停掉然后执行cd e:\desktop\AutoHunter\frontend npm run dev第三步验证后端在浏览器访问http://localhost:18800/docs应该能看到 AutoHunter 的 Swagger 文档而不是之前的 Acunetix。第四步清除浏览器缓存并登录在浏览器控制台执行localStorage.clear(); document.cookie ah_api_token; expiresThu, 01 Jan 1970 00:00:00 GMT; path/; location.reload();然后在令牌输入框粘贴之前.env文件你自己填入的密码再检查一下后端运行情况同时请在另一个终端执行curl.exe -s http://localhost:18800/health显示这样就是没问题啦再重新启动一下服务浏览器刷新一下功能都完整就可以开始漏洞扫描啦 常见问题避坑指南我看不到.env.example文件有些系统会隐藏以.开头的文件。请在文件夹上方点击“查看”勾选“隐藏的项目”。保存后变成了.env.txt这是 Windows 新手的经典坑。记事本默认会加个.txt后缀。你需要开启Windows的“显示文件扩展名”功能把后面的.txt删掉确保它就叫.env。Key 从哪里来这个项目主要依赖FOFA网络空间测绘和LLM大模型如 ChatGPT/DeepSeek。你需要去 FOFA 官网注册获取 Key以及去大模型服务商后台获取 API Key填进去才能工作。注意事项API Key 安全切勿将真实密钥提交到 Git.env文件应加入.gitignore。端口冲突若 8000 端口被占用可在.env或启动命令中修改。日志与调试查看容器日志docker logs autohunter或本地运行时观察终端输出。更新代码定期git pull获取最新修复和功能。 每日启动标准流程以后每次启动这个项目你都需要同时运行两个服务后端和前端。为了让你操作更熟练我把标准流程整理成了“傻瓜式”步骤。建议你在桌面上建个记事本或者直接记住下面这套连招你需要打开两个终端窗口或者在 VS Code 里 split 两个终端。终端 1启动后端 (Python)打开终端确保在项目根目录AutoHunter下。输入启动命令记得带上端口号因为你之前 8000 被占用了uvicorn app.main:app --reload --port 8001注如果下次 8001 没被占用也可以试着去掉--port 8001直接用默认的 8000。终端 2启动前端 (Node.js)打开一个新的终端窗口。进入前端文件夹cd frontend启动开发服务器npm run dev(如果这个报错试一下npm run serve) 几个让开发更爽的小技巧关于“不用每次都输命令”后端如果你用的是 VS Code可以配置.vscode/launch.json按 F5 就能直接启动后端不用手敲命令。前端同理VS Code 也可以配置一键启动前端。关于“端口被占用”的终极解决如果你不想每次都加--port 8001可以在每次关闭程序时确保在终端里按Ctrl C彻底停止服务而不是直接叉掉窗口。这样端口通常会立即释放。关于“依赖安装”不需要每次都运行pip install -r requirements.txt(后端) 或npm install(前端)。只有当你更新了代码库git pull或者换了电脑时才需要重新安装依赖。平时直接启动即可。我下次打开的步骤每个人可能有区别需要启动3 个服务第一步启动后端端口 18800打开一个终端PowerShellcd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800第二步启动前端端口 5173再开一个终端PowerShellcd e:\desktop\AutoHunter\frontend npm run dev第三步访问并登录浏览器打开http://localhost:5173点击顶部「令牌」按钮输入.env文件中自己设置的注意事项顺序无所谓两个终端都启动好就行不要关终端关了对应服务就停了如果之前那个 Acunetix 服务占着 8000 端口不用管AutoHunter 用的是 18800不冲突FOFA 没 API 配额创建任务时用Hunter引擎已在.env配置了 Key
前言欢迎来到 AutoHunter 部署与使用指南本文旨在为安全研究人员和开发者提供一份详尽的 AutoHunter 系统部署手册。AutoHunter 是一个自动化 SRC 漏洞挖掘系统集成了 FOFA 资产测绘与 LLM 多 worker 自主挖掘/审核/情报沉淀功能能够显著提升漏洞挖掘效率。无论你是安全新手还是经验丰富的渗透测试人员本指南都将帮助你快速搭建并运行 AutoHunter 系统。我们将从最基础的 Docker 部署开始逐步深入到本地源码部署、环境变量配置、常见问题排查等各个环节确保你能够顺利启动并使用这个强大的自动化工具。在开始之前请确保你已经准备好以下资源一个可用的 FOFA 账号或 Hunter 等其他网络空间测绘引擎的 API KeyAI 大模型的 API Key如 DeepSeek、通义千问等基本的命令行操作知识Python 3.9 和 Node.js 16 环境如果选择本地源码部署让我们开始吧下载资源GitHub - StanleyNull/AutoHunter: 自动化 SRC 漏洞挖掘系统FOFA 资产测绘 LLM 多 worker 自主挖掘/审核/情报沉淀。Powered By StanleyNull · GitHub如何部署要将AutoHunter部署到本地电脑推荐优先使用Docker 方式最省心环境隔离好其次是本地源码运行。以下是具体步骤一、Docker 部署推荐项目根目录包含Dockerfile说明支持容器化部署这是最简单的方式。安装 Docker DesktopWindows/Mac前往官网下载并安装 Docker Desktop。Linux使用包管理器安装docker.io和docker-compose。克隆项目代码git clone https://github.com/StanleyNull/AutoHunter.git cd AutoHunter配置环境变量复制.env.example为.envcp .env.example .env编辑.env文件填入你的 API Key、数据库地址、FOFA Token 等必要配置。构建并启动容器docker compose up --build -d若无docker-compose.yml可手动构建镜像并运行docker build -t autohunter . docker run -d --name autohunter -p 8000:8000 --env-file .env autohunter访问服务前端页面http://localhost:8000端口根据实际配置调整后端 API通常在http://localhost:8000/api或类似路径二、本地源码部署适合开发者调试安装依赖环境Python ≥ 3.9项目语言占比76%Node.js ≥ 16前端 Vue 项目PostgreSQL / MySQL根据.env配置选择数据库克隆并进入项目git clone https://github.com/StanleyNull/AutoHunter.git cd AutoHunter安装 Python 依赖pip install -r requirements.txt安装前端依赖并构建cd frontend npm install npm run build cd ..配置环境变量同 Docker 部署步骤复制并编辑.env文件。这步不清楚的可以看翻到后面我写了两种方法初始化数据库解释这条命令会自动检测数据库变化并更新表结构。如果看到类似 INFO [alembic.runtime.migration] Context impl SQLiteImpl 或 Running upgrade 的字样且没有报错就说明成功了。若有报错可往后翻有详细解决办法python manage.py migrate # Django 项目 # 或 alembic upgrade head # Flask SQLAlchemy 项目启动服务AutoHunter 是前后端分离的架构你需要分别启动后端和前端。请打开两个终端窗口或者在一个终端里分步操作1. 启动后端 (核心服务)这一步负责调用 AI 和 FOFA 接口。若报错往后翻有详细解决方法确保终端路径在E:\desktop\AutoHunter(项目根目录)。输入以下命令并回车uvicorn main:app --reload成功标志看到类似Uvicorn running on http://127.0.0.1:8000的绿色字样且没有红色报错。2. 启动前端 (网页界面)这一步让你能通过浏览器访问工具。现在打开浏览器访问前端终端里显示的那个地址通常是http://localhost:5173你应该就能看到 AutoHunter 的登录或主界面了 开始使用不要关闭上面的后端终端新开一个终端窗口。先进入前端文件夹cd frontend启动开发服务器npm run dev成功标志看到Local: http://localhost:5173/(端口号可能是 5173 或 3000)。✅ 你现在可以做的下一步操作点击顶栏「新建」按钮截图中右上角“任务”按钮旁边应该有个“”或“新建”入口我上面那个夜间模式的截图是还没认证的要在令牌输入一开始.env文件中设置的密码认证了才会显示若存在疑问可以往后翻有详细解决步骤尝试创建第一个漏洞挖掘任务。观察控制台按F12打开浏览器开发者工具 → 切换到Network网络标签页 → 点击“新建”或任何按钮时看是否有请求发送到http://127.0.0.1:8001。如果看到 200 状态码 → 前后端通信正常如果看到红色报错如 CORS、404、500→ 别慌往后翻我帮你定位问题。#问题原因解决1看不到「新建任务」按钮未认证authRoleRef ! full输入令牌登录2FOFA 报「不符合规范」FOFA 账号是注册用户无 API 配额0/0换用 Hunter 等其他免费引擎3API 请求 404Vite 代理端口写错8000且该端口上跑的是别的程序改用 18800 端口4API 请求 500后端跑在 8000Vite 代理指向 18800空端口统一端口为 18800测试后端接口打开http://127.0.0.1:8001/docs看看 FastAPI 自动生成的 Swagger 文档里有没有/tasks或/create之类的接口可以手动点“Try it out”测试一下。 小提醒若你右上角显示“未认证”说明系统可能有登录/权限机制。如果点击“新建”没反应或提示需要登录你可能需要先注册或登录一个账号看有没有“登录”或“注册”按钮。如果“新建”按钮点不动也可能是前端还没绑定事件或者后端接口还没写好——这时候就要看控制台报错了。第二种本地源码方式如何部署环境变量复制并编辑 .env 文件听起来很专业其实操作非常简单。你可以把它理解为给软件填写“账号密码”和“设置”的过程。因为项目作者不能把他的私人密钥公开所以他提供了一个模板文件.env.example。你需要把这个模板复制一份改个名字然后填入你自己的信息程序才能跑起来。以下是针对 Windows 和 Mac 用户的“保姆级”操作教程第一步找到文件在你克隆下来的AutoHunter文件夹里你会看到两个长得很像的文件.env.example这是模板不要直接改它.gitignore等其它文件第二步复制并重命名二选一方法 A使用命令行最快推荐如果你已经打开了终端Terminal / CMD / PowerShell并且停留在项目目录下直接运行这一行命令Windows (PowerShell):copy .env.example .envMac / Linux:cp .env.example .env运行完后文件夹里会多出一个叫.env的新文件。方法 B手动操作鼠标流在文件夹里右键点击.env.example。选择“复制”。在空白处右键“粘贴”。把新生成的文件重命名为.env注意Windows 可能会提示你“如果改变文件扩展名可能会导致文件不可用”点击是如果看不见.example后缀请确保文件名就是.env而不是.env.txt。第三步编辑内容填空打开文件右键点击刚才生成的.env文件选择用记事本Windows或文本编辑Mac打开。推荐用 VS Code 打开会有颜色高亮看着不累。填写信息你会看到类似下面的内容怎么填这个.env文件虽然看起来很长但其实你只需要关注最前面的几个核心配置后面的大部分参数保持默认即可。根据文件开头的注释提示我为你整理了“三步极简配置法”第一步配置 AI 大模型必填这是整个系统的大脑不填这个程序无法运行。找到文件开头的【必填】AI / LLM 通道区域默认已经帮你选好了 DeepSeek你只需要填入你的 API Key我是用的阿里云的api操作步骤网站上写的很详细了我就不多说了 提示如果你没有 Key可以去 DeepSeek 开放平台注册获取。如果你用的是其他模型如通义、Kimi请修改对应的 BASE_URL 和 MODEL。第二步配置 FOFA 测绘 Key强烈推荐这个工具是用来自动搜集目标资产的如果不填你只能手动录入目标会失去很多自动化功能。找到【推荐】FOFA 网络空间测绘 Key区域# 【在这里填入你的 FOFA Key】 FOFA_KEY你的FOFA_Key 下面的保持留空即可 FOFA_BASE_URL FOFA_ALLOWED_HOSTS 提示去 FOFA 官网 (fofa.info) 登录个人中心或者直接访问网络空间测绘网络空间安全搜索引擎网络空间搜索引擎安全态势感知 - FOFA网络空间测绘系统复制你的 API Key 填进去。第三步配置访问控制令牌保护你的控制台为了防止别人偷偷访问你的本地服务强烈建议设置一个访问密码。找到【强烈建议】访问控制令牌区域# 【在这里填入一个足够长的随机字符串作为密码】 AUTOHUNTER_API_TOKENMySuperSecretPassword123! 下面两个只读和观摩权限本地自己用可以留空 AUTOHUNTER_READ_TOKEN AUTOHUNTER_OBSERVER_TOKEN 剩下的需要改吗完全不需要文件里剩下的服务监听、内置应用层 WAF、Worker 挖掘预算、并发与线程池等几百行参数作者已经为你调好了默认值直接保持原样千万不要去动它们。第四步保存填好后直接按Ctrl S(Windows) 或Command S(Mac) 保存然后关掉文件。确保文件名是.env不要变成.env.txt。确认无误后你就可以回到上面打开终端执行python manage.py migrate开始启动啦初始化数据库常见问题问题1这个错误是因为 Alembic 找不到迁移脚本的配置路径通常发生在项目结构不完整或配置文件缺失时。1. 检查项目根目录是否存在alembic.ini文件打开你的 AutoHunter 项目文件夹就是E:\desktop\AutoHunter。确认根目录下有一个名为alembic.ini的文件。如果没有说明项目初始化不完整需要从源码重新拉取或手动创建。2. 检查alembic文件夹是否存在在根目录下应该有一个名为alembic的文件夹注意不是alembic.ini。这个文件夹里必须包含env.py和versions/子文件夹。如果缺少说明迁移环境未初始化。✅ 修复方法如果上述文件缺失你需要重新初始化 Alembic 环境# 在项目根目录执行 alembic init alembic这会创建alembic.ini和alembic/文件夹。然后再次运行alembic upgrade head⚠️ 特别注意不要手动删除alembic文件夹它包含数据库版本历史删了会导致数据丢失。如果项目是克隆的 Git 仓库检查.gitignore是否误忽略了alembic/versions/导致迁移文件未下载。Windows 路径问题确保项目路径中没有中文或特殊字符如E:\desktop\AutoHunter是安全的但E:\桌面\AutoHunter可能出问题。完成以上步骤后数据库初始化就能正常进行了。问题2这个错误是因为 Alembic 在尝试连接数据库时找不到你配置的数据库驱动dialect。从报错sqlalchemy.exc.NoSuchModuleError: Cant load plugin: sqlalchemy.dialects:driver来看问题出在alembic.ini文件里的数据库连接字符串配置不正确。按上述步骤还是报错问题原因Alembic 依赖 SQLAlchemy 来连接数据库。SQLAlchemy 需要知道你要连的是什么数据库比如 SQLite、MySQL、PostgreSQL以及用什么驱动去连。你的配置里写的是driver这不是一个真实的数据库类型所以 SQLAlchemy 找不到对应的“方言包”来翻译指令。解决方法你需要打开项目根目录下的alembic.ini文件找到sqlalchemy.url这一行把它改成正确的数据库连接地址。如果你用的是 SQLite推荐新手使用若不知道自己用的是什么那大概率就是这个这是最简单的方案不需要安装额外的数据库软件。把sqlalchemy.url改成sqlalchemy.url sqlite:///./app.db这会在你当前目录下创建一个名为app.db的 SQLite 数据库文件。如果你用的是 MySQL你需要先安装 MySQL 驱动pip install pymysql然后把sqlalchemy.url改成sqlalchemy.url mysqlpymysql://用户名:密码localhost:3306/数据库名如果你用的是 PostgreSQL你需要先安装 PostgreSQL 驱动pip install psycopg2-binary然后把sqlalchemy.url改成sqlalchemy.url postgresqlpsycopg2://用户名:密码localhost:5432/数据库名修改后再次执行保存alembic.ini文件后回到终端重新运行alembic upgrade head如果配置正确这次就不会报错了数据库表结构会自动创建成功。启动服务常见问题后端问题1这个错误Could not import module main意思是Uvicorn 在当前目录下找不到名为main.py的文件。这通常是因为你运行命令的目录不对或者项目的主入口文件名字不叫main.py。请按以下步骤排查确认主入口文件名打开你的项目文件夹E:\desktop\AutoHunter。仔细看一眼根目录下的文件列表。找找看有没有叫main.py的文件如果没有找找有没有叫app.py、server.py或者run.py的文件如果有把启动命令里的main换成那个文件名例如uvicorn app:app --reload。如果有请继续看下一步。确认当前终端路径虽然你的截图显示路径是E:\desktop\AutoHunter但有时候终端的“视觉路径”和“实际工作目录”不一致。请在当前终端输入以下命令并回车强制刷新一下路径cd E:\desktop\AutoHunter然后再重新运行启动命令uvicorn main:app --reload检查文件是否被隐藏或后缀名错误有时候 Windows 会隐藏已知文件类型的扩展名。你可能看到了一个叫main的文件但它实际可能是main.txt或者main.py.txt。解决方法在文件夹上方的菜单栏点击“查看”勾选“文件扩展名”确保那个文件确实叫main.py。若找不到.py文件如图所示根目录下确实没有main.py但是有一个app文件夹。最后发现在app文件夹里有现在请回到你的终端PowerShell输入下面这个绝对正确的命令uvicorn app.main:app --reload 命令解析app(第一个)代表项目根目录下的app文件夹。main代表文件夹里的main.py文件。:app(第二个)代表代码里定义的那个 FastAPI 实例变量名通常都叫 app。执行后观察如果看到绿色的Uvicorn running on http://127.0.0.1:8000就说明后端启动成功了后端问题2若还是报错端口被占用和模块导入路径错误。 第一步解决 WinError 10013端口被占这个错误以一种访问权限不允许的方式做了一个访问套接字的尝试99% 的情况是因为8000 端口被其他程序占用了比如之前的 Uvicorn 进程没关干净或者微信、其他开发工具占了。✅ 解决方法换一个端口启动在终端里输入以下命令把端口从 8000 改成 8001uvicorn app.main:app --reload --port 8001如果 8001 也被占了就换 8002、8080 等直到成功为止。️ 进阶找出并杀掉占用端口的进程可选如果你想彻底解决可以查一下谁占了 8000 端口netstat -ano | findstr :8000你会看到一个 PID比如 12345然后用任务管理器或命令杀掉它taskkill /PID 12345 /F 第二步解决 Attribute app not found模块导入错误这个错误Error loading ASGI app. Attribute app not found in module app说明你运行的命令uvicorn app:app --reload是错的——它试图把整个app文件夹当作一个模块但里面没有直接定义一个叫app的变量。✅ 正确命令再次强调你必须指定到具体的文件uvicorn app.main:app --reloadapp.main→ 进入app文件夹找到main.py:app→ 在main.py里找那个叫app的 FastAPI 实例 最终推荐启动命令一步到位结合上面两点最稳妥的启动方式是uvicorn app.main:app --reload --port 8001执行后如果看到绿色的Uvicorn running on http://127.0.0.1:8001就说明后端成功了认证令牌常见问题问题一看不到「新建任务」和「设置」按钮现象页面显示「还没有任务」顶部导航栏没有「新建」按钮。根本原因前端有访问控制App.vue:175-178代码中写了router-link v-ifauthRoleRef full to/create ... span新建/span /router-link只有当用户的认证角色为full时这两个按钮才会渲染。没有令牌 未认证 角色为null 按钮被隐藏。解决在顶部导航栏点击「令牌」按钮输入 .env文件自己设置的密码即可。问题二FOFA 报「不符合规范」现象在任务中使用 FOFA 引擎搜索时返回错误提示。根本原因FOFA 账号类型为「注册用户」免费账号API 配额为0/0。FOFA 当前政策是注册账号仅能通过 Web 界面使用API 接口需要付费会员或单独购买 API 点数。截图显示身份权限: 注册用户 API查询次数余额: 0/0 API数据返回额度: 0/0这不是账号密码错误是账号类型本身就没有 API 调用权限。解决改用其他免费有 API 的引擎。已在.env第 65 行配置了 Hunter奇安信的 KeyHUNTER_KEYff.。。。。自己的API。创建任务时把引擎选为「Hunter」即可。问题三修改.env后令牌仍然无效现象修改了AUTOHUNTER_API_TOKEN为。。。.env文件自己设置的的密码前端输入后提示令牌无效。根本原因有两个叠加问题后端进程在启动时通过app/config.py:10-24的_load_dotenv()加载.env文件到os.environ之后每次令牌校验app/security.py:48-49都是从内存的环境变量读取。修改文件后必须重启后端进程才能生效光刷新浏览器没用。浏览器本地还缓存了旧令牌之前访问过的令牌被存储在localStorage和cookie (ah_api_token)中每次请求都会自动带上旧令牌导致即使.env正确请求中发出去的还是旧令牌。解决后端重启 浏览器清缓存localStorage.clear() 删除 cookie。问题四API 请求返回 404{detail:Not Found}现象所有/api/*请求/api/auth/status、/api/tasks、/api/settings等均返回 404。根本原因vite.config.js:13中 Vite 代理配置的端口写错了/api: { target: http://localhost:8000, ... }端口 8000 上运行的不是 AutoHunter 后端而是一个Acunetix 漏洞扫描系统。访问http://localhost:8000/docs可以看到那是一个完全不同的 Swagger 文档路由是/api/v1/configuration、/api/v1/plugins等。所以 Vite 把前端请求转发到了 Acunetix 的后端Acunetix 不认识 AutoHunter 的/api/auth/status等路由返回 404。解决将 Vite 代理端口改为 AutoHunter 实际运行的端口18800。但最初改好后又出现了问题五。问题五API 请求返回 500Internal Server Error现象把 Vite 代理改到 18800 后请求返回空的 500 错误响应体为空Content-Type 为text/plain。根本原因之前为了修复问题四临时把 Vite 代理从 8000 改成了 18800但后端仍然跑在 8000 端口uvicorn app.main:app --reload --port 8000。所以请求被转发到了 18800 端口而那个端口上没有任何服务在监听 → 空连接 → 500 错误。解决将后端也改为 18800 端口启动uvicorn app.main:app --reload --port 18800同时 Vite 代理保持 18800。前后端端口统一后问题消失。若F12之后点击「响应」标签在「标题」旁边里面的内容错误堆栈是空的说明后端在返回响应之前就崩溃了。这不是令牌问题是后端本身的问题。1. 确认后端是否在运行curl -s http://localhost:18800/health或在powershel里curl.exe -s http://localhost:18800/health如果返回{ok: true}— 后端在跑如果连接失败 — 后端根本没启动也在浏览器里测试一下访问http://localhost:8000/docsFastAPI 自带的 Swagger 文档看看能不能打开。这样能确认后端是否真的正常启动了。若浏览器访问显示则localhost:8000上跑的根本不是 AutoHunter 的后端而是另一个 Acunetix 漏洞扫描系统的后端看/docs里的路由/api/v1/configuration、/api/v1/plugins这些。所以你现在有两个选择方案一让 AutoHunter 跑在别的端口推荐在 AutoHunter 后端的终端里先按CtrlC停掉当前的 uvicorn然后用一个不同的端口重新启动cd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800然后把 Vite 代理也改成 18800但这样你就需要停掉现在跑在 8000 端口的东西。你可以先看看netstat -ano | findstr :8000然后把 Vite 代理改回 8000确保前端代理到正确的后端。第一步停掉当前后端改用 18800 端口启动在后端终端跑uvicorn的那个按CtrlC停掉然后执行cd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800第二步重启 Vite 前端在前端终端跑npm run dev的那个按CtrlC停掉然后执行cd e:\desktop\AutoHunter\frontend npm run dev第三步验证后端在浏览器访问http://localhost:18800/docs应该能看到 AutoHunter 的 Swagger 文档而不是之前的 Acunetix。第四步清除浏览器缓存并登录在浏览器控制台执行localStorage.clear(); document.cookie ah_api_token; expiresThu, 01 Jan 1970 00:00:00 GMT; path/; location.reload();然后在令牌输入框粘贴之前.env文件你自己填入的密码再检查一下后端运行情况同时请在另一个终端执行curl.exe -s http://localhost:18800/health显示这样就是没问题啦再重新启动一下服务浏览器刷新一下功能都完整就可以开始漏洞扫描啦 常见问题避坑指南我看不到.env.example文件有些系统会隐藏以.开头的文件。请在文件夹上方点击“查看”勾选“隐藏的项目”。保存后变成了.env.txt这是 Windows 新手的经典坑。记事本默认会加个.txt后缀。你需要开启Windows的“显示文件扩展名”功能把后面的.txt删掉确保它就叫.env。Key 从哪里来这个项目主要依赖FOFA网络空间测绘和LLM大模型如 ChatGPT/DeepSeek。你需要去 FOFA 官网注册获取 Key以及去大模型服务商后台获取 API Key填进去才能工作。注意事项API Key 安全切勿将真实密钥提交到 Git.env文件应加入.gitignore。端口冲突若 8000 端口被占用可在.env或启动命令中修改。日志与调试查看容器日志docker logs autohunter或本地运行时观察终端输出。更新代码定期git pull获取最新修复和功能。 每日启动标准流程以后每次启动这个项目你都需要同时运行两个服务后端和前端。为了让你操作更熟练我把标准流程整理成了“傻瓜式”步骤。建议你在桌面上建个记事本或者直接记住下面这套连招你需要打开两个终端窗口或者在 VS Code 里 split 两个终端。终端 1启动后端 (Python)打开终端确保在项目根目录AutoHunter下。输入启动命令记得带上端口号因为你之前 8000 被占用了uvicorn app.main:app --reload --port 8001注如果下次 8001 没被占用也可以试着去掉--port 8001直接用默认的 8000。终端 2启动前端 (Node.js)打开一个新的终端窗口。进入前端文件夹cd frontend启动开发服务器npm run dev(如果这个报错试一下npm run serve) 几个让开发更爽的小技巧关于“不用每次都输命令”后端如果你用的是 VS Code可以配置.vscode/launch.json按 F5 就能直接启动后端不用手敲命令。前端同理VS Code 也可以配置一键启动前端。关于“端口被占用”的终极解决如果你不想每次都加--port 8001可以在每次关闭程序时确保在终端里按Ctrl C彻底停止服务而不是直接叉掉窗口。这样端口通常会立即释放。关于“依赖安装”不需要每次都运行pip install -r requirements.txt(后端) 或npm install(前端)。只有当你更新了代码库git pull或者换了电脑时才需要重新安装依赖。平时直接启动即可。我下次打开的步骤每个人可能有区别需要启动3 个服务第一步启动后端端口 18800打开一个终端PowerShellcd e:\desktop\AutoHunter uvicorn app.main:app --reload --port 18800第二步启动前端端口 5173再开一个终端PowerShellcd e:\desktop\AutoHunter\frontend npm run dev第三步访问并登录浏览器打开http://localhost:5173点击顶部「令牌」按钮输入.env文件中自己设置的注意事项顺序无所谓两个终端都启动好就行不要关终端关了对应服务就停了如果之前那个 Acunetix 服务占着 8000 端口不用管AutoHunter 用的是 18800不冲突FOFA 没 API 配额创建任务时用Hunter引擎已在.env配置了 Key
