SQL Server Docker 컨테이너 문제 해결

적용 대상:SQL Server on Linux

이 글에서는 SQL Server Docker 컨테이너를 배포하고 사용할 때 발생하는 흔한 오류를 설명하고, 이를 해결하는 데 도움이 되는 문제 해결 기법을 제공합니다.

Docker 명령 오류

docker 명령과 관련된 오류가 발생할 경우 docker 서비스가 실행되고 있는지 확인하고 관리자 권한으로 실행해 봅니다.

예를 들어 Linux에서 docker 명령을 실행할 때 다음과 같은 오류가 발생할 수 있습니다.

Cannot connect to the Docker daemon. Is the docker daemon running on this host?

Linux에서 이 오류가 발생할 경우 앞에 sudo를 추가하여 동일한 명령을 실행해 봅니다. 이 명령이 실패하면 docker 서비스가 실행되고 있는지 확인하고, 필요한 경우 서비스를 시작합니다.

sudo systemctl status docker
sudo systemctl start docker

Windows에서는 PowerShell이나 명령 프롬프트를 관리자 권한으로 실행하는지 확인하세요.

Important

SA_PASSWORD 환경 변수는 사용되지 않습니다. MSSQL_SA_PASSWORD를 대신 사용하세요.

SQL Server 컨테이너 시작 오류

SQL Server 컨테이너가 실행되지 않으면 다음 테스트를 시도합니다.

• failed to create endpoint CONTAINER_NAME on network bridge. Error starting proxy: listen tcp 0.0.0.0:1433 bind: address already in use. 등과 같은 오류가 발생하면 컨테이너 포트 1433을 이미 사용 중인 포트에 매핑하려고 시도하는 것입니다. 이 문제는 호스트 머신에서 SQL Server를 로컬로 실행하는 경우에 발생할 수 있습니다. 두 개의 SQL Server 컨테이너를 시작하고 둘 다 동일한 호스트 포트에 매핑하려고 하는 경우에도 발생할 수 있습니다. 이 문제가 발생할 경우 -p 매개 변수를 사용하여 컨테이너 포트 1433을 다른 호스트 포트에 매핑합니다. 다음은 그 예입니다.

  docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<password>' -p 1400:1433 -d mcr.microsoft.com/mssql/server:2025-latest
  

  docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" -p 1400:1433 -d mcr.microsoft.com/mssql/server:2025-latest
  

  docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" -p 1400:1433 -d mcr.microsoft.com/mssql/server:2025-latest
  

  Caution

  암호는 SQL Server 기본 암호 정책을 따라야 합니다. 기본적으로 암호는 8자 이상이어야 하며 대문자, 소문자, 0~9까지의 숫자 및 기호 네 가지 집합 중 세 집합의 문자를 포함해야 합니다. 암호는 최대 128자까지 가능합니다. 되도록 길고 복잡한 암호를 사용합니다.

• 컨테이너를 시작하려고 할 때 Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get http://%2Fvar%2Frun%2Fdocker.sock/v1.30tdout=1&tail=all: dial unix /var/run/docker.sock: connect: permission denied 등과 같은 오류가 발생하는 경우 Ubuntu의 Docker 그룹에 사용자를 추가합니다. 그 후 로그아웃했다가 다시 로그인하세요. 이 변경은 새로운 세션에 영향을 미치기 때문입니다.

  usermod -aG docker $USER
  

• 컨테이너에서 오류 메시지가 있는지 확인하세요.

  docker logs e69e056c702d
  

• 빠른 시작 문서의 필수 조건 섹션에 지정된 최소 메모리 및 디스크 요구 사항을 충족하는지 확인합니다.

• 컨테이너 관리 소프트웨어를 사용하는 경우 소프트웨어가 루트로 실행 중인 컨테이너 프로세스를 지원하는지 확인합니다. 컨테이너의 sqlservr.exe 프로세스가 루트로 실행됩니다.

• SQL Server Docker 컨테이너가 시작 후 즉시 종료되는 경우 Docker 로그를 확인합니다. docker run 명령을 사용하여 Windows에서 PowerShell을 사용하는 경우 작은따옴표 대신 큰따옴표를 사용합니다. PowerShell Core에서는 작은따옴표를 사용하세요.

• SQL Server 설치 및 오류 로그를 검토합니다.

덤프 캡처 활성화

컨테이너 내에서 SQL Server 프로세스가 실패하는 경우 SYS_PTRACE 사용하도록 설정된 새 컨테이너를 만들어야 합니다. 그러면 예외 발생 시 덤프 파일을 만드는 데 필요한 Linux 프로세스 추적 기능이 추가됩니다. 덤프 파일은 지원에서 문제를 해결하는 데 사용할 수 있습니다. 다음 docker 실행 명령을 사용하면 이 기능을 사용할 수 있습니다.

docker run -e 'ACCEPT_EULA=Y' -e 'MSSQL_SA_PASSWORD=<password>' -e 'MSSQL_PID=Developer' --cap-add SYS_PTRACE -p 1401:1433 -d mcr.microsoft.com/mssql/server:2025-latest

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" -e "MSSQL_PID=Developer" --cap-add SYS_PTRACE -p 1401:1433 -d mcr.microsoft.com/mssql/server:2025-latest

docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=<password>" -e "MSSQL_PID=Developer" --cap-add SYS_PTRACE -p 1401:1433 -d mcr.microsoft.com/mssql/server:2025-latest

Caution

암호는 SQL Server 기본 암호 정책을 따라야 합니다. 기본적으로 암호는 8자 이상이어야 하며 대문자, 소문자, 0~9까지의 숫자 및 기호 네 가지 집합 중 세 집합의 문자를 포함해야 합니다. 암호는 최대 128자까지 가능합니다. 되도록 길고 복잡한 암호를 사용합니다.

SQL Server 연결 실패

컨테이너에서 실행되는 SQL Server 인스턴스에 연결할 수 없는 경우 다음 테스트를 시도합니다.

• 출력의 docker ps -a 열을 검사하여 SQL Server 컨테이너가 실행되고 있는지 확인합니다. 그렇지 않다면 docker start <Container ID>를 사용하여 시작하세요.

• 기본값이 아닌 호스트 포트(1433이 아님)에 매핑한 경우 연결 문자열에 포트를 지정해야 합니다. 출력의 docker ps -a 열에서 포트 매핑을 볼 수 있습니다. 예를 들어, 다음 명령어는 1401 포트 수신 중인 컨테이너에 sqlcmd 를 연결합니다:

  sqlcmd -S 10.3.2.4,1401 -U sa -P '<password>'
  

  sqlcmd -S 10.3.2.4,1401 -U sa -P "<password>"
  

  sqlcmd -S 10.3.2.4,1401 -U sa -P "<password>"
  

• 기존 매핑된 데이터 볼륨 또는 데이터 볼륨 컨테이너와 함께 docker run를 사용하는 경우 SQL Server는 해당 MSSQL_SA_PASSWORD 값을 무시합니다. 대신 미리 구성된 sa 계정 암호는 데이터 볼륨 또는 데이터 볼륨 컨테이너의 SQL Server 데이터에서 사용됩니다. 연결하려는 데이터와 연결된 비밀번호를 sa사용하고 있는지 확인하세요.

• SQL Server 설치 및 오류 로그를 검토합니다.

SQL Server 가용성 그룹

SQL Server 가용성 그룹과 함께 Docker를 사용하는 경우 두 가지 추가 요구 사항이 있습니다.

• 복제본 통신에 사용되는 포트를 매핑합니다(기본값 5022). 예를 들어 -p 5022:5022 명령의 일부로 docker run를 지정 합니다.

• -h YOURHOSTNAME 명령의 docker run 매개 변수를 사용하여 컨테이너 호스트 이름을 명시적으로 설정합니다. 이 호스트 이름은 가용성 그룹을 구성할 때 사용됩니다. -h를 사용하여 지정하지 않으면 기본적으로 컨테이너 ID로 설정됩니다.

SQL Server 설치 및 오류 로그

/var/opt/mssql/log에서 SQL Server 설정 및 오류 로그를 확인할 수 있습니다. 컨테이너가 실행되고 있지 않으면 먼저 컨테이너를 시작합니다. 그 다음 인터랙티브 명령 프롬프트를 사용해 로그를 검사하세요. docker ps 명령을 실행하여 컨테이너 ID를 가져올 수 있습니다.

docker start <Container ID>
docker exec -it <Container ID> "bash"

컨테이너 내 Bash 세션에서 다음 명령을 실행하세요:

cd /var/opt/mssql/log
cat setup*.log
cat errorlog

Tip

컨테이너를 만들 때 호스트 디렉터리를 /var/opt/mssql에 탑재한 경우 대신 호스트의 매핑된 경로에서 로그 하위 디렉터리를 볼 수 있습니다.

컨테이너에서 명령 실행

실행 중인 컨테이너가 있는 경우 호스트 터미널을 통해 컨테이너 내에서 명령을 실행할 수 있습니다.

컨테이너 ID를 얻으려면 다음을 실행하세요:

docker ps -a

컨테이너에서 Bash 터미널을 시작하려면, 다음을 실행하세요:

docker exec -it <Container ID> /bin/bash

이제 컨테이너 내부 터미널에서 실행하는 것처럼 명령을 실행할 수 있습니다. 완료되면 exit을 입력합니다. 이렇게 하면 인터랙티브 명령 세션이 종료되지만, 컨테이너는 계속 실행됩니다.

관련 콘텐츠

• 빠른 시작: Docker를 사용하여 SQL Server Linux 컨테이너 이미지를 실행하기

• SQL Server Linux 컨테이너 배포 및 연결

• SQL Server Linux 컨테이너 구성 및 사용자 지정

• SQL Server Linux 컨테이너 보호

SQL 설명서 작성에 참여하세요.

SQL 콘텐츠를 직접 편집할 수 있다는 것을 알고 계셨나요? 그렇게 하면 설명서를 개선하는 데 도움이 될 뿐만 아니라 페이지의 기여자로도 인정받게 됩니다.

자세한 내용은 Microsoft Learn 편집 설명서를 참조하세요.