프로젝트 소개

## 개요 Talivia는 창업자들을 위한 수익 추적에 초점을 맞춘 오픈소스, 자체 호스팅 분석 플랫폼입니다. 웹 분석, 세션 재생, 팀 협업 기능, 공유 분석 대시보드, 가져오기/내보내기 기능과 함께 결제 처리업체에서 고객 수익 데이터를 직접 연결할 수 있습니다. 이 프로젝트는 상용 호스팅 서비스인 Talivia Cloud의 자체 호스팅 버전입니다. 관리형 호스팅은 Google Search Console, Bing Webmaster Tools, GitHub 활동, X, Reddit, TikTok 등 소셜 언급과의 통합을 추가로 제공합니다. ## 기능 - **웹 분석**: 삽입 가능한 JavaScript 코드를 통해 방문 추적 - **세션 재생**: 웹사이트에서 사용자 세션 재생 기능 - **수익 추적**: 구독 라이프사이클, 환불, 분쟁, 최초 접촉 및 최종 접촉 추적 - **결제 통합**: Stripe, LemonSqueezy, Polar, Dodo, Yolfi, 수동 결제 API - **협업**: 웹사이트 공동 작업자 및 공유 분석 대시보드 - **가져오기/내보내기**: 데이터 마이그레이션 및 백업 워크플로우 - **암호화 통화 변환**: CoinGecko를 통한 선택적 환율 변환 - **AI 에이전트 키트**: Codex, Claude Code, ChatGPT 등과 호환되는 오픈소스 MCP 호환 툴킷으로, 추적 코드 설치, 설정 계획 생성, 실시간 이벤트 검증, 방문과 결제 추적 연결 기능 제공 ## 기술 스택 - 런타임: Node.js 22 LTS 또는 24 LTS - 패키지 관리자: pnpm 10+ - 데이터베이스: PostgreSQL - ORM: Prisma - 컨테이너화: Docker Engine 및 Docker Compose ## 설치 ### 로컬 개발 1. Node.js 22/24 LTS, pnpm 10+, 그리고 새로운 PostgreSQL 인스턴스가 준비되어 있는지 확인합니다. 2. `.env.example` 파일을 `.env`로 복사하고 `openssl rand -hex 32` 명령어로 32바이트 시크릿을 생성합니다. 3. `.env` 파일 내 `DATABASE_URL`과 `APP_SECRET`을 설정합니다. 4. 의존성 설치 및 마이그레이션 실행: ```bash pnpm install --frozen-lockfile pnpm exec prisma migrate deploy pnpm dev ``` 5. `http://localhost:3000`을 열고 `admin` / `admin`으로 로그인합니다. **설정 → 계정**에서 부트스트랩 비밀번호를 즉시 변경하세요. ### Docker ```bash cp .env.example .env openssl rand -hex 32 docker compose up --build -d ``` 컨테이너는 애플리케이션 시작 전에 OSS 데이터베이스 마이그레이션을 자동으로 적용합니다. 시작 후 기본 관리자 비밀번호를 변경하세요. ## 구성 | 변수 | 필수 여부 | 목적 | |---|---|---| | `DATABASE_URL` | 예 | PostgreSQL 연결 문자열 | | `APP_SECRET` | 예 | 세션 서명 및 자격 증명 암호화를 위한 32바이트 난수 값 | | `COINGECKO_API_KEY` | 아니요 | 암호화 통화 환율 변환 활성화; 없어도 애플리케이션이 작동 | ## 첫 사용 1. Talivia에서 웹사이트 항목을 생성합니다. 2. 제공된 추적 코드를 대상 사이트에 삽입합니다. 3. 대시보드에 방문 기록이 나타나는지 확인합니다. 4. 웹사이트 설정에서 세션 재생을 선택적으로 활성화합니다. 5. **웹사이트 설정 → 결제**에서 고객 수익을 연결합니다. 리버스 프록시 뒤에서 실행하는 경우, 웹훅 URL이 올바르게 생성되도록 원본 `Host` 및 `X-Forwarded-Proto` 헤더를 전달하세요. ## 백업 및 업그레이드 업그레이드 전 PostgreSQL 데이터베이스를 백업하세요. Compose 배포의 경우: ```bash docker compose exec -T postgres pg_dump -U talivia -d talivia_oss > talivia-backup.sql ``` 향후 릴리스에서는 `prisma/migrations` 아래에 순서대로 마이그레이션을 추가합니다. `pnpm exec prisma migrate deploy`로 적용하며, 공식 컨테이너는 시작 시 자동으로 실행됩니다. 기존 마이그레이션은 수정하지 마세요. ## AI 에이전트 키트 및 MCP Talivia는 MCP 클라이언트와 호환되는 오픈소스 에이전트 키트([github.com/talivia-group/agent](https://github.com/talivia-group/agent))를 배포합니다. 에이전트는 추적 코드 설치, 프레임워크별 설정 계획 생성, 실시간 분석 이벤트 검증, 방문과 결제 추적 연결 기능을 제공합니다. - 호스팅된 OAuth 엔드포인트 (Talivia Cloud): `https://talivia.com/mcp` - 로컬 stdio 모드: `npx -y @talivia/agent mcp` 자체 호스팅 버전은 Talivia Cloud OAuth 엔드포인트를 노출하지 않습니다. ## 보안 및 라이선스 취약점 보고 및 배포 가이드는 [SECURITY.md](SECURITY.md)에 있습니다. 개발 워크플로우 세부 정보는 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다. Talivia는 MIT 라이선스 하에 배포됩니다. ## 비교 Talivia는 Datafast의 대안으로 마케팅되며, 단일 자체 호스팅 배포 내에서 내장 수익 추적 및 다중 프로세서 결제 통합을 강조합니다.