StudioForge 2.0：账户管理、限定范围的 API 密钥以及安全的升级路径

StudioForge是我编写的仅支持GPU的模型服务器，旨在取代我电脑上的LM Studio（详细情况请参见原始介绍文章）。版本2.0改变了哪些用户能够访问该服务器。在0.2.0版本中，它会监听所有网络接口，并信任任何能够连接到它的客户端；仅对代理工具设置了可选的PIN码验证机制。而在2.0版本中，除非特意配置，否则它只会在本机上监听请求；一旦启用远程访问功能，所有调用者都必须提供密钥才能连接。

GitHub源代码

我在2026年10月19日对自己的电脑进行了升级。此后几分钟内，所有未提供密钥却试图调用该服务器的程序都返回了 401 错误：包括我的邮件工具、聊天应用、代理网关的记忆搜索功能以及若干脚本。这些程序本身并无任何问题，只是尚未配置对应的访问密钥罢了。这篇文档正是我希望在升级前就能读到的内容。

对您而言有哪些变化？

简单来说，有三点变化。

• 默认情况下为私有状态。 网关（端口1234）、控制面板（端口8080）以及恢复监控程序（端口1235）均绑定到 127.0.0.1。其他机器根本无法访问它们。
• 若要对外开放，必须登录。 如果上述三个服务中的任何一个监听了网络地址，但系统中既没有所有者账户也没有管理员密钥，那么 studioforge serve 会以退出码4终止运行，并提示您如何修复此问题。这样就能避免意外地运行一个开放式的服务器了。
• 每个程序都有专属密钥。 这个密钥是一个类似 sf-i-… 的字符串，程序需将其作为 Authorization: Bearer <key> 发送出去。每个密钥都配有名称、作用域、可选的有效期以及每分钟请求次数限制；您也可以单独撤销某个密钥而不会影响其他密钥。

以下是我进行的测试结果：我将所有主机地址均设为 0.0.0.0，且未创建任何账户，结果服务直接被拒绝访问：

error: Refusing to start: the gateway, the control panel, the watchdog would listen on a
non-loopback address (0.0.0.0, 0.0.0.0, 0.0.0.0) but no owner account or admin API key exists,
so anyone on the network could drive this server. Fix: run `studioforge setup` (creates the
owner account) or `studioforge keys create --name admin --scope admin`, then start again.

有一个细节让我吃了亏：创建第一个密钥后，所有用户（包括同一机器上的程序）都需要经过身份验证才能访问。 我在一台仅允许本地访问的测试服务器上创建了一个密钥；随后从同一台机器上使用 curl 请求 /v1/models，返回状态码立刻从 200 变成了 401。不过 StudioForge 的命令行工具、系统托盘程序及控制面板仍能正常工作，因为它们各自拥有专属的本地管理员密钥（即 local-cli，该密钥仅所有者可访问且存储在数据目录中）。除此之外，其他程序此后都必须使用相应的密钥才能访问服务。

十分钟安全升级指南

以下步骤可确保服务中断时间最短。这些步骤遵循 CHANGELOG 中描述的迁移流程，其中包含了我在实际操作中修正的两处内容。

1. 列出所有客户端。 包括所有聊天应用、代理程序、脚本以及其他会向服务器发送请求的机器。如果不确定，可通过 grep 命令搜索它们的配置文件以找出服务器地址。这份列表就是整个升级工作的基础。
2. 备份并预览。 复制数据目录，更新代码（执行 git pull，然后按照 README 中针对您所用平台的说明重新安装到虚拟环境中），接着运行 studioforge migrate --dry-run。版本 2.0.1 会将数据库升级至 schema 10，而 studioforge migrate 会在执行前自动完成备份。
3. 创建用于启动服务器的凭证。 可以运行 studioforge setup（这是引导式初次设置流程；它会创建管理员账户，若您选择“我的本地网络”选项，还会启用 HTTPS 并生成管理密钥）；或者直接执行 studioforge keys create --name admin --scope admin。
4. 在启动新服务器前，一次性为所有客户端生成密钥：

   studioforge keys create --name chat-app  --scope inference --rate-limit-rpm 120
   studioforge keys create --name dashboard --scope read
   studioforge keys create --name laptop    --scope admin --expires-in-days 30

   每个密钥仅会输出一次且不会被保存，因此请立即将其粘贴到对应客户端的配置文件中。
