Question 1

如何修复 ShellHub Go 镜像中的 CVE-2026-78667 和 CVE-2026-97031，以及失败的 Trivy 扫描？

Accepted Answer

将每个 Go 构建升级到 Go 1.26.9，该版本包含针对这两个漏洞的修复。将所有 go.mod 文件中的 go 指令更新为 go 1.26.9，将 Go 构建器镜像更改为 FROM golang:1.26.9-alpine3.24，并将 agent Dockerfile 参数设置为 ARG GOLANG_VERSION=1.26.9。在 cloud 仓库中应用相同的更改，并确保 CI 使用 go-version-file，以便作业使用更新后的工具链进行编译。重新构建 server、gateway、openapi、agent 和测试镜像，以及原生 agent 二进制文件。使用现有的 trivy-image 扫描和 govulncheck 验证修复；CVE-2026-78667 和 CVE-2026-97031 不应再被报告。

Question 2

运行 ./bin/docker-compose build 时，如何修复“additional privileges requested: pass --allow=network.host”？

Accepted Answer

从开发镜像构建配置中移除 network: host，并停止通过 Compose 传递模块代理构建参数。

1. 在 docker-compose.dev.yml 和 docker-compose.agent.yml 中，移除 server、ui、openapi 和 agent 的构建级 network: host 行。
2. 移除 GOPROXY=${SHELLHUB_GOPROXY:-} 和 NPM_CONFIG_REGISTRY=${SHELLHUB_NPM_REGISTRY:-} 构建参数。
3. 从 server、agent、gateway、openapi 和 UI 的 Dockerfile 中移除相应的 ARG GOPROXY、ARG NPM_CONFIG_REGISTRY 以及相关的 ENV 行。
4. 在 .env 中移除或保持未设置 SHELLHUB_GOPROXY 和 SHELLHUB_NPM_REGISTRY。
5. 使用默认网络重新构建：

./bin/docker-compose build server

然后 Go 使用 proxy.golang.org，npm 使用其默认 registry，因此 BuildKit 不再需要 network.host 权限。如果你需要代理，请在容器的运行时环境中设置 GOPROXY 或 NPM_CONFIG_REGISTRY，而不是将其作为构建参数注入。

Question 3

将 uptrace/bun 升级到 v1.3.0 后，如何修复“cannot use count (variable of type int64) as int value”？

Accepted Answer

将两个 Bun 模块升级到 v1.3.0，并在 PostgreSQL 存储边界处转换类型：

go get github.com/uptrace/bun@v1.3.0
go get github.com/uptrace/bun/dialect/pgdialect@v1.3.0
go mod tidy

在 Bun v1.3.0 中，Count 和 ScanAndCount 返回 int64，而 Limit 和 Offset 接受 int64。在适配现有的 int 存储接口时转换它们的值：

count, err := query.Count(ctx)
if err != nil {
    return 0, err
}
return int(count), nil

对于分页：

query = query.
    Limit(int64(pageSize)).
    Offset(int64((page - 1) * pageSize))

对 ScanAndCount 返回的值应用同样的 int64 到 int 转换。将存储接口、mock 和调用方保持在 int 上，可将更改限制在 Bun 集成层。使用 PostgreSQL 存储集成测试和企业版构建（该构建针对云模块编译 ShellHub）进行验证。

Question 4

如何修复 ShellHub agent 一直重试 '/api/devices/auth' 并报 'namespace not found' 错误的问题？

Accepted Answer

agent 持有的 tenant ID 无法解析到任何已存在的 namespace,因此服务器返回 404,而 agent 按设计会无限重试(namespace "可能尚不存在")。修复方法:1) 使用 `docker logs ` 检查 agent 日志,查找 `failed to authenticate device ... namespace not found` —— 自 PR #7077 起,该日志每 10 次尝试会以 warn 级别记录一次,并包含 tenant 值及其来源。2) 确认 tenant ID 是某个已存在 namespace 的准确 UUID(常见原因是拼写错误,例如在 `TENANT_ID=` 安装中把 `0` 误写成了 `O`)。3) 如果 tenant 来自之前的配对,删除 agent 私钥旁边持久化的 `.tenant` 文件并重新注册 —— 当 `SHELLHUB_TENANT_ID` 未设置时,agent 会静默采用此文件。4) 如果是通过环境变量设置的,更正 `SHELLHUB_TENANT_ID` 并重启容器。5) 升级到包含 PR #7077 和 #7661 的版本:agent 会立即拒绝非 UUID 的 tenant,并且 `install.sh` 现在会以非零状态退出并报告真实的注册结果,而不是对注定失败的注册打印成功信息。注意:对于已删除/不存在的 namespace,语法上有效的 UUID 仍会无限重试;只是现在日志和安装程序会让这一问题可见。

Question 5

如何修复 ShellHub 设备在断开连接后，因排队的心跳延迟到达而显示为在线的问题？

Accepted Answer

将 ShellHub 服务器升级到包含 issue #7401 修复的版本（fix(server): stop a late heartbeat from bringing a device back online）。

竞态条件发生的原因如下：
1. 当隧道注册或收到 pong 时，keep-alive 会被加入队列。
2. heartbeater 每 2 秒刷新一次队列中的心跳。
3. 如果隧道先关闭，OfflineDevice 会设置 disconnected_at。
4. 随后，这条过期的心跳被写入，并无条件地将 disconnected_at 设为 NULL，导致设备在 last_seen 超过在线阈值之前一直显示为在线。

如果维护自定义构建，请进行以下两项更改：

1. 在批处理中按设备保留最新的心跳时间戳，而不是为整个批处理使用同一个时间戳。
2. 仅当心跳时间晚于断开时间时才清除 disconnected_at：

UPDATE devices
SET
  last_seen = $2,
  disconnected_at = CASE
    WHEN disconnected_at > $2 THEN disconnected_at
    ELSE NULL
  END
WHERE uid = $1;

因此，早于 disconnected_at 的心跳会让设备保持离线状态。真正的重新连接仍然有效，因为身份验证或新隧道会在断开时间之后发送心跳。验证方法：在 agent 连接后立即将其停止，并确认它不会在 2 秒的心跳刷新窗口之后短暂恢复在线。

shellhub

核心功能

避坑指南

适用场景

标签

快速上手

相似推荐