1. 시스템 요구사항
🖥️ 서버 하드웨어 권장사양 (Ubuntu OS)
💻 클라이언트 실행 환경 (Windows)
🔧 필수 인프라 소프트웨어 (서버 측)
| 소프트웨어 | 최소 버전 | 용도 |
|---|---|---|
| Docker Engine | 24.0.0+ | 컨테이너 기반 데이터베이스 및 캐시 오케스트레이션 |
| Docker Compose | v2.20.0+ | 멀티 컨테이너 인프라 스택 통합 실행 |
| Node.js Runtime | 20.x LTS+ | CertBridge Express API 코어 서버 구동 |
2. 서버 설치 (Ubuntu)
2-1. 자동 쉘 스크립트 설치 (권장)
제공된 setup.sh 파일을 활용해 도커 엔진, 환경변수, 데이터베이스, systemd 서비스 등록을 한 번에 자동으로 완료합니다.
# 1. 서버 패키지 아카이브 다운로드 wget https://huggingface.co/VanyaJ/certbridge/resolve/main/certbridge-server-v0.1.0-ubuntu.tar.gz # 2. 파일 압축 해제 및 디렉토리 이동 tar -xzf certbridge-server-v0.1.0-ubuntu.tar.gz cd certbridge-server-ubuntu # 3. 설치 권한 부여 및 쉘 실행 chmod +x setup.sh sudo ./setup.sh
2-2. 단계별 수동 설치 프로토콜
Docker 설치 및 실행 환경 구성
# 패키지 업데이트 및 GPG 키 추가 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 레포지토리 정보 추가 및 도커 코어 패키지 설치 echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
도커 컴포즈 기반 인프라 구성요소 실행
PostgreSQL, Redis, MinIO 오브젝트 스토리지 및 Neo4j 그래프 데이터베이스를 하나의 백그라운드 스택으로 띄웁니다.
# server 디렉토리 내부 docker-compose 파일 실행 sudo docker compose up -d # 기동 상태 정상화 확인 sudo docker compose ps
API 환경 파일 구성 (.env)
# Central Data Store Connections DATABASE_URL=postgres://n8n:n8n_password@localhost:5432/certbridge REDIS_URL=redis://localhost:6379/2 # File Storage Configuration MINIO_ENDPOINT=localhost:9000 MINIO_ACCESS_KEY=minioadmin MINIO_SECRET_KEY=minioadmin MINIO_BUCKET=certbridge # Neo4j Graph DB Config NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=certbridge123 # Core Express API Config API_PORT=8090 JWT_SECRET=your-premium-secret-key-change-in-production
⚠️ 필수 보안 주의사항
운영 환경 배포 시, JWT_SECRET 암호화 키와 기본 데이터베이스 패스워드 및 MinIO ACCESS/SECRET 키를 난수 형태로 반드시 교체해 적용하십시오.
API 서버 의존성 설치 및 기동
# server/api 폴더로 이동 후 모듈 다운로드 npm install --production # API 서버 데몬 모드로 수동 기동 source .env && node server.js # 헬스체크 정상 수신 확인 curl http://localhost:8090/health
3. 클라이언트 설치 (Windows)
설치 파일 패키지 다운로드
공식 릴리즈 보관소(HuggingFace 또는 회사 CDN망)에서 CertBridge_0.1.0_x64-setup.exe(자동 빌드 본)를 안전하게 받아옵니다.
설치 마법사 진행 및 언어 타겟팅
설치 마법사 단계에서 원하는 언어를 기본적으로 설정(한글/영어 자동 매칭)한 후, 지정된 경로에 클라이언트 바이너리를 빌드 설치합니다.
중앙 엔드포인트 연결 테스트
바탕화면 단축 아이콘을 통해 실행 후, 우측 아래의 설정 아이콘(⚙️)을 클릭해 중앙에 개방된 API 서버 IP 및 도메인을 입력하여 테스트 통신합니다: http://<중앙서버_IP>:8090
4. 네트워크 및 포트 구성
인프라 시스템 사용 포트 현황
| 연동 서비스 | 기본 포트 | 프로토콜 | 설명 |
|---|---|---|---|
| CertBridge API Gateway | 8090 | HTTP | 코어 클라이언트 REST & 하트비트 연결 창구 (인바운드 허용 필수) |
| Neo4j Bolt Driver | 7687 | TCP / Bolt | 품질 지식 온톨로지 고속 커넥터 포트 |
| MinIO Storage API | 9000 | HTTP | 성적서 PDF 물리 원본 파일 읽기/쓰기 스토리지 API |
| n8n Automation Engine | 5678 | HTTP | 워크플로우 자동화 파이프라인 트리거 엔드포인트 |
Ubuntu 방화벽 (UFW) 설정 스크립트
# 기본 포트 개방 sudo ufw allow 8090/tcp # 보안 권고: 데이터 관리자 IP 대역만 Neo4j, MinIO 콘솔 허용 sudo ufw allow from 192.168.10.0/24 to any port 7474 sudo ufw allow from 192.168.10.0/24 to any port 9001
5. 중앙 관리 환경 초기화
5-1. 최초 관리자 계정 정보
설치가 정상적으로 마쳐지면 데이터베이스 시드 스크립트를 통해 아래 관리자 레코드가 생성됩니다:
| 설정 정보 | 지정된 기본 값 |
|---|---|
| 아이디 | admin |
| 비밀번호 | admin123 |
| 등급 | admin |
5-2. 공장 그룹 및 로컬 프로파일 할당
어드민 로그인 완료 후 [그룹 관리] 탭으로 진입하여 새 조직을 추가합니다. 본사 중앙 서버를 유지하면서 각 로컬 공장(예: 청주공장, 헝가리공장, 미국공장)마다 로컬 DB 접속 문자열 및 로컬 MinIO/Neo4j 정보를 다르게 입력해 데이터를 완벽히 격리할 수 있습니다.
6. 문제 해결 (Troubleshooting)
🔴 Docker 컨테이너 구동 시 Permission Denied 발생
사용자 계정이 docker 권한 그룹에 포함되지 않아 발생합니다. sudo usermod -aG docker $USER 명령을 입력한 후, 쉘 터미널 세션을 완전히 종료했다가 다시 로그인해 시작하십시오.
🔴 "ECONNREFUSED" 서버 응답 에러 수신
중앙 서버 측의 API 실행 데몬 프로세스가 기동되지 않았거나 포트가 충돌한 경우입니다. sudo systemctl status certbridge 상태 조회를 통해 systemd 서비스 생존 유무를 검사하십시오.
🟡 Windows SmartScreen 차단 팝업이 출력됩니다.
본 패키지는 도메인 프라이빗 개발 본으로 코드 사이닝(Code Signing) 서명서가 결여되어 있습니다. 팝업 하단의 "추가 정보"를 클릭한 다음, 나타난 "실행" 버튼을 안심하고 클릭해 셋업을 완수해 주시기 바랍니다.