Initial commit: AI platform app (server, views, lib, data, deploy docs)
Made-with: Cursor
This commit is contained in:
44
docs/AX-APPLY-ARRAY-ERROR-ANALYSIS.md
Normal file
44
docs/AX-APPLY-ARRAY-ERROR-ANALYSIS.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# AX 과제 신청 "malformed array literal: """ 오류 원인 분석
|
||||
|
||||
## 1. 오류 발생 조건
|
||||
|
||||
- **오류 메시지**: `malformed array literal: ""`
|
||||
- **발생 시점**: 필수값만 입력 후 저장 시 (techStack, risks 필드 비어 있음)
|
||||
- **PostgreSQL**: `text[]` 컬럼에 빈 문자열 `""`이 전달되면 발생
|
||||
|
||||
## 2. 데이터 흐름 추적
|
||||
|
||||
### 2.1 프론트엔드 (ax-apply.ejs)
|
||||
|
||||
```
|
||||
FormData 수집 → fd.forEach로 data 객체 생성 → JSON.stringify(data) → POST /api/ax-apply
|
||||
```
|
||||
|
||||
**techStackStr, risksStr가 비어 있을 때:**
|
||||
- `fd.forEach`: k="techStackStr", v="" (빈 문자열)
|
||||
- `k === 'techStackStr' && v` → v가 ""(falsy)이므로 **건너뜀**
|
||||
- `k !== 'techStackStr'` → k가 techStackStr이므로 **건너뜀**
|
||||
- **결과**: data에 techStackStr, risksStr가 **포함되지 않음** (undefined)
|
||||
|
||||
→ 이론상 빈 문자열이 전송되지 않아야 함.
|
||||
|
||||
### 2.2 백엔드 (server.js)
|
||||
|
||||
**node-pg 알려진 이슈**: JavaScript 빈 배열 `[]`을 `text[]` 파라미터로 전달하면, node-pg가 `""`로 직렬화함.
|
||||
- PostgreSQL은 `""`를 배열 리터럴로 파싱할 수 없음 → `malformed array literal: ""` 발생
|
||||
|
||||
**해결책**: 배열 컬럼에 **파라미터 대신 SQL 리터럴 `'{}'`** 사용 (이미 server.js에 적용됨)
|
||||
|
||||
## 3. 가능한 원인
|
||||
|
||||
| 원인 | 가능성 | 설명 |
|
||||
|------|--------|------|
|
||||
| **배포 서버 미재시작** | 높음 | 수정된 server.js가 반영되지 않음. PM2 등으로 재시작 필요 |
|
||||
| **브라우저/FormData 차이** | 낮음 | 일부 환경에서 빈 필드가 ""로 전송될 수 있음 |
|
||||
| **기타 배열 필드** | 낮음 | dataTypes, qualitativeEffects 등 (폼에 없음) |
|
||||
|
||||
## 4. 권장 조치
|
||||
|
||||
1. **서버 재시작**: `pm2 restart webplatform` (배포 환경)
|
||||
2. **프론트엔드 방어**: 전송 직전 배열 관련 빈 문자열 제거
|
||||
3. **배포 반영**: 최신 server.js가 배포 서버에 반영되었는지 확인
|
||||
239
docs/DEPLOYMENT-xavis.ncue.net.md
Normal file
239
docs/DEPLOYMENT-xavis.ncue.net.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# 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 프로젝트 클론
|
||||
|
||||
```bash
|
||||
# 배포 디렉터리로 이동 (예: /var/www)
|
||||
cd /var/www
|
||||
|
||||
# Git 클론
|
||||
sudo git clone https://git.ncue.net/xavis/webplatform.git
|
||||
cd webplatform
|
||||
```
|
||||
|
||||
### 2.2 소유권 설정
|
||||
|
||||
```bash
|
||||
# 웹 서버 사용자(예: www-data)에게 소유권 부여
|
||||
sudo chown -R www-data:www-data /var/www/webplatform
|
||||
```
|
||||
|
||||
### 2.3 의존성 설치
|
||||
|
||||
```bash
|
||||
cd /var/www/webplatform
|
||||
npm install --production
|
||||
```
|
||||
|
||||
### 2.4 환경 변수 설정
|
||||
|
||||
```bash
|
||||
# .env 파일이 없다면 .env.example 복사
|
||||
cp .env.example .env
|
||||
|
||||
# .env 수정 (에디터로)
|
||||
nano .env
|
||||
```
|
||||
|
||||
**필수 수정 항목 예시:**
|
||||
|
||||
```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 설치
|
||||
|
||||
```bash
|
||||
# PM2 전역 설치 (Node.js/npm 필요)
|
||||
sudo npm install -g pm2
|
||||
|
||||
# 설치 확인
|
||||
pm2 --version
|
||||
```
|
||||
|
||||
> **참고:** `pm2: command not found` 오류가 나면 위 명령으로 PM2를 먼저 설치한 뒤 앱을 실행하세요.
|
||||
|
||||
### 3.2 PM2로 앱 실행
|
||||
|
||||
```bash
|
||||
cd /var/www/webplatform
|
||||
pm2 start server.js --name webplatform
|
||||
pm2 save
|
||||
pm2 startup # 시스템 부팅 시 자동 시작 설정
|
||||
```
|
||||
|
||||
### 3.3 PM2 명령어
|
||||
|
||||
```bash
|
||||
pm2 status # 상태 확인
|
||||
pm2 logs webplatform # 로그 보기
|
||||
pm2 restart webplatform # 재시작
|
||||
pm2 stop webplatform # 중지
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Apache2 리버스 프록시 설정
|
||||
|
||||
Apache2가 80/443 포트에서 요청을 받아 Node.js 앱(8030)으로 전달합니다.
|
||||
|
||||
### 4.1 필요한 모듈 활성화
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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 사용 예:
|
||||
|
||||
```bash
|
||||
sudo apt install certbot python3-certbot-apache
|
||||
sudo certbot --apache -d xavis.ncue.net
|
||||
```
|
||||
|
||||
인증서 발급 후 Apache가 자동으로 443 포트 VirtualHost를 생성합니다.
|
||||
이 경우 위 `ProxyPass` 설정이 443 VirtualHost에도 적용되는지 확인하세요.
|
||||
|
||||
### 4.4 사이트 활성화 및 재시작
|
||||
|
||||
```bash
|
||||
sudo a2ensite xavis.ncue.net.conf
|
||||
sudo apache2ctl configtest
|
||||
sudo systemctl reload apache2
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 디렉터리 권한
|
||||
|
||||
```bash
|
||||
# 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 파일의 썸네일과 슬라이드 이미지를 생성하려면:
|
||||
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo apt update
|
||||
sudo apt install libreoffice poppler-utils
|
||||
|
||||
# CentOS/RHEL
|
||||
sudo yum install libreoffice poppler-utils
|
||||
```
|
||||
|
||||
설치 후 PM2로 앱 재시작:
|
||||
|
||||
```bash
|
||||
pm2 restart webplatform
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 방화벽 확인
|
||||
|
||||
```bash
|
||||
# 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`
|
||||
Reference in New Issue
Block a user