설치와 시작

mac status -v, mac env, mac images --check로 먼저 확인하세요.

dpkg -i 후에도 mac 명령을 찾을 수 없음

hash -r를 실행하거나 새 셸을 여세요. 패키지를 설치하기 전에 MAC 스택을 실행했다면 /usr/bin/mac이 디렉터리일 수 있습니다. 빈 디렉터리는 패키지가 직접 제거합니다. 비어 있지 않다면 내용을 확인해 제거한 뒤 패키지를 다시 설치하세요.

mac start가 /var/run/docker.sock에서 "permission denied"로 실패함

사용자를 docker 그룹에 추가하고 필요하면 다시 로그인하세요. 일부 명령에는 여전히 sudo가 필요합니다. sudo 없이 mac 실행하기를 참고하세요.

sudo usermod -aG docker "$USER"
newgrp docker

재부팅 후 mac start가 "port is already allocated"로 실패함

남은 docker-proxy 프로세스가 포트를 점유하고 있습니다. mac start가 이를 정리하지 못하면 sudo systemctl restart docker를 실행한 뒤 다시 시작하세요. 이때 호스트의 다른 컨테이너도 영향을 받습니다.

이미지 다운로드가 unauthorized 또는 denied 오류로 실패함

이미지를 다운로드하는 사용자로 docker login <registry-host>를 실행하세요. sudo로 다운로드한다면 같은 권한으로 로그인하세요. 미러에는 SDK 이미지도 복사하세요. MAC_REGISTRY를 바꿔도 SDK_AGENT_IMAGE는 바뀌지 않습니다.

오프라인 번들 검증이 실패함

체크섬을 확인해 손상된 아카이브를 교체하고, 완전한 릴리스 번들을 사용하세요. 실행 중인 스택을 중지하기 전에 번들을 먼저 검증하세요.

일부 컨테이너가 restarting 상태에서 빠져나오지 못함

mac logs api-server, 포트(sudo ss -tlnp)와 디스크 공간(df -h)을 확인하세요. 원인을 해결한 뒤 mac restart <mode>를 실행하세요.

업그레이드 후 서비스가 중지된 채로 남아 있음

업그레이드 후 다시 시작할 때는 사용자별 설정을 사용하지 않습니다. /var/lib/mango-ai-center/upgrade-restart.log를 확인하고, 필요한 값을 /etc/mango/mac/env로 옮기세요. agent가 사용하는 기존 토큰은 그대로 유지하고, 오래된 MAC_VERSION 고정 값을 제거한 뒤 이미지를 로드하거나 다운로드하세요. 업그레이드를 참고한 뒤 다음 명령을 실행하세요.

sudo env MAC_IGNORE_USER_ENV=1 mac start <mode>