> ## Documentation Index
> Fetch the complete documentation index at: https://doc.howen.ink/llms.txt
> Use this file to discover all available pages before exploring further.

# 자주 묻는 질문

> 배포, 키, 분석, 음성 읽기, 오늘의 문장과 관련된 흔한 문제를 해결합니다.

<Info>
  앱의 오류 메시지는 현재 화면 언어로 표시됩니다. 이 페이지는 한국어 화면에 표시되는 문구를 인용합니다. 모델 제공업체가 반환한 원본 오류 메시지(예: `HTTP 429: ...`)는 번역되지 않습니다.
</Info>

## 배포와 접속

<AccordionGroup>
  <Accordion title="페이지는 열리지만 분석할 때 「API 키가 없습니다」라고 표시됨">
    서버에 유효한 `DEEPSEEK_API_KEY` 또는 `GEMINI_API_KEY`가 없고, 브라우저 설정에도 키를 입력하지 않았습니다.

    * Docker: `.env.production`을 수정한 뒤 `docker compose up -d`를 실행해 컨테이너를 다시 만드세요.
    * Vercel: **Settings** → **Environment Variables**에 변수를 추가한 뒤 다시 배포하세요.
    * 로컬 개발: `.env.local`을 수정한 뒤 `npm run dev`를 다시 시작하세요.
  </Accordion>

  <Accordion title="Gemini 키만 설정했는데 분석이 계속 실패함">
    앱은 기본적으로 DeepSeek를 사용합니다. **설정**을 열고 **AI 제공업체**를 **Gemini**로 바꾼 다음 **설정 저장**을 누르세요.
  </Accordion>

  <Accordion title="서버에서 curl은 정상인데 외부에서 열리지 않음">
    클라우드 보안 그룹이나 시스템 방화벽에서 해당 포트를 열지 않았습니다. `3002`를 열거나, 리버스 프록시를 설정한 뒤 `80`과 `443`을 여세요.
  </Accordion>

  <Accordion title="HTTPS 인증서 발급 실패">
    도메인이 아직 서버를 가리키지 않거나 `80` 포트가 열려 있지 않습니다. A 레코드가 적용되었는지 확인한 뒤 다시 시도하세요.
  </Accordion>

  <Accordion title="접속 비밀번호를 설정했는데 매번 다시 입력해야 함">
    프로덕션 환경에서는 세션 Cookie에 `Secure` 플래그가 붙어 HTTPS에서만 저장됩니다. 사이트에 HTTPS를 설정하세요. `CODE`를 바꾸면 기존 세션도 모두 무효가 됩니다.
  </Accordion>
</AccordionGroup>

## 분석과 번역

<AccordionGroup>
  <Accordion title="스트리밍 출력이 자주 끊김">
    **설정**에서 **스트리밍 출력**을 끄고, 전체 결과를 한 번에 받도록 바꾸세요. Nginx 리버스 프록시를 사용한다면 `proxy_buffering off`를 설정했는지도 확인하세요.
  </Accordion>

  <Accordion title="「분석 결과가 원문과 일치하지 않습니다」라고 표시됨">
    모델이 반환한 단어를 이어 붙인 결과가 원문과 다릅니다. 다시 분석하거나 다른 모델 버전으로 바꾸세요.
  </Accordion>

  <Accordion title="모델이 출력을 잘랐다고 표시됨(finish_reason: length)">
    출력이 모델의 길이 상한을 넘었습니다. 원문을 줄이거나 여러 번에 나누어 분석하세요.
  </Accordion>

  <Accordion title="「상위 API 요청 시간이 초과되었습니다」라고 표시됨">
    모델 제공업체가 60초 안에 응답하지 않았습니다. 서버와 모델 제공업체 사이의 네트워크를 확인하고 잠시 후 다시 시도하세요.
  </Accordion>

  <Accordion title="「상위 스트리밍 응답이 멈췄습니다」라고 표시됨">
    스트리밍 출력에서 90초 넘게 새 내용을 받지 못했습니다. 다시 분석해 보세요. 자주 발생하면 **설정**에서 **스트리밍 출력**을 끄세요.
  </Accordion>

  <Accordion title="단어 분리가 부정확해 한 단어가 여러 조각으로 나뉨">
    해당 단어들을 선택하세요. 앱이 한 단어라고 판단하면 **한 단어로 합치기**를 누르세요. 자세한 내용은 [단어 상세 설명과 여러 단어 선택](/ko/features/word-detail#나뉜-단어-합치기)을 참고하세요.
  </Accordion>
</AccordionGroup>

## 기타 기능

<AccordionGroup>
  <Accordion title="홈 화면의 오늘의 문장이 몇 개의 고정된 문장만 반복됨">
    서버에 사용 가능한 API 키가 없거나, 외부 네트워크에서 모델 제공업체에 접속할 수 없어 앱이 내장된 예비 문장 7개를 사용하고 있습니다. 오늘의 문장은 서버 키만 사용하며 브라우저에 입력한 키는 사용하지 않습니다.
  </Accordion>

  <Accordion title="Gemini TTS로 읽을 수 없음">
    Gemini TTS에는 Gemini API 키가 필요합니다. 서버에 `GEMINI_API_KEY`를 설정하거나 **설정**에서 Gemini 키를 입력하세요. 키가 필요 없는 Edge TTS로 되돌릴 수도 있습니다.
  </Accordion>

  <Accordion title="새로고침하면 최근 기록이 사라짐">
    브라우저에서 로컬 저장소가 비활성화되어 있거나 시크릿 모드입니다. 일반 창을 사용하거나 사이트의 데이터 저장을 허용하세요.
  </Accordion>
</AccordionGroup>

## 문제 보고

위 내용으로 해결되지 않으면 GitHub에 [Issue](https://github.com/cokice/japanese-analyzer/issues)를 등록하세요. 분석 문제를 보고할 때는 다음을 함께 적어 주세요.

* 모델 제공업체와 모델 버전
* 화면 언어
* 문제를 재현할 수 있는 원문

<Warning>
  Issue에 API 키나 접속 비밀번호를 붙여넣지 마세요.
</Warning>