Manual · Revised

MangaViewer 사용 매뉴얼

검색과 감상부터 읽음 상태 동기화, 관리자 설정과 컨테이너 업데이트까지 현재 운영 방식에 맞춰 정리한 매뉴얼입니다.

대시보드 v1.8.0 상태 release-production 2026-08-31 개정

지원 사이트

툰코·늑대·11툰·펀비·K만화·판다툰·블랙툰·바다툰과 HIYOBI·K-HENTAI·E-Hentai·Hitomi·MangaDex를 지원합니다.

읽기와 동기화

회차·진행률·완독 상태를 DB에 저장하고 지원 사이트의 즐겨찾기를 기본 6시간마다 동기화합니다.

운영과 배포

이미지를 최대 6GB·14일 캐시하고, 모든 사이트 주소와 API 상태를 15분마다 자동 확인합니다.

1. 빠른 시작

최초 관리자는 설치할 때 지정한 계정으로 로그인합니다. 일반 회원은 가입 후 관리자 승인이 필요합니다.
HOME 통합검색으로 허용된 사이트 전체를 찾거나, 아래 사이트별 검색을 펼쳐 한 사이트만 검색합니다.
작품 상세의 첫화보기 또는 이어보기를 누릅니다.
읽던 회차가 남아 있으면 같은 회차의 저장 위치로, 다 읽었으면 다음 회차로 이어집니다.
HOME의 전체 동기화로 지원되는 8개 사이트 즐겨찾기의 새 회차를 확인합니다.

2. 화면 구성

상단 사이트 탭
툰코 → 늑대 → 11툰 → 펀비 → K만화 → 판다툰 → 블랙툰 → 바다툰 → K-Hentai → E-Hentai → Hitomi → MangaDex 순으로 표시하며 히요비는 마지막에 유지합니다.

왼쪽 플로팅 메뉴
다크모드 / 매뉴얼 / 환경설정(관리자) / 비밀번호 변경 / 로그아웃 / 맨 위로

HOME 검색
통합검색은 기본 표시되고 사이트 선택 검색은 접혀 있습니다. 통합 결과의 사이트 칩에서 개별 검색으로 이동할 수 있습니다.

탭이 보이지 않을 때: 상단 탭 노출 설정과 사용자별 사이트 접근 권한은 서로 독립적입니다. 관리자는 두 항목을 모두 확인해야 하며, 탭을 숨겨도 직접 주소와 통합검색 권한은 유지할 수 있습니다.

일반 화면	휴대폰에서는 검색 폼·카드·사이트 상태가 화면 폭에 맞춰 1~2열 또는 가로 스크롤 형태로 바뀝니다.
뷰어 화면	이전화, 홈, 뷰어 설정, 폭 조절, 목록, 다음화 버튼으로 감상에 집중합니다.
플로팅 메뉴	뷰어에서는 숨기고, 일반 화면에서만 표시해 화면을 덜 가립니다.

3. 사이트별 메뉴와 검색

툰코	웹툰/단행본, 최신/완결, 일반/성인과 장르를 독립적으로 선택합니다.
늑대	웹툰/만화와 원본에서 실제 제공하는 장르를 사용합니다.
11툰	장르 검색을 중심으로 사용하며 원본에 없는 최신·인기 탭을 임의로 만들지 않습니다.
펀비	최신/완결과 일반/성인 목록을 구분합니다.
K만화·판다툰	최신/완결과 일반/성인을 제공합니다. 지원하지 않는 인기 메뉴는 표시하지 않습니다.
블랙툰·바다툰	원본이 제공하는 최신/완결 및 성인 구분을 사용하며 변경된 주소를 자동 검증합니다.
갤러리 사이트	HIYOBI·K-Hentai·E-Hentai·Hitomi는 사이트별 태그·언어·분류 검색을 사용합니다.
MangaDex	기본 언어는 한글이며 목록 상단에서 전체·영어·일어로 바꿀 수 있습니다.

주소 참고: MangaViewer의 최신 메뉴는 내부 주소 /recent를 사용하며, 서버가 현재 툰코 도메인의 /웹툰 목록을 읽어 최근 항목을 필터링합니다. 브라우저가 원본의 ?fil=최신 주소로 직접 이동하는 방식은 아닙니다.

검색 참고: 툰코 장르 버튼은 원본 fil 필터를 사용하고, 일반 제목 검색은 제목이 실제로 일치하는 결과만 연관순으로 표시합니다. 본문에 검색어가 잠깐 포함된 무관한 작품은 제외합니다.

4. 즐겨찾기와 이어보기

