跳转至

系统架构总览 (Architecture)

Griptape Nodes 由两个核心程序协同构成：用于构建工作流的可视化编辑器 (Editor)，以及在你完全掌控的计算机器上运行工作流的底层应用服务 (Application)。应用服务负责调度执行运算、持久化管理你的本地工作区数据，并且仅在遇到自身无法独立完成的极少数特定服务时，才向上游 Griptape Cloud 发起请求。

这种架构形态在各类部署模式下保持高度一致。不同部署形态之间的唯一区别，仅在于从你的计算工作站到 Griptape Cloud 之间的网络路由拓扑路径：

无论采用哪种拓扑，所运行的软件代码与执行语义完全相同。在不同模式间切换，改变的仅仅是网络通信路由，而不是软件产品本身。

核心软件组件 (The pieces)

核心组件 组件性质与核心职责 物理运行位置
编辑器 (Editor) 用于可视化搭建与调试节点图谱的图形画布界面。 运行在你的 Web 浏览器中，或直接封装在 Griptape Nodes Desktop 客户端中。
应用服务 (Application) 执行与驱动工作流的核心服务，通过 griptape-nodes 分发。负责执行图拓扑调度、管理本地工作区文件，并在本地强行实施席位许可证授予的 Cedar 权限策略。 运行在你的本地物理机或计算节点上。
执行引擎 (Engine) 开源的工作流运行时内核，通过 griptape-nodes-engine 分发（开源源码位于 griptape-nodes-engine）。负责动态加载算子库并执行算子图计算。 运行在应用服务内部。

执行引擎（Engine）是工作流实际计算发生的场所，且完全开源。这意味着你可以自由审查和审计关于工作流如何执行、在何处读写文件以及如何处理内存数据的每一个技术细节。它不是一个独立的部署目标：可视化编辑器始终连接到应用服务（Application），绝不直接连接底层引擎。

Griptape Nodes 桌面客户端 (Desktop) 完整打包了前端编辑器，并内置了预装锁定版本 Python 解释器的应用服务，因此你无需额外手动安装任何复杂的 Python 依赖环境，开箱即用。

你的数据资产存放在哪里？ (Where your data lives)

你在使用过程中创作和生成的几乎所有资产，均直接写入到你的工作区 (Workspace) 中。工作区是应用服务读取和写入的单一根目录，所有相对路径均以此为基准进行解析。其物理存储路径完全由你自行决定。默认情况下它是位于应用目录旁边的一个文件夹，但你可以将其自由重定向至机器能够挂载访问的任何路径，包括 NAS 网络共享存储或 LucidLink 云挂载盘——这也是影视动画工作室将项目工程集中保存在共享基础设施上的通用标准做法。详见 工作区配置指南。

因此，当你评估企业数据安全边界时，工作区是唯一的审计锚点。应用服务仅会读写你显式指定的本地路径，下表所列的任何数据项默认情况下绝对不会发送至 Griptape Cloud：

数据内容分类 实际存储位置 是否会发送至 Griptape Cloud？
工作流与项目工程文件 (.py / .json) 你的本地工作区 绝不发送
生成的多媒体资产：图像、视频、音频 你的本地工作区 绝不发送（除非你主动将存储后端切换为云端存储桶）
环境变量、Secrets 与第三方 API 密钥 依次读取环境变量、工作区内的 .env 文件、用户目录配置 绝不发送
聊天交互与会话上下文历史 你的本地工作区 绝不发送
算子库 (Node Libraries) 代码及虚拟环境 安装在运行应用服务的机器本地，每个算子库拥有独立的 Python 虚拟环境 绝不发送

仅在以下两项可选配置下，数据才会离开本地（两项在出厂时默认全部处于关闭状态，详见 配置指南）：

  1. 存储后端 (Storage Backend)：默认值为 local（将资产写入本地工作区）。若将其显式修改为 gtc，生成的中间资产将转存至 Griptape Cloud 云端存储桶中；
  2. 工作流云端同步 (Synced Workflows)：开启该选项后，工作流文件将通过 Griptape Cloud 存储桶进行跨设备自动同步与漫游。