5. 启动服务器后，对每个客户端发送一次真实请求以测试。 若出现 401 invalid_api_key 错误，说明该客户端尚未获得密钥；若出现 403 permission_denied 错误，则说明其密钥的权限范围不足以满足当前操作需求。
6. 最后再废弃旧凭证。 当所有客户端都能正常使用各自的新密钥后，执行 studioforge keys revoke legacy，清除 server.api_key 的值并关闭 MCP PIN 功能。详见下方的关于 PIN 的注意事项；仅清除 PIN 值并不足以完成操作。
7. 运行 studioforge doctor 并检查输出结果。

如果您之前已使用过 server.api_key，此次升级也不会造成任何问题：旧密钥会被自动复制为名为 legacy 的管理员密钥并继续生效。不过我的测试环境中并未设置共享密钥，仅有 PIN 功能；因此所有客户端在升级后都立即出现了故障。若能在执行第 5 步之前先完成第 4 步操作，便可避免大部分此类问题。

控制面板：登录、设置与创建密钥

这些截图来自我在没有 NVIDIA GPU 的机器上通过 Podman 运行的 2.0.1 测试实例（详情见 下文）。因此图中的两张显卡均为模拟生成，那些密钥实际上也毫无用处。

现在控制面板上有了登录页面。您可以使用拥有者用户名与密码登录；也可以不填用户名而直接粘贴管理员密钥。不过使用 read 或 inference 权限的密钥则无法打开该面板。

位于 /setup 的设置向导共包含八个步骤：创建拥有者账户、配置硬件、设置引擎、添加模型库、选取初始模型、进行测试对话、获取客户端示例代码，以及设定允许访问服务器的对象。所有步骤均可跳过。最后一步则用于选择“仅本机可访问”或“通过 HTTPS 允许局域网内访问”。

所有密钥均存放在 用户与密钥 页面下。请为密钥起一个能表明其用途的名称，选定其作用范围，还可按需设置过期时间及请求频率限制。

生成的密钥令牌只会显示一次。虽然我在截图中将其隐藏了，但在真实服务器上该对话框便是您唯一能看到该令牌的机会。

下方表格列出了每个密钥的作用范围、前几位字符、最后使用时间、过期时间、请求频率限制及其当前状态。表格之下则是审计日志：记录着所有密钥的创建与撤销情况、每次登录行为及管理员所作的任何更改，还包括操作人及其来源信息。不过任何敏感机密内容均不会出现在该日志中。

权限范围：read、inference、admin

权限范围	具备的能力	可授予的对象
read	可查看状态信息、模型列表、/metrics 数据以及所有只读类的 MCP 工具。但无法执行任何 POST 操作。	仪表盘、监控系统
inference	具备 read 权限，还能进行聊天操作（/v1/chat/completions、/v1/messages、/v1/responses），也可加载、卸载及测试模型，还能获取或释放对应的 GPU 资源。	聊天应用、智能代理程序、脚本及其他需要使用 GPU 的程序
admin	可修改系统设置、执行重启操作、安装/更新引擎、下载或删除相关数据、管理密钥与账户信息、查看审计日志以及使用具有破坏性的 MCP 工具。	仅限管理员本人

权限控制由代码决定，而非约定俗成的规则（具体见 api/auth.py:required_scope）。系统会根据路径前缀来匹配相应的权限；任何未被明确归类的状态修改类路由均需要 admin 权限，因此新添加的路由也会自动受到此规则约束。无论服务器是否需要特定权限，只要发送了密钥就必须经过权限校验：即便是在仅允许本地访问的服务器上，拥有 read 权限的密钥同样无法执行 POST 操作。我在测试实例上做了验证：使用 inference 权限的密钥访问 /v1/models 时返回了 200 状态码；而访问 /api/keys 时则返回了 403 错误。

智能代理程序同样可以获取专属密钥，只是绝不会获得管理员密码。在控制面板的“集成”页面中，系统会提供可直接复制使用的配置代码块，适用于 OpenClaw、OpenAI 与 Anthropic 的 Python SDK、DisPatch、curl 工具以及 Claude 所需的 --mcp-config 配置文件。使用时需先从下拉菜单中选择对应的密钥：若选择的是占位符选项，生成的 curl 代码块中会省略 Authorization 请求头，此时直接粘贴运行便会返回 401 错误。

所有者账户、旧版共享密钥以及PIN码

2.0版本有三种凭证类型，其中两种即将被淘汰。

• 所有者账户用于登录控制面板。密码长度必须至少为10个字符，且会以 argon2id 算法进行哈希处理。如果安装了可选的 keyring 扩展组件，该哈希值会被存入操作系统的密钥环中；否则则保存在仅所有者可访问的文件中。该密码不会存储在数据库中，因此即便数据库被复制，也无法用于登录。
• server.api_key（已弃用）仍可作为管理员凭证在任何地方使用，此时它显示为 legacy 类型的密钥；而执行 keys revoke legacy 操作后该密钥即会被彻底禁用。
• mcp.pin（已弃用）是一个由8位数字组成的管理员凭证，仅适用于 MCP 接口。即便服务器上没有其他任何密钥，它仍能允许远程调用者访问那些用于修改配置的 HTTP 接口，因此旧版配对信息仍可正常使用。不过一旦存在其他作用域受限的密钥，此功能便会失效。