작품을 열면 HOME 즐겨찾기에 자동 등록되며 최근 접근 작품 관리 용도로 쓸 수 있습니다.
HOME에서 개별 삭제와 일괄 삭제를 지원합니다.
전체·개별 업데이트 확인은 툰코·늑대·11툰·펀비·K만화·판다툰·블랙툰·바다툰을 지원합니다.
업데이트 확인 전, 업데이트 없음, 새 회차 있음 상태를 구분해 표시합니다.
정기 동기화는 기본 360분(6시간)이며 관리자가 사이트별 대상을 선택합니다.
동기화 대상을 모두 해제하면 주기 값은 보존하면서 자동 실행만 중지됩니다.
예전에 읽은 낮은 회차를 다시 열어도 가장 멀리 읽은 회차가 뒤로 내려가지 않습니다.
다 읽은 회차에서 이어보기를 누르면 다음 회차로, 읽는 중인 회차에서는 저장 위치로 이동합니다.
회차의 ⋮ 메뉴에서 읽음·읽지 않음 처리와 선택 회차까지의 이전 회차 일괄 처리를 할 수 있습니다.

5. 뷰어 조작과 기기 간 동기화

웹툰 모드와 만화책 모드를 작품별로 기억합니다.
이미지 폭 조절로 작은 화면과 큰 화면 모두에 맞춰 읽을 수 있습니다.
이전화/다음화 버튼으로 회차를 이어서 이동합니다.
스크롤 진행률, 페이지 위치, 완독 상태를 서버 DB에 저장합니다.
같은 계정으로 로그인하면 모바일과 데스크톱에서 가장 멀리 읽은 기록을 공유합니다.
현재 위치 주변 이미지를 먼저 표시하고 다음 12장은 낮은 동시성으로 백그라운드 준비합니다.
현재 회차를 설정된 진행률까지 읽으면 다음 회차의 지정 장수만 미리 받아 전환 지연을 줄입니다.
이미지 디스크 캐시는 기본 최대 6GB·14일이며 만료·고아·임시파일을 매시간 자동 정리합니다.

완독 판정 후 마지막 위치를 다시 열어도 현재 회차가 임의로 자동 전환되지는 않습니다. 작품 목록에서 이어보기를 눌렀을 때 다음 회차를 선택합니다.

6. 계정과 권한

신규 가입 계정은 PENDING 승인 대기 상태로 생성됩니다.
성인 메뉴와 성인 사이트 접근은 성인 권한이 있어야 사용할 수 있습니다.
관리자는 사용자별 사이트 접근, ZIP 다운로드, 성인 및 관리자 권한을 따로 지정할 수 있습니다.
로그인 유지를 사용하면 30일 자동 로그인 토큰을 발급하며 로그아웃할 때 폐기합니다.
비밀번호 변경은 좌측 플로팅 메뉴에서 바로 진입합니다.
관리자만 설정 화면과 사용자 관리 기능을 볼 수 있습니다.

7. 관리자 설정과 버전 상태

/settings에서 사이트 URL, 로고, 프록시, FlareSolverr 주소를 조정합니다.
이미지 요청 경로를 warp_first, direct_first, direct_only, warp_only 중에서 선택하며 저장 즉시 적용할 수 있습니다.
FlareSolverr와 Proxy/WARP를 적용할 사이트를 각각 체크해 불필요한 우회 시도를 줄일 수 있습니다.
전체 지원 사이트는 15분마다 현재 주소·최종 리다이렉트 또는 공식 API를 확인합니다.
새 주소는 실제 목록·데이터·API 구조가 검증된 경우에만 저장하며 실패하면 마지막 정상 주소를 유지합니다.
마지막 확인 시각·성공 주소·실패 원인은 사이트 관리에서 확인할 수 있습니다.
WARP 우선·전용 모드는 Proxy 주소가 설정된 경우에만 사용할 수 있으며, 프록시가 없으면 직접 접속으로 동작합니다.
이미지 캐시 사용량·최대 용량·보존일과 백그라운드 저장 작업 수를 연결 설정에서 확인합니다.
DB·이미지 캐시, 중단된 임시파일과 만료 ZIP은 매시간 자동으로 정리됩니다.
현재 회차의 프리로드 시작 진행률(50~95%)과 다음 회차에서 미리 받을 이미지 수(1~12장)를 설정합니다.
로그인 후 어느 화면에서도 같은 왼쪽 플로팅 메뉴를 사용할 수 있습니다.
환경설정은 작은 카드와 상단 바로가기로 나뉘어 필요한 관리 영역으로 바로 이동할 수 있습니다.
사용자 승인, 성인 권한, 관리자 권한을 관리합니다.
정기 동기화를 지원하는 사이트별로 대상을 체크하고 실행 주기를 설정합니다.
DB 자동 백업 주기와 기본 60일 보존 기간, 기간 경과 후 자동 삭제 또는 계속 보관을 설정합니다.
DB 수동 백업·개별 삭제·다운로드·복원을 지원하며 복원 직전 현재 DB를 자동 백업합니다.
백업은 최대 50개를 관리하고 화면에는 약 5개 높이의 내부 스크롤로 표시합니다.
버전 및 배포 상태에서 현재 대시보드 버전·배포 상태·실행 커밋을 확인합니다.
최신 배포 버전과 업데이트 가능 여부, 두 Registry의 버전·커밋 상태를 각각 확인합니다.
사이트 접속 오류가 잦으면 FlareSolverr와 프록시 설정을 먼저 확인합니다.

