PeerClip · 장치 간 클립보드 동기화

한 번 배포하면 여러 장치에서 사용할 수 있습니다. PC, Mac, iPhone, Android, 태블릿을 동일한 "방"으로 가져와 원하는 대로 텍스트, 사진, 파일을 붙여넣을 수 있습니다.

프로젝트 소개

PeerClip은 다중 장치 시나리오를 위한 임시 파일 및 클립보드 전송 도구입니다.

기본 클라이언트를 설치할 필요가 없습니다. PC, Mac, iPhone, Android, 태블릿 및 기타 장치를 같은 방에 추가하려면 브라우저를 열면 되며, 장치 간에 텍스트, 사진, 파일을 빠르게 동기화할 수 있습니다.

이 프로젝트는 “방 + 장비 승인” 메커니즘을 사용하여 접근 권한을 관리하고 QR 코드를 사용하여 모바일 단말기에서 방에 참여하는 운영 비용을 줄입니다. 문자 메시지는 Redis를 통해 유지되고 이미지와 파일은 Cloudflare R2를 사용하여 저장되며 미리 서명된 URL을 통해 브라우저에서 직접 전달됩니다.

PeerClip 소스코드 보기

✨ 핵심 기능

🔗 룸 메커니즘

PeerClip을 처음 열면 고유한 방 ID가 자동으로 생성되며, 현재 방은 URL에 ?room=xxx로 식별됩니다.

룸 링크를 공유하거나 다른 장치가 페이지의 QR 코드를 스캔하도록 하여 동일한 공간에 빠르게 참여하세요.

📱 QR코드로 빠르게 참여 가능

객실 QR 코드가 페이지에 내장되어 있습니다.

휴대폰이나 태블릿에서 객실 번호를 수동으로 입력할 필요가 없으며 코드를 직접 스캔하여 현재 방에 들어갈 수 있으므로 컴퓨터와 휴대폰 간의 임시 콘텐츠 전송에 매우 적합합니다.

🔐 장비 승인

실수로 룸 링크를 공유한 후 낯선 장치가 룸 링크에 참여하는 것을 방지하기 위해 PeerClip은 장치 승인 메커니즘을 도입했습니다.

방에 가장 먼저 입장하는 기기가 자동으로 관리자가 됩니다.
후속 장치는 기본적으로 ‘보류 중’ 상태입니다.
관리자는 ‘승인’ 또는 ‘거부’를 선택할 수 있습니다.
승인된 장치에서만 회의실 콘텐츠를 보고 보낼 수 있습니다.

사용이 간편하면서도 기본 액세스 제어 계층도 추가됩니다.

📝 즉각적인 텍스트 동기화

모든 장치에서 텍스트를 입력하거나 붙여넣고 다른 승인된 장치로 메시지를 보냅니다.

동시에 콘텐츠를 현재 장치의 시스템 클립보드에 직접 복사할 수 있는 원클릭 복사 버튼이 제공됩니다.

임시 이전의 경우:

코드 조각, 명령, 링크 및 구성을 모두 방에 직접 넣을 수 있습니다.

🖼️여러 장의 사진 전송

한 번에 여러 이미지를 선택하고 카드 캐러셀에 표시하는 기능을 지원합니다.

모바일 단말기에는 이미지 미리보기를 위한 터치 조작도 추가되었습니다.

확대/복원하려면 더블클릭하세요.
한 손가락으로 사진을 드래그하세요.
두 손가락으로 핀치하여 확대/축소
전체 화면으로 보기

컴퓨터에서 스크린샷을 찍어 휴대폰으로 전송하는 등의 시나리오에 특히 편리합니다.

📎 범용 파일 업로드

이미지 외에도 다음과 같은 다른 유형의 파일도 지원됩니다.

압축된 패키지
PDF/문서
비디오
코드 파일
기타 공용 파일

파일은 카드로 표시되어 파일 유형, 크기 및 다운로드 작업을 제공합니다.

☁️ Cloudflare R2 사전 서명된 직접 전송