关于 PIN 码的陷阱。 更新日志中要求“清除 server.api_key 和 mcp.pin”。不过，如果你只设置了 mcp.pin: null 而其他设置保持不变，下次启动时系统仍会生成一个新的随机 PIN 码并将其写入，因为 mcp.pin_required 的值仍然是 true。我亲眼目睹了这一过程。要想彻底禁用 PIN 码，必须同时设置这两项才行。

mcp:
  pin: null
  pin_required: false

同样的逻辑意味着：全新安装的 2.0.1 版本在首次启动时会生成一个 PIN 码，而 studioforge doctor 随后会将其标记为已过时。虽然并无危害，但遇到这种情况也无需感到意外。

绑定设置、HTTPS与浏览器

• 绑定规则。 server.host、gui.host 以及 watchdog.host 的默认值均为 127.0.0.1。旧版本生成的配置文件中明确指定了 0.0.0.0，因此新的默认值不会更改该设置：在您添加相应凭证之前，此类配置仍会阻止连接请求。
• HTTPS。 server.tls.mode 这一参数控制着所有三个监听器的加密行为：可设置为 off、self_signed（系统会在数据目录中自动生成证书，其 SHA-256 指纹也会显示在界面上以供客户端验证），或者 cert（使用您自行提供的证书文件）。若启用了网络绑定但关闭了 TLS 加密，doctor 会发出警告：此时密钥信息会以明文形式在网络中传输。不过，在前面配置反向代理或启用 tailscale serve 亦可解决问题。
• 浏览器。 现在 server.cors_origins 的默认值为空（之前为 ["*"]）。非浏览器客户端对此并无要求。MCP 端点还会额外执行 Origin 验证：带有 Origin 请求头的请求必须源自本地回环页面或预先设定的允许源地址；即便配置了 * 也不被视作有效来源。这一机制可有效防止任意网页通过浏览器操控您的设备管理工具。
• 暴力破解防护。 对于同一客户端地址，系统允许三次错误的凭证输入尝试；之后等待时间会成倍增加，最长可达五分钟。此限制分别适用于 API、管理界面以及看门狗服务。

GPU共享机制：租约与租户

如果服务器上还有其他程序需要使用GPU（比如图像生成器、语音服务器或基准测试程序），这些程序可先获取对某块GPU的租约。此时StudioForge不会在该GPU上加载任何模型，直到租约被释放或超时为止。2.0版本新增了租户注册机制，这样这些程序就能在“Placement”页面上显示自身状态；此外还引入了 devices: "auto" 参数，允许租户请求任意一块具备足够空闲内存的GPU，而无需指定具体编号。StudioForge能够识别各个租户，并可指示它们预热或释放GPU资源，但无法直接启动或停止这些程序。

2.0.1版本的修复非常重要：在2.0.0版本中，租户端路由功能需要 admin 密钥才能运作；因此那些使用 inference 密钥的语音或图像服务器在尝试获取租约时均返回了 403 错误。2.0.1版本中这些路由变为 inference 路由，且每个租约都与创建它的密钥绑定：其他 inference 密钥无法释放该租约（我亲自试过，结果收到 “lease … was not created by this API key” 的 403 permission_denied 错误）；而 admin 密钥仍可执行此操作。

指定租户名称时需注意：系统会依据“家族名”来匹配租约与租户，所谓“家族名”即从租户名称中截取到第一个 - 符号前的部分。例如，若注册的租户名为 speech-demo，它便无法看到属于自己的 speech-demo 租约（该租约的家族名实为 speech）；而若注册名为 speech，则能正常匹配。因此请务必使用不含连字符的租户名称。相关协议细节可查阅代码库中的 docs/TENANTS.md 文档。

sfctl 2.0.1：远程控制工具

sfctl是一款小型客户端程序，用于从另一台机器上操控 StudioForge 服务器，同时它还充当 MCP 与各代理之间的桥梁。现在使用时需要提供密钥。该工具并未发布在 PyPI 上（其 README 中的 uv tool install studioforge-companion 命令无法正常运行），因此需通过代码克隆的方式来安装：

git clone https://github.com/LaserLloyd/StudioForge.git
uv tool install ./StudioForge/packages/studioforge-companion
sfctl servers add rig http://192.0.2.10:1234 --api-key sf-i-your-key --use
sfctl status

