11.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

런타임은 감지되지만 명령이 실패함¶

증상: 런타임이 사용 가능으로 표시되는데도 컨테이너 작업이 실패합니다.

해결 방법:

컨테이너 데몬을 재시작합니다: Docker Desktop은 종료 후 다시 열고, Apple Container는 container system stop && container system start를 실행합니다
사용 가능한 디스크 공간을 확인합니다 (컨테이너 실행에는 디스크 공간이 필요합니다)
Backend.AI GO 애플리케이션 로그에서 자세한 오류 메시지를 살펴봅니다

이미지 빌드 문제¶

빌드가 즉시 실패함¶

증상: 이미지 빌드가 시작되자마자 실패합니다.

진단:

curl http://localhost:55765/api/v1/container/image/status

해결 방법:

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

빌드가 끝나지 않고 멈춤¶

증상: 빌드 진행 표시가 한참 동안 돌기만 하고 결과가 나오지 않습니다.

해결 방법:

네트워크 문제로 베이스 이미지 다운로드가 멈출 수 있으니 인터넷 연결을 확인합니다
프록시를 사용 중이라면 Docker/Apple Container가 해당 프록시를 쓰도록 설정되어 있는지 확인합니다
네트워크 연결을 점검한 뒤 빌드를 취소하고 다시 시도합니다

이미지가 오래됨¶

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

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

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

마운트 보안 문제¶

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

증상: 마운트 검증이 차단 패턴 오류와 함께 실패합니다.

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

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

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

증상: 경로에 차단 패턴이 없는데도 마운트 검증이 실패합니다.

원인: 경로가 설정된 허용 루트 어디에도 속하지 않습니다.

해결 방법:

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

심볼릭 링크 우회 차단됨¶

증상: 겉보기에는 안전한 경로인데도 거부됩니다.

원인: 경로가 심볼릭 링크를 거쳐 차단된 위치로 연결됩니다.

해결 방법: 심볼릭 링크가 아닌 정규(실제) 경로를 사용하세요. 마운트 검증기는 검사 전에 모든 경로를 정규화합니다.

자격증명 프록시 문제¶

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

증상: 컨테이너 에이전트가 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 확인

컨테이너 환경을 확인합니다:
- ANTHROPIC_BASE_URL은 http://host-gateway:3001을 가리켜야 합니다
- ANTHROPIC_API_KEY는 CREDENTIAL_PROXY_PLACEHOLDER여야 합니다

해결 방법:

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

프록시는 시작되지만 요청이 실패함¶

증상: 프록시 상태는 실행 중으로 표시되는데, 컨테이너에서 보내는 API 호출은 여전히 실패합니다.

해결 방법:

플랫폼에 맞는 host-gateway 주소인지 확인합니다:
- Apple Container: 보통 192.168.64.1
- Linux의 Docker: 보통 172.17.0.1
- macOS/Windows의 Docker: host-docker-internal 또는 docker network inspect bridge로 확인
방화벽 규칙이 3001 포트를 막고 있지 않은지 확인합니다

IPC 통신 문제¶

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

증상: Cowork이나 Squad 실행 중에 보낸 스티어링 메시지가 컨테이너에 전달되지 않습니다.

진단:

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

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

해결 방법:

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

컨테이너가 메시지를 보내지만 전달되지 않음¶

증상: 컨테이너가 ipc/messages/에 기록하는데도 메시지가 채널에 나타나지 않습니다.

해결 방법:

채널이 연결되어 있는지 확인합니다: 설정 > 채널 > {채널}
애플리케이션 로그에서 메시지 라우터 상태를 확인합니다
메시지의 채팅 JID가 연결된 채널의 JID 형식과 일치하는지 확인합니다

채널 연결 문제¶

Telegram 봇이 응답하지 않음¶

해결 방법:

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

연결 상태를 확인합니다:

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

그룹 채팅에서는 봇이 그룹의 멤버이고 메시지 읽기 권한을 갖고 있는지 확인하세요.
먼저 봇에게 다이렉트 메시지로 테스트해 보세요.

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

해결 방법:

두 토큰이 모두 유효한지 확인합니다 (봇 토큰 xoxb-...와 앱 토큰 xapp-...)
Slack 앱 구성에서 소켓 모드가 활성화되어 있는지 확인합니다
필요한 봇 범위가 부여되어 있는지 확인합니다:
- app_mentions:read, channels:history, chat:write, groups:history, im:history, im:read, im:write
봇이 워크스페이스에 설치되어 있고, 모니터링할 채널에 추가되어 있는지 확인합니다

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

해결 방법:

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

게이트웨이 연결 상태를 확인합니다:

curl http://localhost:55765/api/v1/channels/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

cron 작업이 엉뚱한 시간에 실행됨¶

해결 방법:

시스템 시간대가 올바르게 설정되어 있는지 확인합니다
cron 표현식 검증 도구(예: crontab.guru)로 표현식을 점검합니다
cron은 UTC가 아니라 로컬 시스템 시간을 사용한다는 점을 기억하세요

인터벌 작업 실행 시각이 점점 밀림¶

해결 방법:

스케줄러는 드리프트가 누적되지 않도록 next_run을 실행 시각이 아니라 예정 시각 기준으로 계산합니다
시스템 시계가 정확한지 확인합니다 (NTP 동기화)
작업 실행 시간이 지나치게 길어 스케줄러를 지연시키는 경우가 없는지 확인합니다

보안 이벤트 문제¶

감사 로그에 예상치 못한 "violation" 이벤트가 나타남¶

증상: 허용될 것으로 기대한 컨테이너 작업이 감사 로그에 권한 위반으로 기록됩니다.

진단:

curl "http://localhost:55765/api/v1/container/audit-log?severity=violation"

해결 방법:

비메인 그룹의 컨테이너가 다른 그룹의 채팅 JID로 메시지를 보내려 한 것인지 확인합니다 (이 경우 차단은 의도된 정상 동작입니다)
위반이 예상 밖이라면 그룹 네임스페이스 설정을 검토합니다

보안 감사가 컨테이너를 비준수로 표시함¶

증상: 주기적인 보안 감사가 컨테이너를 비준수 상태로 보고합니다.

해결 방법:

컨테이너 환경 변수(특히 ANTHROPIC_API_KEY)를 수정하지 않았는지 확인합니다
컨테이너 시작 이후 마운트가 바뀌지 않았는지 확인합니다
감사 로그에서 어떤 검사가 실패했는지 세부 내용을 살펴봅니다

도움 받기¶

이 가이드로 문제가 해결되지 않을 때는 다음 순서로 진행합니다.

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

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

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

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