除上述明确的主动配置外，数据离开工作区的唯一可能，就是工作流自身的设计行为：例如某个节点显式调用了第三方商业大模型服务商，该节点的输入 Prompt 自然会被发送至该服务商的 API。关于与外部服务的交互细节，请参阅下一小节。

哪些服务需要与 Griptape Cloud 通信？ (What talks to Griptape Cloud)

应用服务仅在以下极少数特定功能场景下依赖 Griptape Cloud。以下为完整的交互清单：

能力项 是否为强制依赖？ 跨越安全边界传输的数据内容
许可证鉴权与会话管理 是 (强制依赖)。应用服务必须依赖它才能合法运行。 你的许可证密钥，以及会话分配 (allocate)、续期 (renew) 和释放 (release) 请求。绝不包含任何工作流业务内容。
权限权利清单 (Entitlements) 是，在会话分配与握手时一并返回。 你的席位许可证所绑定的 Cedar 权限策略规则。由云端返回给本地应用服务，并由应用服务在本地强行拦截和执行。
云端模型代理中继 (Model Proxy) 否 (可选)。 当节点显式选择通过云端代理路由时，传入该节点的 Prompt 提示词与输入参数会被中继转发给对应的模型服务商。
存储桶与云端资产 (Buckets & Assets) 否 (默认关闭，需用户主动开启)。 仅在开启云端同步时传输你选择同步的资产和工作流。
Nodes API WebSocket 中继 否 (仅跨机模式使用)。 当前端编辑器与后端应用服务不在同一台物理机器上时，用于在云端中继转发编辑器与应用之间的操作事件。
管理看板 (Admin Dashboard) 否 (仅供企业管理员使用)。 在浏览器中进行席位发证、访问组划分与权限策略编排。详见 企业管理看板。

许可证鉴权是系统唯一的强依赖项。 许可证是允许应用服务启动运行的合法凭据：应用启动时会验证许可证、向 Griptape Cloud 请求分配一个活跃并发会话、拉取挂载在该席位上的 Cedar 策略，并在本地运行时全程把关。工作流的图拓扑、参数与数据内容绝不参与该握手流转。激活流程详见 使用企业管理服务器激活。

模型调用也完全可以做到与 Griptape Cloud 零交互：你可以在节点上直接配置第三方供应商的私有 API Key（直连外部服务），或者直接调用运行在内网的 Ollama 或 LM Studio 本地大模型。在此类场景下，Prompt 提示词与推理结果 100% 停留在你的内网或本机中。详见 AI 供应商指南。

前端编辑器与后端应用服务的连接机制

由于前端编辑器与后端应用服务属于两个解耦的独立程序，二者之间的状态同步与指令交互依赖以下两种 WebSocket 传输通道之一：

  1. 直接直连 WebSocket (Direct WebSocket)：应用服务在本地监听端口，编辑器直接发起内网 TCP/WebSocket 连接。所有交互事件、连线拓扑和状态完全不出本机或内网。这也是 Griptape Nodes Desktop 桌面客户端在通过许可证激活时采用的原生工作机制；
  2. Nodes API 云端中继 WebSocket：前端编辑器与后端应用服务分别向 Griptape Cloud 发起出站长连接，由云端负责在双向之间中继转发事件。这种模式允许用户在轻薄便携笔记本的浏览器中打开编辑器，直接远程驱动处于机房或高性能工作站上的运算服务。

这种区别对数据隐私至关重要：因为编辑器与应用之间的通信流量承载着完整的工作流内容（节点拓扑图、参数数值、生成的图像/音视频缩略图预览）。在 Direct WebSocket 模式下，这些敏感数据完全被锁死在内网，不会暴露至公网。无论采用哪种模式，你的本地工作区始终驻留在运行工作流的机器本地。

SaaS 公网直连架构 (SaaS Configuration)

这是个人与中小型团队开箱即用的默认架构。你的工作站直接访问 Griptape Cloud，无需企业 IT 部门部署任何中继网关。根据编辑器与应用服务所处物理位置的不同，细分为两种具体形态。

