641 lines
30 KiB
Markdown
641 lines
30 KiB
Markdown
# 🎬 Huobao Drama - AI 숏드라마 생성 플랫폼
|
||
|
||
<div align="center">
|
||
|
||
**TypeScript 풀스택 기반 AI 숏드라마 자동 제작 플랫폼**
|
||
|
||
[](https://nodejs.org)
|
||
[](https://vuejs.org)
|
||
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
||
[](https://github.com/chatfire-AI/huobao-drama/releases/latest)
|
||
|
||
[中英双语](README.md) | [English](README.en.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | **한국어**
|
||
|
||
[기능](#-기능) • [빠른 시작](#-빠른-시작) • [튜토리얼](#-그림-튜토리얼) • [데스크톱 앱](#-데스크톱-앱-권장) • [배포](#-배포)
|
||
|
||
<h2>🔑 <a href="https://api.firemux.com">Huobao API Key 받기 👉 바로 보기</a></h2>
|
||
|
||
**텍스트 · 이미지 · 영상 모든 AI 기능, Key 하나로 활성화**
|
||
|
||
배포 후 「설정 → 火宝快捷 설정」에 Key 를 붙여넣으면 추천 설정 3개가 한 번에 입력됩니다
|
||
|
||
<h3>📥 <a href="https://github.com/chatfire-AI/huobao-drama/releases/latest">데스크톱 앱 다운로드 (macOS / Windows)</a></h3>
|
||
<h3>🌐 <a href="https://www.firemux.cn">공식 웹사이트</a></h3>
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
## 📖 프로젝트 소개
|
||
|
||
Huobao Drama는 AI 기반 숏드라마 자동 제작 플랫폼으로, 각본 생성, 캐릭터 디자인, 스토리보드 제작부터 영상 합성까지 전 과정을 자동화합니다.
|
||
|
||
### 🎯 핵심 가치
|
||
|
||
- **🤖 AI 기반**:대규모 언어 모델로 각본을 분석하여 캐릭터, 장면, 스토리보드 정보를 추출
|
||
- **🎨 지능형 창작**:AI 이미지 생성으로 캐릭터 이미지와 장면 배경 제작
|
||
- **📹 영상 생성**:텍스트→영상 및 이미지→영상 모델로 스토리보드 영상 자동 생성
|
||
- **🔄 워크플로**:아이디어부터 완성 영상까지 숏드라마 제작 전 과정을 한 곳에서 완료
|
||
|
||
### 🛠️ 기술 아키텍처
|
||
|
||
```
|
||
frontend/ — Nuxt 3 + Vue 3 + TypeScript (순수 CSS, UI 프레임워크 없음)
|
||
backend/ — Hono + Drizzle ORM + Mastra AI Agents + better-sqlite3
|
||
backend/workspace/skills/ — Agent 스킬 정의 (SKILL.md, UI에서 온라인 편집 가능)
|
||
desktop/ — Electron 데스크톱 버전 (메인 프로세스 + esbuild 번들 + electron-builder로 dmg/exe 생성)
|
||
data/ — 생성된 에셋과 SQLite 데이터베이스
|
||
```
|
||
|
||
---
|
||
|
||
## ✨ 기능
|
||
|
||
### 🎭 캐릭터 관리
|
||
|
||
- ✅ AI 캐릭터 이미지 생성
|
||
- ✅ 캐릭터 일괄 생성
|
||
- ✅ 캐릭터 이미지 업로드 및 관리
|
||
|
||
### 🎬 영상 작업
|
||
|
||
- ✅ AI 영상 작업 자동 생성
|
||
- ✅ 장면 설명 및 영상 프롬프트 생성
|
||
- ✅ 작업별 영상 일괄 생성
|
||
|
||
### 🎥 영상 생성
|
||
|
||
- ✅ 텍스트→영상 자동 생성
|
||
- ✅ FFmpeg 샷 단위 합성 및 자막 처리
|
||
- ✅ 에피소드 전체 병합 및 납출
|
||
|
||
### 📦 에셋 관리
|
||
|
||
- ✅ 소재 라이브러리 통합 관리
|
||
- ✅ 로컬 스토리지 지원
|
||
- ✅ 작업 진행 상황 추적
|
||
|
||
### 🤖 AI Agents
|
||
|
||
4개의 Mastra Agent 내장, 데이터베이스 설정과 Skill 확장 지원:
|
||
|
||
| Agent | 역할 |
|
||
|---|---|
|
||
| `script_rewriter` | 소설 → 형식화된 각본 리라이팅 |
|
||
| `extractor` | 캐릭터 / 장면 / 소품 지능형 추출 및 중복 제거 |
|
||
| `storyboard_breaker` | 각본 → 스토리보드 시퀀스 분해 |
|
||
| `prompt_generator` | 캐릭터/장면/소품 이미지 프롬프트 + 스토리보드 영상 프롬프트 생성 |
|
||
|
||
### 🌐 다국어 UI
|
||
|
||
인터페이스는 **中文 / English / 日本語 / 한국어** 4개 언어를 내장하고, AI 생성 콘텐츠의 언어를 전역으로 설정할 수 있습니다.
|
||
|
||
### 🔌 멀티 프로바이더 지원
|
||
|
||
| 유형 | 지원 프로바이더 |
|
||
|---|---|
|
||
| **텍스트** | OpenAI(호환 API), Gemini |
|
||
| **이미지** | OpenAI, Gemini, Volcano Engine |
|
||
| **영상** | Volcano Engine Seedance 2.0(Standard / Fast / Mini), MiniMax H3, Alibaba Bailian Wan 3.0(Prime / Standard) |
|
||
|
||
---
|
||
|
||
## 🚀 빠른 시작
|
||
|
||
### 📋 환경 요구 사항
|
||
|
||
| 소프트웨어 | 버전 | 설명 |
|
||
|---|---|---|
|
||
| **Node.js** | 20+ | 프런트엔드/백엔드 실행 환경 |
|
||
| **npm** | 9+ | 패키지 관리 도구 |
|
||
|
||
> **데이터베이스 설치 불필요**:SQLite 내장(프로젝트 데이터 디렉터리의 단일 파일)으로 데이터베이스 서버 설치가 필요 없습니다.
|
||
> **FFmpeg 설치 불필요**:`ffmpeg-static` / `ffprobe-static` npm 패키지에 바이너리가 내장되어 바로 사용할 수 있습니다.
|
||
|
||
### ⚙️ 환경 변수
|
||
|
||
설정 파일 없이 환경 변수로 설정합니다(모두 기본값이 있어 로컬 개발은 무설정으로 시작 가능):
|
||
|
||
| 변수 | 기본값 | 설명 |
|
||
|---|---|---|
|
||
| `SQLITE_PATH` | `<저장소>/data/huobao.sqlite3` | SQLite 데이터베이스 파일 위치 |
|
||
| `PORT` | `5679` | 백엔드 서비스 포트 |
|
||
| `STORAGE_PATH` | `<저장소>/data/static` | 생성 파일 저장 디렉터리 |
|
||
| `HUOBAO_DATA_DIR` | — | 데스크톱 버전에서 Electron 메인 프로세스가 주입(userData 데이터 루트) |
|
||
| `WORKSPACE_PATH` | `backend/workspace` | Agent 스킬/프롬프트 디렉터리(데스크톱 버전은 userData의 쓰기 가능한 복사본) |
|
||
| `FRONTEND_DIST` | `frontend/dist` | 프런트엔드 정적 빌드 디렉터리 |
|
||
| `FFMPEG_BIN` / `FFPROBE_BIN` | npm 내장 바이너리 | 사용자 지정 ffmpeg/ffprobe 실행 파일 경로 |
|
||
| `PUBLIC_BASE_URL` | — | Seedance가 로컬 참조 리소스를 사용할 때 필요한 공개 주소(서버 배포용) |
|
||
|
||
> **설명**:AI 서비스의 API Key, Base URL, 모델 파라미터는 모두 웹 UI의 「설정」 페이지에서 설정하여 데이터베이스에 저장합니다. 설정 파일이나 환경 변수로 관리하지 않습니다.
|
||
|
||
### 📥 설치
|
||
|
||
```bash
|
||
# 저장소 클론
|
||
git clone https://github.com/chatfire-AI/huobao-drama.git
|
||
cd huobao-drama
|
||
|
||
# 백엔드 의존성 설치
|
||
cd backend && npm install
|
||
|
||
# 프런트엔드 의존성 설치
|
||
cd ../frontend && npm install
|
||
```
|
||
|
||
### 🎯 실행
|
||
|
||
#### 방법 1: 개발 모드(권장)
|
||
|
||
프런트엔드와 백엔드를 분리하여 핫 리로드 지원:
|
||
|
||
```bash
|
||
# 터미널 1: 백엔드
|
||
cd backend
|
||
npm run dev
|
||
|
||
# 터미널 2: 프런트엔드
|
||
cd frontend
|
||
npm run dev
|
||
```
|
||
|
||
- 프런트엔드 주소: `http://localhost:3013`
|
||
- 백엔드 API: `http://localhost:5679/api/v1`
|
||
- 프런트엔드가 `/api`와 `/static`을 백엔드로 자동 프록시
|
||
|
||
#### 방법 2: 단일 서비스 모드
|
||
|
||
백엔드가 API와 프런트엔드 정적 파일을 모두 제공:
|
||
|
||
```bash
|
||
# 1. 프런트엔드 빌드
|
||
cd frontend && npm run generate
|
||
|
||
# 2. 빌드 산출물을 백엔드가 읽는 디렉터리로 복사
|
||
# (generate 산출물은 .output/public, 백엔드는 frontend/dist를 읽음)
|
||
cp -r .output/public dist
|
||
|
||
# 3. 백엔드 시작
|
||
cd ../backend && npm start
|
||
```
|
||
|
||
접속: `http://localhost:5679`
|
||
|
||
### 🗄️ 데이터베이스
|
||
|
||
SQLite 내장(`better-sqlite3` + WAL 모드). 최초 시작 시 테이블 자동 생성(멱등 DDL 재생 + 시드 데이터). 기본 파일은 `data/huobao.sqlite3`이며 `SQLITE_PATH`로 변경 가능. 데스크톱 버전의 데이터는 사용자 데이터 디렉터리(`~/Library/Application Support/HuobaoDrama/data/`)에 저장됩니다.
|
||
|
||
구버전 MySQL에서 데이터 마이그레이션:
|
||
|
||
**시작 시 자동 마이그레이션(권장)**: MySQL이 명시적으로 설정되어 있고(`DATABASE_URL` 또는 `MYSQL_HOST`) SQLite가 비어 있으면, 백엔드 시작 시 자동으로 감지하여 모든 테이블을 한 번만 가져옵니다(테이블별 행 수 검증, 단일 트랜잭션 원자적 쓰기, 실패 시 자동 롤백 후 다음 시작 때 재시도, 성공 시 `.mysql-imported` 마커를 기록하여 중복 방지). `MYSQL_AUTO_IMPORT=false`로 비활성화할 수 있습니다.
|
||
|
||
```bash
|
||
# 수동 실행도 가능(대상 DB가 비어 있지 않으면 --force 필요, 쓰기 전 자동 백업)
|
||
cd backend && npx tsx scripts/import-mysql-to-sqlite.ts
|
||
```
|
||
|
||
> 마이그레이션은 데이터베이스 행만 포함합니다. 구 배포의 `data/static/` 아래 이미지/영상 등 미디어 파일은 수동으로 복사해야 하며, 그렇지 않으면 기존 소재에 접근할 수 없습니다.
|
||
|
||
### 🔑 첫 사용: AI 서비스 설정
|
||
|
||
시작 후 모든 AI 기능(텍스트/이미지/영상)을 사용하려면 먼저 모델 서비스를 설정해야 합니다. 미설정 시 페이지 상단에 배너로 안내합니다:
|
||
|
||
1. 「설정」 페이지 열기
|
||
2. 「火宝快捷 설정」에 Huobao API Key 붙여넣기([api.firemux.com에서 발급](https://api.firemux.com)). 텍스트, 이미지, 영상 추천 설정 3개가 한 번에 입력됩니다
|
||
3. 또는 「수동 템플릿」으로 프로바이더별 추가. 연결 테스트 지원
|
||
|
||
설정이 완료되면 배너가 자동으로 사라지고 에피소드 제작을 시작할 수 있습니다.
|
||
|
||
---
|
||
|
||
## 📖 그림 튜토리얼
|
||
|
||
소설부터 완성 에피소드까지의 전체 제작 흐름입니다. 왼쪽 진행 표시줄이 항상 현재 단계를 보여줍니다.
|
||
|
||
### 1단계 · 프로젝트 생성
|
||
|
||
홈에서 "새 프로젝트"를 클릭하고 **화면 비율**(16:9 가로 / 9:16 세로, 생성 후 변경 불가)과 **화풍**(3D / 실사 등, 모든 이미지 프롬프트에 주입)을 선택합니다.
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/02-create-drama.png" alt="프로젝트 생성" width="800">
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/01-projects.png" alt="프로젝트 목록" width="800">
|
||
</p>
|
||
|
||
### 2단계 · AI 서비스 설정 (최초)
|
||
|
||
설정 페이지의 "휘바오 빠른 설정"에 API 키를 붙여넣으면 추천 설정 3종을 한 번에 등록합니다. 수동 템플릿으로 직접 추가할 수도 있습니다. 사용 모델은 상단 바에서 언제든 전환 가능합니다(5단계 참고).
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/03-settings-quick.png" alt="AI 서비스 설정" width="800">
|
||
</p>
|
||
|
||
### 3단계 · 대본 단계
|
||
|
||
제작 화면에 **원문(소설)**을 붙여넣고 "AI 재작성"을 실행하면 촬영용 대본이 생성됩니다 — 에피소드별 분할 및 장면·캐릭터 주석 포함. 모델과 톤을 바꿔가며 재작성할 수 있습니다.
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/05-script.png" alt="대본 단계" width="800">
|
||
</p>
|
||
|
||
### 4단계 · 에셋 제작
|
||
|
||
대본에 **추출**을 실행하면 캐릭터 / 장면 / 소품 목록이 자동 생성됩니다. 각 항목의 "이미지 생성"으로 일관성 있는 참조 이미지를 만들 수 있습니다(일괄 생성 지원). 이 이미지들은 영상 생성 시 참조 소재로 주입됩니다.
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/06-assets.png" alt="에셋 제작" width="800">
|
||
</p>
|
||
|
||
### 5단계 · 스토리보드와 영상
|
||
|
||
"영상 제작" 페이지에서 먼저 **스토리보드 분할**을 실행하세요(AI가 컷을 나누고 영상 프롬프트 생성). 그 후:
|
||
|
||
- 상단 바에서 **영상 모델** 선택(Seedance / Wan 3.0 / MiniMax 등). 해상도와 길이 옵션은 모델에 연동됩니다
|
||
- 오른쪽에서 각 컷의 프롬프트를 확인·조정(`@캐릭터명` 참조는 자동으로 참조 이미지에 매핑)
|
||
- "일괄 영상 생성"으로 작업 시작. 실패한 작업은 원클릭 재시도
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/07-storyboard.png" alt="스토리보드 분할" width="800">
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/08-videos.png" alt="영상 생성" width="800">
|
||
</p>
|
||
|
||
### 6단계 · 병합과 내보내기
|
||
|
||
컷을 선택(호버로 각 클립 미리보기)하고 "병합 시작"을 누르면 FFmpeg이 완성 에피소드를 자동 합성합니다. 온라인 재생·다운로드 가능. 완료 후 "완료 표시"를 누르면 진행 표시줄이 켜집니다.
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/09-export.png" alt="병합과 내보내기" width="800">
|
||
</p>
|
||
|
||
에피소드 목록에서 각 화의 제작 현황을 확인하고 "제작 열기"로 이어서 작업할 수 있습니다:
|
||
|
||
<p align="center">
|
||
<img src="docs/screenshots/04-episodes.png" alt="에피소드 목록" width="800">
|
||
</p>
|
||
|
||
---
|
||
|
||
## 📦 배포
|
||
|
||
### 🖥️ 데스크톱 앱(권장)
|
||
|
||
**⬇️ 빌드된 설치 파일: [GitHub Releases](https://github.com/chatfire-AI/huobao-drama/releases/latest) · [중국용 미러(Tencent COS)](https://installer.firemux.site/huobao-drama/v4.0.11/)**
|
||
|
||
| 플랫폼 | 다운로드 파일 |
|
||
|---|---|
|
||
| macOS(Apple Silicon, M 시리즈) | `HuobaoDrama-4.0.5-arm64.dmg` |
|
||
| macOS(Intel) | `HuobaoDrama-4.0.5.dmg` |
|
||
| Windows | `HuobaoDrama.Setup.4.0.5.exe` |
|
||
|
||
> 중국 본토에서는 GitHub이 불안정하므로 Tencent COS 미러를 이용하세요. 앱 내 업데이터도 COS를 우선하고 GitHub으로 폴백합니다.
|
||
|
||
**커맨드라인 설치(권장, 복구 불필요)**: curl로 다운로드하면 macOS 격리 속성이 붙지 않아 "손상됨" 경고 없이 바로 실행됩니다(Apple Silicon은 `-arm64.dmg`, Intel은 일반 dmg 사용):
|
||
|
||
```bash
|
||
curl -L -o /tmp/HuobaoDrama.dmg https://installer.firemux.site/huobao-drama/v4.0.11/HuobaoDrama-4.0.11-arm64.dmg \
|
||
&& hdiutil attach -nobrowse /tmp/HuobaoDrama.dmg \
|
||
&& cp -R /Volumes/HuobaoDrama*/HuobaoDrama.app /Applications/ \
|
||
&& hdiutil detach /Volumes/HuobaoDrama*
|
||
```
|
||
|
||
빌드 불필요 — dmg/exe를 다운로드해 바로 설치하면 됩니다. 설치된 클라이언트는 내장 업데이터로 자동 업데이트됩니다. (소스에서 직접 패키징하려면 아래 명령을 참조하세요.)
|
||
|
||
더블클릭 설치로 바로 사용할 수 있는 데스크톱 버전(macOS + Windows). 데이터베이스(SQLite), 생성된 미디어 파일, Agent 스킬은 모두 사용자 데이터 디렉터리에 저장되며 앱을 삭제필필도 데이터에 영향이 없습니다.
|
||
|
||
```bash
|
||
# 원커맨드 패키징(프런트엔드 generate → 백엔드 esbuild → electron-builder)
|
||
npm run dist # macOS dmg(arm64 + Intel)
|
||
npm run dist:win # Windows NSIS 설치 프로그램(win-x64, macOS에서 크로스 빌드 가능)
|
||
|
||
# 산출물
|
||
# desktop/release/HuobaoDrama-<버전>-arm64.dmg (Apple Silicon)
|
||
# desktop/release/HuobaoDrama-<버전>.dmg (Intel)
|
||
# desktop/release/HuobaoDrama Setup <버전>.exe (Windows)
|
||
```
|
||
|
||
설치 안내:
|
||
|
||
- macOS 미서명 패키지는 첫 실행 시 "App이 손상되어 열 수 없습니다"라는 메시지가 뜰 수 있습니다(Apple Silicon에서 흔함). 이는 Gatekeeper 격리 속성 때문이며 파일이 실제로 손상된 것은 아닙니다. 복구 방법은 두 가지입니다:
|
||
1. **dmg에 복구 스크립트 포함**: 앱을 "응용 프로그램"으로 드래그한 후 dmg 창 하단의 "如提示已损坏请双击我.command"를 더블클릭하면 자동으로 복구됩니다;
|
||
2. 또는 터미널에서 `sudo xattr -cr /Applications/HuobaoDrama.app` 실행.
|
||
|
||
복구는 처음 한 번만 필요하며, 이후에는 정상 실행되고 앱 내 자동 업데이트에도 영향이 없습니다.
|
||
- Windows 미서명 패키지는 SmartScreen에서 「추가 정보 → 실행」 선택
|
||
- 사용자 데이터 디렉터리: `~/Library/Application Support/HuobaoDrama/`(데이터베이스, 생성된 미디어, 온라인 편집한 스킬 복사본)
|
||
- FFmpeg/FFprobe 바이너리 내장, 시스템 설치 불필요
|
||
- Electron은 37.x로 고정: better-sqlite3의 win32 프리빌드가 해당 ABI까지만 지원(크로스 패키징 시 컴파일 불필요의 핵심)
|
||
- 앱 내 외부 링크(「api.firemux.com에서 Key 받기」 등)는 시스템 브라우저로 바로 열립니다
|
||
|
||
#### 🔄 앱 내 업데이트(Apple 서명 불필요)
|
||
|
||
데스크톱 버전에는 업데이터가 내장되어 있습니다(Tauri와 동류 방식: macOS 디렉터리 교체 / Windows 사일런트 설치, 로컬 sha256 검증). 새 버전 릴리스 절차:
|
||
|
||
```bash
|
||
# 1. desktop/package.json의 version을 수정한 후 패키징
|
||
npm run dist # macOS(dmg + 업데이트용 zip 산출)
|
||
npm run dist:win # Windows(Setup.exe 산출)
|
||
|
||
# 2. 버전 매니페스트 release/latest.json 생성(플랫폼별 sha256 포함)
|
||
cd desktop && npm run feed
|
||
|
||
# 3. 릴리스: latest.json + 설치 패키지 + zip을 GitHub Release에 업로드(태그는 v1.0.1 형식)
|
||
```
|
||
|
||
설치된 클라이언트는 시작 후 매니페스트를 자동으로 확인하고(「설정 → 정보 및 업데이트」에서 수동 확인도 가능), 새 버전을 발견하면 다운로드 및 설치를 안내합니다. 매니페스트 주소는 `HUOBAO_UPDATE_FEED` 환경 변수로 변경할 수 있습니다.
|
||
|
||
데스크톱 버전 개발 디버깅:
|
||
|
||
```bash
|
||
npm run build:frontend # 프런트엔드 정적 산출물(frontend/.output/public)
|
||
cd desktop && npm run dev # 백엔드 번들 후 Electron 창으로 실행
|
||
```
|
||
|
||
> 알려진 제한: Seedance 영상 모델이 로컬 참조 리소스를 사용하려면 `PUBLIC_BASE_URL` 공개 주소가 필요합니다. 데스크톱 버전에는 공개 진입점이 없어 해당 시나리오에서는 명확한 오류 메시지가 표시됩니다. 텍스트→영상/이미지 생성 등 나머지 기능에는 영향이 없습니다.
|
||
|
||
---
|
||
|
||
### 🏭 서버 배포
|
||
|
||
```bash
|
||
# 1. 프런트엔드 빌드
|
||
cd frontend && npm run generate
|
||
|
||
# 2. 빌드 산출물 복사(generate 산출물은 frontend/.output/public, 백엔드는
|
||
# frontend/dist를 읽음. 이 단계를 생략하면 API는 정상이지만 페이지가 404)
|
||
cp -r .output/public dist && cd ..
|
||
|
||
# 3. 백엔드 시작
|
||
cd backend && npm start
|
||
```
|
||
|
||
서버에 업로드할 파일:
|
||
|
||
```
|
||
backend/ # 백엔드 소스 + node_modules
|
||
backend/workspace/skills/ # Agent 스킬 파일
|
||
frontend/dist/ # 프런트엔드 빌드 산출물
|
||
data/ # 데이터 디렉터리(최초 실행 시 자동 생성)
|
||
```
|
||
|
||
#### Nginx 리버스 프록시
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
# 참조 영상/오디오 업로드 최대 50MB
|
||
client_max_body_size 100m;
|
||
|
||
# 생성된 이미지/영상은 디스크에서 직접 서빙(Node를 거치지 않음):
|
||
# sendfile 제로 카피 + 장기 캐시
|
||
# (파일은 uuid 명명, 내용 불변이므로 immutable 캐시 안전)
|
||
location /static/ {
|
||
alias /path/to/huobao-drama/data/static/;
|
||
sendfile on;
|
||
tcp_nopush on;
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
location / {
|
||
proxy_pass http://localhost:5679;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
}
|
||
}
|
||
```
|
||
|
||
> 미디어 로딩 최적화: 이미지 생성 시 백엔드가 목록 페이지용 400px 썸네일(`*_thumb.webp`)을 자동 생성하고, 영상은 포스터 프레임(`*_poster.jpg`)을 커버로 추출합니다. 프런트엔드는 큰 이미지를 열거나 재생할 때만 원본 파일을 로드합니다. 기존 파일은 `backend/`에서 `npm run backfill-artwork`를 실행해 일괄 보완할 수 있습니다.
|
||
|
||
### 🐳 Docker 배포(앱 내 업데이트 포함)
|
||
|
||
**방법 A — 사전 빌드 이미지(클론·빌드 불필요)**: 멀티 아키텍처(`linux/amd64` + `linux/arm64`), x86 서버와 ARM 디바이스 자동 매칭
|
||
|
||
```bash
|
||
docker pull huobao/huobao-drama:4.0.6
|
||
|
||
docker run -d \
|
||
--name huobao-drama \
|
||
-p 5679:5679 \
|
||
-v huobao-data:/app/data \
|
||
--restart unless-stopped \
|
||
huobao/huobao-drama:4.0.6
|
||
```
|
||
|
||
**방법 B — docker compose(소스 빌드 + Watchtower 인앱 업데이트)**: 저장소 루트에 올인원 `Dockerfile`(프런트엔드 generate + 백엔드 의존성/런타임 3단계, 백엔드는 서버 배포와 동일하게 tsx로 실행)과 `docker-compose.yml`(앱 + Watchtower)을 제공합니다:
|
||
|
||
```bash
|
||
# 1. 환경 설정(Watchtower 토큰, app과 watchtower 양쪽이 일치해야 함)
|
||
cp .env.example .env # WATCHTOWER_TOKEN 수정
|
||
|
||
# 2. 빌드 및 시작(릴리스 시 버전을 주입하여 「정보 및 업데이트」 비교에 사용)
|
||
HUOBAO_VERSION=4.0.5 docker compose up -d --build
|
||
|
||
# 3. http://localhost:5679 접속
|
||
```
|
||
|
||
- **데이터 영속화**: 네임드 볼륨 `huobao-data`를 `/app/data`에 마운트(SQLite + 생성된 이미지/영상 + workspace/skills). 이미지 업데이트 시에도 데이터 유지
|
||
- **앱 내 업데이트**: compose에 [Watchtower](https://containrrr.dev/watchtower/) 사이드카 포함(`--label-enable`로 라벨이 지정된 컨테이너만 업데이트, `--cleanup`으로 구 이미지 정리, 매일 자체 점검). 「설정 → 정보 및 업데이트」에서 새 버전 확인 및 「지금 업데이트」 가능 — 백엔드가 Watchtower HTTP API를 통해 트리거하여 새 이미지를 가져와 컨테이너를 재생성합니다. 몇 분 후 페이지를 새로고침하면 완료
|
||
- **수동 모드**: `docker-compose.yml`에서 app의 `HUOBAO_WATCHTOWER_*` 환경 변수 2개(또는 watchtower 서비스 전체)를 삭제하면 「정보 및 업데이트」는 새 버전 알림 + 수동 명령 `docker compose pull && docker compose up -d`으로 전환됩니다
|
||
- **이미지 릴리스**: `docker buildx build --platform linux/amd64,linux/arm64 --build-arg HUOBAO_VERSION=x.y.z -t huobao/huobao-drama:x.y.z -t huobao/huobao-drama:latest --push .`. 버전 매니페스트는 데스크톱 버전과 GitHub Releases의 `latest.json`을 공유(`HUOBAO_UPDATE_FEED`로 재정의 가능)
|
||
|
||
---
|
||
|
||
## 🎨 기술 스택
|
||
|
||
### 백엔드
|
||
|
||
- **런타임**: Node.js 20+
|
||
- **웹 프레임워크**: Hono
|
||
- **ORM**: Drizzle ORM + better-sqlite3(WAL 모드)
|
||
- **AI Agent**: Mastra + AI SDK(OpenAI 호환)
|
||
- **영상 처리**: FFmpeg(fluent-ffmpeg + 내장 바이너리)
|
||
- **이미지 처리**: Sharp
|
||
|
||
### 데스크톱
|
||
|
||
- **셸**: Electron(utilityProcess가 백엔드를 호스팅, BrowserWindow는 동일 출처로 로드)
|
||
- **패키징**: esbuild(백엔드 단일 파일 번들) + electron-builder(dmg arm64/x64, NSIS win-x64)
|
||
|
||
### 프런트엔드
|
||
|
||
- **프레임워크**: Nuxt 3(SPA 모드)
|
||
- **언어**: Vue 3 + TypeScript
|
||
- **라우팅**: 파일 라우팅(Vue Router 4)
|
||
- **스타일**: 순수 CSS + CSS Variables
|
||
- **아이콘**: Lucide Vue
|
||
- **i18n**: vue-i18n(中文 / English / 日本語 / 한국어)
|
||
|
||
---
|
||
|
||
## 📝 자주 묻는 질문
|
||
|
||
### Q: 데스크톱 버전의 데이터는 어디에 저장되나요?
|
||
|
||
A: `~/Library/Application Support/HuobaoDrama/data/`(SQLite 데이터베이스 + 생성된 이미지/영상)에 저장되며, 온라인 편집한 스킬의 복사본은 같은 수준의 `workspace/` 디렉터리에 있습니다. 개발 모드에서는 저장소의 `data/` 디렉터리를 사용합니다.
|
||
|
||
### Q: 구버전 MySQL 데이터를 SQLite로 마이그레이션하려면?
|
||
|
||
A: MySQL에 연결 가능한 상태(환경 변수 또는 `backend/.env`)를 유지하고 `cd backend && npx tsx scripts/import-mysql-to-sqlite.ts`를 실행하세요. 스크립트가 자동으로 테이블을 생성하고 테이블별로 가져오며 행 수를 검증합니다(대상 DB가 비어 있지 않으면 `--force` 필요, 쓰기 전 자동 백업).
|
||
|
||
### Q: FFmpeg가 설치되지 않았거나 찾을 수 없다고 나옵니다?
|
||
|
||
A: 설치할 필요가 없습니다. 프로젝트에 `ffmpeg-static` / `ffprobe-static` 바이너리가 내장되어 있습니다(데스크톱 버전에도 포함). 시스템 `PATH`의 FFmpeg와 충돌하지 않으며, `FFMPEG_BIN`/`FFPROBE_BIN`으로 명시적으로 지정할 수도 있습니다.
|
||
|
||
### Q: 페이지 상단에 「모델 미설정」이 표시됩니다?
|
||
|
||
A: 정상적인 첫 배포 안내입니다. 「설정」 페이지에서 「火宝快捷 설정」에 API Key를 붙여넣어 한 번에 입력하거나, 「수동 템플릿」으로 프로바이더를 추가하세요. 텍스트, 이미지, 영상 3가지 모두에 활성화된 설정이 있으면 배너가 자동으로 사라집니다.
|
||
|
||
### Q: 프런트엔드가 백엔드 API에 연결되지 않습니다?
|
||
|
||
A: 백엔드가 시작되었는지, 포트가 올바른지 확인하세요. 개발 모드의 프록시 설정은 `frontend/nuxt.config.ts`에 있습니다.
|
||
|
||
### Q: 데이터베이스 테이블이 생성되지 않았습니다?
|
||
|
||
A: 백엔드는 최초 시작 시 모든 테이블을 자동으로 생성합니다. 로그에서 초기화 성공 여부를 확인하세요.
|
||
|
||
---
|
||
|
||
## 📋 업데이트 로그
|
||
|
||
### v4.0.0 (2026-08)
|
||
|
||
#### 🖥️ 데스크톱 앱 + 데이터베이스 마이그레이션
|
||
|
||
- Electron 데스크톱 버전(macOS dmg, arm64/x64 듀얼 아키텍처)
|
||
- 더블클릭 설치, 즉시 사용: 자동 포트 선택, 단일 인스턴스 잠금, 충돌 분리된 백엔드 서브프로세스
|
||
- 사용자 데이터 분리: SQLite DB / 생성된 미디어 / 스킬 복사본 모두 userData 디렉터리에 저장
|
||
- FFmpeg/FFprobe 포함 배포. workspace 스킬 템플릿은 첫 시작 시 복사, 업그레이드 시 누락분만 보충하고 덮어쓰지 않음
|
||
- 데이터베이스를 MySQL에서 SQLite로 완전 마이그레이션(better-sqlite3 + WAL)
|
||
- 비즈니스 코드 변경 제로(Drizzle 쿼리 계층은 본질적으로 이식 가능), 멱등 DDL 재생
|
||
- 1회용 가져오기 스크립트 `import-mysql-to-sqlite.ts` 추가(테이블별 행 수 검증 + 자동 백업)
|
||
- 백엔드 esbuild 단일 파일 번들(externals: sharp/better-sqlite3/ffmpeg 바이너리 패키지)
|
||
- Docker/MySQL 배포 방식 제거(git 히스토리에서 복구 가능)
|
||
|
||
### v3.1.0 (2026-09)
|
||
|
||
- Alibaba Bailian Wan 3.0 동영상 모델 추가(Prime / 표준, 공식 input.media/parameters 파라미터 지원)
|
||
- 작업대 상단 바에 해상도 선택기 추가, 제공사별 네이티브 단계 표시(Seedance 480p/720p, MiniMax 768P/2K, Wan 480P/720P/1080P)
|
||
- 기본 동영상 모델을 Seedance 2.0 Mini로 변경
|
||
- 동영상 모델 전환 시 제공사/모델 불일치로 인한 생성 오류 수정
|
||
- 배치 동영상: 선택 모드 + 생성 전 확인(숏 수/총 길이/모델/해상도), 실패 작업 원클릭 재시도
|
||
- 스토리보드 길이를 동영상 생성 파라미터 영역에서 직접 편집·저장, 단건/배치 생성에 통일 적용
|
||
- 실사/민감 콘텐츠 심사 실패 시 모델 전환 후 재시도 안내
|
||
|
||
### v3.0.0 (2026-08)
|
||
|
||
|
||
#### 🚀 배포 및 경험 최적화
|
||
|
||
- Docker 배포 준비 개선
|
||
- MySQL / 앱 헬스 체크, 데이터베이스 준비 후 앱 시작
|
||
- 데이터베이스 초기화에 재시도 추가, 컨테이너 오케스트레이션에서 첫 배포 무인 완료
|
||
- 시스템 FFmpeg 의존 제거, 내장 바이너리로 전면 전환
|
||
- Agent skills 디렉터리 볼륨 영속화(설정 페이지 온라인 편집 유실 방지)
|
||
- `docker/init.sql` 및 납출 스크립트 추가(DBA 검토 / 사전 테이블 생성)
|
||
- 첫 사용 가이드
|
||
- AI 서비스 미설정 시 사이트 상단 배너로 설정 페이지 안내
|
||
- 설정 페이지에 「火宝快捷 설정」 추가: Key 하나로 텍스트/이미지/영상 추천 설정 3개 입력
|
||
- 모델 미설정 오류의 중국어화 및 설정 페이지 안내
|
||
- 영상 모델 기본값을 Seedance 2.0 Fast로 조정
|
||
- 프로바이더 통합: OpenAI / Gemini / Volcano Engine만 유지
|
||
- 워크벤치: 작업 목록 드로어, 파이프라인 대섹션 상태, 선택적 병합(병합 전 영상 파일 존재 검증)
|
||
- 소재 라이브러리 개편, @멘션 최적화, 에피소드 목록 재구성
|
||
|
||
### v2.0.0 (2026-04)
|
||
|
||
#### 🚀 대규모 업데이트
|
||
|
||
- 프로젝트를 TypeScript 기술 스택으로 전면 마이그레이션
|
||
- 백엔드: Hono + Drizzle ORM + mysql2
|
||
- 프런트엔드: Nuxt 3 + Vue 3
|
||
- AI Agent: Mastra 프레임워크
|
||
- 에피소드 워크벤치 UI와 제작 플로우 재구축
|
||
- 더 컴팩트한 콘솔 레이아웃
|
||
- 스토리보드 편집 영역 재구축
|
||
- 샷 이미지, 영상, 합성, 납출 화면 재구축
|
||
- Docker 배포 지원 추가, 프런트엔드와 백엔드를 단일 이미지로 통합
|
||
- 런타임 Skill 로딩 메커니즘 추가
|
||
- 멀티 프로바이더 미디어 어댑터 확장
|
||
- 이미지: OpenAI, Gemini, Volcano Engine, Alibaba
|
||
- 영상: Volcano Engine/Seedance, Vidu, Alibaba
|
||
- 로컬 파일 처리 및 참조 이미지 온디맨드 트랜스코딩 최적화
|
||
|
||
### v1.0.4 (2026-01-27)
|
||
|
||
- 로컬 스토리지 전략 도입으로 외부 리소스 링크 실효 회피
|
||
- Base64 참조 이미지 임베디드 전송
|
||
- 샷 전환 상태 리셋 문제 수정
|
||
- 장면의 챕터 마이그레이션 추가
|
||
|
||
### v1.0.3 (2026-01-16)
|
||
|
||
- 데이터베이스 동시 접근 성능 최적화
|
||
- Docker 크로스 플랫폼 host.docker.internal 지원
|
||
|
||
### v1.0.2 (2026-01-14)
|
||
|
||
- 영상 생성 API 응답 파싱 문제 수정
|
||
- OpenAI Sora 영상 엔드포인트 설정 추가
|
||
- 오류 처리 및 로그 출력 최적화
|
||
|
||
---
|
||
|
||
## 📄 라이선스
|
||
|
||
이 프로젝트는 **[CC BY-NC-SA 4.0](LICENSE)**(저작자표시-비영리-동일조걳경변경허락 4.0 국제) 라이선스를 채택하고 있습니다.
|
||
|
||
- ✅ 개인 사용, 학습·연구, 비영리 프로젝트는 자유롭게 사용 가능
|
||
- ✅ 수정 및 재배포 가능, 단 저작자 표시와 동일 라이선스로 공유 필요
|
||
- ❌ **상업적 사용 금지** — 저작자의 서면 허가 없이 이 프로젝트의 전부 또는 일부를 어떠한 상업적 목적(유료 서비스, 상업 배포, 재판매 등)으로도 사용할 수 없습니다
|
||
|
||
라이선스 전문은 [LICENSE](LICENSE)를 참조하세요.
|
||
|
||
---
|
||
|
||
## 🤝 기여 가이드
|
||
|
||
Issue와 Pull Request를 환영합니다!
|
||
|
||
1. 이 프로젝트를 Fork
|
||
2. 기능 브랜치 생성(`git checkout -b feature/AmazingFeature`)
|
||
3. 변경 사항 커밋(`git commit -m 'Add some AmazingFeature'`)
|
||
4. 브랜치 푸시(`git push origin feature/AmazingFeature`)
|
||
5. Pull Request 생성
|
||
|
||
자주 쓰는 검사 명령:
|
||
|
||
```bash
|
||
cd backend && npm run typecheck
|
||
cd ../frontend && npm run build
|
||
```
|
||
|
||
---
|
||
|
||
## 💬 WeChat 그룹
|
||
|
||
QR 코드를 스캔하여 WeChat 그룹에 참여하세요:
|
||
|
||
<div align="center">
|
||
<img src="docs/images/wx-group.png" width="200" alt="WeChat 그룹 QR 코드" />
|
||
</div>
|
||
|
||
---
|
||
|
||
> _"AI가 더 창의적인 일을 돕게 하자"_
|
||
|
||
## 🔗 관련 링크
|
||
|
||
이 프로젝트는 [LINUX DO](https://linux.do/) 커뮤니티의 링크 승인을 받았습니다.
|
||
|
||
- [LINUX DO](https://linux.do/) — 진정한 오픈소스 정신, 함께 만들고 공유하는 기술 커뮤니티
|
||
|
||
---
|