跳到正文
Hacker News· asernasr·· 6 天前AI 评分46

Figranium：可视化搭建浏览器自动化并作为 API 运行

Show HN: Figranium – Build browser automations visually and run them as APIs

AI 导读

Figranium 是一个可视化搭建浏览器自动化的工具，用户通过点击、输入、等待、悬停和执行 JavaScript 等积木式动作构建流程，并将保存的任务通过 HTTP API 触发运行，支持运行时传入变量和 API key 鉴权。它提供执行记录与截图录制查看、代理管理、社区模板导入、定时调度以及会话认证、IP 白名单和审计日志等安全能力，可通过 Docker Compose 自托管部署。

正文 · AI 翻译

Figranium Demo

你将获得

  • 基于块的自动化 — 使用点击、输入、等待、悬停和执行 JavaScript 等操作针对现代页面构建流程。
  • 任务 API — 通过 HTTP API 触发已保存的任务，在运行时传递变量，并使用你控制的 API 密钥保护运行安全。
  • 执行与文件柜 — 在执行中查看结果、截图和录制；将浏览器下载内容路由到任务选定的文件柜，以便稍后下载或上传。
  • 代理管理 — 托管、轮换或导入 HTTP/SOCKS 代理，标记默认代理，并按任务切换轮换。
  • 嵌入式模板 — 直接从仪表板或任务创建菜单浏览、预览和导入社区工作流。
  • 任务调度 — 使用可视化的间隔/每日/每周/每月设置或高级 cron 表达式自动运行工作流。
  • 可靠执行 — 跟踪排队和运行中的任务，取消排队的执行，并获取超出有限历史预览的完整结果。
  • 安全优先 — 会话身份验证、IP 允许列表、密钥管理和审计跟踪完全在你的环境中运行。

官方合作伙伴

Figranium 荣幸获得以下支持：

精选合作伙伴

Thordata — 优质住宅代理基础设施，用于可靠的网页抓取和浏览器自动化。

RapidProxy

RapidProxy — 9000 万+ 住宅 IP，专为浏览器自动化和网页抓取打造，具有智能轮换和稳定会话。起价 $0.55/GB，流量永不过期。使用 RAPID10 享受 10% 折扣。

集成合作伙伴

SimplyNode — 用于网页抓取和浏览器自动化的住宅代理，具有灵活定位和可靠轮换。

基础设施支持者

快速开始

这会在 http://localhost:11345 上启动应用，并在 http://localhost:54311 上启动 VNC 查看器。

Docker Compose（标准）

1. 创建项目目录

为你的 Figranium 安装创建一个目录并进入其中：

mkdir figranium-server
cd figranium-server

2. 创建 docker-compose.yml

在项目目录中创建 docker-compose.yml 文件：

wget https://raw.githubusercontent.com/figranium/figranium/main/docker-compose.deploy.yml -O docker-compose.yml

3. 使用 Docker Compose 启动

运行以下命令以分离模式启动应用：

docker compose up -d

反向代理部署

仅代理主应用端口（11345）。嵌入式浏览器查看器通过应用经过身份验证的 /websockify 端点连接，因此不需要单独的公共 VNC/noVNC 端口。

对于在同一 VM 上运行的 Caddy，标准反向代理就足够了：

figranium.example.com {
    reverse_proxy 127.0.0.1:11345
}

Caddy 会自动转发 WebSocket 升级。查看器会收到一个绑定到已登录会话的短期一次性票据，因此即使代理更改上游 Host 标头，它也能继续安全连接。嵌入式浏览器查看器不需要 TRUST_PROXY；仅当应用需要依赖转发的客户端地址或协议标头进行其他部署行为时才启用它。

会话密钥

Figranium 在首次启动时自动生成加密随机会话密钥，并将其存储在持久数据目录（session_secret.txt）中。后续启动会重用已保存的密钥。你可以选择设置 SESSION_SECRET 来提供自己的密钥；保持数据目录持久化，以便现有会话保持有效。

配置

