跳转到内容
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SaaS 配置文件

将 OpenHuman 作为多用户服务运行:每个用户一个用户档案,置于可信网关之后,可在单节点或带有租用用户档案的集群上运行。

OpenHuman 核心可以通过一个进程服务多个用户。每个用户都是一个 profile: 他们自己的配置、凭据、工作区、沙盒和线程,布局与桌面应用的 users/<id>/ 目录。位于核心前方的可信网关对用户进行身份验证,并代表他们调用核心。核心从不看到用户的密码或登录信息;它信任网关的服务令牌以及网关所指定的用户 ID。

本页介绍如何部署该服务。对于希望在没有网关的情况下获得同样隔离效果的 Rust 服务器,其进程内变体是 ProfileRuntime。内部实现在 profiles/README.md.

用户可获得的内容

  • 每个用户一个配置文件。 它会在用户第一次请求时打开,在使用期间保持打开,并在以下情况下关闭: idle_evict_secs 处于空闲状态后(或者当 max_profiles_open 达到上限且它是最近最少使用的空闲项时)。

  • 每个会话、每个界面各一个线程。 Web 聊天线程由用户命名(t1, work-notes);网关从托管平台(Telegram、iMessage、Discord)转发的消息会落到该用户的 channel:<platform>/<sender>/<chat> 线程中。线程 ID 在每个配置文件内都是唯一的,因此两个用户的 t1 永远不会相遇。

  • 经过审核的接口面。 用户的请求只会到达用户方法:他们的线程、Web 聊天(启动、取消、队列控制)、频道转发,以及对自己记忆的读写。其他一切都会以未知方法作答。

  • 他们自己的事件。 GET /events?client_id= 只会流式返回该用户的聊天进度、最终回复以及转发的 channel_outbound 回复。

  • 关闭的宿主工具。 独立版 SaaS CLI 不会暴露任何文件或 shell 工具,即使当 host_files 或 host_shell 位于 tool_allowlist中也是如此。嵌入式宿主可以提供配置文件工具适配器;允许列表限制这些适配器可以暴露哪些宿主工具组。

运维配置

核心在 SaaS 模式下从运维自己的 TOML 文件运行,绝不会从用户的 config.toml:

openhuman-core run --mode saas --saas-config /etc/openhuman/saas.toml
root = "/srv/openhuman"              # 绝对路径、已存在、不可被所有人写入
# service_token_file = "/srv/openhuman/service.token"   # 默认值
max_profiles_open = 256              # 本节点同时打开的配置文件数
idle_evict_secs = 1800               # 在空闲这么久后关闭配置文件
profile_ids = "raw"                  # 或 "hashed"
require_user_signature = true        # 每个用户请求都需要 X-OpenHuman-User-Sig
tool_allowlist = []                  # 仅用于准入;CLI 没有宿主工具适配器
shared_backend_api_key = true        # 让每个用户共用 OPENHUMAN_BACKEND_API_KEY
custom_definitions = false

# 集群设置(见下文)
# storage_url = "mongodb://db.internal/openhuman"   # OPENHUMAN_STORAGE_URL 优先
# node_id = "node-a"                                # 否则用 OPENHUMAN_NODE_ID,再否则随机
# advertise_url = "http://10.0.0.11:7788"           # 将该节点标记为集群节点
# lease_ttl_secs = 30
# operator_dir = "/var/lib/openhuman/node-a"        # 默认 <root>/operator

[sandbox]                            # 由嵌入式宿主提供的 host_shell 策略
image = "alpine:3.20"
network = "none"
memory_limit_mb = 512
cpu_limit = 1.0

tool_allowlist 是准入策略,不是工具安装器。它识别的组有 host_files 和 host_shell。要暴露这些工具,请使用带有配置文件工具适配器和权限回调的嵌入式宿主。将任一组添加到独立 CLI 配置并不会使这些工具可用。 host_shell 当该组被加入允许列表时,Docker 启动检查仍然适用。

未知键会被拒绝。启动守卫在根目录为相对路径、缺失、可被所有人写入,或位于 ~/.openhuman;当服务令牌缺失、可被他人读取或短于 32 字节时;当设置了单用户变量(OPENHUMAN_WORKSPACE, OPENHUMAN_CORE_TOKEN, OPENHUMAN_DEV_CONNECT, OPENHUMAN_BACKEND_SESSION_TOKEN)或者某个保护被关闭(OPENHUMAN_APPROVAL_GATE, OPENHUMAN_SANDBOX);当 host_shell 在没有可用 Docker 的情况下被列入允许列表;以及当集群节点没有能够保持租约独占的存储后端时。

只写入一次服务令牌,仅所有者可读写:

网关契约

每个请求都携带服务令牌。针对用户的请求还会指定该用户并对该名称签名:

  • 没有 X-OpenHuman-User 时,请求会运行在 运维平面: profiles.provision, 取消配置, list, status, set_credential, clear_credential 和 release (openhuman.profiles_* ,通过 JSON-RPC)。

  • 有了它,核心会按顺序检查:持有者令牌(401),重复或无法读取的用户头(400),签名必须与核心时钟相差不超过 60 秒(401),以及用户的配置文件,且该配置文件必须已预配置(403)。节点已满或存储故障会返回 503.

  • 用户的 TinyHumans 凭据(会话 JWT 或 API 密钥)通过 profiles.set_credential只需传入一次;核心会将其用于该用户的推理和后端调用,且绝不会验证或回显它。

最小签名器:

