• 주요 기능
• 설치
• 사용 방법
• 단축키
• 설정
• API 엔드포인트
• 프로젝트 구조
• 문제 해결
• 라이선스

• 드래그 앤 드롭 업로드/다운로드
• 대용량 파일 자동 청크 업로드(최대 10GB)
• 폴더 생성/이름 변경/삭제, ZIP 다운로드
• 인덱스 + 파일시스템 fallback 기반 실시간 파일명 검색
• 다중 선택 일괄 작업

• 역할 기반 접근 제어(Admin/Guest)
• PBKDF2-SHA256 비밀번호 해시
• 상태 변경 요청에 대한 전역 CSRF 검증
• 로그인 실패 누적 시 IP 차단
• AES-GCM(v2) 파일 암호화 + 구버전 CBC 복호화 호환
• Markdown/파일 정보 미리보기 XSS 방어

• 비밀번호/만료시간/다운로드 제한을 가진 공유 링크
• 공유 링크 JSON 영속화(.webshare_share_links.json)
• 모바일 접속용 QR 코드 생성

• 휴지통/복원/자동 정리
• 파일 버전 관리 및 백업 스냅샷
• 태그/메모, 즐겨찾기
• 세션 단위 최근 파일 기록
• SHA256 기반 중복 파일 스캔
• 폴더별 읽기/쓰기/삭제 권한 + allow_guest_upload 기반 게스트 변경 제어
• 감사 로그 저장
• 드래그 앤 드롭 이동
• PDF/Markdown 미리보기
• 멀티 탭 탐색
• Google Drive 수동 업로드/다운로드 동기화
• 재시작 후 복원되는 클라우드/중복 작업 ledger
• 검색 인덱스 스냅샷 + watchdog 기반 변경 감지(fallback 지원)
• 수동형 UPnP 포트 매핑

• 실시간 트랜스코딩 + HLS 스트리밍
• PWA 지원(manifest.json, 설치형 셸)
• 네트워크 유틸리티(UPnP, WebDAV)
• Docker 지원(Dockerfile, docker-compose.yml)
• 보안 강화(XSS/PKCS7/경로 보호)

참고: 현재 로그인 모델은 admin_pw / guest_pw의 password-only 방식입니다. /api/users는 상태 조회만 제공하고 사용자 CRUD는 비활성화됩니다.

• Python 3.8+
• pip

git clone https://github.com/your-repo/webshare.git
cd webshare

# 기본 권장
pip install -r requirements.txt

# 최소 필수
pip install flask werkzeug pillow cryptography watchdog

# GUI (권장)
pip install pyqt6

# 선택
pip install qrcode
pip install python-docx
pip install openpyxl
pip install python-pptx
pip install miniupnpc
pip install wsgidav cheroot
pip install flask-compress cachetools
pip install orjson

# FFmpeg는 시스템에 별도 설치 후 PATH 등록 필요

python main.py

pyinstaller webshare.spec
# 결과: dist/WebSharePro_v<APP_VERSION>.exe

docker compose up -d

• 기본 포트: 5000
• 볼륨: ./shared_files -> /data
• 엔트리포인트: docker_entrypoint.py

1. python main.py 실행
2. GUI에서 공유 폴더/포트/비밀번호 설정
3. 서버 시작
4. 브라우저에서 http://localhost:5000 또는 표시된 LAN IP 접속

{
  "folder": "C:\\Users\\User\\shared_files",
  "port": 5000,
  "admin_pw": "1234",
  "guest_pw": "0000",
  "allow_guest_upload": false,
  "display_host": "0.0.0.0",
  "session_timeout": 60,
  "enable_versioning": true,
  "language": "ko",
  "ip_whitelist": [],
  "daily_download_limit": 0,
  "daily_bandwidth_limit_mb": 0,
  "disk_warning_threshold": 90,
  "trusted_proxies": [],
  "trusted_hops": 1,
  "webdav_allow_insecure": false
}

