콘텐츠로 이동

컨테이너 문제 해결 가이드

이 가이드는 Backend.AI GO의 컨테이너 실행과 멀티 채널 메시징에서 자주 발생하는 문제를 다룹니다.

컨테이너 런타임 문제

런타임이 감지되지 않음

증상: 설정 > 스쿼드의 컨테이너 런타임이 사용 불가로 표시됩니다.

진단:

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

해결 방법:

  1. Apple Container가 설치되어 있는지 확인합니다:

    which container
container --version

  2. 컨테이너 시스템 서비스를 시작합니다:

    container system start

  3. 명령어를 찾을 수 없는 경우 Apple Container GitHub 릴리스에서 재설치합니다.

  1. Docker가 실행 중인지 확인합니다:

    docker version

  2. Docker가 실행 중이 아니라면 Docker Desktop(macOS/Windows)이나 Docker 데몬(Linux)을 시작합니다:

    # Linux만 해당
sudo systemctl start docker
sudo systemctl enable docker

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

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

Docker가 응답하지 않음

증상: 런타임 상태에 Docker CLI found but the daemon did not answer within 10s가 표시됩니다.

Docker CLI는 설치되어 있지만 데몬이 연결만 받고 응답하지 않는 상태인데, Docker Desktop이 시작하다 멈췄거나 DOCKER_HOST가 응답하는 데몬이 없는 소켓을 가리킬 때 생깁니다. 런타임 확인은 10초가 지나면 중단되고 컨테이너는 사용할 수 없는 상태로 표시되므로, 앱과 aigo-server는 그대로 시작됩니다.

해결 방법:

  • Docker Desktop을 종료했다가 다시 열거나, Linux에서는 데몬을 재시작(sudo systemctl restart docker)한 뒤 docker version이 응답하는지 확인합니다.
  • DOCKER_HOST를 해제하거나 실행 중인 데몬을 가리키도록 바꿉니다.
  • Hermes를 사용하기 전에 Backend.AI GO나 aigo-server를 재시작합니다. Hermes가 사용할 런타임은 앱이 시작될 때 한 번만 정해지므로, 나중에 복구된 데몬은 사용되지 않습니다.

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

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

해결 방법:

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

이미지 빌드 문제

빌드가 즉시 실패함

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

진단:

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

해결 방법:

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

빌드가 끝나지 않고 멈춤

증상: 빌드 버튼에 빌드 중... 표시가 한참 동안 남아 있고 결과가 나오지 않습니다.

해결 방법:

  • 네트워크 문제로 베이스 이미지 다운로드가 멈출 수 있으니 인터넷 연결을 확인합니다
  • 프록시를 사용 중이라면 Docker/Apple Container가 해당 프록시를 사용하도록 설정되어 있는지 확인합니다
  • 앱에는 진행 중인 빌드를 취소하는 기능이 없습니다. 네트워크 연결을 점검한 뒤, 현재 빌드가 끝나면 다시 빌드합니다

이미지가 오래됨

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

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

  • 설정 > 스쿼드 > 에이전트 러너 이미지 → 이미지 재빌드 클릭

스쿼드 작업이 에이전트 러너 프로토콜 오류로 실패함

증상: 컨테이너 모드 에이전트에 할당된 모든 스쿼드 작업이 실패하고, 작업 오류나 컨테이너 상태에 다음 중 하나가 표시됩니다:

  • Container agent error: ... (the image predates agent runner protocol 2; rebuild aigo-agent-runner:latest or update the custom image)
  • Container agent speaks protocol version <v>; this app speaks 2 (rebuild aigo-agent-runner:latest or update the custom image)

원인: 에이전트 러너 이미지와 앱이 서로 다른 버전의 에이전트 러너 프로토콜을 사용합니다. 첫 번째 메시지는 프로토콜이 생기기 전에 빌드되어 앱이 보내는 작업을 읽지 못하는 이미지에서 나옵니다. 두 번째 메시지는 다른 프로토콜 버전용으로 빌드된 이미지에서 나옵니다. 예를 들어 이전 앱이 빌드한 버전 1 이미지는 그대로 두면 에이전트의 모델을 무시하고 자체 기본 모델을 호출합니다.

해결 방법:

  • 이 앱에 맞게 이미지를 다시 빌드합니다: 설정 > 스쿼드 > 에이전트 러너 이미지 → 이미지 재빌드 클릭, 또는 소스 체크아웃에서 ./container/build.sh 실행
  • 에이전트가 사용자 지정 이미지를 쓴다면 버전 2 입력을 읽고, 받은 model을 호출하고, 출력 블록 하나를 쓰도록 수정한 뒤 다시 빌드합니다
  • 재빌드 후 스쿼드 요청을 다시 실행합니다. 이미지는 각 작업이 시작될 때 읽히므로, 이미 실패한 작업은 실패 상태로 남습니다