配置文件应保存于 ~/.config/studioforge/companion.toml 路径下；由于该文件包含密钥信息，故仅允许所有者进行读写。SF_API_KEY 也可作为环境变量来使用。如果网关并非运行在 1234 端口上，则需添加 --watchdog-url 参数，因为看门狗服务的地址是由网关地址推导而来的。以下是我在自己的测试实例上的配置示例，其中使用了 inference 类型的密钥：

$ sfctl status
┏━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━━━┓
┃ GPU ┃ Name                           ┃ Total    ┃ Used ┃ Free     ┃
┡━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━━━┩
│ 0   │ Demo GPU 0 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
│ 1   │ Demo GPU 1 (simulated) (sm_86) │ 24.0 GiB │ 0 B  │ 24.0 GiB │
└─────┴────────────────────────────────┴──────────┴──────┴──────────┘
no models loaded

$ sfctl leases add --devices 1 --holder image-render --reason "a render job outside StudioForge"
lease 933d9554c0c6 holds GPU 1 for image-render
release it with: sfctl leases release 933d9554c0c6

（为便于阅读，我删减了 Util 与 Temp 列以及服务器相关表格的内容。）

Doctor工具与支持包

studioforge doctor会检查端口、GPU、引擎、磁盘、文件权限、证书、数据库迁移情况以及身份验证设置，并针对每个问题给出修复建议。--strict参数则会在出现警告时也以非零状态码退出，这一特性非常适合用于监控。这是一个演示用容器：它通过网络监听请求，使用管理员账户且未启用TLS加密。

[ok  ] GPU: 2 GPU(s) via fake: Demo GPU 0 (simulated) (24 GiB), Demo GPU 1 (simulated) (24 GiB).
[WARN] Engine: No llama.cpp engine is installed.
        fix: Run `studioforge setup` or `studioforge engine --update` to install and smoke-test one.
[ok  ] Permissions: The data directory is writable and credential files are owner-only.
[ok  ] Migrations: The database is at schema 10 (current).
[info] Authentication: The server listens on the network and requires an API key or an account.
[WARN] Authentication: The network listeners use plain HTTP, so keys and passwords cross the network in the clear.
        fix: Set server.tls.mode to self_signed (or cert), or front the server with a TLS reverse proxy / `tailscale serve`.
[info] Authentication: mcp.pin is set. It is deprecated and grants admin on the MCP endpoints.

9 ok, 3 info, 2 warnings, 0 failures.

在仍设置了 server.api_key 的本地测试服务器上，运行相同命令后会显示警告：“server.api_key 仍被设置。虽然它目前还能正常使用（作为管理员密钥‘legacy’），但该用法已不推荐使用”。对应的修复措施为：创建具有特定权限范围的密钥、将相关客户端迁移至新密钥体系，并撤销 legacy 密钥的权限。

studioforge support-bundle会生成一个用于提交错误报告的压缩包：其中包含经过脱敏处理的配置文件、Doctor工具的检测结果、各组件版本信息、GPU列表以及日志片段。我的测试包大小仅为6 KiB，其中的PIN码被显示为 [REDACTED]。该工具还对 engine.pinned_tag（即 llama.cpp的构建版本号）进行了脱敏处理；其实这一信息在错误报告中很有用且并不属于机密内容，因此需要手动将其还原。该命令本身也提示“分享前请先确认内容”，此提醒确实很有必要。

在容器中运行

2.0版本提供了包含CUDA、ROCm及Vulkan版本的Dockerfile，还设置了非root用户、只读的根文件系统以及一个命名卷。此外还有适用于Docker和Podman的编排文件。当首次使用新的卷启动容器时，系统会根据 SF_OWNER_PASSWORD 的值或保存在卷中的随机生成的密码来创建管理员账户——因为容器内开放的端口被视为“超出回环接口范围”。除非设置了 SF_BIND，否则端口默认会绑定到 127.0.0.1。

目前这些镜像尚未上传至任何镜像仓库（如今尝试拉取 ghcr.io/laserlloyd/studioforge 会被拒绝），因此你需要自行构建镜像；README文档中提供了各平台对应的具体命令。为了拍摄这些截图，我使用Podman构建了Vulkan版本的镜像：其大小仅为568 MB，且以只读模式运行，所有功能均被禁用。只有NVIDIA版本的镜像能够成功运行真正的模型；AMD和Vulkan版本的镜像虽然能正常启动并响应 /health 请求，但尚未在AMD或Intel硬件上实际运行过。关于镜像大小、GPU相关配置参数、升级兼容性测试以及整个系统的备份方法等内容，详见 Docker中的各个模块，此处就不再赘述了。

