Question 1

ShellHub Go イメージおよび失敗している Trivy スキャンにおける CVE-2026-78667 と CVE-2026-97031 を修正するにはどうすればよいですか？

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 に設定してください。クラウドリポジトリにも同じ変更を適用し、CI が go-version-file を使用して、ジョブが更新されたツールチェーンでコンパイルされるようにしてください。server、gateway、openapi、agent、test イメージ、およびネイティブ 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

dev イメージのビルド構成から network: host を削除し、Compose 経由で module-proxy の build args を渡すのをやめます。

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:-} の build args を削除します。
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 はデフォルトのレジストリを使用するため、BuildKit は network.host entitlement を必要としなくなります。プロキシが必要な場合は、build arg として注入するのではなく、コンテナのランタイム環境で 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 への変換を適用します。ストアインターフェース、モック、呼び出し元を int のままにしておくことで、変更は Bun 統合層に限定されます。PostgreSQL ストア統合テストと、ShellHub をクラウドモジュールに対してコンパイルするエンタープライズビルドで検証します。

Question 4

ShellHub エージェントが 'namespace not found' エラーで '/api/devices/auth' への再試行を繰り返して停止してしまう問題の修正方法

Accepted Answer

エージェントが保持しているテナント ID が既存のどのネームスペースにも解決されないため、サーバーは 404 を返し、エージェントは仕様上（ネームスペースは「まだ存在していないだけかもしれない」ため）無限にリトライを続けます。修正方法は次のとおりです。 1) `docker logs ` でエージェントのログを確認し、`failed to authenticate device ... namespace not found` を探してください。PR #7077 以降、このメッセージは 10 回の試行ごとに warn レベルで記録され、テナントの値とその取得元も含まれます。 2) テナント ID が既存のネームスペースの正確な UUID と一致していることを確認してください（よくある原因は、`TENANT_ID=` を使ったインストール時に `0` を `O` と打ち間違えるようなタイポです）。 3) テナントが以前のペアリングに由来する場合は、エージェントの秘密鍵の隣に保存されている `.tenant` ファイルを削除して再登録してください。`SHELLHUB_TENANT_ID` が未設定の場合、エージェントはこのファイルを警告なしに採用します。 4) 環境変数経由で設定している場合は、`SHELLHUB_TENANT_ID` を修正してコンテナを再起動してください。 5) PR #7077 と #7661 を含むリリースにアップグレードしてください。これにより、エージェントは UUID でないテナントを即座に拒否し、`install.sh` は失敗が確定している登録に対して成功と表示する代わりに、ゼロ以外の終了コードで終了して実際の登録結果を報告するようになります。注：削除済み・存在しないネームスペースに対する構文的に有効な 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`がオンラインしきい値より古くなるまでデバイスがオンラインとして表示されます。

カスタムビルドを維持している場合は、次の2つの変更を行ってください：

1. バッチ全体で1つのタイムスタンプを使用するのではなく、バッチ内でデバイスごとに最新のハートビートタイムスタンプを保持します。
2. ハートビートが切断時刻よりも新しい場合にのみ`disconnected_at`をクリアします：

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

したがって、`disconnected_at`より古いハートビートではデバイスはオフラインのままになります。認証または新しいトンネルが切断時刻以降にハートビートを送信するため、実際の再接続は引き続き機能します。エージェントが接続した直後に停止し、2秒のハートビートフラッシュウィンドウの後に一時的にオンラインに戻らないことを確認して検証してください。

shellhub

主な機能

できないこと

使用例

タグ

はじめ方

類似プロジェクト