Skip to content

guide_admin.md

Latest commit

 

History

History
183 lines (131 loc) · 13.3 KB

guide_admin.md

File metadata and controls

183 lines (131 loc) · 13.3 KB
Raw
title 관리자 가이드
project BookOasis
category guide
date 2026-06-22
tags
admin
guide
management

👑 북 오아시스 (BookOasis) 관리자 가이드

이 문서는 북 오아시스 시스템을 관리하고 최적화하기 위한 관리자(Administrator) 전용 매뉴얼입니다.

1. 계정 체계 및 권한 격리

북 오아시스는 다중 사용자 환경을 지원하며 계정 등급에 따라 접근 범위가 격리됩니다.

계정 역할 접근 가능한 영역 설명
Admin (관리자) 전체 시스템 (대시보드, 뷰어, 환경설정, 스캐너 제어, 사용자 관리) 시스템의 물리 리소스 및 모든 세부 설정을 제어할 수 있는 최상위 계정입니다.
User (일반 사용자) 도서 목록 조회 및 미디어 뷰어 읽기 콘텐츠 감상만 가능하며, 환경설정이나 스캐너 제어 등 관리자 메뉴에 진입할 수 없습니다.

Warning

성인용 만화/소설이 수납된 성인 전용 서재(Adult Library)의 경우, 일반 계정 중 '성인 인증(Is Adult)' 플래그가 참(1)으로 부여된 계정만 진입 및 조회가 가능합니다.

2. 사용자 관리 (Users Tab)

관리자는 [설정 아이콘 ⚙️] -> [사용자 관리] 탭을 통해 시스템 접근 권한을 제어할 수 있습니다.

① 사용자 등록

  • 신규 사용자의 Username, Password를 입력하고 권한 등급(Role: Admin/User) 및 성인 여부(Is Adult)를 체크한 뒤 등록합니다.
  • 비밀번호는 데이터베이스 저장 시 안전하게 해싱 처리되어 보관됩니다.

② 사용자 삭제

  • 등록된 사용자 리스트 우측의 '삭제' 버튼을 클릭하여 즉각 권한을 회수할 수 있습니다.
  • 자기 자신(현재 로그인된 관리자 계정)은 실수로 시스템 관리 권한을 잃지 않도록 자가 삭제가 금지되어 있습니다.

③ 카테고리별 권한 제어 (Permissions Tab)

  • 관리자는 [설정 아이콘 ⚙️] -> [권한 관리] 탭에서 특정 사용자가 접근할 수 있는 라이브러리 카테고리를 개별 통제할 수 있습니다.
  • 표 그리드 상에 모든 사용자 목록과 카테고리 목록이 매핑되어 제공되며, 스위치(Toggle)를 켜고 끔에 따라 해당 보관함에 대한 접근 권한을 즉각적으로 부여하거나 차단할 수 있습니다.
  • 일반 사용자(User)는 권한이 허용된(has_access = 1) 보관함의 시리즈와 책만 메인 화면 및 사이드바, OPDS 클라이언트에 노출됩니다.

3. 라이브러리(카테고리) 설정

라이브러리는 물리 디렉터리의 책들을 웹 UI 상의 특정 서재 카테고리로 바인딩해주는 단위입니다.

① 라이브러리 추가 항목

  • 라이브러리 이름: 웹 UI 사이드바에 표시될 이름
  • 대상 물리 경로: 도서 파일들이 수납된 서버상의 절대 경로 (예: D:\Manga 또는 /home/user/books)
  • 원격 드라이브 여부 (Is Remote): Rclone VFS 등으로 마운트된 구글 드라이브나 원격 스토리지인 경우 체크합니다.
    • 체크 시: 네트워크 병목을 방지하기 위해 압축 파일 내부 상세 오프셋 분석 및 임시 표지 자동 추출 처리를 스킵합니다.
    • 체크를 해제하면: 스캔 중 원격 VFS 갱신(RC / vfs/refresh)을 시도하지 않습니다.
  • 성인 라이브러리 여부 (Is Adult): 체크 시 성인 인증 플래그가 지정된 계정에게만 서재가 공개됩니다.
  • 스캔 시 VFS 캐시 갱신 (VFS Refresh before scan): 원격 드라이브의 최신 동기화를 위해 스캔 직전 Rclone API를 호출해 캐시를 리프레시할지 지정합니다.