变量 用途 默认值
SESSION_SECRET 用于自动生成并持久化的会话 cookie 签名密钥的可选覆盖。 自动生成
MASTER_KEY 可选的 256 位密钥，用于启用静态加密的机密文件。若不设置，共享机密存储将写入明文 JSON。请提供以 base64url 编码的 32 字节，或 64 个十六进制字符。 未设置（无共享机密存储加密）
MASTER_KEY_FILE 可选的旧版本地主密钥位置，用于在迁移期间解密先前加密的文件。若没有 MASTER_KEY，则不会为新写入启用加密。在迁移完成前请保留原始密钥。 data/master.key（旧密钥位置）
PASSWORD_CACHE_KEY 用于加密服务器端 1Password 缓存的机密。设置此项可将加密密钥保存在 Figranium 数据目录之外。 自动生成并存储在 data/password_cache.key
PASSWORD_CACHE_ENABLED 启用对 1Password 登录元数据和已解析密码的加密服务器端缓存。设置为 false 可始终从 1Password 获取。 true
FIGRANIUM_TELEMETRY_ENABLED 向 Figranium 遥测发送匿名安装环境详情和每日 UI/API 使用标志。设置为 false 可禁用。 true
ALLOWED_IPS 用于基本 IP 允许列表的逗号分隔列表。 无（开放）
TRUST_PROXY 遵循 X-Forwarded-* 以实现应用级代理行为。嵌入式浏览器查看器不需要此项。 0
ALLOW_PRIVATE_NETWORKS 允许抓取本地/私有 IP（SSRF 风险）。 false
VITE_DEV_PORT 前端开发服务器端口。 5173
VITE_BACKEND_PORT 用于代理和脚本的后端端口。 11345
DB_TYPE 可选的数据库类型，覆盖磁盘存储。设置为 postgres 以使用 PostgreSQL。 —
DB_POSTGRESDB_HOST PostgreSQL 数据库的主机名（若 DB_TYPE 为 postgres 则必填）。 —
DB_POSTGRESDB_PORT PostgreSQL 数据库的端口号（若 DB_TYPE 为 postgres 则必填）。 —
DB_POSTGRESDB_USER PostgreSQL 数据库的用户名（若 DB_TYPE 为 postgres 则必填）。 —
DB_POSTGRESDB_PASSWORD PostgreSQL 数据库的密码（若 DB_TYPE 为 postgres 则必填）。 —
DB_POSTGRESDB_DATABASE PostgreSQL 的数据库名称。 postgres
USE_CLOAK_ENGINE 设置为 true 以在 CloakBrowser 上运行浏览器引擎，而非默认的 Playwright 隐身栈。 false
CLOAKBROWSER_LICENSE_KEY 用于最新二进制文件的 CloakBrowser 许可证密钥。 —
MAX_CONCURRENT_EXECUTIONS 覆盖自动浏览器执行限制。 主机感知

升级到 0.21.1

共享机密存储中的静态加密现为可选启用。若不设置 MASTER_KEY，新的基于文件的机密写入将使用明文 JSON；配置 MASTER_KEY 可保持其加密。现有加密文件仅在其原始密钥可用时才会被解密并迁移。在迁移完成前请保留 data/master.key（或已配置的旧版 MASTER_KEY_FILE）；密钥缺失绝不会触发破坏性重置。命名 API 密钥仍经过加盐和哈希处理，不会以明文存储。独立的 1Password 密码缓存加密设置仍与 MASTER_KEY 无关。

| MAX_EXECUTION_QUEUE | 新工作收到 503 前的最大等待执行数。 | 50 | | EXECUTION_QUEUE_TIMEOUT_MS | 执行等待容量的最长时间。 | 600000 | | EXECUTION_TIMEOUT_MS | 非无头执行的最长运行时间。 | 900000 | | RESOURCE_MEMORY_RESERVE_MB | 为主机保留的最小内存余量。 | max(512 MB, 15%) | | RESOURCE_CPU_THRESHOLD | 暂停出队的归一化 CPU 负载。 | 0.9 | | RESOURCE_PROBE_INTERVAL_MS | 运行时资源保护采样间隔。CAPTCHA 容量在启动时检测。 | 30000 |

