CoNAI Docs

Appearance

문제 해결 ​

CoNAI 사용 중 자주 만나는 문제와 확인 순서입니다. 먼저 증상을 좁히고, 그다음 설정/로그/권한을 봅니다.

앱이 켜지지 않음 ​

  1. Node.js 버전을 확인합니다. CoNAI는 Node.js >= 18.0.0이 필요합니다.
  2. 의존성을 다시 설치합니다.
bash
npm install
npm run install:all
  1. .env가 있는지 확인합니다.
  2. PORT=1666, FRONTEND_URL=http://localhost:1677 값을 확인합니다.
  3. 포트 1666, 1677 충돌 여부를 확인합니다.
  4. 로그를 확인합니다.

프론트엔드가 백엔드에 연결되지 않음 ​

확인 항목:

  • 백엔드가 PORT=1666으로 실행 중인지
  • 프론트엔드가 http://localhost:1677에서 열렸는지
  • .env의 FRONTEND_URL이 현재 프론트 주소와 맞는지
  • BIND_ADDRESS가 접속 방식과 맞는지
  • 브라우저에서 백엔드 주소에 접근 가능한지
  • 방화벽/프록시가 막고 있지 않은지

내부망 접속이면 BIND_ADDRESS=0.0.0.0과 방화벽 인바운드 규칙을 함께 확인합니다.

이미지가 홈에 보이지 않음 ​

  1. /settings → 감시 폴더에서 폴더가 등록되어 있는지 확인합니다.
  2. 폴더가 활성 상태인지 확인합니다.
  3. 전체 스캔을 실행합니다.
  4. 최근 스캔 로그에서 신규/기존/오류 수를 봅니다.
  5. 제외 확장자/패턴을 확인합니다.
  6. 파일 형식이 지원되는지 확인합니다.
  7. 현재 계정에 홈 보기 권한이 있는지 /access에서 확인합니다.
  8. 업로드 파일이라면 /upload 결과의 실패 목록을 확인합니다.

감시 폴더 스캔이 실패함 ​

  • 경로가 실제로 존재하는지 확인합니다.
  • CoNAI 실행 계정이 해당 폴더를 읽을 수 있는지 확인합니다.
  • 네트워크 드라이브라면 연결이 유지되는지 확인합니다.
  • 제외 패턴이 대상 파일을 모두 막고 있지 않은지 확인합니다.
  • 폴더 내 임시 파일/잠금 파일이 많은지 확인합니다.
  • 최근 스캔 로그의 오류 수와 메시지를 확인합니다.

watcher가 멈춤 ​

  1. /settings → 감시 폴더 운영 카드에서 watcher 오류 수를 확인합니다.
  2. 개별 폴더 상세에서 watcher 상태 배지를 확인합니다.
  3. watcher 재시작을 실행합니다.
  4. 폴더 경로가 여전히 존재하는지 확인합니다.
  5. 네트워크 드라이브라면 polling 간격을 늘립니다.
  6. 반복되면 자동 스캔 중심으로 운영합니다.

메타데이터 추출 실패 ​

  • 파일이 손상되지 않았는지 확인합니다.
  • 해당 포맷의 메타데이터가 실제로 있는지 확인합니다.
  • /settings → 메타데이터에서 stealth 스캔 모드를 확인합니다.
  • 파일 크기/해상도가 stealth 제한보다 큰지 확인합니다.
  • 업로드 페이지에서 단일 파일 추출로 재현합니다.
  • 필요하면 /settings → 메타데이터에서 모든 항목 재추출을 큐에 넣습니다.

자동 태그/작가 추출 실패 ​

  • /settings → 자동의 개요 상태를 확인합니다.
  • WD Tagger 의존성 확인 상태를 봅니다.
  • Kaloscope 설정과 상태를 확인합니다.
  • 테스트 카드에서 해시 확인 또는 랜덤 선택 후 추출을 실행합니다.
  • 모델 파일이 필요하면 모델 경로와 다운로드 상태를 확인합니다.

이미지 상세의 유사도 결과가 이상함 ​

  • 상세 화면에서 유사/중복 검사를 수동 실행해 봅니다.
  • /settings → 일반에서 자동 실행 정책을 확인합니다.
  • 상세 화면의 유사도 설정 패널에서 임계값과 결과 수를 조정합니다.
  • 이미지 유사도와 텍스트 유사도 탭을 구분해서 봅니다.
  • 메타데이터 필터가 결과를 지나치게 좁히지 않는지 확인합니다.

메타데이터 저장/다운로드 실패 ​

  • 대상이 정적 이미지인지 확인합니다.
  • 원본 파일 경로가 존재하는지 확인합니다.
  • 파일이 다른 프로그램에서 잠겨 있지 않은지 확인합니다.
  • 출력 형식(PNG/JPEG/WebP)을 바꿔 봅니다.
  • 브라우저 다운로드 차단 여부를 확인합니다.
  • 저장 전 파일/DB 백업이 필요한지 확인합니다.

ComfyUI 연결 실패 ​

  • ComfyUI 서버가 실행 중인지 확인합니다.
  • 서버 URL과 포트를 확인합니다.
  • 브라우저에서 ComfyUI에 직접 접근 가능한지 확인합니다.
  • CoNAI의 서버 등록 정보를 다시 테스트합니다.
  • 원격 서버라면 방화벽과 인증을 확인합니다.
  • 워크플로우 JSON과 Marked Field가 실제 노드 구조와 맞는지 확인합니다.

Codex 생성 실패 ​

  • Codex 탭의 상태 카드에서 CLI 사용 가능 여부를 확인합니다.
  • Codex CLI가 설치되어 있고 로그인/인증이 끝났는지 확인합니다.
  • 프롬프트와 입력 이미지 경로가 너무 길거나 접근 불가하지 않은지 확인합니다.
  • 큐 상태에서 실패 메시지를 확인합니다.
  • 결과 이미지가 생성됐지만 CoNAI가 가져오지 못했다면 출력 경로와 파일 권한을 확인합니다.

권한 때문에 페이지가 안 보임 ​

  1. /access에서 현재 계정이 열 수 있는 페이지를 확인합니다.
  2. 관리자 계정으로 로그인합니다.
  3. /settings → 보안에서 계정의 권한 그룹을 확인합니다.
  4. 권한 그룹에 필요한 페이지 권한을 부여합니다.
  5. 저장 후 페이지 새로고침 또는 재로그인을 합니다.

삭제/복구 문제 ​

  • /settings → 일반에서 삭제 보호가 켜져 있는지 확인합니다.
  • RecycleBin 경로를 확인합니다.
  • 원본 파일이 외부에서 이미 삭제되지 않았는지 확인합니다.
  • database, uploads, RecycleBin 백업 시점이 맞는지 확인합니다.
  • 대량 삭제 후에는 전체 파일 검증을 실행합니다.

빌드/문서 문제 ​

문서 빌드:

bash
npm run docs:build

앱 빌드:

bash
npm run build

VitePress chunk size 경고는 빌드 실패가 아닙니다. 종료 코드가 0인지, docs/.vitepress/dist가 생성되는지 확인하세요.

그래도 안 풀릴 때 가져올 정보 ​

  • 어떤 페이지에서 발생했는지
  • 재현 단계
  • 브라우저 콘솔 오류
  • 백엔드 로그
  • 최근 스캔 로그
  • 관련 composite hash
  • 감시 폴더 경로와 제외 규칙
  • 현재 계정 권한 상태

다음 문서: 설정 전체 지도