• 로그인된 상태 변경 요청(POST/PUT/PATCH/DELETE)은 CSRF 검증이 필요합니다.
• .webshare* 등 숨김/시스템 경로는 다운로드/스트리밍/미리보기/WebDAV에서 차단됩니다.
• 비TLS WebDAV 쓰기 메서드는 기본적으로 차단됩니다.
• /api/active_sessions는 관리자 전용입니다.
• 공유 링크의 hours, max_downloads는 범위 검증됩니다.
• 감사 로그/공유 링크는 JSON 파일로 주기 저장됩니다.
• 로그인된 브라우저 다운로드 quota는 session_id 기준으로 집계되고, 공유 링크/비로그인 요청은 IP 기준을 유지합니다.
• /stream/*와 HLS 재생은 daily_download_limit의 횟수 quota를 소모하지 않고, daily_bandwidth_limit_mb만 반영합니다.
• Markdown 미리보기는 sanitize 후 렌더링되므로 raw HTML 일부가 그대로 표시되지 않을 수 있습니다.

(repo root)/
|-- main.py
|-- config.py
|-- i18n.py
|-- server.py
|-- utils/
|-- security/
|-- features/
|   |-- audit_log.py
|   |-- share_links_store.py
|   |-- network.py
|   |-- webdav_server.py
|   `-- transcoder.py
|-- routes/
|   |-- main_routes.py
|   |-- file_routes.py
|   |-- cloud_routes.py
|   |-- network_routes.py
|   `-- pwa_routes.py
|-- templates/
|   |-- index.html
|   |-- share_password.html
|   `-- share_expired.html
|-- static/
|   `-- js/
|       |-- app-core.js
|       |-- app-modals.js
|       `-- app-upload.js
|-- gui/
|-- legacy/
|   `-- 웹서버 프로그램v4.py
|-- scripts/
|   |-- generate_dataset.py
|   `-- perf_bench.py
|-- tests/
|-- webshare.spec
|-- WebSharePro.spec
|-- pyrightconfig.json
|-- typings/
|   `-- cachetools/
|       `-- __init__.pyi
|-- Dockerfile
|-- docker-compose.yml
`-- docker_entrypoint.py

Error: Address already in use

해결: 설정에서 포트를 변경하세요.

ModuleNotFoundError: No module named 'PyQt6'

해결: pip install pyqt6

• 100MB 이상 파일은 자동 청크 업로드를 사용합니다.
• 네트워크 불안정 시 재시도를 지원합니다.
• 최대 10GB를 지원합니다.

1. 방화벽에서 포트를 개방합니다.
2. 공유기 포트포워딩을 설정합니다.
3. display_host를 0.0.0.0으로 설정합니다.

MIT License

Copyright (c) 2026 WebShare Pro

• 보안/정합성 실행 계획 반영 완료:
  • 경로 검증(validate_path) 심볼릭 링크 우회 차단
  • 청크 업로드 소유권 검증 + 총량/동시성 제한
  • 공유 링크 max_downloads 원자적 reserve/rollback
  • 일반 실행/Docker 모두 동일 WebDAV WSGI 마운트 경로 사용
  • 시작 시 임시 업로드 폴더(.webshare_uploads, .upload_temp) 정리 복구
• Cloud Sync는 현재 Google Drive만 실제 구현되어 있습니다.
  • 업로드/다운로드는 수동 one-way 작업이며 충돌 정책은 skip입니다.
  • 작업 상태는 .webshare_jobs.json에 저장되어 재시작 후에도 /api/cloud/jobs/<job_id>로 복원됩니다.
  • Dropbox는 백엔드 placeholder(501)만 유지하고 UI에서는 숨겨집니다.
• 빌드 스펙 정합성:
  • webshare.spec, WebSharePro.spec 모두 config.py의 APP_VERSION을 기준으로 산출물명을 WebSharePro_v{APP_VERSION}로 맞췄습니다.
  • watchdog/job ledger 모듈을 동결 빌드 hiddenimports에 반영했습니다.

• JSON error responses are standardized to: { "success": false, "error": "...", "code": "ERROR_CODE", "message": "...", "request_id": "..." }
• Backward compatibility is kept by preserving the error field while adding code, message, and request_id.
• Metadata list APIs now return only readable paths for the current requester:
  • GET /api/tags (all tags mode)
  • GET /api/favorites
  • GET /bookmarks
• Text editor APIs enforce a 10MB limit and return 413 when exceeded:
  • GET /get_content/<path>
  • POST /save_content/<path>
• Chunk upload hardening:
  • Actual chunk bytes must be <= chunk_size
  • Cumulative uploaded bytes must be <= total_size
  • Violations immediately clean up the upload session
• Batch ZIP download now performs a pre-check of download limits before ZIP creation, then re-checks after ZIP creation for race safety.
• PyInstaller 스펙에 utils.api_errors를 hiddenimports로 추가해, 동결 빌드에서도 표준 에러 유틸이 누락되지 않도록 맞췄습니다.
• .gitignore에 WebShare 런타임 임시 산출물(.webshare_*.tmp, .webshare_*.json)과 업로드/트랜스코드 임시 디렉터리 제외 규칙을 보강했습니다.

• pyrightconfig.json을 추가해 실사용 코드와 테스트를 정적분석 범위로 고정하고, 보관용 legacy/는 제외했습니다.
• config.py의 ConfigManager.get()에 타입 오버로드를 추가해 Pylance/Pyright가 주요 설정 키를 구체 타입으로 추론하도록 정리했습니다.
• typings/cachetools/__init__.pyi 로컬 스텁과 pyrightconfig.json의 외부 source-warning 정리를 함께 적용해 cachetools 관련 Pylance 경고를 제거했습니다.
• features.network, features.webdav_server가 importlib 기반 선택 의존성 로딩으로 바뀌었기 때문에, webshare.spec와 WebSharePro.spec 모두 miniupnpc, wsgidav.* hidden import를 명시적으로 포함하도록 동기화했습니다.
• 개발 검증 기준선:
  • pyright -> 0 errors, 0 warnings
  • pytest -q -> 44 passed, 1 skipped

• 프런트 보안 정합성:
  • Markdown 편집기 미리보기와 별도 Markdown 프리뷰가 sanitize 경로를 거치도록 통일했습니다.
  • 파일 정보 모달의 파일명/경로/MIME/MD5는 escape 후 렌더링하도록 맞췄습니다.
• 다운로드/스트리밍 정책 정합성:
  • 일반 다운로드/ZIP/배치/공유 단일 파일만 논리적 다운로드 count를 증가시킵니다.
  • Range 스트리밍과 HLS playlist/segment는 count를 증가시키지 않고 bytes만 누적합니다.
  • 최근 파일은 세션 단위로 분리되며, 다운로드/텍스트 읽기/스트림 시작/HLS playlist 시작에서만 채워집니다.
• 백엔드 안정성 정합성:
  • 비Windows에서 main.py import 시 DPI 초기화가 실행되지 않도록 분리했습니다.
  • 비Windows HLS 트랜스코더는 독립 세션으로 실행되고, 종료도 해당 세션만 정리하도록 맞췄습니다.
  • ZIP 압축 해제는 기존 폴더와 merge하지 않고 name_1, name_2 식의 새 디렉터리에 풉니다.
  • 버전 백업 파일명은 encoded relative path를 포함하는 새 포맷으로 저장하며, legacy 백업 조회/복원 호환은 유지합니다.
  • config/metadata/permissions/share-links/cloud/audit 저장은 os.replace() 기반 원자적 쓰기로 통일했습니다.
  • 설정 로드는 ConfigManager.set() 검증 경로를 통과하며 잘못된 값은 warning 후 기본값을 유지합니다.
• 2026-03-25 정합성 반영:
  • 게스트 변경 작업은 allow_guest_upload=true일 때만 폴더 권한에 따라 허용됩니다.
  • /search는 인덱싱 중 fallback 검색을 사용하고 indexing, search_mode를 반환합니다.
  • GUI/Tk 서버 시작 상태는 실제 bind/readiness 이후에만 성공으로 표시됩니다.
  • Google Drive OAuth + 작업 상태 조회 + 수동 UPnP API를 추가했습니다.
• 최신 검증 기준선:
  • pytest -q --basetemp .pytest_tmp -> 64 passed, 1 skipped