이미지와 파일은 먼저 Next.js Serverless Function을 거치지 않고 대신 다음을 수행합니다.

浏览器
  ↓
请求上传地址
  ↓
Next.js / Vercel 生成 Presigned URL
  ↓
浏览器直接 PUT
  ↓
Cloudflare R2

이 방법을 사용하면 파일 업로드가 서버를 통해 전송되는 것을 방지할 수 있으며 동시에 R2의 액세스 키가 프런트 엔드에 노출되지 않습니다.

현재 프로젝트에는 이미지 및 파일 크기에 대한 제한이 있습니다.

이미지: 10MB 이하
파일: 50MB 이하

⚡ 낙관적 업데이트 + 여론 조사

복잡한 WebSocket 아키텍처를 사용하는 대신 PeerClip은 폴링을 사용하여 최신 뉴스를 얻습니다.

메시지를 보낸 후 표시되지 않도록 하려면:

보내기 → 사라지기 → 다시 나타나기

시각적 비트인 프런트 엔드는 낙관적 업데이트 + ID별 폴링 결과 병합 방법을 사용합니다.

사용자가 메시지를 보낸 후 즉시 인터페이스에 표시되고 병합 전에 서버 데이터가 백그라운드에서 폴링됩니다.

동시에 폴링 중에 메시지 ID 목록과 길이가 비교됩니다. 데이터가 변경되지 않은 경우 ‘setState’를 건너뛰어 불필요한 렌더링을 줄입니다.

🤖 온라인 기기 관리

장치는 주기적으로 하트비트를 보냅니다.

특정 기간 동안 장치에 하트비트가 없으면 시스템은 오프라인 장치가 장치 목록에 오랫동안 남아 있는 것을 방지하기 위해 자동으로 이를 지웁니다.

💾 Redis 지속성

회의실, 장치 및 메시지 데이터는 Redis에 저장됩니다.

따라서 Vercel Serverless 환경에 배포하더라도 기능 콜드 스타트나 인스턴스 변경으로 인해 데이터가 완전히 손실되지는 않습니다.

🛠 기술 스택

계층 구조	기술	사용법
프레임워크	Next.js 16	앱 라우터, 페이지 및 API
UI	리액트 19	프런트 엔드 상호 작용 및 구성 요소
스타일링	순풍 CSS 4	원자 CSS
언어	타입스크립트 5	유형 안전
아이콘	루시드반응	SVG 아이콘
QR코드	qrcode.반응	객실 QR 코드
데이터베이스	레디스/ioredis	방, 장비, 메시지 지속성
파일 저장	클라우드플레어 R2	이미지 및 파일 저장
업로드	미리 지정된 URL	브라우저 직접 전송 R2
배포	베르셀	서버리스 배포

프로젝트는 실제로 Next.js + React + Tailwind CSS + TypeScript를 사용하여 구축되었습니다. Redis는 세션 및 메시지 데이터 저장에 사용되고 Cloudflare R2는 이미지 및 파일 저장에 사용됩니다. 전체 프로젝트는 Vercel Serverless 환경에 맞게 조정되었습니다.

🚀 사용 방법

1. 방 만들기

PeerClip을 열면 시스템이 자동으로 방을 생성합니다.

방에 처음 입장하는 장치가 자동으로 관리자가 됩니다.

2. 다른 장치 추가

현재 방 URL을 직접 복사하거나 페이지의 QR 코드를 사용할 수 있습니다.

휴대폰의 코드를 스캔하시면 빠르게 객실에 입장하실 수 있습니다.

3. 장비 승인

새 장치는 진입 후 기본적으로 보류 상태입니다.

관리자가 기기 목록에서 승인을 클릭하면 해당 기기가 공식적으로 방에 입장할 수 있습니다.

4. 전송 시작

그러면 직접 다음을 수행할 수 있습니다.

텍스트 붙여넣기
스크린샷 붙여넣기
사진 선택
파일 업로드
한 번의 클릭으로 텍스트 복사
다른 기기에서 보낸 파일 다운로드

전체 프로세스에는 추가 클라이언트를 설치할 필요가 없습니다.