配置文件 ID

使用 profile_ids = "raw",匹配的用户 ID ^[a-z0-9][a-z0-9_-]{0,63}$ 会原样作为配置文件 ID(本地, 运维 和 h-* 是保留项);任何其他 ID 都会变成 h-<32 hex of sha256(user id)>. "hashed" "hashed" 会对每个 ID 进行哈希,这样可以让你的用户 ID 不出现在路径和日志中。更改模式会把用户映射到新的空配置文件。

转发托管聊天平台

网关拥有各个平台的 webhook 以及用户的账号关联。对于每条入站消息,它都会以该用户身份调用:

答案会立即返回(已接受, thread_id, request_id);一个 message_id 已记录的消息 ID 会返回 duplicate: true ,并且不会执行任何操作,因此重试是安全的。回复会以事件流的形式到达用户的 /events?client_id=channel-relay 流,作为一个 channel_outbound 携带 full_response 以及 channel 和 chat_id 以将其送达。

单节点

在单节点部署中,保持 storage_url 和 advertise_url 不设置。配置文件注册表是 profile.toml 位于以下路径下的文件: <root>/users/,且每个配置文件的租约都是对以下文件的文件锁: <root>/users/<id>/.lease,这也会阻止同一根目录上的第二个进程打开同一个配置文件。

集群

多个节点可以服务同一用户群。每个配置文件在任一时刻都只由一个节点托管,这由 租约 在共享存储后端中强制保证;任何节点都可以托管任何配置文件。

  1. 一个存储后端。 将 storage_url (或 OPENHUMAN_STORAGE_URL)设置为一个在进程间具有原子比较并交换的驱动:MongoDB(mongodb://…/<db>, storage-mongodb 构建特性)用于分布在多台主机上的节点,或者 SQLite(sqlite:<path>, storage-sqlite)用于同一主机上的多个进程。不要把 SQLite 放在网络文件系统上。它保存着配置文件注册表、租约、会话存储,以及每个配置文件的记录(密钥、认证配置文件、审批、cron、流程),位于作用域 profile:<id>.

  2. 一个共享卷,用于 root. 线程文件、成本和运行账本、后台完成项以及每个用户的 sandbox/ 仍然是以下路径下的文件: <root>/users/<id>/。将 root 挂载到每个节点上的读写多节点卷(NFS、EFS、CephFS)上。把内存放在远程引擎中:配置文件使用托管的 TinyHumans 内存引擎,它不需要卷。

  3. 每个节点一个唯一且稳定的 node_id 节点 ID, 以及一个 advertise_url 网关可以通过它访问的 advertise_url 端点。设置该项会将节点标记为集群节点;启动守卫随后会要求使用跨进程后端。稳定的节点 ID 让重启后的节点能够立即取回自己的配置文件。

  4. 自己的 operator_dir 节点 ID, ,这样共享同一根目录的节点就不会共享运维工作区和密钥环。

路由与 409

对用户进行粘性路由:将用户 ID 哈希到某个节点上(使用一致性哈希可在节点增减时让大多数用户保持不变)。粘性只为速度;正确性由租约保障。当请求到达某个节点,而另一个节点持有该用户的配置文件时,核心会返回:

网关应将请求转发到 端点 (并更新该用户的路由),或者当 端点 为空或不可达时,在以下时间后重试: retry_after_ms。 409 是在持有者令牌检查之后才返回的,因此未认证的调用方无法获知哪些用户存在。

若要有意迁移某个用户(清空节点、重新均衡),请调用 profiles.release {"profile_id": ...} 由持有该配置文件的节点执行。该操作会在配置文件使用中时拒绝;稍后重试。

故障切换与恢复

  • 持有者会每隔租约时长的三分之一续租一次 lease_ttl_secs。崩溃或失去后端的节点会停止续租,其配置文件在租约到期后会对其他节点可用(最多 lease_ttl_secs,默认 30 秒)。

  • 接管从未释放过的租约的节点,会在提供服务前恢复该配置文件:正在进行中的轮次会标记为中断,孤立的运行账本行会被结清。干净的交接(空闲驱逐、释放、关闭)不会恢复任何内容。

  • 如果某个节点发现自己的租约在其之下发生变化(另一个节点接管,或运维人员释放了它),它会对该配置文件实施隔离:停止该配置文件正在运行的轮次,并且不再启动新的轮次。

  • 在正常关闭时,节点会立即释放其空闲配置文件的租约;仍在忙碌的配置文件会保留租约,因此其下一个持有者会恢复其轮次。

已知限制:存储写入不携带代际隔离,因此一个与后端分区但仍在运行的节点,可能会在租约过期后短暂写入。请将 lease_ttl_secs 设置得远高于网络抖动,并将每轮前的隔离检查以及失去租约时的轮次取消视为缓解措施。

检查清单

  • root 绝对路径,且不可被所有人写入,位于共享 RWX 卷上(集群)。

  • service.token mode 0600,至少 32 字节,仅与网关共享。

  • 网关签名 X-OpenHuman-User 并保持时钟同步(±60 秒)。

  • storage_url 使用 MongoDB(或同一主机上进程使用 SQLite),并启用相应的构建特性(集群)。

  • node_id, advertise_url 和 operator_dir 每个节点唯一(集群)。

  • 负载均衡器对用户进行粘性哈希,并遵守 409 重定向。

  • 为用户预配置(profiles.provision)并安装其凭据(profiles.set_credential)后,再让其发起首次请求。

最后更新于