마운트 보안 문제

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

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

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

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

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

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

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

해결 방법:

  1. 코워크 설정 드로어를 열고(코워크 대화에서 워크스페이스 레일의 컨텍스트 섹션에 있는 코워크 설정 클릭) 마운트 보안 탭을 선택합니다. 허용 루트 추가를 참고하세요.

  2. 사용하려는 경로의 상위 디렉토리를 허용 루트로 추가합니다.

  3. 홈 디렉토리 같은 광범위한 루트는 피하고 가능한 한 구체적으로 지정하세요.

심볼릭 링크 우회 차단됨

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

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

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

자격 증명 프록시 문제

스쿼드 컨테이너는 자격 증명 프록시의 라우터 경로를 거쳐 모델에 연결하며, 컨테이너 작업에 필요할 때 앱이 프록시를 직접 시작합니다. 스쿼드 작업에는 자격 증명 매핑이 필요 없습니다. 매핑은 외부 API를 직접 호출하는 사용자 지정 이미지에만 쓰입니다. 모델 경로를 참고하세요.

컨테이너 작업이 모델에 연결하지 못함

증상: 컨테이너 모드 작업이 모델 호출 전이나 호출 중에 실패합니다.

진단 단계:

  1. 컨테이너 작업이 실행되는 동안 프록시가 실행 중인지 확인합니다:

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

  2. 실행 중인 작업 컨테이너의 환경을 확인합니다(docker inspect <container>):

    • ANTHROPIC_BASE_URL은 Docker에서는 http://host.docker.internal:<프록시 포트>/router/anthropic, Apple Container에서는 http://localhost/router/anthropic이고 AIGO_INFERENCE_SOCKET=/tmp/aigo-inference.sock이 함께 있어야 합니다
    • ANTHROPIC_API_KEY는 cpt_ 토큰이어야 합니다. 이 토큰은 해당 작업이 실행되는 동안에만 유효합니다.

  3. 작업 오류를 대조합니다:

    오류 원인 해결 방법
    Container mode under Apple Container needs the credential proxy's Unix socket, which this process could not create 프록시는 실행 중이지만 TCP로만 수신합니다. Apple Container 게스트가 호스트에 닿는 유일한 경로인 Unix 소켓을 만들지 못했습니다. 보통 소켓 디렉토리가 원인입니다. 예를 들어 다른 사용자가 소유했거나 그룹 또는 다른 사용자에게 열려 있는 경우입니다. 앱 로그에서 자격 증명 프록시 소켓 경고를 찾아 지목된 문제를 고친 뒤, 프록시를 중지했다가 다시 시작하거나(POST /api/v1/container/credential-proxy/stop 후 start) 앱을 재시작합니다.
    Container agents need the credential proxy, which this runtime did not provide 이 런타임은 자격 증명 프록시 없이 시작되었습니다. 에이전트를 인프로세스로 실행하거나, 프록시를 제공하는 데스크톱 앱이나 헤드리스 서버를 사용합니다.
    Container inference route unavailable: <error> 프록시가 시작되지 못했습니다. 포트(기본값 3001)가 이미 사용 중이거나, Linux에서 수신할 docker0 브리지 주소가 없습니다(rootless Docker, Linux용 Docker Desktop). 포트를 비우거나 PUT /api/v1/container/credential-proxy/port로 다른 포트를 지정하거나, 기본 브리지를 쓰는 Docker를 사용합니다.
    Container agent error: ... 안의 Router unreachable: <error> 프록시가 라우터에 연결하지 못했습니다. 작업이 실행되는 동안 라우터가 중지되었거나 재시작되었습니다. 추론이 실행 중인지 확인한 뒤 작업을 다시 실행합니다.
    Request must carry a valid router access token 요청에 토큰이 없거나, 이미 끝난 작업의 토큰이 실렸습니다. 토큰은 작업보다 오래 살지 않습니다. 토큰을 재사용하지 말고 작업을 다시 실행합니다.
    Container agent error: ... 안의 라우터 HTTP 401 라우터가 키를 요구하는데(외부 접속 허용이 켜짐) 앱이 쓸 수 있는 키가 없습니다. 앱이 라우터 키를 읽을 수 있도록 앱을 재시작하거나, 외부 접속 허용을 끕니다.

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

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

