跳转至

私有化本地部署极速上手 (On-Premises Quick Start)

本指南是从零构建企业级私有化本地部署的最短路径：在内网搭建一台 Admin Server 管理服务器，通过 Admin Dashboard 管理看板 分发授权席位，并将内网工作站上的 Griptape Nodes 桌面客户端统一收敛，仅通过该中继服务器与 Griptape Cloud 建立受信连接。

内网客户端将不再直接连接公网的 cloud.griptape.ai，而是统一指向 Admin Server。企业因此获得了单点出口防火墙策略管控以及全量出站流量集中审计的能力。

若工作站本身已具备合法直接访问 cloud.griptape.ai 的公网权限，且符合安全合规要求，则无需部署此套私有化架构。

第 1 至 4 步由企业 IT 管理员一次性配置；第 5 至 7 步为向终端用户的席位铺设流程。

前置环境准备

在开始之前，请确保具备以下资产与网络条件：

  • Admin Server 二进制可执行文件：企业版专享分发产物 —— 联系 Foundry 商务团队 获取；
  • 企业主 Griptape Cloud 组织所有者账号：Admin Dashboard 仅对 Organization Owner 开放展示；
  • 企业内网服务器主机：允许向外通过 HTTPS 访问 cloud.griptape.ai，并开放指定内网端口（默认为 8080）供工作站访问。内网其他所有工作站均无需任何公网访问权限；
  • 一台联网的管理操作机：用于访问 Admin Dashboard 进行发证与策略配置（控制台直连云端，不能在完全断网的机房机器上直接打开看板）。

步骤 1：生成 Griptape Cloud API Key

Admin Server 启动时必须加载 Griptape Cloud API Key。该 API Key 用于向云端证明 Admin Server 代表该企业组织，与后续颁发给普通用户的席位许可证（License Keys）属于不同层级的凭据。

通过任意联网计算机的浏览器登录 Web 编辑器进入管理看板：

  1. 点击 Login or Sign-Up 登录，确保切换至你所管辖的企业组织；
  2. 打开 Admin Dashboard：
    • Web 编辑器：点击左下角的用户菜单，看板将替换当前视图；点击 Back to Editor 可随时返回；
    • 桌面客户端：点击右上角的个人资料菜单，看板将在独立窗口中弹出。
  3. 默认进入 License Keys 页面。此时点击顶部统计栏中的 API Keys 卡片；
  4. 点击新建 API Key。系统仅展示一次完整明文，请立即复制并妥善保管。

License Keys 页面中高亮标出的 API Keys 卡片

该 Key 不参与具体算子业务的鉴权流转。客户端的算子调用依然遵循自身的 Bearer 鉴权，Admin Server 会原样透传。

步骤 2：解压与安装 Admin Server

在选定的内网中继服务器上解压安装包，目录结构如下：

  • server —— 主运行二进制可执行文件
  • config.example.yaml —— 配置模版样例
  • README 与 LICENSE

步骤 3：配置 Admin Server

最关键的必要配置是通过环境变量注入此前获取的 API Key：

export GT_CLOUD_API_KEY="gt-..."

服务器在启动引导时会立即验证该 Key 的合法性，校验失败则拒绝启动。配置文件本身仅允许指定读取该密钥的环境变量名，严禁将明文密钥直接硬编码写入配置文件。

config.yaml 配置文件是完全可选的。若无定制需求，直接启动 ./server 会采用出厂安全缺省配置与环境变量覆盖项。

检查版本并确认默认超时时间

运行 ./server -version。仅在 Admin Server 0.3.0 及更高版本上才建议采用无配置默认启动。在更早版本中，read_timeout 与 write_timeout 默认为 30s，可能导致长时流式输出中断 —— 详见 Admin Server 配置手册。

若需自定义监听端口或日志输出，拷贝模版进行编辑：

cp config.example.yaml config.yaml

配置生效优先级：环境变量 > 配置文件 (config.yaml) > 原生出厂缺省值。

步骤 4：启动并验证服务

./server                      # 使用默认配置与环境变量启动
./server -config config.yaml  # 显式指定配置文件启动

服务的所有运行日志直接输出至标准输出（stdout/stderr），不额外落盘文本日志文件，推荐交由系统的 Systemd 或 Supervisor 进行托管捕获。

通过内网发起健康检查验证存活状态：

curl http://<admin-server-address>:8080/health
# 正常响应：{"status":"ok"}

若 API Key 缺失或无法连通 Griptape Cloud，服务会在标准错误中输出明确根因并立刻退出。

步骤 5：批量颁发席位许可证 (License Keys)

回到 Admin Dashboard，导航至 License Keys → + Create License Key：

  • License Name(s)：席位唯一标识名（支持批量填入多行名称一次性生成多个席位）；
  • License Type：
    • Interactive：面向艺术家在图形编辑器中交互式操作；
    • Headless：面向自动化渲染农场或 CI/CD 流水线节点。一旦生成严禁更改类型；
  • Expiration Date：强制有效期截止日（范围 1 至 730 天）；
  • Access Groups：将席位预先编入权限访问组（建议提前在策略面板配置好允许调用的模型、算子库与项目范围，参见 Admin Dashboard 权限策略编辑器）。

每个生成的许可证 Token 仅在弹窗中展示一次，请复制并分发给目标用户。若丢失，可在列表中点击 Reissue 重新生成。

步骤 6：向工作站分发桌面客户端

在内网各工作站电脑上统一安装 Griptape Nodes 桌面客户端 —— 参见 安装指南。

重要说明：私有化部署场景下必须使用桌面版客户端。Web 版编辑器依托云端中继调度，无法适配纯内网环境；桌面客户端原生支持通过 WebSocket 直接连接内网引擎。工作站本身无需外网访问权限，仅需与 Admin Server 保持网络通畅。

向每位用户提供两项凭据： 1. 专属的许可证 Token 字符串； 2. 企业 Admin Server 的内网服务地址（例如 http://admin.internal.example.com:8080）。

步骤 7：工作站客户端激活

  1. 启动 Griptape Nodes 桌面应用；
  2. 在登录欢迎界面，点击下方的 Activate with a License（使用许可证激活）；
  3. 将许可证字符串粘贴进 License Key 输入框；
  4. 在 Griptape Server Endpoint 地址框中，将默认的 https://cloud.griptape.ai 替换为企业内网 Admin Server 地址；
  5. 点击 Activate License 完成激活。

客户端会自动记住该地址与席位。后续启动可在 Saved licenses 列表中免密一键登入。

常见故障排查 (Troubleshooting)

看不到 Admin Dashboard 菜单项？
这表明你当前是使用普通许可证登入的，或者登录的账号不是该企业组织的 Owner 所有者。必须点击 Login or Sign-Up 使用主组织账号登入。

其它关于 502 Bad Gateway、403 {"error":"path not permitted"} 路径拦截或 Token 激活异常的排查，请参阅： - Admin Server 服务端运维排错指南 - 使用 Admin Server 客户端激活排错指南

延伸阅读