图示阅读约定：在本文档的所有架构拓扑图中，实线表示必须通畅的必要连接，虚线表示可选功能连接；双向箭头表示数据沿同一网络链路原路返回。全系统中唯一不可或缺的外部流量仅为许可证握手流量。

1. 编辑器与引擎部署在同一台机器上

这是安装 Griptape Nodes Desktop 桌面客户端获得的默认架构。前端编辑器直接通过本机 Direct WebSocket 与内置的应用服务通信，因此任何工作流业务内容绝对不会触碰外网。

flowchart TB
    subgraph machine["你的本地工作站 (Your machine)"]
        direction TB
        editor["前端编辑器 (Editor)"]
        app["Griptape Nodes 应用服务<br/>引擎内核 + 本地 Cedar 策略执行"]
        workspace[("工作区 (Workspace)<br/>工作流、多媒体资产、Secrets")]
        local["本地大模型<br/>Ollama、LM Studio 等"]
        editor <-->|"本机 Direct WebSocket 直连"| app
        app <--> workspace
        app <-.-> local
    end

    subgraph cloud["Griptape Cloud 云端管控面"]
        direction TB
        control["许可证鉴权与会话管理<br/>Cedar 权限策略清单下发"]
        modelproxy["云端模型代理中继"]
        buckets["云端存储桶与资产同步"]
    end

    providers["第三方大模型服务商 (OpenAI / Anthropic 等)"]

    app <==>|"出站发起许可证与会话握手<br/>回传 Cedar 权限策略"| control
    app <-.->|"可选：Prompt 提示词转发<br/>回传大模型流式响应"| modelproxy
    app <-.->|"可选：资产与工作流同步"| buckets
    modelproxy <--> providers
    app <-.->|"可选：使用开发者自带 API Key 直连"| providers

2. 编辑器与引擎部署在不同的物理机器上

适用于希望在轻量笔记本的浏览器中编辑工作流，但让计算任务跑在高性能独立服务器上的分布式场景。此时前端编辑器与远程应用服务各自向 Griptape Cloud 的 Nodes API WebSocket 发起单向出站连接，由云端负责双向中继事件。

flowchart TB
    subgraph remote["远端终端设备 (笔记本/平板等)"]
        editor["Web 浏览器中的前端编辑器"]
    end

    subgraph machine["计算节点工作站 (High-End Machine)"]
        direction TB
        app["Griptape Nodes 应用服务<br/>引擎内核 + 本地 Cedar 策略执行"]
        workspace[("工作区 (Workspace)<br/>工作流、多媒体资产、Secrets")]
        local["本地大模型<br/>Ollama、LM Studio 等"]
        app <--> workspace
        app <-.-> local
    end

    subgraph cloud["Griptape Cloud 云端管控面"]
        direction TB
        wsapi["Nodes API<br/>WebSocket 中继"]
        control["许可证、<br/>会话状态、<br/>权限策略下发"]
        modelproxy["云端模型<br/>代理中继"]
        buckets["存储桶<br/>与资产同步"]
    end

    providers["第三方大模型服务商"]

    editor <-.->|"单向出站长连接"| wsapi
    app <-.->|"单向出站长连接"| wsapi
    app <==>|"出站发起许可证握手<br/>回传权限策略"| control
    app <-.->|"模型请求中继"| modelproxy
    app <-.->|"可选资产同步"| buckets
    modelproxy <--> providers
    app <-.->|"使用自带 API Key 直连"| providers

由于两端均为主动向外拨号出站，因此该方案不需要在机房端开放任何入站端口 (Inbound Port)，双方也无需知晓对方的物理 IP 地址。但相应的权衡是：编辑器与引擎之间的控制流数据（节点图、参数值、生成的缩略图预览）将会经过公网 Griptape Cloud。工作区依然完好保存在运行引擎的机器上，计算依然在本地发生。

重要合规说明：上述跨机模式不适用于纯离线内网私有化环境。由于 Nodes API WebSocket 属于公网托管服务，企业私有化部署架构必须统一使用 Direct WebSocket 本地连接，从而将所有工作流事件彻底锁死在企业内网中。

On-Premises 企业私有化内网架构 (On-premises configuration)