CAPTCHA 求解

Figranium 使用 Fiptcha 进行 CAPTCHA 求解。Fiptcha 拥有 CAPTCHA 求解器实现及其配置、支持的提供商、本地/远程求解行为、模型设置以及平台特定的配套工具。请参阅 Fiptcha 仓库以获取当前的 CAPTCHA 文档，而不要依赖此处重复的配置。

代理轮换也遵循 data/proxies.json（见下文），且 data/allowed_ips.json 可作为另一种允许列表格式使用。

高级配置

  • 使用共享 Playwright 安装时，PLAYWRIGHT_BROWSERS_PATH（或设置 PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH）。
  • NODE_ENV=production 启用捆绑的 dist/ 客户端并降低控制台详细程度。
  • HOST=0.0.0.0 允许在 Docker 容器内绑定到 localhost 之外，而 PORT 会覆盖 Express 监听端口（默认为 11345）。
  • 如果需要更多 Playwright 或代理诊断信息，请将 LOG_LEVEL 设置为 debug。

任务模式

Figranium 有两种任务模式：

  • Agent 模式 — 由有序的操作序列、控制流、变量和提取构建的确定性浏览器自动化。
  • Scrape 模式 — 无需启动浏览器的轻量级基于 HTTP 的抓取和提取。

可见的浏览器会话是一种调试/运行时能力，而不是第三种任务模式。

UI 导览

  • 仪表盘 — 查看指标、搜索和排序任务、浏览精选模板，以及从零开始或基于模板创建任务。
  • 模板 — 浏览内嵌的社区目录，搜索和筛选现成的工作流，预览其详情和预期输出，并将它们导入你的工作区。
  • 任务编辑器 — 构建 Agent 或 Scrape 任务，配置操作和提取，测试块，管理变量，选择 Cabinet，安排运行计划，添加可调整大小的画布笔记，并触发执行。
  • 执行 — 浏览排队中、运行中和已完成的任务；检查结果、完整结果、截图和录制；并取消排队的执行。
  • Cabinets — 管理任务下载和 Upload 块使用的持久文件队列，包括文件、ZIP、文件夹和上传状态。
  • 设置 — 管理 API 密钥、User Agent、代理、外观和高级设置，包括保留策略、账户控制和资源信息。

任务能力

  • 任务支持的操作包括导航、点击、输入、等待、按键、滚动、JavaScript、悬停、截图、条件、循环、变量、上传和错误处理。
  • 变量模板化（{$var}）和结构化条件使任务能够通过运行时输入实现复用。
  • 提取可以从浏览器或抓取执行中返回结构化数据。
  • 有关任务 schema 和操作契约，请参阅 AGENT_SPEC.md。

代理

代理可以通过 UI 或 data/proxies.json 定义：

[
  "http://user:pass@proxy1.example.com:8000",
  { "server": "socks5://proxy2.example.com:1080", "label": "data center" }
]
  • host 始终可用，代表你机器的默认 IP。
  • 轮换设置（round-robin 或 random）位于设置中，并通过后端端点持久化。
  • 导入/导出操作位于 /api/settings/proxies/import 之后。

API 接口

Figranium 为工作流工具、应用程序和自定义集成提供 REST API。所有端点都托管在你的 Figranium 实例上，通常位于端口 11345。

身份验证： 如果启用，请提供 x-api-key 头或 Authorization: Bearer <key>。对于内部网络使用，根据你的设置，这可能是可选的。

任务管理 API

  • GET /api/tasks：列出所有已保存的任务。
  • POST /api/tasks：创建新任务。
  • PUT /api/tasks/:id：更新现有任务。
  • POST /api/tasks/:id/api：执行预定义任务。在请求体中传入 {"variables": {}} 以动态覆盖执行变量。

调度 API

  • GET /api/schedules：列出所有已调度的任务及其状态。
  • POST /api/schedules/:taskId：创建或更新调度（支持可视化配置或原始 cron）。
  • DELETE /api/schedules/:taskId：禁用/移除调度。
  • GET /api/schedules/status/all：获取所有活动调度任务的概览。

