Reel

用于网络钓鱼模拟和安全意识培训的框架，支持可配置工作流、活动管理以及可选凭据代理。

快速开始（运维用途）

1. 克隆仓库并 cd 进入目录。
2. 运行 ./deploy.sh — 假设你在 Ubuntu 上，该脚本会为你配置好所有前置依赖。
3. 运行 ./start.sh --preload-ml。这会启动服务器并预加载我们使用的 ML 模型。

你会获得 http://localhost:8000 上的管理后台 UI 和 http://localhost:1234 上的钓鱼服务器。默认登录：admin / admin123。首次登录后请修改密码。

通过 ssh 将 8000 端口转发到本地以访问管理面板。切勿将管理面板或 Flask 服务器（端口 1234）直接暴露到互联网。

deploy.sh 会在同一主机上安装 caddy 服务器，所有配置均假设你将使用 caddy 作为反向代理。你也可以不使用，但需自行承担风险。

start.sh 的可选参数：

• --with-caddy — 通过 Docker 启动 Caddy（仅限本地测试）。
• --preload-ml — 预下载钓鱼检测模型（约 1.3GB）；避免使用 Phishing Detector 插件时首次调用产生延迟。
• --reset-db — 重置数据库并重新初始化。
• --admin-only — 仅启动管理服务器（端口 8000）。
• --phishing-only — 仅启动钓鱼服务器（端口 1234）。
• --skip-init — 跳过数据库初始化。
• --skip-setup — 跳过 venv/依赖安装；仅加载 .env 并启动服务器。

如果不使用 start.sh，在安装依赖并初始化数据库后，你可以在两个服务器上运行：uv run python -m cli start。

依赖

Python： 参见 requirements.txt。核心技术栈包括 Flask、SQLAlchemy、Jinja2、Pydantic、Flask-Login、python-jose、passlib、cryptography 和 Flask-WTF。Phishing Detector 插件使用 transformers 和 torch。凭据代理使用 Playwright；可选集成使用 OpenAI/Anthropic 和 boto3（AWS Connect）。

开发环境： requirements-dev.txt 增加了 pytest、pytest-cov 及相关测试工具。使用 uv pip install -r requirements-dev.txt 安装以运行测试和覆盖率检查。

系统（生产环境）： 部署脚本面向 Ubuntu/Debian。它会安装 uv、Caddy（反向代理）以及 libmagic1 等系统包。对于凭据代理，start.sh 会运行 uv run playwright install chromium 安装 Chromium。

脚本

deploy.sh

在 Ubuntu 上进行生产环境准备。幂等操作。它会：

1. 检查是否为 Ubuntu/Debian。
2. 安装系统包（curl、ca-certificates、libmagic1 等）。
3. 若缺少 uv 则安装。
4. 安装 Caddy 作为反向代理（APT）。
5. 创建虚拟环境并从 requirements.txt 安装 Python 依赖。
6. 若缺少 .env 则从 .env.example 创建，并在未设置时生成 SECRET_KEY 和 JWT_SECRET_KEY。
7. 创建所需目录（storage/caddy/data、storage/caddy/config、storage/uploads、storage/templates、storage/assets、instance）。
8. 可选：使用 --init-db 初始化数据库（运行 uv run python -m cli init --force）。

该脚本不会启动应用。生产环境中：先启动 Caddy（反向代理），然后通过 ./start.sh 或进程管理器启动应用，使所有流量经由代理到达应用。

start.sh

开发环境与本地启动。它会：

1. 加载 .env 并确保 SECRET_KEY 和 JWT_SECRET_KEY 存在（若为默认值则生成）。
2. 验证 uv 是否已安装。
3. 若缺少虚拟环境则创建。
4. 从 requirements.txt 安装依赖。
5. 为凭据代理运行 uv run playwright install chromium。
6. 可选：使用 --preload-ml 预下载钓鱼检测模型（约 1.3GB）。
7. 若不存在数据库文件则初始化数据库（除非使用 --skip-init）。使用 --reset-db 删除并重新初始化。
8. 可选：使用 --with-caddy 通过 Docker 启动 Caddy（仅限本地测试）。
9. 启动服务器：默认通过 uv run python -m cli start 同时启动管理端和钓鱼端；使用 --admin-only 或 --phishing-only 只运行其中一个。

生产部署

在生产环境中，应用必须运行在反向代理之后。切勿将 Flask 开发服务器直接暴露到互联网。