在影视特效制作公司、游戏大厂或军工金融等高安全合规要求场景下，企业内网的成百上千台计算工作站和渲染节点被物理切断外网访问路由。此时企业在内网部署一台 Admin Server 管理服务器，作为全内网唯一允许触碰公网的出口网关。IT 部门仅需在核心防火墙上针对这台机器配置单点放行，即可完成对全企业集群的安全合规接入：

flowchart TB
    subgraph network["企业内部受控局域网 (Your network)"]
        direction TB
        editor["前端编辑器<br/>(内置于 Desktop 客户端)"]
        app["Griptape Nodes 应用服务<br/>引擎内核 + 本地 Cedar 策略执行"]
        workspace[("工作区 (Workspace)<br/>工作流、多媒体资产、Secrets")]
        local["内网私有大模型<br/>Ollama、LM Studio、vLLM 等"]
        admin["企业 Admin Server 管理服务器<br/>单点公网出口中继<br/>支持 API 出站路径白名单过滤"]
        editor <-->|"Direct WebSocket 直连<br/>绝不离开企业内网"| app
        app <--> workspace
        app <-.-> local
        app <-->|"内网 HTTPS 请求"| admin
        %% 隐式对齐约束
        local ~~~ admin
    end

    subgraph cloud["Griptape Cloud 公网管控面"]
        direction TB
        control["许可证鉴权与会话管理<br/>Cedar 权限策略清单下发"]
        modelproxy["云端模型代理中继"]
    end

    admin <==>|"HTTPS 出口：全内网唯一<br/>离开企业防火墙的加密流量"| control
    admin <-.->|"严格受控：仅在管理员白名单中显式放行时中继"| modelproxy

企业私有化架构具备三大核心安全支柱：

  1. 工作流的设计与运算绝不越过安全边界：客户端桌面版完整打包了前端画布，无需连网下载任何 Web 静态资源；其通过内网 Direct WebSocket 与本地应用服务通信。工作流拓扑、中间计算多媒体以及环境变量均驻留在机器本地工作区。配合内网部署的开源模型服务（如 vLLM、Ollama），整个工作流从触发到渲染输出可以做到 100% 零数据包出网；
  2. 单一出站主机，出站内容完全透明受控：所有工作站客户端统一将服务端点指向 Admin Server，而非公网 cloud.griptape.ai。管理员不仅在物理边界上仅需维护单一 IP 的防火墙规则，还可以在 Admin Server 的配置文件中启用严格的路径白名单模式（Forwarding Rules），将模型调用等非必要请求完全掐死在内网，仅放行底层鉴权握手；
  3. 出站通信路径清晰固定且完全可审计：维持席位鉴权仅需放行以下 5 条标准化路由，Admin Server 若检测到核心鉴权路由被阻断，会在启动时立即拦截报错并拒绝运行：
必需出站路由 接口核心用途
/api/sessions/* 分配并管理允许客户端运行的并发在线会话。
/api/session-renew 维持活动会话的心跳保活长连接。
/api/session-release 客户端主动登出或关闭时安全释放席位，返还并发配额。
/api/users 启动引导及周期心跳时向云端核验许可证持有者身份。
/api/organizations 启动引导及周期心跳时核验该席位绑定的企业组织归属。

为什么保持轻量云端握手连接是企业的最优选择？

保持这条极简出站通信链路带来的收益远不止维持会话存活：它也是客户端实时动态拉取最新权限策略（Entitlements）的下发生命线。当企业管理员在管理看板中修改了某部门的可用模型或算子库黑名单时，内网正在运行的工作站会在下一次心跳周期或新会话启动时无缝、即时生效新策略，彻底告别传统的重新分发安装包或手动批量修改配置文件的繁重运维。

因此，“企业私有化部署”并不等同于“完全断网单机运行”。它的本质是将你企业的数据资产、工程资产与业务算力 100% 物理封锁在内网，而将轻量的身份凭证与安全策略通过受控单点中继保持动态同步。若因网络故障导致 Admin Server 无法连通云端，Admin Server 会主动返回错误并快速失败，绝不会基于过期的陈旧凭证盲目放行，从而杜绝任何席位冒用隐患。

延伸阅读