Macbook
4b86b2a660
- server-dev start/stop/deploy 및 Gitea push 자동 배포 - local-dev 로컬 개발 환경 Co-authored-by: Cursor <cursoragent@cursor.com>
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# chatbotApp — 카카오 인앱·브라우저 단독 챗봇 UI (Next.js + SSE)
|
|
|
|
`chatbotAdmin`의 챗봇 테스트 화면과 **별개**인, 고속도로 이용객 대상 **단독 웹 챗봇**입니다.
|
|
|
|
| 구분 | 경로 | 기술 |
|
|
|------|------|------|
|
|
| **chatbotApp (기존)** | `/chatbot/app/` | Next.js 14 · 카카오톡 스타일 · SSE |
|
|
| **chatbotApp (AI 모드)** | `/chatbot/ai/` | Next.js 14 · 정부24 AI 스타일 · SSE |
|
|
| **chatbotApp (배너)** | `/chatbot/banner/` | 검색창 + 드롭다운 · iframe/embed.js 임베드 |
|
|
| **chatbotApp (샘플)** | `/chatbot/sample/` | 국민참여로 UI + banner iframe 데모 |
|
|
| chatbotAdmin ChatPage | `/chatbot/admin/` | Admin RAG 디버그 |
|
|
|
|
## 운영 URL
|
|
|
|
```
|
|
https://chatbot.exdev.co.kr/chatbot/app/ ← 기존 UI
|
|
https://chatbot.exdev.co.kr/chatbot/ai/ ← AI 모드 UI
|
|
https://chatbot.exdev.co.kr/chatbot/banner/ ← 배너 검색 (임베드)
|
|
https://chatbot.exdev.co.kr/chatbot/sample/ ← 국민참여로 샘플
|
|
```
|
|
|
|
## 아키텍처
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
APP[브라우저/카카오 인앱] -->|/chatbot/ask/stream SSE, /chatbot/ask JSON| SK[kakaoChatbotSkill /web/ask +/stream]
|
|
SK --> RAG[RAG :28012 /agent/chat]
|
|
RAG --> OUT([answer + 카드 + faqUrls])
|
|
```
|
|
|
|
- **웹 입력 전용 경로**: chatbotApp 질의는 kakaoChatbotSkill의 `/web/ask` 또는 `/web/ask/stream`을 거쳐 RAG Agent(`/agent/chat`)로 전달됩니다.
|
|
- **속도**: SSE는 kakao-skill에서 전체 답변 완료 후 `done` 이벤트로 전달 (카카오 callback과 유사).
|
|
- **안정성**: JSON API도 유지해 스트림 실패 시 일반 응답을 받을 수 있습니다.
|
|
- **FAQ/세션**: `/chatbot/faq/*`, `/chatbot/session/*`는 웹 UI 보조 API입니다.
|
|
|
|
### botId · 세션 정책 (현재)
|
|
|
|
- 웹앱은 `sessionStorage`에 저장한 랜덤 `botId`(`web-...`, `src/lib/session.ts`)를 사용하며, **대화마다 새 botId로 시작하는 무상태 정책**입니다.
|
|
- 카카오톡과 **세션을 연계하지 않으며**, 웹 진입 시 **과거 대화를 화면에 복원하지 않습니다**(`useChatSession`은 빈 상태로 시작, `/web/ask`만 호출).
|
|
- 서버(MongoDB `chat_history`)에는 botId별 이력이 남지만, botId가 매번 새로 발급되므로 사실상 새 세션입니다. 정책 배경·향후 세션 연계(서명 토큰) 옵션: [`../SYSTEM_ARCHITECTURE.md`](../SYSTEM_ARCHITECTURE.md), [`../IMPROVEMENTS.md`](../IMPROVEMENTS.md).
|
|
|
|
## 로컬 단독 실행 (nginx :8089)
|
|
|
|
> **포트:** `8089` = chatbotApp 전용. Caddy HTTP는 `9089` (`CADDY_HTTP_PORT`).
|
|
> GoldenChart 로그인이 보이면 `docker stop ex-chatbot-caddy` 후 `./start.sh` 재실행.
|
|
|
|
```bash
|
|
cd chatbotApp
|
|
./start.sh
|
|
# → http://localhost:8089/chatbot/app/
|
|
```
|
|
|
|
RAG API(`:28012`)가 기동되어 있어야 질의·SSE가 동작합니다.
|
|
|
|
로컬 UI + **원격 API**(기본): `./start.sh` — nginx가 `/chatbot/*`를 `https://chatbot.exdev.co.kr`로 프록시합니다. 로컬 LLM/RAG는 필요 없습니다.
|
|
|
|
로컬 RAG로 테스트하려면:
|
|
|
|
```bash
|
|
CHATBOT_API_UPSTREAM=http://host.docker.internal:28012/chatbot/ \
|
|
CHATBOT_API_HOST=host.docker.internal \
|
|
./start.sh
|
|
```
|
|
|
|
## 개발
|
|
|
|
```bash
|
|
cd chatbotApp/web
|
|
npm install
|
|
npm run dev # http://localhost:3000 — /chatbot/* 는 exdev.co.kr 로 프록시 (next.config rewrites)
|
|
```
|
|
|
|
## 배포 빌드
|
|
|
|
```bash
|
|
cd chatbotApp
|
|
chmod +x build.sh
|
|
./build.sh # → public/ (VERSION 3.0.0)
|
|
```
|
|
|
|
프로젝트 루트에서 RAG 반영:
|
|
|
|
```bash
|
|
./scripts/reload-chatbot-app.sh
|
|
# 또는
|
|
./remote-start-chatbot.sh
|
|
```
|
|
|
|
## API
|
|
|
|
| Method | Path | 설명 |
|
|
|--------|------|------|
|
|
| POST | `/chatbot/ask/stream` | SSE 스트리밍 질의 (웹앱 기본) |
|
|
| POST | `/chatbot/ask` | JSON 응답 |
|
|
| GET | `/chatbot/faq/popular` | FAQ |
|
|
| POST | `/chatbot/session/start` | 세션 추적 |
|
|
|
|
## 파일 구조
|
|
|
|
```
|
|
chatbotApp/
|
|
├── web/ # Next.js 소스
|
|
│ ├── src/
|
|
│ └── scripts/export-public.mjs
|
|
├── public/ # 빌드 산출물 (배포)
|
|
├── build.sh
|
|
├── nginx/
|
|
└── docker-compose.yml
|
|
```
|