4. 라이브러리 스캐너 제어 (Scanner Management)

스캐너는 큐 기반 백그라운드 워커 프로세스에서 파일 시스템과 데이터베이스를 동기화하는 핵심 엔진입니다.

  • 전체 스캔 (Scan All): 지정한 라이브러리의 신규 도서 추가, 경로 이동, 삭제된 도서 제거를 통합 실행합니다.
  • 표지 전용 스캔 (Covers Only): 메타데이터 파싱이나 오프셋 추출을 제외하고, 누락되거나 깨진 표지 이미지(Cover)만 타겟팅하여 빠르게 추출/생성합니다.
  • 스캔 중단 (Cancel): 스캔 작업 실행 중 '중단' 버튼을 누르면 스캐너가 현재 진행 중인 폴더 단위까지만 안전하게 마친 후 작업을 자진 종료합니다.
  • 체크포인트 메커니즘: 스캔 중 오류나 강제 종료가 발생해도, 이미 완료된 폴더 기록은 scanner_progress에 온전히 남아있어 다음 스캔 시 남은 부분부터 자동으로 이어받아 진행합니다.

⑤ 스캔 제외 패턴 및 .bookoasisignore 설정

시놀로지 NAS 썸네일 폴더(@eaDir/), 휴지통(#recycle/), 임시 파일(*.tmp, *.sample.cbz) 등 특정 파일이나 디렉토리를 스캔 대상에서 예외 처리할 수 있습니다.

  • 전역 제외 패턴 (관리자 설정):
    • [설정 아이콘 ⚙️] -> [일반 설정] 탭의 "도서 스캔 제외 패턴" 영역에서 한 줄에 하나씩 설정합니다.
    • 디렉토리 명시: 끝에 /를 붙여 명시합니다. (예: @eaDir/, #recycle/, .git/, .svn/)
    • 파일 패턴: 와일드카드를 포함한 파일명을 입력합니다. (예: *.tmp, *.sample.cbz, Thumbs.db, .DS_Store, desktop.ini)
  • 폴더별 개별 설정 (.bookoasisignore):
    • 특정 디렉토리 내에 .bookoasisignore 파일을 배치하면 해당 폴더 이하 하위 스캔에만 적용되는 개별 예외 패턴을 등록할 수 있습니다.
  • 스캔 로그 및 휴지통 연동:
    • 제외 처리된 디렉토리는 하위 물리 탐색이 즉각 차단되며 스캔 로그(media_server.log)에 [Scanner-Ignore]로 명시됩니다.
    • 기존에 등록되었던 항목이 예외 처리되면 휴지통(소프트 딜리트)으로 안전 이동됩니다.

5. 시스템 및 플러그인 설정

① 메타데이터 플러그인 (알라딘 등)

  • API Key 동적 등록: 최신 플러그인 아키텍처를 통해 이제 알라딘(TTBKey), 구글 북스, 아마존 등 다양한 외부 도서 정보 연동 플러그인을 환경설정 탭에서 손쉽게 켜고 끄며(ON/OFF) API 키를 관리할 수 있습니다.
  • 활성화된 플러그인은 개별 도서 상세 모달에서 수동 메타데이터 검색 시 선택 옵션으로 등장하며, 검색된 정확한 메타데이터(작가, 출판사, 설명, 고화질 표지 등)를 원클릭으로 병합할 수 있습니다.

② 시스템 스크롤 및 썸네일 규격 설정

  • 썸네일 너비 및 스크롤 캐싱: 성능 최적화를 위한 썸네일 해상도 규격을 설정 탭에서 동적으로 조율할 수 있습니다.

6. 스캔 에러 리포트 (Scan Reports)

스캔 도중 손상된 압축 파일(Bad Zip File), 손상된 이미지, 또는 권한 문제로 읽지 못한 파일 정보는 삭제되거나 누락되는 대신 **[스캔 에러 리포트]**에 아카이빙됩니다.

  • 관리자는 에러 리포트를 조회하여 물리 드라이브에서 어떤 파일이 깨졌는지 핀포인트로 파악할 수 있으며, 조치 완료 후 리포트 목록을 '전체 삭제'하여 초기화할 수 있습니다.

7. 커스텀 폰트(사용자 폰트) 추가

웹 뷰어(TXT/EPUB)에서 사용자가 원하는 글꼴을 사용하도록 추가할 수 있습니다.

  • 지원 포맷: .ttf, .otf, .woff, .woff2
  • 추가 방법:
    1. 서버의 설치 경로 내 static/fonts/custom/ 폴더로 이동합니다. (해당 폴더가 없다면 새로 생성하세요.)
    2. 준비한 폰트 파일을 위 경로에 업로드(복사)합니다.
    3. 브라우저에서 북 오아시스에 접속한 뒤 뷰어를 열고, 폰트 설정(A)을 눌러 폰트 선택 드롭다운 메뉴를 확인하면 추가한 폰트가 자동으로 목록에 표시됩니다.

8. 데이터베이스 엔진 관리 및 MariaDB 마이그레이션

북 오아시스는 기본 내장형 SQLite 외에도 엔터프라이즈 모드인 MariaDB / MySQL을 공식 지원합니다.

① SQLite vs MariaDB 선택 가이드

  • SQLite (기본값): 별도 설치 없이 단일 파일로 손쉽게 구동. 소규모 및 1인 사용자 환경에 적합.
  • MariaDB / MySQL (권장): 대용량(수만~수십만 권 도서) 및 다중 스캐너/웹 동시 접속 환경에서 파일 락 병목 및 DB 손상 위험을 100% 소거하고 초고속 응답 보장.

② MariaDB 설정 (.env)

DB_ENGINE=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASSWORD=your_mariadb_password

③ SQLite -> MariaDB 원클릭 자동 마이그레이션

기존 SQLite 데이터(도서 메타데이터, 독서 히스토리, 계정 권한 등)를 MariaDB로 손실 없이 100% 이전할 수 있는 마이그레이션 도구를 제공합니다:

python tools/migrator_sqlite_to_mariadb.py
  • 마이그레이션 특징:
    • media_general, media_adult, media_audiobook 3개 독립 데이터베이스를 자동 생성 및 마이그레이션.
    • 마이그레이션 후 스키마 검증 및 데이터 건수 자동 검증 수행.

④ MariaDB 성능 튜닝: innodb_buffer_pool_size

MariaDB 공식 이미지의 innodb_buffer_pool_size 기본값은 128MB에 불과합니다. 도서 수가 많아질수록(특히 수만 권 이상) 이 값이 실제 데이터 용량보다 작으면 조회 때마다 캐시가 밀려나 디스크 I/O가 반복되면서 통계·진단성 조회가 비정상적으로 느려질 수 있습니다.

  • 권장값: 보유 RAM 여유분 내에서, media_general + media_adult + media_audiobook 전체 DB 용량 이상으로 설정 (docker-compose.mariadb.yml은 기본 2G로 설정되어 있습니다).
  • Docker Compose 배포 시: 기본값(2G)을 넘겨야 하는 대용량 라이브러리는 docker-compose.mariadb.yml을 직접 고치는 대신 docker-compose.override.mariadb.example.yml을 복사해 오버라이드하세요. (자세한 절차는 설치 가이드의 "MariaDB + Redis 콤보 모드" 항목 참고)
  • 네이티브(비-Docker) MariaDB 운영 시: /etc/mysql/mariadb.conf.d/50-server.cnf(배포판에 따라 경로가 다를 수 있음)의 [mysqld] 섹션에 아래를 추가하고 systemctl restart mariadb로 재시작합니다. 
    innodb_buffer_pool_size = 2G
  • 적용 확인: 
    SHOW VARIABLES LIKE 'innodb_buffer_pool_size';

9. rclone VFS 마운트 튜닝 (Google Drive 등 원격 보관함)

Rclone VFS로 마운트된 원격 드라이브(Google Drive 등)를 라이브러리 물리 경로로 쓰는 경우, 북 오아시스 자체의 오프셋 기반 페이지 스트리밍과는 별개로 rclone 마운트 옵션이 체감 로딩 속도를 좌우합니다. --vfs-cache-mode full로 마운트하면 rclone이 파일을 sparse 파일로 로컬 캐싱하며 접근한 부분만 원격에서 청크(chunk) 단위로 받아오는데, 이 청크 크기 설정이 도서 파일 크기보다 작으면 책 한 권을 읽는 도중에도 청크 경계를 넘을 때마다 로딩이 반복됩니다.

① 청크 배증(doubling) 방식과 체감 로딩의 관계

rclone은 --vfs-read-chunk-size(기본 128M, 흔히 쓰이는 커스텀값은 32M)로 시작해 계속 읽히면 매번 청크 크기를 2배씩 늘려가며(--vfs-read-chunk-size-limit까지) 원격에 새로 Range 요청을 보냅니다. 예를 들어 시작 청크가 32M인 상태로 150~200MB 만화 파일을 처음부터 끝까지 읽으면:

32M → +64M(누적 96M) → +128M(누적 224M, 파일 끝까지 커버)

총 3번의 별도 원격 요청이 걸리고, 그때마다 사용자 입장에선 "다 읽고 있었는데 또 로딩"으로 체감됩니다.

② 권장 설정

  • 서재의 도서 파일 크기 분포를 먼저 파악하세요(예: 만화/웹툰 zip 대부분이 100~200MB대라면).
  • --vfs-read-chunk-size를 그 크기보다 넉넉히 큰 값(예: 256M)으로 올리면, 대부분의 책이 첫 요청 1번으로 끝까지 캐싱되어 중간 로딩이 사실상 사라집니다.
  • 더 작은 파일은 실제 파일 크기만큼만 받아오므로(청크 크기는 상한일 뿐) 대역폭 낭비는 없습니다.
  • --vfs-read-chunk-size-limit, --vfs-cache-max-size는 별개 설정이라 그대로 둬도 무방합니다 — 이번 문제는 시작 청크 크기가 작아서 생기는 것이지 상한선이나 캐시 총량 문제가 아닙니다.

③ 적용 방법

mount 옵션 변경은 rclone 마운트 프로세스를 재시작해야 반영됩니다(북 오아시스 자체 설정이 아니라 rclone 마운트를 실행하는 시스템 서비스/스크립트 쪽 옵션). 마운트를 직접 운영 중이라면 해당 실행 커맨드나 systemd 유닛의 --vfs-read-chunk-size 값을 조정한 뒤 마운트를 재시작하세요. 재시작 시점에 열려있던 파일 핸들에는 영향이 있을 수 있으니, 이용자가 적은 시간대에 적용하는 것을 권장합니다.

Note

Google Drive API는 한 요청에 여러 byte range를 묶어 보내는 멀티 range(Range: bytes=A-B,C-D)를 지원하지 않습니다(501 Not Implemented로 명시 거부, 실측 확인됨). 따라서 청크 요청 횟수 자체를 줄이는 유일한 방법은 청크 크기를 키우는 것입니다.