국산 OS인统信UOS 1060e 서버 버전에 OpenGauss 5.0.0을 구축할 때 발생하는 다양한 장애 요소를 분석하고, 실무 검증된 해결책을 정리한다. 단순한 설명서 나열이 아, 현장에서 직접 마주친 오류와 그 대응 방안을 중심으로 기술한다.

1. 사전 환경 구성의 핵심 포인트

OpenGauss는 엔터프라이즈급 데이터베이스인 만큼 OS 레벨의 세밀한 튜닝을 요구한다. UOS 1060e의 기본 설정값은 데이터베이스 부하를 감당하기 어려우므로, 설치 이전에 시스템 파라미터를 재정의해야 한다.

1.1 필수 라이브러리 설치

패키지 의존성 충돌을 방지하기 위해 UOS 공식 저장소를 우선 사용한다.

# 기본 빌드 도구 및 런타임 라이브러리 설치
sudo apt-get update
sudo apt-get install -y libaio1 libaio-dev flex bison ncurses-dev \
    libglib2.0-dev patch lsb-release libreadline-dev python3 python3-pip

1.2 커널 파라미터 튜닝

/etc/sysctl.conf 파일에 데이터베이스 특화 설정을 추가한다. 영역별로 구분하여 기술하면 추후 관리가 용이하다.

네트워크 연결 최적화

net.ipv4.tcp_max_tw_buckets = 10000
net.ipv4.tcp_tw_reuse = 1
net.core.somaxconn = 65535
net.core.netdev_max_backlog = 65535
net.ipv4.tcp_max_syn_backlog = 65535

메모리 및 버퍼 설정

kernel.shmall = 1152921504606846720
kernel.shmmax = 18446744073709551615
vm.min_free_kbytes = 201318
net.core.rmem_default = 21299200
net.core.wmem_default = 21299200
net.core.rmem_max = 21299200
net.core.wmem_max = 21299200
net.ipv4.tcp_rmem = 8192 250000 16777216
net.ipv4.tcp_wmem = 8192 250000 16777216

세마포어 및 예약 포트

kernel.sem = 250 6400000 1000 25600
net.ipv4.ip_local_reserved_ports = 15400-15407,20050-20057

설정 반영:

sudo sysctl -p

1.3 사용자 자원 한계 해제

/etc/security/limits.conf에 데이터베이스 계정(예: omm)의 제약을 완화한다.

* soft stack 3072
* hard stack 3072
* soft nofile 1000000
* hard nofile 1000000
* soft nproc unlimited

1.4 투명 대형 페이지(THP) 비활성화

Transparent HugePages는 데이터베이스 워크로드에서 성능 불안정성을 유발할 수 있으므로, 설치 전 반드시 해제한다.

# 즉시 적용
echo never | sudo tee /sys/kernel/mm/transparent_hugepage/enabled
echo never | sudo tee /sys/kernel/mm/transparent_hugepage/defrag

# 영구 적용
echo 'echo never > /sys/kernel/mm/transparent_hugepage/enabled' | sudo tee -a /etc/rc.local
echo 'echo never > /sys/kernel/mm/transparent_hugepage/defrag' | sudo tee -a /etc/rc.local
sudo chmod +x /etc/rc.local

2. 설치 과정 빈번 오류 및 대응

2.1 "Insufficient memory" 메모리 부족 오류

증상: 설치 스크립트 실행 중 메모리 검증 단계에서 실패

원인: OpenGauss 5.0.0은 단일 노드 설치 시 최소 4GB 이상의 물리 메모리를 요구하며, 스왑 영역은 실 메모리의 50% 이상이어야 한다.

해결:

# 스왑 공간 확인
free -h

# 스왑 파일 생성 (8GB 예시)
sudo dd if=/dev/zero of=/swapfile bs=1G count=8
sudo mkswap /swapfile
sudo swapon /swapfile

# /etc/fstab 영구 등록
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

2.2 "Python version is too low" 파이썬 버전 불일치

증상: 설치 마법사가 Python 3.6 이상을 요구하나, UOS 1060e 기본 제공 버전이 3.5.x인 경우

해결:

# 대체 Python 경로 지정 또는 직접 빌드
wget https://www.python.org/ftp/python/3.9.16/Python-3.9.16.tgz
tar xzf Python-3.9.16.tgz
cd Python-3.9.16
./configure --prefix=/usr/local/python3.9
make -j$(nproc)
sudo make install

# 심볼릭 링크 설정 (설치 스크립트 호환용)
sudo ln -sf /usr/local/python3.9/bin/python3.9 /usr/bin/python3

2.3 "Cannot find libssl.so" SSL 라이브러리 누락

증상: 암호화 모듈 초기화 단계에서 공유 라이브러리 로드 실패

해결:

# UOS 저장소에서 호환 패키지 검색
sudo apt-cache search libssl | grep -E "1\.1|1\.0"

# 특정 버전 수동 링크 (예: libssl.so.1.1이 실제로는 1.1.1 위치에 있는 경우)
sudo find / -name "libssl.so*" 2>/dev/null

# 락 시 소스 빌드 또는 호환 패키지 설치
sudo apt-get install -y libssl-dev

2.4 설치 후 gs_ctl 프로세스 기동 실패

증상: gs_ctl start 명령 시 "Data directory permissions are not correct" 경고

원인: OpenGauss 데이터 디렉터리는 소유자 omm의 권한이 700이어야 하며, 상위 경로에 다른 사용자의 쓰기 권한이 있으면 보안 정책상 거부된다.

해결:

# 데이터 저장 경로 권한 검증
ls -ld /opt/opengauss/data
# 잘못된 경우: drwxrwxrwx ... (777 등)

# 정정 조치
sudo chown -R omm:dbgrp /opt/opengauss/data
sudo chmod 700 /opt/opengauss/data

# 상위 경로 권한 점검 (예: /opt/opengauss 가 777이면 문제)
ls -ld /opt /opt/opengauss

3. 설치 검증 및 후처리

정상 설치 후 필수 확인 항목:

# 프로세스 상태 확인
ps -ef | grep gaussdb

# 포트 리스닝 확인
ss -tlnp | grep 15400

# 데이터베이스 접속 테스트
gsql -d postgres -p 15400 -r

# 핵심 파라미터 확인
SHOW shared_buffers;
SHOW max_connections;

로그 모니터링 경로: $GAUSSLOG/gs_log 및 pg_log 하위 파일에서 실시간 에러 트레이싱 가능