执行 API

  • GET /api/executions：检索过去运行的分页历史记录。
  • GET /api/executions/:id：查看特定运行的步骤、结果数据和配置状态。

模板 API

  • GET /api/templates：浏览社区模板目录，支持搜索、分类、排序和分页。
  • GET /api/templates/:id：检索单个 Template 以进行预览或导入。这些端点需要经过身份验证的工作区会话。

Cabinets API

  • GET /api/cabinets：列出 Cabinets。
  • /api/cabinets 下的 Cabinet 路由管理文件队列、项目、下载、上传状态、ZIP 创建和解压。

任务脚本编写技巧

  • Use JavaScript blocks when you need custom browser-side logic: 
    return document.querySelectorAll('article').length;
  • 保持选择器范围狭窄，并使用选择器选取器生成确定性的候选项。
  • 通过 API 设置 Task 变量，以便在多个输入或域中复用通用工作流。

工作流配方

  1. 在编辑器中设计一个 Task，并添加工作流所需的操作。
  2. 在需要确定性控制流的地方使用条件、循环、变量和 JavaScript。
  3. 当需要结构化输出或视觉证据时，添加提取或截图操作。
  4. 当工作流需要不同的出口策略时，配置代理轮换。
  5. 使用 Schedule 选项卡进行自动运行，或通过其 API 端点触发 Task。
  6. 从其他工具调用 Task 时，传入运行时变量，例如 {"variables":{"query":"books"}}。

任务调度

Figranium 包含一个内置调度器，无需外部 cron 作业或触发器即可处理自动 Task 执行。

  • 可视化模式：配置周期性、每小时、每天、每周或每月的运行。
  • 高级模式：使用标准 5 字段 cron 表达式（* * * * *）来设置复杂计划。
  • 持久性：计划与 Task 元数据一起存储，并在服务器重启后保留。
  • 监控：可从 Task 调度界面和执行历史中获取下次运行和上次运行的信息。

测试与验证

  • 在生产打包前运行 npm run build；dist/ 文件夹包含编译后的资源。
  • 后端日志记录会写入控制台，用于调试代理、身份验证或浏览器故障。
  • 在更改执行关键行为时，使用仓库的测试和资格验证脚本。

故障排除

  • UI 中的 “Session expired”：确认 SESSION_SECRET 一致，并且 cookie 未被浏览器阻止。
  • 代理导入失败：检查 data/proxies.json 中是否有有效 URL；后端在使用前会验证代理配置。
  • API 密钥丢失：打开 Settings → API Keys 以查看或重新生成 API 凭据。

数据生命周期

  • 截图和录制内容可通过 Executions 访问，而不是单独的 Captures 页面。
  • 大型执行结果与有界历史预览分开持久化，并按需检索；保留清理也会删除其存储的负载。
  • 浏览器下载内容存储在 Cabinets 中。Task 可以选择一个 Cabinet，Upload 块可以消费排队的 Cabinet 项目。
  • 浏览器状态可以在执行之间持久化；当一次运行应在没有持久化 cookie 或本地存储的情况下启动时，启用 Task 的无状态执行选项。
  • 代理列表、用户代理偏好和其他服务器设置持久化在 data/ 下；当这些设置对你的部署很重要时，请备份该目录。

维护

  • 该项目受 GNU General Public License v3.0 约束，该许可证根据 GPLv3 条款授予分发和修改的权利。
  • 如果你依赖持久化设置或浏览器状态，请保持 data/ 已备份。
  • 发布更新：Docker 安装应运行 docker compose pull，然后运行 docker compose up -d；源码安装应拉取 figranium/figranium 并遵循项目设置命令。
  • 贡献：遵循 .github/ 模板，遵守 CONTRIBUTING.md，如果你触及关键区域，请运行可用的 lint/test 脚本。

