1. GPUWorks 的安装包里有什么？

安装之前，先了解一下 GPUWorks 的安装包（40+ MB）都有什么。

总大小只有 40+ MB 的 GPUWorks 的安装包由控制面 Server 和节点 Agent 两部分组成。

1. 控制面 Server：提供 Web 控制台和模型服务网关，负责节点接入、模型与部署管理；

2. 节点 Agent：安装在 GPU 主机上，主动连接控制面并上报算力。

GPUWorks 的控制台和 API 默认监听 8800 端口。节点 Agent 从节点侧发起连接，因此只需要节点能访问控制面，不必在节点上开放入站端口。这个设计也决定了升级的影响范围：升级只替换控制面，节点上已经运行的推理容器和模型不受影响。

首次部署 GPUWorks 的重点，是把控制面跑起来，并确认节点能够访问它。

本文按安装、验证、升级三段展开，命令与默认值以 release-26.11 文档[1] 为准。

2. 安装的前置条件

安装 GPUWorks 的前置条件要求并不高，常见的 Linux 和 Apple 设备都可以。

项目	要求
操作系统与架构	linux-amd64；Apple 芯片 Mac 使用 macOS 15+ 的安装包
磁盘	安装目录所在文件系统至少 2 GiB 空闲
端口	默认 8800 未被其他进程占用
权限	注册 systemd / launchd 服务需要 root 或 sudo；没有 sudo 可装到用户目录

注意：主机不能联网时，先在可联网的机器下载发布包再拷入；节点必须能访问控制面的监听地址。

3. 三种安装方式

GPUWorks 提供了 AI 助手安装、一键安装和手动安装 三种方式实现快速部署。

3.1 AI 助手帮你装

在 GPUWorks 的 GitHub Readme 中专门准备了适合 AI 编程助手（WorkBuddy、CodeX 等）识别安装的提示词：

在这台主机上安装 GPUWorks 控制面并验证。
1. 执行 `bash <(curl -fsSL https://dl.gpuworks.ai/get.sh) --quiet`：它会下载最新构建、校验后安装为监听 8800 端口的服务
   （需要时用 sudo）。如果我没有 sudo 或没有 systemd，在命令后追加 `--dir ~/gpuworks-server --no-systemd`。
2. 用 `curl -fsS http://<监听地址>/healthz` 验证（应包含 "status":"ok"），并把安装摘要告诉我：访问地址、
   安装目录、数据目录，以及 admin 初始密码存放在哪。
3. 不要开防火墙端口、不要改动其他服务、不要接入 GPU 节点。告诉我 GPU 节点应该用哪个地址访问 server，
   节点我会在 Web 界面里自己加。

只需将提示词或 GitHub 地址（https://github.com/flitai-io/gpuworks/）丢给 AI 编程助手即可完成安装。

3.2 一键安装/脚本安装

在目标主机（Linux 或 Apple 芯片 Mac）的终端执行：

