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로 변경하며, 에이전트 Dockerfile 인수를 ARG GOLANG_VERSION=1.26.9로 설정하세요. 클라우드 저장소에도 동일한 변경을 적용하고 CI가 go-version-file을 사용하도록 하여 작업이 업데이트된 툴체인으로 컴파일되게 하세요. 서버, 게이트웨이, openapi, 에이전트, 테스트 이미지와 네이티브 에이전트 바이너리를 다시 빌드하세요. 기존 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 빌드 인자 전달을 중단하세요.

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은 기본 레지스트리를 사용하므로 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-to-int 변환을 적용하세요. 스토어 인터페이스, mocks, 호출자를 int로 유지하면 변경 범위가 Bun 통합 계층으로 제한됩니다. ShellHub를 클라우드 모듈에 대해 컴파일하는 PostgreSQL 스토어 통합 테스트와 엔터프라이즈 빌드로 검증하세요.

Question 4

ShellHub 에이전트가 'namespace not found' 오류로 '/api/devices/auth'를 계속 재시도하며 멈춘 문제를 해결하는 방법은?

Accepted Answer

에이전트가 어떤 기존 네임스페이스로도 해석되지 않는 tenant ID를 보유하고 있으므로, 서버는 404를 반환하고 에이전트는 설계상 무한히 재시도합니다(네임스페이스가 '아직 존재하지 않을 수 있음'). 해결 방법: 1) `docker logs `로 에이전트 로그에서 `failed to authenticate device ... namespace not found`를 확인하세요 — PR #7077 이후에는 10번 시도할 때마다 warn 레벨로 로깅되며, tenant 값과 그 출처가 포함됩니다. 2) tenant ID가 기존 네임스페이스의 정확한 UUID인지 확인하세요(흔한 원인은 `TENANT_ID=` 설치 시 `0` 대신 `O`를 입력하는 오타입니다). 3) tenant가 이전 페어링에서 유래한 경우, 에이전트의 private key 옆에 저장된 `.tenant` 파일을 삭제하고 다시 등록하세요 — `SHELLHUB_TENANT_ID`가 설정되지 않은 경우 에이전트는 아무 알림 없이 이 파일을 채택합니다. 4) 환경 변수로 설정된 경우, `SHELLHUB_TENANT_ID`를 수정하고 컨테이너를 재시작하세요. 5) PR #7077 및 #7661이 포함된 릴리스로 업그레이드하세요: 에이전트가 UUID가 아닌 tenant를 즉시 거부하며, `install.sh`는 이제 실패할 운명의 등록에 대해 성공을 출력하는 대신 0이 아닌 코드로 종료하고 실제 등록 결과를 보고합니다. 참고: 삭제되었거나 존재하지 않는 네임스페이스에 대한 구문적으로 유효한 UUID는 여전히 무한히 재시도되며, 이제 로그와 설치 프로그램만이 이를 드러낼 뿐입니다.

Question 5

큐에 대기 중이던 하트비트가 늦게 도착하여 ShellHub 디바이스가 연결 해제 후에도 온라인으로 표시되는 문제를 어떻게 해결할 수 있나요?

Accepted Answer

ShellHub 서버를 issue #7401(`fix(server): stop a late heartbeat from bringing a device back online`)에 대한 수정이 포함된 릴리스로 업그레이드하세요.

경합(race)은 다음과 같은 이유로 발생합니다:
1. 터널이 등록되거나 pong이 수신될 때 keep-alive가 큐에 추가됩니다.
2. heartbeater는 2초마다 큐에 쌓인 heartbeat를 플러시합니다.
3. 터널이 먼저 닫히면 `OfflineDevice`가 `disconnected_at`을 설정합니다.
4. 이후 오래된(stale) heartbeat가 기록되면서 `disconnected_at = NULL`을 무조건 설정하므로, `last_seen`이 온라인 임계값보다 오래될 때까지 디바이스가 온라인으로 표시됩니다.

커스텀 빌드를 유지 관리하는 경우 다음 두 가지를 변경하세요:

1. 배치 전체에 하나의 타임스탬프를 사용하는 대신 배치 내 디바이스별로 최신 heartbeat 타임스탬프를 유지하세요.
2. heartbeat가 연결 해제 시점보다 최신인 경우에만 `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`보다 오래된 heartbeat는 디바이스를 오프라인 상태로 둡니다. 인증 또는 새 터널이 연결 해제 시점 이후에 heartbeat를 전송하므로 실제 재연결은 여전히 정상적으로 작동합니다. 에이전트가 연결된 직후 중지하고, 2초 heartbeat 플러시 윈도우 이후에도 잠시 온라인으로 돌아오지 않는지 확인하여 검증하세요.

shellhub

주요 기능

할 수 없는 것

사용 사례

태그

시작하기

유사한 프로젝트