企业管理服务器 (Admin Server)

Admin Server 运行在企业内网中，代表内部所有的 Griptape Nodes 桌面应用实例统一向 Griptape Cloud 发送请求。内网工作站实例不再直接连接公网的 cloud.griptape.ai，而是统一指向 Admin Server，由其中继转发各请求。

这使得企业在完全切断各个工作站直接访问外网公网的前提下，依然能够顺畅使用席位鉴权、会话管理以及各类 Griptape Cloud 云端能力。

为什么采用 Admin Server？

在影视、游戏及工业级本地部署场景中，IT 部门通常严禁内部成百上千台渲染机和艺术工作站随意访问公网。Admin Server 带来了三大核心治理优势：

物理隔离工作站：工作站仅需与内网 Admin Server 保持通信，完全剥离直接出网权限；
单一出口管控：仅需在防火墙白名单中开放该中继主机到公网的 HTTPS 通信，大幅降低网络暴露面，便于对出站请求实施集中安全审计；
集中化路由与出口拦截：在单一点位统筹配置云端服务接入点，并可细粒度定义允许离网的 API 路径白名单。

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

系统网络拓扑拓扑详见系统架构总览。

核心功能特性

云端请求安全代理：中继转发应用实例的请求至上游目标（默认为 https://cloud.griptape.ai），原封不动地保留调用者的 Authorization Bearer 令牌，Griptape Cloud 始终保持鉴权与授权的权威性；
启动引导强校验：启动时主动向云端验证管理员 API Key 的有效性，配置错误即刻快速失败，避免后续暗病；
网络出站路由白名单过滤 (Egress Filtering)：可精准定义允许离开内网的 Cloud API 路径；
本地健康探测：提供原生 GET /health 端点，返回 {"status":"ok"}，适配各类 Kubernetes / 负载均衡探针；
结构化审计日志：请求处理完毕后自动输出包含 HTTP Method、Path、Status、Latency、客户端 IP、写入字节数的 JSON/Text 审计流水。

配置文件规范 (`config.yaml`)

Admin Server 读取 config.yaml 配置文件。配置项生效优先级依次为：环境变量 > 配置文件 (config.yaml) > 原生出厂缺省值。

版本注意事项：本文档基于 Admin Server 0.3.0+ 规范。更早版本中 read_timeout 与 write_timeout 默认为 30s，极易导致大模型流式 Token 生成被意外腰斩中断。

标准 config.yaml 全量配置模版如下：

server:
  host: "0.0.0.0"
  port: 8080
  read_header_timeout: "10s"
  write_stall_timeout: "60s"
  idle_timeout: "120s"
  shutdown_timeout: "10s"

upstream:
  base_url: "https://cloud.griptape.ai"
  timeout: "120s"
  # 存放 Griptape Cloud API 密钥的环境变量名称
  # 密钥明文严禁在此处书写！
  api_key_env: "GT_CLOUD_API_KEY"

logging:
  level: "info"   # debug | info | warn | error
  format: "json"  # json | text

forwarding:
  mode: "allow_all"  # allow_all | allow | deny
  rules: []

1. `server` 核心服务配置

键名	默认值	详细技术说明
`host`	`0.0.0.0`	服务绑定的内网监听 IP 地址。
`port`	`8080`	服务监听端口。
`read_header_timeout`	`10s`	等待客户端完整发送 HTTP 请求头的超时上限。
`write_stall_timeout`	`60s`	针对客户端单次写入阻塞的容忍上限。每次写入成功后重置，不会限制长时流式传输的总时长。置为 `0` 表示禁用。
`idle_timeout`	`120s`	Keep-Alive 空闲长连接的保活维持时间。
`shutdown_timeout`	`10s`	优雅停机等待进行中任务收尾的超时时间。
`read_timeout`	`0` (关闭)	已弃用。限制整个请求体的读取总时长，会直接截断大文件上传。建议使用 `read_header_timeout`。
`write_timeout`	`0` (关闭)	已弃用。限制整个响应的写入总时长，只要大于 0 就会掐断所有流式 Token 输出。建议使用 `write_stall_timeout`。

高危警告：write_timeout 必导致长流式输出崩溃

若你的老版本配置文件中依然存在 write_timeout: "30s"，务必将其改为 "0"！

大模型生成 Token 是随着时间逐步打字吐出的，整体耗时经常超过 30 秒。若配置了全局 write_timeout，30 秒一到服务器会强行切断 TCP 连接，导致前端聊天文本生成到一半突然中断，客户端抛出 httpx.RemoteProtocolError: peer closed connection without sending complete message body。