反向代理负责 TLS 终止、正确的 Host 头、路径和域名路由，以及将管理流量与活动流量分离。应用监听 localhost 或内部端口；代理处理公开 HTTPS 并根据你的配置转发到管理服务器（例如端口 8000）和钓鱼服务器（例如端口 1234）。

推荐： 使用 Caddy 作为反向代理。deploy.sh 通过 APT 安装 Caddy。项目包含 Caddyfile 示例（例如 Caddyfile.minimal）。运行 deploy.sh 后，启动 Caddy（例如 caddy run --config /path/to/Caddyfile.minimal），然后通过 ./start.sh 或进程管理器启动应用。任何等效的反向代理（nginx、Traefik 等）均可接受，只要应用不被直接暴露。

项目意图

Reel 是一个网络钓鱼模拟和安全意识培训框架。操作员使用管理后台 UI 管理活动、工作流、模板和目标。钓鱼服务器为活动提供落地页服务，并在每个请求上运行工作流——由插件组成的基于节点的图。

app.py 中有两个应用入口点：create_app() 用于钓鱼服务器，create_admin_app() 用于管理后台 UI。活动可以是入站的（访客点击链接；GET 和 POST 工作流处理页面浏览和表单提交），也可以是出站的（系统通过发送工作流发送电子邮件或拨打电话）。Caddy 可用于基于域名的活动路由。凭据代理使用 Playwright 进行浏览器自动化，以在目标站点上重放捕获的凭据。

工作流概念

入站

用户访问活动 URL（例如 /<campaign_uid>）。钓鱼服务器按活动 UID 路由。对于 GET 请求，它运行活动的 GET 工作流（例如渲染落地页、CAPTCHA）；对于 POST 请求，它运行 POST 工作流（例如验证输入、捕获凭据、重定向）。工作流类型为 campaign，并声明 HTTP 方法支持（GET、POST 或 BOTH）。执行上下文包括 campaign、request、session 和 variables。响应取自上下文键，如 _response_html、_response_redirect 或 _response_json。入站工作流用于落地页、CAPTCHA、凭据捕获、重定向和日志记录。

出站

操作员从管理后台 UI 运行一个发送工作流，该工作流关联到一个活动（活动的“Workflow”/发送工作流）。发送执行器运行一个类型为 sending 的工作流：它选择目标（例如从 CSV 或已跟踪用户），可选地验证或预渲染内容，然后遍历目标——渲染电子邮件、应用速率限制，并通过插件（例如 SMTP）发送。没有访客 GET/POST；工作流生成内容并发送到目标列表。

总结：

• 入站： 由访客驱动。GET 和 POST 请求触发活动工作流。用于落地页和表单处理。
• 出站： 由操作员驱动。单个发送工作流在管理上下文中运行，并向目标批量发送（电子邮件、语音等）。

工作流变量

构建工作流时，使用 {{variable}} 语法进行插值。嵌套路径使用点号表示法：{{nested.key}}。

目标数据（来自 CSV / 循环）

CSV 示例： email,first_name,last_name,company,landing_page → 使用 {{target.email}}、{{target.first_name}}、{{target.company}}、{{target.custom_data.landing_page}}。

活动 / 配置

URL

URL 混淆器： 使用 url 或 target.landing_page 作为源，或进行插值：http://{{target.ip}}/login。

HTML / BERT 钓鱼检测器

Phishing Detector： 将 html_content 设置为 {{template_html}}、{{campaign.template_html}} 或 {{email_html}}。

插件输出

简单发送工作流示例

Target Selector (CSV) → Loop (array_source: targets, item_key: target) → Render Template → SMTP Sender

模板中的典型标签：{{target.email}}、{{target.first_name}}、{{target.last_name}}、{{target.custom_data.X}} 用于任何额外的 CSV 列。

插件

工作流由节点构建；每个节点都是一个带配置的插件。以下内置插件可用。

开发

• 运行测试：make test-fast 或 ./run_tests.sh
• 带覆盖率的测试：make test-coverage 或 ./run_tests.sh --coverage
• 代码检查：make lint
• 格式检查：make format-check

参见 Makefile 获取其他目标（单元/集成/功能测试拆分、数据库初始化/重置、仅运行管理服务器或钓鱼服务器）。

文档

• DEVELOPMENT.md — 开发自定义插件的详细说明。
• AGENT_README.md — 供 AI 代理使用：代码库概念、插件系统、风格指南和提示词。