해결 방법:

  • 컨테이너가 호스트에 연결하는 방법을 확인합니다:
    • Linux의 Docker: 컨테이너에 --add-host=host.docker.internal:<docker0 주소>가 주어지고, 프록시도 같은 주소에서 수신합니다. ip -4 addr show docker0의 주소와 프록시 상태의 bindAddress를 비교합니다.
    • macOS/Windows의 Docker Desktop: host.docker.internal이 기본으로 제공되고, 프록시는 127.0.0.1에서 수신합니다.
    • Apple Container: 프록시의 Unix 소켓이 컨테이너 안의 /tmp/aigo-inference.sock으로 중계됩니다. 프록시 상태에는 소켓이 표시되지 않으므로, 프록시가 실행 중일 때 앱 소켓 디렉토리에 credential-proxy-<인스턴스>.sock이 있는지 확인합니다.
  • 방화벽 규칙이 프록시 포트(기본값 3001)를 막고 있지 않은지 확인합니다

IPC 통신 문제

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

증상: 스쿼드 실행 중에 보낸 스티어링 메시지가 컨테이너에서 실행되는 에이전트에 전달되지 않습니다.

원인: 정상 동작입니다. 컨테이너 하나는 작업 하나를 실행합니다. 호스트는 후속 메시지를 보내지 않고, 기본 제공 aigo-agent-runner 이미지는 결과를 기록하는 즉시 종료됩니다. 에이전트 러너 프로토콜을 참고하세요.

해결 방법:

  • 변경 사항을 새 작업이나 스쿼드에 대한 새 요청으로 보냅니다.
  • 작업 중에 스티어링이 필요한 에이전트는 인프로세스로 실행합니다.

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

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

해결 방법:

  • 채널이 연결되어 있는지 확인합니다: 설정 > 스쿼드의 채널에서 해당 채널 카드에 연결됨이 표시되어야 합니다
  • 애플리케이션 로그에서 메시지 라우터 상태를 확인합니다
  • 메시지의 채팅 JID가 연결된 채널의 JID 형식과 일치하는지 확인합니다

채널 연결 문제

Telegram 봇이 응답하지 않음

해결 방법:

  1. 설정 > 스쿼드의 채널에서 텔레그램 봇 카드에 연결됨이 표시되는지 확인합니다. 폼은 토큰 형식만 검사하므로, 토큰이 아직 유효한지 확실하지 않다면 @BotFather에서 토큰을 다시 받아 다시 연결합니다.

  2. 연결 상태를 확인합니다:

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

  3. 그룹 채팅에서는 봇이 그룹의 멤버이고 메시지 읽기 권한을 갖고 있는지 확인하세요.

  4. 먼저 봇에게 다이렉트 메시지로 테스트해 보세요.

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

해결 방법:

  1. 두 토큰이 모두 유효한지 확인합니다 (봇 토큰 xoxb-...와 앱 토큰 xapp-...)

  2. Slack 앱 구성에서 소켓 모드가 활성화되어 있는지 확인합니다

  3. 필요한 봇 범위가 부여되어 있는지 확인합니다:

    • app_mentions:read, channels:history, chat:write, groups:history, im:history, im:read, im:write

  4. 봇이 워크스페이스에 설치되어 있고, 모니터링할 채널에 추가되어 있는지 확인합니다

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

해결 방법:

  1. Discord 개발자 포털에서 메시지 내용 인텐트가 활성화되어 있는지 확인합니다

  2. 봇이 올바른 권한으로 서버에 초대되었는지 확인합니다

  3. 텍스트 채널에서 봇은 @멘션에만 응답하므로, 봇을 멘션하고 있는지 확인하세요

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

    curl http://localhost:8001/api/v1/channels/discord

WhatsApp 웹훅 검증 실패

해결 방법:

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

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

  2. Backend.AI GO의 검증 토큰이 Meta 개발자 포털에 입력한 값과 일치하는지 확인합니다

  3. HTTPS 인증서가 유효한지 확인합니다 (자체 서명 인증서는 WhatsApp에서 허용되지 않음)

작업 스케줄링 문제

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

진단:

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

해결 방법:

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

  • 컨테이너 태스크의 실행 로그에서 오류를 검토합니다:

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

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

해결 방법:

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

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

해결 방법:

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

보안 이벤트 문제

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

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

진단:

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

해결 방법:

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

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

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

해결 방법:

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

도움 받기

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

  1. 설정 > 고급에서 로깅 레벨을 디버그로 설정합니다

  2. 애플리케이션 로그를 수집합니다:

    aigo log --last 500

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

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

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