AI 캐릭터 챗 서비스

Hono + Cloudflare Pages + D1 기반 AI 롤플레이 채팅 서비스
관리자 패널에서 설정만 바꾸면 누구나 원하는 캐릭터로 서비스 운영 가능

---

현재 구현 완료 기능

기능	상태
캐릭터 완전 변수화 (관리자 패널)	✅
D1 데이터베이스 영속 저장	✅
모바일 앱 UI (max-width 420px, 다크모드)	✅
게스트 / 회원 이중 구조	✅
3단계 온보딩 회원가입	✅
대화 히스토리 영속 저장	✅
장기 기억 압축 (30턴 초과 시 자동 요약)	✅
상황 이미지 트리거	✅
DomoAI 영상 생성	✅
Claude / OpenAI 호환 API 자동 감지	✅
게스트 대화 → 회원가입 시 이어받기	✅
JWT 인증 (사용자 30일, 게스트 7일, 관리자 8시간)	✅

---

기술 스택

구분	기술
프레임워크	Hono v4 (Cloudflare Workers)
배포 플랫폼	Cloudflare Pages
데이터베이스	Cloudflare D1 (SQLite)
인증	JOSE (JWT HS256)
빌드 도구	Vite + @hono/vite-build
프론트엔드	Vanilla HTML/CSS/JS + Tailwind CSS CDN

---

프로젝트 구조

webapp/
├── src/
│   ├── index.tsx              # 메인 Hono 앱 + HTML 렌더링
│   ├── types.ts               # TypeScript 타입 정의
│   ├── lib/
│   │   ├── db.ts              # D1 데이터베이스 헬퍼
│   │   ├── jwt.ts             # JWT 서명/검증 (jose)
│   │   └── llm.ts             # LLM 호출, 응답 파싱, 기억 압축
│   ├── middleware/
│   │   └── auth.ts            # 사용자/관리자 인증 미들웨어
│   └── routes/
│       ├── public.ts          # 공개 API (/api/character, /api/guest/init)
│       ├── user.ts            # 회원 API (/api/user/*)
│       ├── chat.ts            # 채팅 API (/api/chat)
│       └── admin.ts           # 관리자 API (/api/admin/*)
├── migrations/
│   └── 0001_initial_schema.sql
├── .dev.vars                  # 로컬 환경변수
├── wrangler.jsonc             # Cloudflare 설정
├── vite.config.ts
├── ecosystem.config.cjs       # PM2 설정
└── package.json

---

접속 URL

페이지	경로
사용자 채팅	/
관리자 패널	/admin
API 상태	/api/status

• 샌드박스: https://3000-i1e9pl235886crge5yrqt-02b9cc79.sandbox.novita.ai
• 관리자 기본 비밀번호: admin1234

---

API 레퍼런스

공개 API

Method	Path	설명
GET	/api/character	캐릭터 공개 정보
POST	/api/guest/init	게스트 세션 + JWT 발급
GET	/api/status	서버 상태

사용자 API (Bearer JWT)

Method	Path	설명
POST	/api/user/register	회원가입 (3단계 온보딩)
POST	/api/user/login	로그인
POST	/api/user/profile	프로필 업데이트
GET	/api/user/me	내 정보 조회
POST	/api/chat	채팅 메시지 전송
GET	/api/chat/history	대화 히스토리
DELETE	/api/chat/history	대화 초기화

관리자 API (Bearer adminJWT)

Method	Path	설명
POST	/api/admin/login	관리자 로그인
GET	/api/admin/character	전체 설정 조회
POST	/api/admin/character/basic	기본 정보
POST	/api/admin/character/intro	인트로 & 예시 대화
POST	/api/admin/character/prompt	시스템 프롬프트
POST	/api/admin/character/detail	캐릭터 상세
POST	/api/admin/character/lore	세계관 & 스펙
POST/PUT/DELETE	/api/admin/character/situation/:id	상황 이미지 CRUD
POST	/api/admin/keys	API 키 저장
POST	/api/admin/generate-images	DomoAI 영상 생성
POST	/api/admin/reset-sessions	전체 세션 초기화

---

데이터 모델 (D1)

테이블	설명
character_config	캐릭터 설정 싱글톤 (id=1)
users	회원 계정
chat_sessions	회원별 대화 히스토리
guest_sessions	게스트 임시 세션 (7일 TTL)

---

환경변수 (.dev.vars)

변수	기본값	필수
JWT_SECRET	—	필수 (32자 이상)
ADMIN_PASSWORD	admin1234	권장 변경
GUEST_TOKEN_LIMIT	10	선택
MEMBER_TOKEN_LIMIT	100	선택

LLM API 키는 관리자 패널 → API 키 설정에서 런타임 중 변경 가능

---

로컬 개발

# 의존성 설치
npm install

# D1 로컬 마이그레이션
npm run db:migrate:local

# 빌드
npm run build

# PM2로 실행 (포트 3000)
pm2 start ecosystem.config.cjs

# 로그 확인
pm2 logs webapp --nostream

---

Cloudflare 배포

# 1. Cloudflare API 키 설정 후
npx wrangler d1 create webapp-production
# → database_id를 wrangler.jsonc에 입력

# 2. 프로덕션 마이그레이션
npm run db:migrate:prod

# 3. 빌드 & 배포
npm run deploy

# 4. 환경변수 설정
npx wrangler pages secret put JWT_SECRET --project-name webapp
npx wrangler pages secret put ADMIN_PASSWORD --project-name webapp

---

배포 상태

• 플랫폼: Cloudflare Pages (예정)
• 로컬 상태: ✅ 정상 실행 중
• 마지막 업데이트: 2026-03-24