bash <(curl -fsSL https://dl.gpuworks.ai/get.sh)

脚本会挑选响应最快的发布源（中国大陆通常是阿里云 OSS 或华为云 OBS），下载本机平台的发布包并按 SHA256SUMS 校验，然后运行 ./gpuworks install。之后的交互与手动安装完全相同。

脚本参数会原样传给安装程序，例如静默安装：

bash <(curl -fsSL https://dl.gpuworks.ai/get.sh) --quiet

需要滚动预览版时，用 GPUWORKS_CHANNEL=nightly 指定渠道；需要指定发布源时，用 GPUWORKS_SOURCE=<源地址>。还没有 release 版本时，脚本会自动改装 nightly。

3.3 手动安装

需要逐项核对，或主机只能离线拷入发布包时，使用手动安装（以中国大陆的阿里云 OSS 为例）：

src=https://gpuworks-dl.oss-cn-shanghai.aliyuncs.com
id=$(curl -fsSL $src/release/latest)
curl -fLO $src/releases/$id/gpuworks-$id-linux-amd64.tar.gz
curl -fLO $src/releases/$id/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing

校验结果显示 OK 后，在同一终端解压并运行安装程序：

tar -xzf gpuworks-$id-linux-amd64.tar.gz
cd gpuworks-$id-linux-amd64
./gpuworks install

其他可用源：华为云 OBS https://gpuworks-dl.obs.cn-east-3.myhuaweicloud.com，海外 https://dl.gpuworks.ai，三个源提供相同的发布包。把命令中的 release 换成 nightly，即安装滚动预览版。

3.4 安装过程中提示填写安装信息

提问项	默认值与说明
安装目录	默认 /opt/gpuworks/server
监听地址	默认“主机出口 IP:8800”；只填端口时保留默认 IP
是否开机自启	默认 yes
管理员密码	默认随机生成，仅在全新安装时询问

已有安装会沿用现值；已有 admin 账户时不再询问密码；命令行已指定的参数不再提问。使用 --quiet 时，未指定项全部采用默认值。

安装信息摘要

摘要包含访问地址、管理员密码、安装目录和数据目录。默认安装目录是 /opt/gpuworks/server，自定义目录以摘要为准。后面的验证、改密和升级都要用到这些信息。

4. 验证与首次登录

安装完成后做四步，确认控制面真的可用。

4.1 检查健康状态

在控制面主机执行，把 <监听地址> 换成摘要中的 IP 和端口：

curl -fsS http://<监听地址>/healthz

返回的 status 为 ok、version 为当前运行版本，说明服务正常。失败时先查日志和端口。

4.2 登录控制台

浏览器打开摘要中的访问地址，用 admin 和摘要中的密码登录，确认能进入控制台。

4.3 修改初始密码

在实际安装目录执行。systemd 安装先按摘要提示运行 newgrp gpuworks 或重新登录，取得组权限：

./gpuworks reset-password --password '<新密码>'

在 Web UI 界面实现修改初始密码，会在后续的版本中提供。

该命令从二进制同目录的 server.yaml 读取数据目录，也可以用 --data 显式指定。不要把真实密码留在命令历史或日志中。

4.4 重新登录并删除明文凭据

确认新密码可以登录后，删除实际数据目录中的 initial-credentials。该文件保存初始凭据，删除它不会修改账户密码。

注意：上述命令必须使用安装目录中的二进制。安装器不会把它加入 PATH。

到这里，控制面已经可用。下一步是在控制台生成安装命令、接入节点，再部署第一个模型。详见 操作指南[2]。

5. 升级须知

• 升级时服务会短暂中断。 控制台和 /v1 网关不可用；节点上的推理容器和模型不受影响。

• 有备份，回滚有代价。 升级前会自动备份，失败时自动回滚到升级前快照；升级期间产生的新数据可能随回滚丢失。

• 只升级控制面。 已有节点的 Agent 不会自动升级。新 Agent 已内嵌在 Server 中，可在节点页点击升级 Agent，不需要访问发布源。

注意：重复执行 ./gpuworks install 并不是升级。它用于修复服务或切换 systemd/nohup，会替换二进制并重启，但没有升级备份与回滚。

6. 三种升级方式

GPUWorks 提供了三种升级方式，请根据适合的场景选择。

方式	适用场景
控制台升级	控制面能访问发布源，且由 systemd、launchd 或 serve --supervise 托管
命令行升级	能登录主机，希望通过脚本控制升级过程
离线升级	内网环境，或控制面无法访问发布源

6.1 控制台升级

前提是控制面由 systemd、launchd 或 serve --supervise 托管，运行的是安装目录中的二进制，且服务账户可写该目录。不满足时，页面会说明原因并给出处理命令。

1. 以管理员身份进入 设置 → 通用 → 版本与更新，查看服务端当前版本。

2. 选择更新渠道（正式发布版 release 或滚动预览版 nightly），点击检查更新，核对最新版本。

3. 点击服务端行的升级，在确认框中核对目标版本和中断提示，再确认。

4. 等待页面恢复。出现“服务端已升级到目标版本”，且当前版本与目标一致，才算完成。

页面最多等待 5 分钟。超时只说明页面没有等到新版本应答，不等于升级失败或已经回滚。到主机上检查 /healthz 的实际版本和日志，必要时查看实际数据目录中的 install-history.jsonl。

控制面不能访问发布源时，可在同一行点击上传升级包，选择与服务器系统和架构匹配的 gpuworks-<release_id>-<os>-<arch>.tar.gz。选择文件后立即开始上传和升级，不再出现确认框。

自动检测新版本默认开启，检查时会向发布方报告安装规模；关闭后改为手动点击检查更新。

6.2 命令行升级

在控制面主机的实际安装目录执行。systemd 安装先取得 gpuworks 组权限；同一主机有多套安装时，进入要升级的那一套目录。

./gpuworks upgrade --check
./gpuworks upgrade

升级后重新访问控制台或调用 /healthz，确认运行版本与目标一致。命令以非零码退出时按提示处理；探活失败会自动恢复旧版本，备份路径会显示在输出中。已是最新版时以 0 退出，不会重复升级。

使用内网发布站或自建镜像时，用 --base-url 或 --source 替代默认源。先加 --check 核对，再去掉执行：

./gpuworks upgrade --base-url https://releases.example.internal
./gpuworks upgrade --source https://mirror.example.com/gpuworks

渠道中的版本比当前版本旧时默认不降级；确认需要降级或替换本地构建后，才使用 --force。

6.3 离线升级

在可联网的机器下载匹配目标主机系统和架构的发布包，以及同一版本的 SHA256SUMS，一起拷到控制面主机。校验通过后，用 --archive 指定包路径：

sha256sum -c SHA256SUMS --ignore-missing
/opt/gpuworks/server/gpuworks upgrade --archive ./gpuworks-<release_id>-linux-amd64.tar.gz --check
/opt/gpuworks/server/gpuworks upgrade --archive ./gpuworks-<release_id>-linux-amd64.tar.gz

无需解压，流程也不访问发布源。包损坏、架构不匹配或属于本地构建时，会在停服前报错。不要用新包中的 ./gpuworks install 代替升级，那样没有备份和回滚。

7. 安装升级常见问题

Q1：安装或升级后无法访问

查看 <安装目录>/logs/gpuworks-server.log，修复后重试，并重新核对 /healthz。

Q2：提示 cannot listen on :8800

端口被占用。先用 systemctl status gpuworks 确认是否为旧服务，不要直接重复安装。

Q3：提示 create /opt/gpuworks/server needs root

使用有 sudo 权限的账户，或改为 --dir ~/gpuworks/server --no-systemd。

Q4：改密或升级报权限错误

终端可能还没取得 gpuworks 组权限，执行 newgrp gpuworks 或重新登录。

Q5：控制台升级超时或失败

查看服务日志和 install-history.jsonl，再核对 /healthz；不要只凭页面超时判断回滚。

Q6：发布索引签名校验失败

检查服务端出网代理、网关或登录拦截；暂时可用匹配的本地升级包。

Q7：提示渠道尚无版本

换到已有发布的渠道，或等待该渠道发布后重新检查。

Q8：无法连接发布源

检查服务端出网与代理；改用上传升级包或离线升级。

更多问题提问，欢迎加入 GPUWorks 社区用户交流群交流（下方扫码）。

参考资料

[1] CLI 参考: https://gpuworks.readthedocs.io/release-26.11/reference/cli/

[2] 部署节点: https://gpuworks.readthedocs.io/release-26.11/how-to/connect-nodes/

加入社区

GPUWorks 的开源之路才刚刚开始。无论你是 AI 开发者、基础设施工程师，还是硬件厂商，都欢迎参与进来，尝试不同的模型与算力组合，分享使用经验，反馈问题，与我们一起完善 GPUWorks。

 体验 GPUWorks，参与开源共建！🎉欢迎加入第一期社区实践征集活动！

GPUWorks 第一期社区实践征集活动启动！

• GitHub：http:// https://github.com/flitai-io/gpuworks/

• 文档站：https://gpuworks.readthedocs.io

  欢迎关注 FlitAI！

让算力自由流动

ZStack 旗下的 AI Infra 品牌，相信基础设施应该开放、解耦、按需组装