ai_platform/docs/DEPLOYMENT-xavis.ncue.net.md

xavis.ncue.net 서버 설치 가이드 (Apache2)

이 문서는 XAVIS 웹플랫폼을 xavis.ncue.net 서버에 Apache2를 사용해 배포하는 방법을 설명합니다.

---

1. 사전 요구사항

항목	버전/설명
Node.js	v18 이상 권장
npm	Node.js와 함께 설치
PostgreSQL	DB는 ncue.net 원격 서버 사용 (이미 설정됨)
Apache2	mod_proxy, mod_proxy_http 필요
LibreOffice	PPTX→PDF 변환용 (선택, brew install --cask libreoffice 또는 apt install libreoffice)
poppler-utils	pdftoppm 포함, 썸네일/슬라이드 이미지용 (apt install poppler-utils)

---

2. 서버에 프로젝트 배포

2.1 프로젝트 클론

# 배포 디렉터리로 이동 (예: /var/www)
cd /var/www

# Git 클론
sudo git clone https://git.ncue.net/xavis/webplatform.git
cd webplatform

2.2 소유권 설정

# 웹 서버 사용자(예: www-data)에게 소유권 부여
sudo chown -R www-data:www-data /var/www/webplatform

2.3 의존성 설치

cd /var/www/webplatform
npm install --production

2.4 코드 갱신(git pull) 직후 (503·앱 기동 실패 시)

package.json에 새 npm 패키지가 추가되면, pull만 하고 npm install을 하지 않은 상태로 PM2(또는 node)를 재시작하면 Cannot find module로 프로세스가 바로 종료됩니다. Apache는 업스트림이 없다고 503 Service Unavailable을 반환할 수 있습니다.

cd /var/www/webplatform   # 실제 배포 경로
git pull
npm install --production
pm2 restart webplatform   # PM2로 실행 중인 앱 이름에 맞게

2.5 환경 변수 설정

# .env 파일이 없다면 .env.example 복사
cp .env.example .env

# .env 수정 (에디터로)
nano .env

필수 수정 항목 예시:

PORT=8030
ADMIN_TOKEN=실제_관리자_토큰_변경

# PostgreSQL (ncue.net 원격 DB)
ENABLE_POSTGRES=1
DB_HOST=ncue.net
DB_PORT=5432
DB_DATABASE=ai_web_platform
DB_USERNAME=ncue
DB_PASSWORD=실제_DB_비밀번호

# 채팅 API 키 (선택)
OPENAI_API_KEY=
CLAUDE_API_KEY=
GENAI_API_KEY=

---

3. Node.js 앱 실행 (PM2 권장)

앱을 백그라운드에서 안정적으로 실행하려면 PM2를 사용합니다.

3.1 PM2 설치

# PM2 전역 설치 (Node.js/npm 필요)
sudo npm install -g pm2

# 설치 확인
pm2 --version

참고: pm2: command not found 오류가 나면 위 명령으로 PM2를 먼저 설치한 뒤 앱을 실행하세요.

3.2 PM2로 앱 실행

cd /var/www/webplatform
pm2 start server.js --name webplatform
pm2 save
pm2 startup   # 시스템 부팅 시 자동 시작 설정

3.3 PM2 명령어

pm2 status          # 상태 확인
pm2 logs webplatform   # 로그 보기
pm2 restart webplatform # 재시작
pm2 stop webplatform   # 중지

---

4. Apache2 리버스 프록시 설정

Apache2가 80/443 포트에서 요청을 받아 Node.js 앱(8030)으로 전달합니다.

4.1 필요한 모듈 활성화

sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod headers
sudo a2enmod ssl
sudo systemctl restart apache2

4.2 가상 호스트 설정

설정 파일: docs/apache-xavis.ncue.net.conf (git.ncue.net 스타일, HTTPS)

sudo cp docs/apache-xavis.ncue.net.conf /etc/apache2/sites-available/xavis.ncue.net.conf

