IPFS (InterPlanetary File System) | KAITRUST AI 백과사전

📖 상세 설명

IPFS(InterPlanetary File System)는 Protocol Labs가 2015년에 개발한 P2P 분산 파일 시스템입니다. 기존 HTTP가 서버 위치 기반(Location-based)으로 파일을 찾는 반면, IPFS는 콘텐츠의 해시값(CID, Content Identifier)으로 파일을 찾는 콘텐츠 주소 지정(Content-Addressing) 방식을 사용합니다. 같은 내용의 파일은 어디에 저장되어 있든 동일한 CID를 가집니다.

IPFS의 핵심 구성 요소는 세 가지입니다. 첫째, MerkleDAG 구조로 파일을 256KB 청크로 분할하여 해시 트리로 연결합니다. 둘째, DHT(Distributed Hash Table)로 어떤 노드가 어떤 콘텐츠를 가지고 있는지 분산 저장합니다. 셋째, Bitswap 프로토콜로 필요한 블록을 가진 노드를 찾아 P2P로 데이터를 교환합니다.

IPFS에서 파일을 추가하면 고유한 CID가 생성됩니다. 예: QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco. 이 CID로 전 세계 어느 IPFS 노드에서든 동일한 파일을 가져올 수 있습니다. 파일 내용이 1비트라도 변경되면 완전히 다른 CID가 생성되어, 데이터 무결성이 자동으로 보장됩니다.

Web3 생태계에서 IPFS는 NFT 메타데이터, DApp 프론트엔드, 탈중앙화 웹사이트 호스팅에 핵심적으로 사용됩니다. Filecoin은 IPFS 위에 구축된 인센티브 레이어로, 저장 제공자에게 토큰 보상을 지급하여 장기적인 데이터 보존을 보장합니다. OpenSea, Uniswap, Audius 등 주요 Web3 서비스들이 IPFS를 활용합니다.

💻 코드 예제

// IPFS HTTP Client (브라우저/Node.js)
import { create } from 'ipfs-http-client';

// Infura IPFS 게이트웨이 연결
const ipfs = create({
    host: 'ipfs.infura.io',
    port: 5001,
    protocol: 'https',
    headers: {
        authorization: 'Basic ' + btoa(PROJECT_ID + ':' + PROJECT_SECRET)
    }
});

// 파일 업로드
async function uploadFile(content) {
    const { cid } = await ipfs.add(content);
    console.log('CID:', cid.toString());
    // CID: QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
    return cid;
}

// JSON 메타데이터 업로드 (NFT용)
async function uploadNFTMetadata(metadata) {
    const json = JSON.stringify(metadata);
    const { cid } = await ipfs.add(json);
    return `ipfs://${cid}`;  // ipfs://Qm...
}

// 파일 가져오기
async function getFile(cid) {
    const chunks = [];
    for await (const chunk of ipfs.cat(cid)) {
        chunks.push(chunk);
    }
    return Buffer.concat(chunks).toString();
}

// 디렉토리 업로드
async function uploadDirectory(files) {
    const result = await ipfs.addAll(files, { wrapWithDirectory: true });
    for await (const file of result) {
        console.log(`${file.path}: ${file.cid}`);
    }
}

# IPFS 설치 (macOS)
brew install ipfs

# IPFS 노드 초기화
ipfs init
ipfs daemon  # 노드 시작 (별도 터미널)

# 파일 추가 (로컬 노드에 저장)
ipfs add myfile.txt
# added QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco myfile.txt

# 디렉토리 전체 추가
ipfs add -r ./my-website/
# 마지막 출력이 루트 디렉토리 CID

# 파일 가져오기
ipfs cat QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
ipfs get QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco -o output.txt

# 핀 고정 (가비지 컬렉션 방지)
ipfs pin add QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
ipfs pin ls  # 핀 목록 확인

# IPNS (가변 이름 시스템)
ipfs name publish QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
# Published to k51qzi5uqu...: /ipfs/Qm...