🏗️ 프로젝트 구조

peerclip/
├─ app/
│  ├─ page.tsx
│  ├─ layout.tsx
│  ├─ globals.css
│  └─ api/
│     ├─ clipboard/
│     │  └─ route.ts
│     └─ upload/
│        └─ route.ts
├─ public/
│  └─ logo.jpg
├─ .env.example
├─ next.config.ts
├─ postcss.config.mjs
├─ eslint.config.mjs
├─ tsconfig.json
├─ package.json
└─ README.md

핵심 로직은 주로 두 가지 API에 집중되어 있습니다.

clipboard/route.ts: 메시지 폴링, 장치 하트비트, 메시지 전송 및 장치 승인을 담당합니다.
upload/route.ts: Cloudflare R2 사전 서명된 업로드 URL 생성을 담당합니다.

프런트 엔드 ‘page.tsx’는 페이지 UI, 폴링, 메시지 병합, 파일 업로드 및 이미지 제스처 상호 작용을 담당합니다.

🔧 로컬에서 실행

이 프로젝트에는 Node.js 20+와 액세스 가능한 Redis 및 Cloudflare R2 버킷이 필요합니다.

git clone https://github.com/Licy711/lan-clipboard.git
cd lan-clipboard

npm install

cp .env.example .env.local

npm run dev

그런 다음 다음을 방문하세요.

http://localhost:3000

처음 열면 방이 자동으로 생성됩니다. 휴대폰을 사용하여 페이지의 QR 코드를 스캔하여 장치 간 동기화를 테스트하세요.

프로덕션 환경에서는 다음을 사용할 수 있습니다.

npm run build
npm start

🔐 환경 변수

PeerClip은 Redis 및 Cloudflare R2 관련 환경 변수를 구성해야 합니다.

REDIS_URL=

R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_DOMAIN=

그중 R2 API 토큰은 최소 권한의 원칙을 따르고 전체 Cloudflare 계정에 대한 관리 권한이 아닌 대상 버킷에 대한 개체 읽기 및 쓰기 권한만 부여하는 것이 좋습니다.

☁️ R2 직접 전송을 선택하는 이유는 무엇인가요?

브라우저가 파일을 Next.js API에 직접 업로드한 후 서버에서 객체 스토리지로 전달하도록 하면 서버리스 기능이 파일 전송의 중간 계층이 됩니다.

PeerClip이 미리 서명된 URL을 채택한 후 프로세스는 다음과 같습니다.

Client
  │
  │ 请求上传 URL
  ▼
Next.js API
  │
  │ 生成 Presigned PUT URL
  ▼
Client
  │
  │ 直接上传
  ▼
Cloudflare R2

이렇게 하면 서버의 데이터 전송 부담이 줄어들 뿐만 아니라 R2 키가 브라우저로 전송되는 것을 방지할 수 있습니다.

또한 Vercel Serverless Function의 요청 본문 제한을 우회할 수도 있습니다.

🌐 배포

이 프로젝트는 Vercel Serverless 환경에 최적화되어 있으므로 배포를 위해 GitHub 저장소로 직접 가져올 수 있습니다.

기본 프로세스:

GitHub
  ↓
Vercel Import
  ↓
配置 Redis
  ↓
配置 Cloudflare R2
  ↓
Deploy

배포가 완료된 후 휴대폰, 컴퓨터 및 기타 장치가 고정된 주소를 통해 직접 액세스할 수 있도록 자신의 도메인 이름을 바인딩할 수 있습니다.

🧩어떤 장면에 어울리는가요?

PeerClip은 임시적이고 가벼우며 여러 장치 간 데이터 전송을 선호합니다.

예를 들어:

💻 컴퓨터 → 휴대폰

컴퓨터에 있는 텍스트, 스크린샷 또는 파일을 복사하고 PeerClip을 열고 직접 보내세요. 휴대폰으로 QR코드를 스캔하시면 객실에 입장하여 수령하실 수 있습니다.

📱 모바일 → 컴퓨터

