프로젝트 소개

## 프로젝트 개요 cups-web-print는 Python Flask와 CUPS를 기반으로 한 웹 인쇄 서비스로, CUPS 인쇄 서버에 HTTP 그래픽 인터페이스를 제공합니다. 서버에 연결된 USB 프린터를 네트워크 프린터로 전환하여, 로컬 네트워크의 장치가 브라우저를 통해 인쇄를 완료할 수 있게 하며, 각 장치에 드라이버를 설치하거나 인쇄 큐를 구성할 필요가 없습니다. ## 주요 기능 ### 파일 관리 - PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, TXT, RTF 및 JPG, JPEG, PNG, GIF, BMP, SVG 등 이미지 형식 지원 - 드래그 앤 드롭 업로드 지원 - 온라인 미리보기: PC에서 PDF 미리보기, 모바일에서 이미지 미리보기 - 파일 목록 확인 및 삭제 ### 인쇄 설정 - 용지 크기: 사무용 A1-A4, 사진 5-10인치 등 - 용지 재질: 일반 용지, 광택 사진 용지 등 - 색상 모드: 컬러 / 흑백 - 양면 인쇄: 단면, 양면 긴 쪽 제본, 양면 짧은 쪽 제본 - 인쇄 방향: 세로 / 가로 - 인쇄 부수: 1-99부 - 페이지 범위: 예: 1-5 8 10-12 - 인쇄 배율: 자동 / 맞춤 / 채우기 / 배율 없음 - 페이지 미러: 수평 뒤집기 지원 ### 작업 관리 - 프린터 온라인 상태 감지 (IPP 프린터 전용) - 실시간 작업 상태 모니터링: 제출됨 / 처리 중 / 완료 / 실패 / 취소됨 - 작업 진행률 표시 (시간 및 CUPS 큐 기반 추정) - 작업 취소 - 인쇄 큐 실시간 확인 - 용지함 정보, 잉크 카트리지 정보, 프린터 정보 (가동 시간, 펌웨어 버전, 경고 등) 모두 IPP 프로토콜로 획득 ### 보안 - 경로 탐색 공격 방지 - 파일 형식 화이트리스트 검증 - 파일 크기 제한 100MB - 로그 자동 순환 - 파일 삭제 시 미리보기 캐시 자동 정리 ### 이중 언어 인터페이스 - 중국어 인터페이스: http://localhost:5000/zh - 영어 인터페이스: http://localhost:5000/en ## 기술 스택 - 백엔드: Python 3.9+ 및 Flask 3.0+ - 프론트엔드: HTML5 및 Tailwind CSS (CDN) - 인쇄 서비스: CUPS 2.0+ - 문서 변환: LibreOffice 6.0+ - PDF 처리: poppler-utils (pdftoppm), pdftk - IPP 프로토콜: ipptool (cups-client) ## 호환성 설명 프로젝트는 IPP 표준 프로토콜과 CUPS 표준 명령을 사용하므로, 이론적으로 IPP 프로토콜을 지원하는 대부분의 프린터와 호환됩니다. README에는 Canon G3881에서 테스트 완료되었다고 명시되어 있으며, 다른 프린터는 직접 검증이 필요합니다. ## 배포 방법 ### 컨테이너 설치 (권장) Docker로 실행하며, 5000 (웹 인터페이스) 및 631 (CUPS) 포트를 매핑하고 CUPS 구성, 큐, 로그 및 업로드/미리보기 디렉터리를 마운트합니다. USB 프린터는 권한 모드와 USB 장치 마운트가 필요하며, 네트워크 프린터만 사용하는 경우 이 두 항목을 제거할 수 있습니다. 프린터 추가 예시 (네트워크 프린터 기준): ``` docker exec cups-web-print lpadmin -p Canon_G3881 -v ipp://192.168.1.16:631/ipp/print -m everywhere -E ``` ### 로컬 설치 cups, cups-client, LibreOffice 구성 요소, poppler-utils, pdftk 및 Python 종속성을 설치하고, CUPS 서비스를 시작한 후 lpadmin으로 프린터를 추가하고 app.py를 실행해야 합니다. README에는 crontab을 통한 부팅 시 자동 시작의 선택적 방법도 제시되어 있습니다. ## 디렉터리 구조 - app.py: Flask 애플리케이션 메인 파일 - ipp_client.py: IPP를 통해 용지함, 잉크 카트리지 등 상태 정보 획득 - printer_checker.py: IPP, BJNP 등 프로토콜을 통해 프린터 온라인 상태 확인 - templates/: index.html (중국어 메인 페이지) 및 index_en.html (영어 메인 페이지) - uploads/, previews/: 업로드 파일 및 미리보기 파일 디렉터리 ## 문제 해결 README는 비교적 완전한 문제 해결 체크리스트를 제공하며, 다음을 포함합니다: lpadmin 프린터 추가 실패 (각 브랜드 IPP 주소 차이, 드라이버리스 모드, cupsenable/cupsaccept 포함), 5000 포트 무응답 (프로세스, 포트 리스닝, 방화벽, Flask 바인딩 주소), 페이지에 사용 가능한 프린터 없음, 문서 변환 실패, PDF 미리보기 생성 실패, 페이지 범위 추출 실패, 잉크 카트리지/용지함 정보 획득 불가, 및 "성공 알림이지만 출력 없음" 상황 (-m everywhere 매개변수, CUPS 드라이버 및 PPD 파일, 프린터 유휴 상태 및 CUPS 로그 확인 필요). ## 라이선스 GPLv3. README는 소프트웨어가 "있는 그대로" 제공되며, 작성자는 사용 결과에 대한 책임을 지지 않는다고 명시합니다.