# 공개 게이트웨이로 접근
curl https://ipfs.io/ipfs/QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco
curl https://cloudflare-ipfs.com/ipfs/Qm...

import ipfshttpclient  # pip install ipfshttpclient

# 로컬 IPFS 노드 연결
client = ipfshttpclient.connect('/ip4/127.0.0.1/tcp/5001')

# 파일 추가
result = client.add('myfile.txt')
print(f"CID: {result['Hash']}")
# CID: QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco

# 바이트 데이터 추가
data = b'Hello IPFS!'
result = client.add_bytes(data)
print(f"CID: {result}")

# JSON 추가 (NFT 메타데이터)
metadata = {
    "name": "My NFT",
    "description": "An awesome NFT",
    "image": "ipfs://QmImageCID..."
}
result = client.add_json(metadata)
print(f"Metadata CID: {result}")

# 파일 가져오기
content = client.cat(result['Hash'])
print(content.decode('utf-8'))

# 디렉토리 추가
result = client.add('my-website/', recursive=True)
for item in result:
    print(f"{item['Name']}: {item['Hash']}")

# 핀 고정
client.pin.add('QmXoypizjW3WknFiJnKLwHCnL72vedxjQkDDP1mXWo6uco')

# 노드 정보 확인
info = client.id()
print(f"Peer ID: {info['ID']}")

🗣️ 실무에서 이렇게 말하세요

💬 NFT 프로젝트 설계 회의에서

"NFT 메타데이터와 이미지는 IPFS에 올리고, 토큰 URI에 ipfs:// 스킴으로 저장합시다. CID는 콘텐츠 해시라서 한번 민팅하면 메타데이터 위변조가 불가능합니다. Pinata나 NFT.Storage로 핀 서비스를 이용하면 영구 보존도 보장됩니다."

💬 DApp 아키텍처 논의에서

"프론트엔드를 IPFS에 배포하면 단일 장애점 없이 탈중앙화됩니다. Fleek이나 4EVERLAND로 CI/CD 파이프라인 구축하면 git push만으로 자동 배포되고, ENS 도메인 연결하면 myapp.eth로 접근 가능합니다. Cloudflare IPFS 게이트웨이 쓰면 로딩 속도도 빨라요."

💬 면접에서

"IPFS는 콘텐츠 주소 지정 방식으로 HTTP의 위치 기반 주소 지정과 다릅니다. 같은 파일은 전 세계 어디서든 동일한 CID를 가지므로, 가장 가까운 노드에서 받아올 수 있어 CDN 효과가 있습니다. Filecoin과 결합하면 경제적 인센티브로 장기 저장도 보장됩니다."

⚠️ 흔한 실수 & 주의사항

❌

핀 고정 없이 파일 업로드

IPFS에 파일을 추가만 하면 가비지 컬렉션으로 삭제됩니다. 반드시 Pinata, Infura, NFT.Storage 같은 핀 서비스를 사용하거나 자체 노드에서 핀 고정하세요.

❌

IPFS를 데이터베이스처럼 사용

IPFS는 불변(immutable) 스토리지입니다. 파일 수정 시 새 CID가 생성됩니다. 자주 변경되는 데이터는 IPNS나 OrbitDB 같은 솔루션을 고려하세요.

❌

공개 게이트웨이만 의존

ipfs.io 같은 공개 게이트웨이는 속도 제한과 가용성 문제가 있습니다. 프로덕션에서는 자체 게이트웨이 운영이나 Cloudflare IPFS, Infura 유료 플랜을 사용하세요.

✅

올바른 IPFS 활용법

중요 파일은 최소 2개 이상의 핀 서비스에 복제. CIDv1 사용으로 URL 호환성 확보. 대용량 파일은 CAR 파일로 패키징. 민감 데이터는 암호화 후 업로드하세요.

🔗 관련 용어

📚 더 배우기

📄 IPFS 공식 문서 🎓 ProtoSchool - 콘텐츠 주소 지정 튜토리얼 📖 NFT.Storage - 무료 NFT 스토리지