INU AppCenter Integrated AI Server

이 프로젝트는 인천대학교 앱센터 통합 AI 서버입니다. 외부에 노출되는 운영 웹 서버는 Spring Boot 하나만 사용하고, 현재는 유니돔 전용 API와 공용 AI API를 함께 제공하며, 앞으로 다른 프로젝트용 AI API를 같은 서버 안에 계속 추가할 수 있도록 정리합니다.

기존 FastAPI 웹 레이어는 운영 경로에서 제거했고, archive/fastapi-web-layer 아래에 참고용으로만 보관합니다.

API 구조

• 프로젝트 전용 API 현재 /unidorm
• 공용 AI API 현재 /shared
• 향후 확장 방식 다른 프로젝트 API는 /{project-prefix} 형태로 같은 서버 안에 추가

현재 폴더 구조

• src/main/java Spring Boot API, 인증, 관리자 기능, 운영 로직
• src/main/resources/bridge/bridge_server.py Spring Boot가 내부적으로 기동하는 Python 브리지
• runtime/python/unidorm 유니돔 전용 AI 엔진, 크롤러, 데이터, DB, 로그
• runtime/python/shared 공용 AI 로직과 관련 데이터
• runtime/python/projects 향후 다른 프로젝트별 Python 런타임 확장 영역
• runtime/python/.env 내부 Python 런타임 환경 변수
• archive/fastapi-web-layer 기존 FastAPI 웹 서버와 라우터 보관본

운영 원칙

• 외부 요청은 Spring Boot 서버만 받습니다.
• Python은 내부 런타임으로만 남겨두고, Spring Boot가 브리지와 크롤러를 직접 호출합니다.
• 기존 FastAPI 서버는 별도로 실행하지 않습니다.
• 현재 API 계약과 응답 형식은 최대한 유지하면서 통합 서버 구조로 확장합니다.

포트 구성

• 기본 안전 모드 서버 포트: 18080
• 기본 안전 모드 브리지 포트: 18081
• 운영 프로필 서버 포트: 1024

운영에서는 Spring Boot만 1024 포트로 실행하면 됩니다.

로컬 실행

1. 안전 모드 실행

mvn spring-boot:run

특징:

• 포트 18080
• 스케줄러 비활성화
• 런타임 파일 쓰기 비활성화

Swagger:

• http://localhost:18080/swagger-ui.html
• http://localhost:18080/v3/api-docs

2. 운영 모드 실행

.\start-production.ps1

또는

mvn spring-boot:run -Dspring-boot.run.profiles=production

특징:

• 포트 1024
• 내부 Python 브리지 자동 기동
• 스케줄러 활성화
• 관리자 쓰기 및 재구성 기능 활성화
• 실행 전 루트에 남아 있던 구 FastAPI 잔여물 정리 시도

운영 Swagger:

• http://localhost:1024/swagger-ui.html

Docker 운영 배포

운영 배포는 docker-compose.production.yml 기준으로 진행합니다.

핵심 원칙:

• 운영 서버는 Docker의 production 프로필로만 실행
• 운영 설정/상태/관리자 입력은 MySQL을 우선 저장소로 사용
• 운영 데이터는 Docker volume으로 분리
• 새 이미지를 배포해도 unidorm/data, unidorm/db, shared/data, 로그는 유지
• 개발은 로컬에서 하고, 검증된 버전만 새 이미지 태그로 운영 반영

준비:

Copy-Item .\docker\.env.production.example .\docker\.env.production

docker/.env.production 에서 아래 값을 반드시 채웁니다.

• APPCENTER_AI_JWT_SECRET_KEY
• SHARED_API_KEY
• UNIDORM_INTERNAL_API_KEY
• OLLAMA_HOST
• APPCENTER_AI_MYSQL_PASSWORD
• MYSQL_ROOT_PASSWORD
• 필요하면 HOST_PORT, JAVA_OPTS

배포:

$env:APP_IMAGE_TAG="2026.03.28-001"
docker compose -f .\docker-compose.production.yml build
docker compose -f .\docker-compose.production.yml up -d

롤백:

$env:APP_IMAGE_TAG="2026.03.28-000"
docker compose -f .\docker-compose.production.yml up -d

주의:

• docker compose down -v 는 운영 데이터 volume까지 삭제하므로 사용하지 않습니다.
• 관리자 available-models API 는 컨테이너 안에 ollama CLI가 없으면 빈 목록을 돌려줄 수 있습니다. 챗/추출 자체는 OLLAMA_HOST 가 연결되면 계속 동작합니다.

주요 설정

기본 Python 런타임 루트는 아래 설정을 사용합니다.

appcenter-ai:
  runtime-root-dir: runtime/python

배포 환경에서 절대 경로를 명시하려면 아래처럼 설정할 수 있습니다.

appcenter-ai:
  runtime-root-path: C:/deploy/springboot-unidorm/runtime/python

Python 실행 명령을 고정하고 싶으면 아래처럼 설정합니다.

appcenter-ai:
  python-command:
    - py
    - -3

MySQL 1차 전환 설정 예시:

appcenter-ai:
  mysql:
    enabled: true
    host: mysql
    port: 3306
    database: appcenter_ai
    username: appcenter
    password: your-password

현재 제공 API

• GET /
• POST /unidorm/auth/login
• POST /unidorm/chat
• POST /unidorm/notice-search (Bearer UNIDORM_INTERNAL_API_KEY)
• POST /unidorm/reload
• GET /unidorm/
• POST /shared/extract-schedule
• GET/POST/PUT/DELETE /unidorm/admin/...

참고

• 현재는 운영 웹 서버 단일화가 완료된 상태입니다.
• 다만 AI 엔진과 크롤러는 내부 Python 런타임으로 유지됩니다.
• src/main/resources/bridge/bridge_server.py 는 내부 브리지 구현에 FastAPI 라이브러리를 사용하지만, 운영 웹 서버로 별도 배포하거나 외부에 직접 노출하지는 않습니다.
• Python 의존성까지 완전히 제거하려면 AI 엔진, 일정 추출기, 크롤러/DB 재구성 로직을 Java로 재구현하는 2차 작업이 필요합니다.