9.9. 컨테이너 문제 해결 가이드¶

이 가이드는 Backend.AI GO의 컨테이너 실행 및 멀티 채널 메시징과 관련된 일반적인 문제를 다룹니다.

컨테이너 런타임 문제¶

런타임이 감지되지 않음¶

증상: 설정 > 컨테이너에서 런타임이 "사용 불가"로 표시됩니다.

진단:

curl http://localhost:55765/api/v1/container/runtime
# 예상: "available": true

해결 방법:

macOS (Apple Container)macOS/Windows/Linux (Docker)

Apple Container가 설치되어 있는지 확인합니다:
```
which container
container --version
```
컨테이너 시스템 서비스를 시작합니다:
```
container system start
```
명령어를 찾을 수 없는 경우 Apple Container GitHub 릴리스에서 재설치합니다.

Docker가 실행 중인지 확인합니다:
```
docker version
```
Docker가 실행 중이 아닌 경우 Docker Desktop(macOS/Windows)을 시작하거나 Docker 데몬(Linux)을 시작합니다:
```
# Linux만 해당
sudo systemctl start docker
sudo systemctl enable docker
```

사용자가 docker 그룹에 있는지 확인합니다 (Linux):

groups $USER | grep docker
# 그룹에 없는 경우:
sudo usermod -aG docker $USER
newgrp docker

이미지 빌드 문제¶

빌드가 즉시 실패함¶

해결 방법:

빌드를 시도하기 전에 컨테이너 런타임이 실행 중인지 확인합니다
사용 가능한 디스크 공간을 확인합니다 (에이전트 러너 이미지는 약 1-2GB)
빌드 상태 응답의 output 필드에서 오류를 확인합니다

이미지가 오래됨¶

증상: 컨테이너 에이전트가 누락된 도구나 호환되지 않는 의존성으로 실패합니다.

해결 방법: Backend.AI GO 업데이트 후 이미지를 다시 빌드합니다:

설정 > 컨테이너 > 이미지 → 이미지 재빌드 클릭

마운트 보안 문제¶

마운트 거부됨: "차단된 패턴 포함"¶

원인: 호스트 경로에 차단된 패턴(예: .ssh, .env, .aws)이 포함되어 있습니다.

해결 방법: 민감한 디렉터리 이름이 포함되지 않은 다른 경로를 사용하거나, 필요한 파일만 승인된 위치에 복사하세요.

마운트 거부됨: "허용된 루트 아래에 경로 없음"¶

원인: 경로가 설정된 허용 루트 아래에 없습니다.

해결 방법:

설정 > 컨테이너 > 마운트 보안으로 이동합니다.
사용하려는 경로의 상위 디렉터리를 허용 루트로 추가합니다.
홈 디렉터리와 같은 광범위한 루트를 추가하지 않도록 구체적으로 지정하세요.

자격증명 프록시 문제¶

컨테이너 내에서 API 호출 실패¶

진단 단계:

프록시가 실행 중인지 확인합니다:

curl http://localhost:55765/api/v1/container/credential-proxy/status
# 예상: "running": true

자격증명 매핑이 있는지 확인합니다:

curl http://localhost:55765/api/v1/container/credential-proxy/status
# "mappingCount" > 0 확인

해결 방법:

자격증명 프록시를 재시작합니다: 설정 > 컨테이너 > 자격증명 프록시 → 끄고 켜기
자격증명 매핑의 업스트림 URL이 올바르고 접근 가능한지 확인합니다
실제 API 키가 유효한지 확인합니다

IPC 통신 문제¶

컨테이너가 후속 메시지에 응답하지 않음¶

진단:

IPC 디렉터리 구조가 존재하는지 확인합니다:

DATA_DIR/sessions/{group}/{session}/ipc/input/

해결 방법:

컨테이너가 여전히 실행 중인지 확인합니다 (실행 기록 확인)
IPC 디렉터리가 생성되었는지 확인합니다: POST /api/v1/container/ipc/directories 사용
컨테이너에 /workspace/ipc에 IPC 디렉터리가 마운트되어 있는지 확인합니다

채널 연결 문제¶

Telegram 봇이 응답하지 않음¶

해결 방법:

봇 토큰이 유효한지 확인합니다: 설정 > 채널 > Telegram > 토큰 검증

연결 상태를 확인합니다:

curl http://localhost:55765/api/v1/channels/telegram

그룹 채팅에서 봇이 그룹의 멤버인지 확인하세요.
먼저 봇에게 직접 메시지(DM)로 테스트하세요.

Slack 봇이 메시지를 수신하지 않음¶

해결 방법:

두 토큰이 모두 유효한지 확인합니다 (봇 토큰 xoxb-... 및 앱 토큰 xapp-...)
Slack 앱 구성에서 소켓 모드가 활성화되어 있는지 확인합니다
필요한 봇 범위가 부여되어 있는지 확인합니다:
- app_mentions:read, channels:history, chat:write, groups:history, im:history, im:read, im:write

Discord 봇이 채널에서 응답하지 않음¶

해결 방법:

Discord 개발자 포털에서 메시지 내용 인텐트가 활성화되어 있는지 확인합니다
봇이 올바른 권한으로 서버에 초대되었는지 확인합니다
텍스트 채널에서 봇은 @멘션에만 응답합니다 — 봇을 멘션하고 있는지 확인하세요

WhatsApp 웹훅 검증 실패¶

해결 방법:

웹훅 URL이 공개적으로 접근 가능한지 확인합니다 (HTTPS 필요):

curl "https://your-domain.com/api/v1/channels/whatsapp/webhook?hub.mode=subscribe&hub.verify_token=your-token&hub.challenge=test"
# 응답: test

Backend.AI GO의 검증 토큰이 Meta 개발자 포털에 입력한 것과 일치하는지 확인합니다
HTTPS 인증서가 유효한지 확인합니다 (자체 서명 인증서는 WhatsApp에서 허용되지 않음)

작업 스케줄링 문제¶

예약된 작업이 실행되지 않음¶

진단:

curl http://localhost:55765/api/v1/container/schedules
# "enabled": true 및 "nextRun" 타임스탬프 확인

해결 방법:

스케줄의 enabled가 true인지 확인합니다
컨테이너 런타임이 사용 가능한지 확인합니다

스케줄의 실행 로그에서 오류를 검토합니다:

curl http://localhost:55765/api/v1/container/schedules/{id}/logs

도움 받기¶

이 가이드를 사용하여 문제를 해결할 수 없는 경우:

설정 > 고급에서 디버그 로깅을 활성화합니다.
애플리케이션 로그를 수집합니다:
```
aigo logs --last 500
```

컨테이너 감사 로그를 내보냅니다:

curl "http://localhost:55765/api/v1/container/audit-log?limit=500" > audit.json

수집한 로그와 함께 Backend.AI GO GitHub 저장소에 문제를 보고합니다.