STEP1. 概要流程 #

1. 启用 WSL 2 + 必要的 Windows 功能

2. 安装 Docker Desktop（WSL 2 后端）

3. 克隆 AgentSeek 仓库并准备 Python 虚拟环境 (venv)

4. 使用 Docker Compose 启动「前端 + Redis + SearxNG」

5. 手动确认 FastAPI 后端 → 使用 NSSM 将其设置为 Windows 服务

6. 将 BACKEND_URL 修改为 host.docker.internal:8000 以与前端联动

7. 重启测试 & 运维确认

STEP2. 前提环境检查 #

推荐: 所有操作均使用管理员权限的 PowerShell 可以避免权限错误。

STEP3. 启用 WSL 2 & Windows 功能 #

wsl --install -d Ubuntu          # 默认安装 22.04
# 如果出现错误: 请逐个执行以下命令
# dism /online /enable-feature ...
# wsl --update
# wsl --set-default-version 2

完成后重启 PC,使用 wsl -l -v 确认 Ubuntu 以 Version 2 运行。

STEP4. 安装 Docker Desktop #

winget install -e --id Docker.DockerDesktop

初次启动时的设置 #

• Use the WSL 2 based engine → 开启

• Add Docker CLI to the PATH → 开启

• Start Docker Desktop when you log in → 开启 (General 标签页)

任务托盘中的鲸鱼图标显示_绿色标记_并稳定即可。

STEP5. 获取源代码 & 配置 Python 虚拟环境 #

cd C:Dev               # 任意工作目录
git clone https://github.com/AgenticSeek/agenticSeek.git
cd agenticSeek
python -m venv .venv
..venvScriptsActivate.ps1
pip install -r requirements.txt

编辑 config.ini,指定 GPUStack 等后端 LLM 的端点:

[PROVIDER]
provider_name = gpustack
provider_server_address = http://<GPUStack_IP>:<port>/v1

[BROWSER]
headless_browser = True  ; 如需隐藏浏览器

STEP6. 使用 Docker Compose 启动前端 #

修改 docker-compose.yml 中的 frontend.environment,使其引用主机上的 FastAPI。

environment:
  - NODE_ENV=development
  - CHOKIDAR_USEPOLLING=true
  - BACKEND_URL=http://host.docker.internal:8000
  - VITE_BACKEND_URL=http://host.docker.internal:8000

# 应用配置
docker compose down
docker compose up -d --build   # 初次运行推荐使用 --build

检查状态:

docker compose ps

确认 frontend | Up、redis | Up、searxng | Up 即准备完成。

STEP7. FastAPI 后端的手动启动测试 #

cd C:AgentSeekagenticSeek
..venvScriptsActivate.ps1
python api.py --host 0.0.0.0 --port 8000

• 在浏览器中打开 http://localhost:8000/docs 即表示成功。

• 按 Ctrl + C 停止。

STEP8. 使用 NSSM 将后端服务化为 Windows 服务 #

8-1 下载 NSSM #

从 https://nssm.cc/download 下载并解压 nssm-2.24.zip:例如 C:Toolsnssmnssm.exe

8-2 注册服务(管理员 PowerShell) #

& "C:Toolsnssmnssm.exe" install AgentSeekBackend ^
  "C:AgentSeekagenticSeek.venvScriptspython.exe" ^
  "api.py --host 0.0.0.0 --port 8000" ^
  -d "C:AgentSeekagenticSeek"

附加设置 #

• I/O 选项卡

  • Output: C:AgentSeekagenticSeek.logsbackend.log

  • Error: C:AgentSeekagenticSeek.logsbackend-err.log

• Service 选项卡

  • Start type: Automatic (Delayed Start)

Start-Service AgentSeekBackend
Get-Service AgentSeekBackend   # Status: Running

STEP9. 运行验证 #

1. 浏览器 → http://localhost:3000 → 右上显示 Connected

2. Swagger UI → http://localhost:8000/docs 可以打开

3. 重启测试后①②仍能保持即表示自动启动设置完成

STEP10. 代理使用提示 #

• GUI 通过自动路由分配代理

• 指定特定代理

  • @FileAgent zip *.csv into files.zip

  • 也可使用 JSON 指令格式: @FileAgent {"action":"zip","pattern":"*.csv"}

• 需要 100% 固定时使用 CLI:

  python cli.py --agent FileAgent "zip *.csv"

STEP11. 故障排查速查表 #

STEP12. 参考链接 #

• Docker Desktop Documentation https://docs.docker.com/desktop/windows/

• NSSM – the Non‑Sucking Service Manager https://nssm.cc/

• AgentSeek GitHub (开发分支) https://github.com/AgenticSeek/agenticSeek

至此,在 Windows 11 上稳定运行 AgentSeek WebGUI 的设置步骤已全部完成。