2.0版本的其他新特性

• 更多客户端无需修改即可使用： LM Studio的原生REST API位于 /api/v1；兼容Anthropic协议的 /v1/messages（此时 x-api-key 或 Bearer令牌均可使用）；此外还有无状态模式的 OpenAI API /v1/responses。
• 错误提示会指导用户如何修复： 共有76种错误代码，每个错误信息中都包含 fix（修复方法）与 docs（相关文档链接）。当未提供API密钥的客户端遇到 401 错误时，系统还会提示生成密钥所需的命令。
• 理论上支持更多硬件平台： 系统可检测 ROCm、Vulkan及Metal架构的GPU；安装程序还能识别后端类型并校验存档文件的完整性。不过这些测试仅基于模拟数据，并未在真正的AMD或Apple硬件上进行验证。另外，像 llvmpipe这样的软件实现的Vulkan设备会被拒绝使用——因为StudioForge的目的正是防止用户只能在CPU上运行模型的情况发生。
• 界面面板有所扩展： 现在共有11个功能板块（概览、模型管理、服务配置、引擎设置、部署选项、集成方案、用户与密钥管理、更新信息、日志与指标监控、诊断工具以及高级设置），还新增了三种主题可供选择。
• 语义化版本控制： 2.0.0版本对应之前的日历版本1.26-09-23；更新程序也能正确处理这两种版本命名方式。

我是如何测试的，以及哪些内容未测试

我用来测试的机器上没有 NVIDIA GPU，因此无法加载模型。StudioForge 为其测试套件提供了模拟的 GPU 后端（通过设置 SF_GPU_PROBE=fake，并在 SF_FAKE_GPUS 中指定显卡列表来实现）。面板、密钥管理、账户管理、租约管理、租户管理以及技术支持相关功能均在该模拟环境下运行。所有标有“我已尝试”或显示输出结果的测试都是在 2.0.1 版本上进行的：一次是在临时目录中的代码副本上执行，另一次则是在 Podman 容器中执行；两次测试均使用回环端口，所用的模型文件仅包含头部信息而无实际权重数据。面板中显示的模型尺寸与量化参数均为真实的头部信息值，但模型本身并不存在。

我未在此处测试的内容包括：模型的加载与服务功能、self_signed 模式下的 TLS 配置、Windows 系统托盘功能，以及从 1.26 版本数据目录进行的原地升级（关于同一存储卷上的升级操作，可参阅 Docker 相关文档）。文首提到的升级经验源自我的实际测试环境，而非临时测试实例。

尚待完善之处

• 尚未发布正式版本。 目前 2.0.1 版本仅存在于 main 分支中，没有打标签，也没有任何 GitHub 发布记录、PyPI 包或已发布的镜像文件。在正式版本问世前，自动更新功能也无内容可更新。
• 具有误导性的警告信息。 在一台拥有管理员账户但缺少 server.api_key 设置的联网服务器上，“概览”页面的设置检查清单仍显示该服务器“无需 API 密钥即可访问：局域网内的任何人都能加载、卸载及删除模型”。但实际上并非如此：用户与密钥管理页面以及实际请求均表明必须登录才能操作。该检查清单仅依据旧版的共享密钥进行判断。
• 文档中对容器引擎的描述不一致。 README 中推荐的 Docker 安装方式会使用大小为 14 GB 的 -cuda-devel 镜像，并在首次启动时编译 llama.cpp；而容器使用指南则指出较小的 -cuda 镜像会直接下载预先编译好的引擎。由于我没有 NVIDIA 显卡，无法验证哪种方式才是正确的；在两者描述达成一致前，建议按照 README 的说明操作。
• 尚未经过第三方安全审计。 系统的安全机制详见仓库中的 docs/SECURITY.md 文件，其中也列出了系统无法防范的情况（比如同一台机器上的管理员权限滥用、在不受控制的网络中使用明文 HTTP 传输）。在将 StudioForge 部署到共享网络中之前，请务必阅读该文档。

获取方式

git clone https://github.com/LaserLloyd/StudioForge.git

</>

之后请参照对应平台的说明文档进行操作。在 原始文章 中提供的旧版压缩包版本为 0.2.0，其中并不包含上述功能。许可证类型：MIT。

相关链接：StudioForge：仅使用 GPU 的 LLM 服务器（包含规划说明、各项指标数据以及 MCP 工具），在 Docker 中运行各个模块（整个技术栈的容器化部署方案），以及 DisPatch（一款可通过密钥连接至该服务器的聊天应用）。