企业官网建设流程全解析

如何快速部署 Shannon：Windows、macOS、Linux 全平台 WSL2 与 Docker 网络配置避坑指南

【免费下载链接】shannonShannon is an AI pentester for web applications and APIs. It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production.项目地址: https://gitcode.com/GitHub_Trending/shan/shannon

Shannon 是一款开源的 AI 渗透测试工具（AI Pentester），它会自动分析你的 Web 应用与 API 源码，识别攻击向量，并真实执行漏洞利用来"证明"风险。本文带你完成 Shannon 在 Windows、macOS、Linux 三大平台的一键部署，重点讲透 WSL2 配置与 Docker 网络这两个最容易踩的坑，让你一次跑通第一次渗透扫描。

一、部署 Shannon 前：先备齐这 3 个条件

Shannon 采用 "CLI + Docker 容器" 的架构：命令行客户端负责调度，所有扫描任务都跑在一次性的 Docker 工作容器（worker）里。因此部署前先确认：

⚠️安全提醒：Shannon 会主动执行真实漏洞利用，请只对你自己拥有、或获得书面授权的目标环境（沙箱、staging、本地开发环境）运行，切勿指向生产系统。

二、Windows 部署：WSL2 是唯一正确姿势

Windows 平台官方只支持 WSL2，原生 Windows（包括 Git Bash）都不支持。这是新手最常卡住的地方，按下面三步走即可避坑。

1. 一键安装并切换到 WSL2

在 PowerShell（管理员）中执行：

wsl --install wsl --set-default-version 2

然后用wsl --list --verbose检查已安装的发行版。如果你的 Ubuntu 显示VERSION 1，需要手动升级：

wsl --set-version Ubuntu 2

2. 启用 Docker Desktop 的 WSL2 后端

安装 Docker Desktop for Windows 后，进入Settings > General，勾选Use the WSL 2 based engine。这一步没做的话，Docker 引擎版本过旧，Shannon 的容器编排会直接失败。

3. 一切命令都在 WSL 里跑

打开 Ubuntu 终端，而不是 PowerShell 或 Git Bash：

# 交互式向导配置 AI 密钥 npx @keygraph/shannon setup # 启动渗透测试 npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo

两个 Windows 专属小坑：

• Temporal Web UI 打不开：在 WSL 里执行ip addr拿到 WSL 的 IP，再用 Windows 浏览器访问http://<wsl-ip>:8233（而不是 localhost）。
• Windows Defender 误报：渗透报告里包含漏洞利用代码片段，可能被 Defender 标记为威胁。为 Shannon 目录添加排除项即可，详见 docs/platforms.md。

三、Linux 部署：原生 Docker 最简单

Linux 是体验最顺的平台，无需任何虚拟化中间层：

npx @keygraph/shannon setup npx @keygraph/shannon start -u https://your-app.com -r /path/to/repo

避坑要点：

• 如果docker命令提示权限不足，把你的用户加入 Docker 组或临时用sudo；
• 结果文件出现权限问题时，检查当前用户是否同时拥有 Docker socket 和 workspace 目录的写权限。

Shannon 的客户端在 apps/cli/src/docker.ts 中已经帮你处理了一个 Linux 细节：原生 Linux 没有内置的host.docker.internal，它会自动注入--add-host host.docker.internal:host-gateway，所以 Linux 上访问宿主机服务也不会踩坑。

四、macOS 部署：装好 Docker Desktop 即可

macOS 开箱即用，只需确保 Docker Desktop 在运行（菜单栏有鲸鱼图标），然后：

npx @keygraph/shannon setup npx @keygraph/shannon start -u https://your-app.com -r /path/to/repo

macOS 自带host.docker.internal解析，这是它相比 Linux 少一个坑的地方。

五、Docker 网络配置：Shannon 部署最核心的 3 个坑

这是本文的重点。Shannon 的 worker 容器和 Temporal 编排服务跑在独立的shannon-netDocker 网络里（定义见 docker-compose.yml），容器无法直接访问宿主机的localhost。

坑 1：容器访问不了你本机的应用

如果你在本地用localhost:3000跑着被测应用，直接把 URL 传给 Shannon 会连接失败。请统一改用host.docker.internal：

npx @keygraph/shannon start -u http://host.docker.internal:3000 -r /path/to/repo

坑 2：依赖自定义域名？Shannon 会帮你转发

如果你的本地开发栈在/etc/hosts里配置了自定义域名（比如myapp.local），Shannon 启动扫描时会自动把这些条目转发进 worker 容器（实现见 apps/cli/src/docker.ts），其中回环地址（127.x.x.x）会被自动改写为指向宿主机网关，无需手动配置。

不需要该行为时，设置环境变量即可关闭：

export SHANNON_FORWARD_HOSTS=false

坑 3：Temporal 端口与 Web UI

Shannon 启动时会自动拉起 Temporal 编排服务，端口映射已固定在 docker-compose.yml 中：7233（gRPC，仅本机回环）和8233（内置 Web UI）。扫描过程中可以随时用浏览器打开http://localhost:8233（Windows/WSL2 下用第二节的http://<wsl-ip>:8233）查看多智能体流水线状态：

六、验证部署成功：跑通第一次扫描

部署是否成功，用两条命令验证：

# 查看运行状态与进度 npx @keygraph/shannon status npx @keygraph/shannon logs <workspace>

看到 worker 容器出现在docker ps中、日志开始滚动，说明 WSL2/Docker 环境已全部就绪。完整流程会经历 Pre-Recon → Recon → 漏洞分析 → 利用验证 → 报告生成，一次全量扫描大约需要 1～1.5 小时，报告默认输出到~/.shannon/workspaces/（源码构建模式为./workspaces/），最终交付物是Security-Assessment-Report.md。

扫描结束后，用下面命令清理环境：

npx @keygraph/shannon stop # 停止扫描 npx @keygraph/shannon uninstall # 完整卸载（含编排服务）

七、避坑清单速查表

延伸阅读

• 平台与网络完整指南：docs/platforms.md
• CLI 命令与输出路径：docs/development.md
• AI 提供商与密钥配置：docs/ai-providers.md
• 工作区命名与断点续扫：docs/workspaces.md
• 安全使用规范：docs/safety.md
• 容器编排定义：docker-compose.yml
• Docker 调度与网络注入源码：apps/cli/src/docker.ts

按这份指南走完，你在任何一台 Windows、macOS 或 Linux 机器上都能顺利部署 Shannon，把 AI 渗透测试纳入日常的发布流程中。

【免费下载链接】shannonShannon is an AI pentester for web applications and APIs. It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production.项目地址: https://gitcode.com/GitHub_Trending/shan/shannon