2. `upstream` 上游代理配置

base_url：默认 https://cloud.griptape.ai；
timeout：等待 Griptape Cloud 开始产生首次响应的握手超时时间（默认为 120s）。该超时不限制后续流式传输时长；
api_key_env：声明读取管理员 API 密钥的环境变量名，默认为 GT_CLOUD_API_KEY。

3. `logging` 日志审计

支持 json 与 text 格式。排查连接中断时，重点留意两行关键日志： - starting server：启动时打印已生效的最终超时字典，第一时间核查 write_timeout 是否为 0； - response stream aborted before completion：标识流式传输被异常终止（附带 bytes_out 传输进度与 request_id）。

4. `forwarding` 网络出站白名单管控

控制允许通过 Admin Server 流向公网 Cloud 的接口路由：

allow_all（默认）：放行所有请求；
deny：黑名单模式，拦截匹配 rules 的路由；
allow：绝对最小化白名单模式，仅放行匹配 rules 的请求。

若采用严苛的 allow 白名单模式，以下核心接口绝不可漏配（否则 Admin Server 会拒绝启动并抛错）：

forwarding:
  mode: "allow"
  rules:
    - "/api/sessions/*"      # 会话生命周期分配
    - "/api/session-renew"   # 会话保活心跳
    - "/api/session-release" # 会话释放
    - "/api/users"           # 启动与周期心跳验证
    - "/api/organizations"   # 启动与周期心跳验证
    # 若需使用模型代理转发，按需追加：
    - "/api/proxy/*"

被拦截的路由会在本地直接返回 403 {"error":"path not permitted"}，绝不向公网发出。

环境变量全量覆盖对照表

所有参数均可通过环境变量进行强行覆盖（环境变量优先级高于一切文件）：

环境变量名	默认值	对应配置项
`GT_CLOUD_API_KEY`	(必填)	管理员身份密钥
`SERVER_HOST`	`0.0.0.0`	`server.host`
`SERVER_PORT`	`8080`	`server.port`
`SERVER_READ_HEADER_TIMEOUT`	`10s`	`server.read_header_timeout`
`SERVER_WRITE_STALL_TIMEOUT`	`60s`	`server.write_stall_timeout`
`SERVER_IDLE_TIMEOUT`	`120s`	`server.idle_timeout`
`SERVER_WRITE_TIMEOUT`	`0`	`server.write_timeout`
`UPSTREAM_BASE_URL`	`https://cloud.griptape.ai`	`upstream.base_url`
`UPSTREAM_TIMEOUT`	`120s`	`upstream.timeout`
`FORWARDING_MODE`	`allow_all`	`forwarding.mode`
`FORWARDING_RULES`	(空)	`forwarding.rules` (英文逗号分隔)

时间数值必须显式携带单位（如 30s、2m），若写成裸数字 30 会导致服务器拒绝启动并阻断报错。

运维排障指南 (Troubleshooting)

AI 对话打字到一半突然截断：排查控制台日志中的 write_timeout 是否被配成了非零值。执行 export SERVER_WRITE_TIMEOUT=0 并重启。若该值已为 0 仍发生截断，排查挂载在 Admin Server 前方的 Nginx、F5 或云负载均衡器是否配置了 proxy_read_timeout；
非流式耗时任务返回 502 Bad Gateway：上游非流式计算需要生成全量结果后才开始回包，调大 upstream.timeout（如提升至 300s）；
大文件上传到一半中断：检查是否存在遗留的 read_timeout 限制，将其置零；
服务完全无法启动：核验 GT_CLOUD_API_KEY 是否有效注入；核验所有时间环境变量是否均带有 s 或 m 单位；
所有请求均返回 403 {"error":"path not permitted"}：核验 forwarding.mode 是否误启用了 allow，但未在 rules 中放行对应的前缀路径。

延伸阅读

私有化本地部署极速上手 —— 从发证到桌面端配置的端到端流程
企业管理看板指南 (Admin Dashboard) —— 深入了解席位与 Cedar 权限模型
终端用户激活手册 (Using the Admin Server) —— 艺术家工作站交互图解

企业管理服务器 (Admin Server)

为什么采用 Admin Server？

核心功能特性

配置文件规范 (config.yaml)

1. server 核心服务配置

2. upstream 上游代理配置

3. logging 日志审计

4. forwarding 网络出站白名单管控