路线图

  • 设置快捷方式 — 专用的 API 密钥、用户代理、代理和外观部分让操作员无需离开 UI 即可调整核心设置。
  • 统一执行历史 — 通过 Executions 查看结果、截图和录制，而不是重复的 Captures 页面。
  • IP 轮换工具 — 导入代理并自动轮换它们。
  • API 密钥工作流 — 无需额外设置即可管理 API 访问。
  • 作用域 API 密钥 — 支持多个可单独撤销且具有明确权限的 API 密钥。
  • 密码管理器与凭据注入器 — 安全存储凭据并在运行时将其注入浏览器任务。
  • 任务代理轮换开关 — 为每次任务执行启用轮换。
  • 空间编辑器过渡 — 基于空间块的任务编辑器。
  • 操作键组合 — 为浏览器交互添加修饰键快捷方式。
  • 点击并拖动块 — 添加拖动手势自动化。
  • 录制控制 — 按任务禁用自动录制。
  • 文件下载 — 从目标页面下载文件并通过 Cabinets 呈现它们。
  • Cabinet 支持的文件工作区 — 将下载路由到共享 Cabinets 并从 Upload 块中使用它们。
  • 无状态模式 — 在不持久化 cookie 或本地存储的情况下启动任务运行。
  • 广告拦截过滤器 — 为执行上下文提供可选的广告/恶意软件过滤。
  • 提取响应模式 — 在 HTML+数据 和仅数据 API 响应之间选择。
  • 文件夹组织 — 将任务和资产组织到命名文件夹中。
  • 可配置的捕获和执行保留 — 在高级设置中设置保留时间，并自动清理。
  • 工作区模板 — 可复用的工作区预设。
  • 地理定位出口 — 为任务选择代理区域。
  • 完整的反检测覆盖 — 跨浏览器执行的反检测控制。
  • 会话录制脱敏 — 从录制和日志中脱敏敏感字段。
  • 双因素认证 — 可选的 TOTP/第二因素支持。
  • 自动自愈选择器 — 在页面更改后恢复损坏的定位器。
  • 使用 translate.js 的多语言任务页面 — 可选地在操作和提取之前翻译浏览器渲染的页面。
  • AI 辅助修复 — 在运行失败后建议修复方案供用户批准。
  • 配套应用 — 为重要执行事件提供轻量级通知。
  • 社区预设中心 — 发布和发现可复用的自动化预设。
  • 嵌入式模板即用 — 直接在 Figranium UI 中浏览、预览和导入现成的模板。
  • 数据库选项卡 / 本地 CRM — 用于提取数据的内置界面。
  • iframe 交互支持 — 定位并与 iframe 内的元素交互。
  • 自动保存 — 自动持久化任务更改和编辑器状态。
  • 高亮工具 — 在构建工作流时高亮元素。
  • Cron 触发器 — 使用 cron 表达式调度任务。
  • 可调整大小的画布笔记 — 在工作流旁边添加并调整注释大小。
  • 页面触发器 — 当页面以指定方式发生变化时触发任务。
  • 任务专用浏览器状态与 Cookie 桶 — 在任务之间隔离或有意共享持久化浏览器状态。

安全注意事项

  • 切勿将你的 SESSION_SECRET 或 API 密钥提交到共享仓库中。
  • 在部署到暴露于网络的主机时，使用 ALLOWED_IPS/data/allowed_ips.json 来限制 UI 访问。
  • 通过设置定期轮换 API 密钥，并使用执行记录来审查自动化运行情况。
  • 保持依赖项和部署环境为最新版本。

社区

  • 通过 GitHub 仓库的问题跟踪器报告问题或请求功能。
  • 在 https://github.com/figranium 上关注作者以获取发布信息。
  • 在你的组织内与其他自托管用户分享自动化方案，但分享基础设施时请遵守许可证。
  • 加入 Discord 社区。

支持项目

如果你觉得这个项目有帮助，请考虑支持它的开发。你的贡献有助于维持项目的维护，让项目持续运转！

Support on Ko-fi

其他帮助方式：

  • 加星该仓库，帮助其他人发现它。
  • 分享该项目给你的社交网络。
  • 贡献代码或文档。

来源：Hacker News · github.com

Agent 智能体开源生态部署工程产品更新#产品更新#开源/仓库#Agent#部署/工程