주 배포처	`ghcr.io/hanmin7117/mangaviewer:latest`
미러·백업	`git.joau.net/phm0702/mangaviewer:latest`

비공개 Registry는 읽기 전용 토큰이 없으면 해당 카드에 인증 필요가 표시됩니다. 토큰은 서버에서만 사용하며 브라우저에는 전달하지 않습니다.

8. Docker 설치와 업데이트

처음 설치할 때는 저장소의 docker-compose.yml과 .env.example을 함께 사용합니다.

git clone https://github.com/hanmin7117/mangaviewer.git
cd mangaviewer
cp .env.example .env
mkdir -p lib log
chmod 600 .env
openssl rand -hex 32

생성된 임의 문자열과 최초 관리자 정보를 .env에 입력하고 실행합니다.

TOON_SECRET_KEY=생성한_긴_임의_문자열
TOON_BOOTSTRAP_ADMIN_ID=admin
TOON_BOOTSTRAP_ADMIN_NAME=관리자
TOON_BOOTSTRAP_ADMIN_PASSWORD=10자_이상의_최초_비밀번호

docker compose config
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 mangaviewer

최초 관리자: 계정 생성 후 .env의 TOON_BOOTSTRAP_ADMIN_PASSWORD를 비우고 MangaViewer만 재생성합니다. 실제 비밀번호와 토큰은 Git에 커밋하지 않습니다.

새 이미지로 업데이트할 때는 DB 백업을 만든 뒤 MangaViewer 컨테이너만 교체합니다.

docker login ghcr.io
docker compose pull mangaviewer
docker compose up -d --no-deps mangaviewer

Compose의 MangaViewer 이미지는 ghcr.io/hanmin7117/mangaviewer:latest가 기본입니다. GHCR 장애 시 같은 커밋의 git.joau.net/phm0702/mangaviewer:<커밋-SHA>로 전환할 수 있습니다. DB와 로그는 호스트 볼륨에 남으므로 컨테이너 재생성으로 삭제되지 않습니다.

9. 데이터 경로와 주요 환경 변수

DB	`lib/webtoon.db`
로그	`log/`
백업·이미지	`lib/backups/`, `lib/image_cache/`, `lib/downloads/`
서버 진입점	`webtoon_server.py`
기본 포트	`9997`
기본 설정	`HOST`, `PORT`, `TOON_DB_FILE_PATH`, `TOON_FLARESOLVERR_URL`, `TOON_SECRET_KEY`
Registry 조회	`TOON_GHCR_USERNAME`, `TOON_GHCR_TOKEN`, `TOON_GITEA_USERNAME`, `TOON_GITEA_TOKEN`
캐시 기본값	`TOON_IMAGE_CACHE_MAX_MB=6144`, `TOON_IMAGE_CACHE_TTL_SECONDS=1209600`

10. 문제 해결 체크리스트

DB 경로가 비어 있거나 잘못되면 새 DB가 생성되어 기존 데이터가 안 보일 수 있습니다.
첫 실행이 안 되면 docker compose config, docker compose ps, docker compose logs --tail=100 순서로 확인합니다.
WARP가 시작되지 않으면 호스트의 /dev/net/tun과 NET_ADMIN 사용 가능 여부를 확인합니다.
Cloudflare 차단이 심한 사이트는 FlareSolverr가 꺼져 있으면 목록/상세 로딩이 불안정할 수 있습니다.
이미지가 느리거나 열리지 않으면 관리자 설정의 WARP 프록시 주소와 컨테이너 상태를 확인합니다.
사이트 주소 확인 실패가 표시되어도 마지막 성공 주소는 유지됩니다. 실패 원인을 보고 Proxy·FlareSolverr 상태를 먼저 확인합니다.
GHCR 상태가 인증 필요면 TOON_GHCR_TOKEN에 read:packages 권한 토큰을 지정합니다.
업데이트 전후 이미지가 같은지 헷갈리면 설정의 현재 실행 커밋과 Registry 커밋을 비교합니다.
배포 환경에서는 TOON_SECRET_KEY를 기본값 대신 별도 값으로 지정하는 편이 안전합니다.
복원 작업 전에는 현재 DB를 한 번 더 백업해 두는 편이 안전합니다.