내 환경에서 시작하는 LorelyChat

1. 준비할 것

Git과 실행 중인 Docker, Docker Compose가 필요합니다. Windows·macOS에서는 Docker Desktop을, Linux에서는 Docker Engine과 Compose 플러그인을 사용할 수 있습니다. 아래 명령은 설치할 컴퓨터의 터미널에서 실행하세요.

git --version
docker version
docker compose version

Docker 클라이언트 설치만으로는 실행되지 않습니다. Docker Desktop 또는 Docker 데몬을 먼저 시작하세요. Node.js와 Python을 호스트에 별도로 설치할 필요는 없습니다.

2. 제품 저장소 내려받기

브랜드 사이트가 아닌 실제 LorelyChat 제품 저장소의 main 브랜치를 사용합니다. 이미 lorelychat 폴더가 있다면 새 폴더 이름을 정하거나 기존 설치를 확인하세요.

git clone --branch main --single-branch https://github.com/orderthan31/lorelychat-public.git lorelychat
cd lorelychat

3. 환경 설정 파일 만들기

macOS·Linux 터미널에서는 다음 명령으로 예제 설정을 복사합니다. 이미 .env가 있다면 덮어쓰지 말고 기존 설정을 먼저 확인하세요.

cp .env.example .env

Windows PowerShell에서는 Copy-Item .env.example .env 를 실행하세요. .env와 API 키를 Git에 올리거나 공개 문의에 첨부하지 마세요.

4. 실행하고 브라우저에서 열기

첫 실행은 이미지와 의존성을 내려받아 빌드하므로 인터넷 연결과 시간이 필요합니다. api와 web이 healthy 상태인지 확인한 뒤 설치한 컴퓨터에서 아래 주소를 여세요.

docker compose config --quiet
docker compose up --build -d
docker compose ps

127.0.0.1은 지금 브라우저를 여는 기기 자신을 가리킵니다. 이 안내 사이트가 제공하는 온라인 체험 주소가 아닙니다. 8080 포트가 이미 사용 중이면 .env의 LORECHAT_PORT를 빈 포트로 바꾸고 접속 주소도 함께 바꾸세요.

5. 기본 모드와 실제 AI 응답 구분하기

예제 설정은 LLM_MOCK=true로 시작합니다. 설치 확인용 예시 캐릭터와 세계관을 제공하며, 이 모드의 채팅 응답은 실제 AI 모델 생성이 아닙니다. 유료 AI 키 없이 먼저 화면과 기본 흐름을 확인할 수 있습니다.

• 실제 AI를 쓰려면 웹의 설정 → 모델 설정에서 사용할 프로바이더 계정을 만듭니다.
• 지원 프로토콜과 base URL을 확인하고 내 API 키를 등록합니다.
• 호환되는 채팅 모델을 동기화하거나 직접 추가하고 런타임 기본 모델로 지정합니다.
• .env의 LLM_MOCK를 false로 바꾼 뒤 아래 명령으로 API 컨테이너를 재생성합니다.

docker compose up -d --force-recreate api

BYOK는 선택한 AI 서비스에 내 계정으로 사용 비용을 지불하는 방식입니다. LorelyChat은 AI 사용료에 추가 마진을 붙이지 않습니다. 모델별 요금·사용 제한·전송 데이터 정책은 해당 서비스에서 확인하세요. API 키는 설치 서버의 비밀정보 파일에 보관되며 파일 자체는 암호화되어 있지 않습니다.

6. 저장 데이터와 백업

Docker named volume에는 데이터베이스, 업로드, 로그와 프로바이더 비밀정보가 들어 있습니다. 브라우저 데이터를 지우거나 컨테이너를 재생성해도 서버 데이터는 남습니다.

업데이트·서버 이전 전에 컨테이너를 중지하고 실제 프로젝트에 속한 네 저장 볼륨을 호스트의 백업 도구 또는 검토한 백업 절차로 보관하세요. 데이터베이스뿐 아니라 업로드와 비밀정보도 함께 필요합니다. 백업은 접근을 제한하고 암호화해 저장소 밖에 보관하세요.

docker compose stop
docker volume ls --filter label=com.docker.compose.project=lorechat

위 명령은 중지와 볼륨 확인까지만 수행하며 백업 자체를 만들지 않습니다. 기본 프로젝트 이름은 lorechat입니다. COMPOSE_PROJECT_NAME을 바꿨다면 필터도 실제 이름으로 바꾸세요. 백업이 끝나면 docker compose start 로 다시 시작합니다.

7. 업데이트와 종료

저장 볼륨과 .env를 백업한 뒤 업데이트합니다. git pull이 충돌하거나 로컬 수정 때문에 실패하면 변경을 확인하세요. 강제 초기화로 덮어쓰지 마세요.

git pull --ff-only
docker compose build --pull
docker compose up -d
docker compose ps

일반 종료는 docker compose down 입니다. 이 명령은 기본적으로 named volume을 보존합니다. 볼륨 제거 옵션은 데이터베이스·업로드·로그·저장된 키를 영구 삭제할 수 있으므로 일상 종료나 업데이트에 사용하지 마세요.

8. 다른 기기에서 접속하기

기본 구성은 신뢰할 수 있는 단일 사용자가 설치한 컴퓨터에서 사용하는 환경입니다. 완전한 다중 사용자 인증 경계를 제공하지 않으므로 바인드 주소를 바꿔 공개 인터넷에 바로 노출하지 마세요.

다른 기기에서 접속하려면 사설 VPN 또는 인증과 TLS를 갖춘 리버스 프록시 등 접근 제어를 먼저 준비하세요. 0.0.0.0 바인드나 포트포워딩만으로 안전한 원격 접속이 되는 것은 아닙니다.

문제가 생겼을 때

• Docker에 연결할 수 없음: Docker Desktop 또는 Docker 데몬이 실행 중인지 확인합니다.
• 포트 사용 중: 다른 서비스는 중지하지 말고 .env의 LORECHAT_PORT를 빈 포트로 변경합니다.
• 화면은 열리지만 예시 응답만 나옴: LLM_MOCK=false와 API 재생성, 런타임 기본 모델을 확인합니다.
• 프로바이더 연결 실패: 프로토콜·base URL·모델명·키와 사용 한도를 확인합니다.
• Docker 안의 모델 서버 주소: 컨테이너의 127.0.0.1은 호스트가 아닙니다. 호스트 모델 서버 연결은 저장소 프로바이더 안내를 확인하세요.

docker compose ps
docker compose logs --tail 100 api web

로그에는 민감정보가 포함될 수 있습니다. 공개 문의 전에 API 키, 대화 원문, 개인정보와 내부 접속 정보를 제거하세요. 보안 문제는 공개 Issues가 아닌 저장소 보안 정책의 비공개 신고 절차를 이용하세요.