사진을 찍거나 휴대폰에 파일을 저장하면 위챗, QQ, 이메일을 통해 전송할 필요 없이 바로 방에 업로드하고 컴퓨터에 다운로드할 수 있습니다.

🧑‍💻 개발 시나리오

개발 과정에서 서로 다른 장치 간에 데이터를 전송해야 하는 경우가 종종 있습니다.

URL
代码片段
JSON
Token
Shell 命令
配置文件
截图
日志

PeerClip은 임시 “환승역”으로 사용될 수 있습니다.

🏠 여러 장치 간 임시 공유

집에서 Mac, Windows, iPhone, Android 등의 기기를 동시에 사용할 때 장기간 사용할 수 있는 방을 만들어 개인용 크로스 디바이스 클립보드로 사용할 수 있습니다.

⚠️ 참고 사항

PeerClip은 임시 전송 도구로 포지셔닝되므로 배포 시 다음 사항에 주의해야 합니다.

R2 API Token은 최소 권한을 사용하며 지정된 Bucket에만 권한을 부여합니다.
.env.local, 특히 Redis 비밀번호와 R2 비밀 액세스 키를 제출하지 마세요.
키가 유출된 것으로 의심되는 경우, 기존 토큰을 즉시 취소하고 재생성해야 합니다.
브라우저의 시스템 클립보드 읽기 기능을 사용하려면 일반적으로 HTTPS 또는 ‘localhost’ 환경이 필요합니다.
R2 파일에서는 저장 공간이 지속적으로 증가하는 것을 방지하기 위해 오랫동안 사용하지 않은 파일을 자동으로 정리하도록 수명 주기 규칙을 구성할 것을 권장합니다.
Redis에서는 단일 메시지에 지나치게 큰 페이로드를 저장하지 않는 것이 좋습니다. 이미지와 파일은 R2에 제공되어야 합니다.

💡 프로젝트 하이라이트

PeerClip의 가장 흥미로운 점은 “파일 업로드 페이지 만들기”가 아니라 간단해 보이는 몇 가지 문제의 조합입니다.

**순수한 웹 애플리케이션을 사용하여 다양한 장치를 임시 공유 클립보드로 전환하는 방법은 무엇입니까? **

결국 다음을 사용했습니다.

룸 역학

→ 여러 장치가 동일한 공간에 들어갈 수 있는 방법을 해결합니다.

QR 코드

→ 휴대폰으로 방입실 시 주소 입력이 번거로운 문제를 해결합니다.

장비 승인

→ 공유링크로 인한 낯선 기기 접근 문제를 해결합니다.

Redis

→ Serverless 환경의 데이터 지속성 문제를 해결합니다.

R2 Presigned URL

→ 이미지 및 파일 업로드가 서버리스 기능을 거치지 않던 문제를 해결합니다.

낙관적 업데이트 + 여론조사

→ WebSocket을 도입하지 않고도 동기화 경험을 최대한 실시간에 가깝게 만듭니다.

전체 프로젝트의 기술적 구현은 상대적으로 제한되었습니다. ‘실시간 동기화’를 위해 복잡한 장기 연결 인프라를 강제 도입하는 대신 실제 사용 시나리오를 기반으로 보다 간단한 폴링 솔루션을 선택했습니다.

😀 요약

PeerClip은 임시 장치 간 전송을 위한 작지만 완전한 도구입니다.

브라우저를 통합 입구로 사용하고 회의실 메커니즘을 통해 다양한 장치를 연결하며 Redis, Cloudflare R2 및 Vercel을 결합하여 다음을 수행합니다.

텍스트, 이미지, 파일 → 방 → 승인된 모든 장치

이 링크는 아주 간단합니다.

컴퓨터와 휴대폰 간에 텍스트, 스크린샷, 파일을 자주 전송해야 하고 추가 클라이언트를 설치하고 싶지 않은 경우 PeerClip은 비교적 가벼운 솔루션이 될 것입니다.

이 프로젝트는 MIT 라이선스를 채택하고 있으며 직접 포크, 수정 및 배포가 가능합니다.

GitHub · Licy711/lan-clipboard