SSL 인증서 경로가 ncue.net과 다르면(예: xavis.ncue.net 전용 인증서) 설정 파일에서
SSLCertificateFile, SSLCertificateKeyFile 경로를 수정하세요.

4.3 HTTPS (SSL) 설정 (권장)

Let's Encrypt 사용 예:

sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d xavis.ncue.net

인증서 발급 후 Apache가 자동으로 443 포트 VirtualHost를 생성합니다.
이 경우 위 ProxyPass 설정이 443 VirtualHost에도 적용되는지 확인하세요.

4.4 사이트 활성화 및 재시작

sudo a2ensite xavis.ncue.net.conf
sudo apache2ctl configtest
sudo systemctl reload apache2

---

5. 디렉터리 권한

# uploads, data 디렉터리 쓰기 권한
sudo mkdir -p /var/www/webplatform/uploads/thumbnails
sudo mkdir -p /var/www/webplatform/uploads/slides
sudo mkdir -p /var/www/webplatform/data
sudo chown -R www-data:www-data /var/www/webplatform/uploads
sudo chown -R www-data:www-data /var/www/webplatform/data

---

6. 선택: LibreOffice 및 poppler 설치 (PPT 썸네일/슬라이드)

PPTX 파일의 썸네일과 슬라이드 이미지를 생성하려면:

# Ubuntu/Debian
sudo apt update
sudo apt install libreoffice poppler-utils

# CentOS/RHEL
sudo yum install libreoffice poppler-utils

설치 후 PM2로 앱 재시작:

pm2 restart webplatform

---

7. 방화벽 확인

# 80, 443 포트 허용 (Apache)
sudo ufw allow 80
sudo ufw allow 443
sudo ufw reload

8030 포트는 localhost에서만 사용하므로 외부에 열 필요 없습니다.

---

8. 배포 체크리스트

• Git 클론 완료
• npm install --production 완료
• .env 설정 (DB, ADMIN_TOKEN 등)
• PM2로 앱 실행 (pm2 start server.js --name webplatform)
• Apache2 mod_proxy, mod_proxy_http 활성화
• VirtualHost 설정 및 사이트 활성화
• uploads/, data/ 디렉터리 권한 설정
• (선택) LibreOffice, poppler-utils 설치
• https://xavis.ncue.net 접속 확인

---

9. 트러블슈팅

502 Bad Gateway

• Node.js 앱이 8030 포트에서 실행 중인지 확인: pm2 status
• .env의 PORT=8030과 Apache ProxyPass 포트가 일치하는지 확인

403 Forbidden

• uploads/, data/ 디렉터리 권한 확인
• Apache 사용자(www-data)가 해당 디렉터리에 쓰기 권한이 있는지 확인

PostgreSQL 연결 실패

• DB_HOST, DB_PORT, DB_USERNAME, DB_PASSWORD 확인
• 서버에서 ncue.net:5432로 접근 가능한지 확인: nc -zv ncue.net 5432

썸네일/슬라이드 이미지 미생성

• LibreOffice, poppler-utils 설치 여부 확인
• PM2 로그 확인: pm2 logs webplatform

업로드 413 Request Entity Too Large (Apache)

• VirtualHost에 **LimitRequestBody**가 작게 잡혀 있지 않은지 확인합니다. 회의 음성·엑셀 등은 바이트 단위로 크게 필요합니다 (deploy/apache-ai.ncue.net-ssl.conf.example의 예시 참고).

회의록 음성(SSE)·진행 막대가 한동안 안 움직임

• 노드 처리 전체가 길므로 같은 VirtualHost에서 TimeOut / ProxyTimeout 이 충분한지 확인합니다.
• 브라우저로 직접 http://127.0.0.1:8030(또는 앱 바인 포트)에 붙였을 때는 정상인데 Apache 경유만 이상하면, 프록시 앞단 mod_deflate 등 출력 필터가 text/event-stream 응답을 버퍼링하지 않는지 점검합니다.
• 앱이 붙이는 X-Accel-Buffering: no 는 Nginx 전용이며, Apache에서는 동작하지 않습니다(무시됨).