· Nacho Coll · Guides  · 8 min čítania

IPFS CID vysvetlené: čo to je a ako funguje adresovanie obsahu

Jasné technické vysvetlenie IPFS Content Identifierov (CIDs). Ako funguje adresovanie obsahu, verzie CID a ako vytvoriť svoj prvý CID.

Jasné technické vysvetlenie IPFS Content Identifierov (CIDs). Ako funguje adresovanie obsahu, verzie CID a ako vytvoriť svoj prvý CID.

Ak ste niekedy pracovali s IPFS (InterPlanetary File System), pravdepodobne ste narazili na reťazce ako QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG alebo bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Toto nie sú náhodné nezmysly — sú to Content Identifiers (CIDs), chrbtová kosť systému adresovania obsahu IPFS.

Pochopenie CIDs je kľúčové pre každého, kto stavia na IPFS, či už nahrávate súbory, vytvárate decentralizované aplikácie alebo implementujete systémy distribúcie obsahu. Tento sprievodca rozoberie všetko, čo potrebujete vedieť o IPFS CIDs, ako funguje adresovanie obsahu a ako začať ich používať vo vašich projektoch.

IPFS Ninja

Čo je IPFS CID?

Content Identifier (CID) je jedinečný odtlačok prsta, ktorý reprezentuje časť obsahu na IPFS. Na rozdiel od tradičných webových URL, ktoré ukazujú na umiestnenie (ako https://example.com/file.pdf), CIDs ukazujú na samotný obsah, bez ohľadu na to, kde je uložený.

Predstavte si to takto:

  • Adresovanie na základe umiestnenia: „Choďte na Hlavnú ulicu 123 a vypýtajte si červenú knihu”
  • Adresovanie na základe obsahu: „Nájdite knihu s ISBN 978-0-123456-78-9” (nezáleží na tom, ktorá knižnica ju má)

CIDs fungujú podobne — identifikujú obsah na základe jeho kryptografického hashu, čím robia obsah nemenným a overiteľným. Ak sa v súbore zmení čo i len jeden bajt, CID sa zmení úplne.

Prečo na adresovaní obsahu záleží

Tradičná webová architektúra sa spolieha na adresovanie založené na umiestnení. Keď navštívite https://example.com/image.jpg, dôverujete tomu, že:

  1. Vlastník domény nezmenil obsah
  2. Server je online a dostupný
  3. Obsah nebol manipulovaný

S adresovaním obsahu pomocou CIDs:

  1. Nemennosť: CID zaručuje, že sa obsah nezmenil
  2. Decentralizácia: Obsah je možné získať z akéhokoľvek IPFS uzla, ktorý ho má
  3. Overenie: Môžete kryptograficky overiť, že ste dostali správny obsah
  4. Efektivita: Identický obsah sa automaticky deduplikuje

Anatómia CID

Rozoberme typický CID, aby sme pochopili jeho komponenty:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash obsahu (Base32 kódovaný)
  └─ Multibase prefix (označuje kódovanie)

CID obsahuje niekoľko informácií:

1. Multibase prefix

Prvý znak označuje, ako je CID kódovaný:

  • Q = Base58 kódovanie (CIDv0)
  • b = Base32 kódovanie (CIDv1)
  • f = Base16/hexadecimálne (CIDv1)
  • z = Base58 (CIDv1)

2. Verzia CID

  • CIDv0: Vždy začína Qm, používa SHA-256, obmedzený na DAG-PB codec
  • CIDv1: Flexibilnejší, podporuje viac hashovacích funkcií a codecov

3. Multicodec

Špecifikuje, ako je obsah štruktúrovaný (DAG-PB, DAG-CBOR, surové bajty atď.)

4. Multihash

Skutočný kryptografický hash obsahu, vrátane:

  • Identifikátora hashovacej funkcie (zvyčajne SHA-256)
  • Dĺžky hashu
  • Hash digestu

CIDv0 vs CIDv1: Porozumenie rozdielom

IPFS sa vyvinul cez dve hlavné verzie CID, každá s odlišnými charakteristikami:

CIDv0: Pôvodný formát

CIDv0 CIDs vždy začínajú Qm a vyzerajú takto:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Charakteristiky:

  • Iba Base58 kódovanie
  • Iba SHA-256 hashovacia funkcia
  • Iba DAG-PB (Protobuf) codec
  • 46 znakov dlhý
  • Spätne kompatibilný so všetkými IPFS implementáciami

Kedy použiť CIDv0:

  • Maximálna kompatibilita so staršími IPFS uzlami
  • Práca s existujúcimi systémami, ktoré očakávajú Qm prefixy
  • Ukladanie súborov (najbežnejší prípad použitia)

CIDv1: Moderný štandard

CIDv1 CIDs sú flexibilnejšie a môžu vyzerať takto:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi  # Base32
zb2rhj7crUKTQYRGCRATFaQ6YFLTde2YzdqbbhAASkL9uRDXn      # Base58
f01551220d1e2c35...                                      # Base16

Charakteristiky:

  • Viacero formátov kódovania (Base32, Base58, Base16)
  • Podpora rôznych hashovacích funkcií (SHA-256, SHA-512, BLAKE2 atď.)
  • Viacero codecov (Raw, DAG-CBOR, DAG-JSON atď.)
  • Samoposisujúci formát
  • Necitlivý na veľkosť písmen pri použití Base32

Kedy použiť CIDv1:

  • Vytváranie nových aplikácií
  • Potreba identifikátorov necitlivých na veľkosť písmen
  • Práca so štruktúrovanými dátami (JSON, CBOR)
  • Použitie alternatívnych hashovacích funkcií

Konverzia medzi verziami

Môžete konvertovať CIDs medzi verziami pri zachovaní rovnakého odkazu na obsah:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

// Convert to CIDv1 Base32
const cidv1 = "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi";

// Both reference the same content!

Ako funguje adresovanie obsahu

Adresovanie obsahu v IPFS sleduje deterministický proces, ktorý zabezpečuje, že rovnaký obsah vždy produkuje rovnaký CID:

1. Príprava obsahu

Keď pridáte obsah do IPFS, najprv sa rozdelí:

  • Malé súbory: Uložené ako jednotlivé bloky
  • Veľké súbory: Rozdelené na kúsky a organizované v Merkle DAG (Directed Acyclic Graph)
  • Adresáre: Reprezentované ako DAG štruktúry odkazujúce na súbory

2. Hashovací proces

Každý kus obsahu prechádza:

  1. Serializácia: Obsah je formátovaný podľa svojho codecu
  2. Hashovanie: Kryptografická hashovacia funkcia spracováva serializované dáta
  3. Vytvorenie Multihash: Hash je zabalený s informáciami o algoritme a dĺžke
  4. Zostavenie CID: Verzia, codec a multihash sú kombinované

3. Štruktúra Merkle DAG

IPFS organizuje obsah v Merkle DAG, kde:

  • Každý uzol má CID
  • Rodičovské uzly odkazujú na potomkov pomocou CID
  • Zmeny v akomkoľvek uzle sa šíria stromom nahor
  • Celé štruktúry je možné kryptograficky overiť
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktické príklady: Práca s CIDs

Preskúmajme, ako pracovať s CIDs v praxi pomocou IPFS Ninja API:

Nahrávanie obsahu a získanie CID

// Upload a file and get its CID
const uploadFile = async (content, filename) => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content), // Base64 encode binary content
      description: `Upload of ${filename}`
    })
  });
  
  const result = await response.json();
  console.log('CID:', result.cid);
  console.log('IPFS URL:', result.uris.ipfs);
  console.log('HTTP URL:', result.uris.url);
  
  return result.cid;
};

// Example usage
uploadFile('Hello, IPFS!', 'greeting.txt');
// Returns: bafkreifjxz6zwqh27k5xnr5qfbx4w6n5vuwwwdcngguwjewzj2e3xxfgvi

Pripnutie existujúceho obsahu pomocou CID

Ak už máte CID, môžete ho pripnúť, aby ste zabezpečili dostupnosť:

const pinByCID = async (cid) => {
  const response = await fetch('https://api.ipfs.ninja/pin', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      cid: cid,
      description: 'Pinned via API'
    })
  });
  
  const result = await response.json();
  console.log('Pinned CID:', result.cid);
  
  return result;
};

// Pin the "Hello World" of IPFS
pinByCID('QmWATWQ7fVPP2EFGu71UkfnqhYXDYH566qy47CnJDgvs8u');

Prístup k obsahu cez CID

Akonáhle máte CID, môžete pristupovať k obsahu rôznymi metódami:

// Direct IPFS gateway access
const ipfsUrl = `https://ipfs.ninja/ipfs/${cid}`;

// Custom gateway (if configured)
const customGatewayUrl = `https://my-app.gw.ipfs.ninja/ipfs/${cid}`;

// Fetch content programmatically
const fetchContent = async (cid) => {
  const response = await fetch(`https://ipfs.ninja/ipfs/${cid}`);
  const content = await response.text();
  return content;
};

Najlepšie postupy CID pre vývojárov

1. Vždy validujte CIDs

Pred použitím CID vo vašej aplikácii overte jeho formát:

const isValidCID = (cid) => {
  // Basic validation patterns
  const cidv0Pattern = /^Qm[1-9A-HJ-NP-Za-km-z]{44}$/;
  const cidv1Pattern = /^[bf][a-z2-7]{58}$/;
  
  return cidv0Pattern.test(cid) || cidv1Pattern.test(cid);
};

2. Spracujte obe verzie CID

Vaša aplikácia by mala fungovať s CIDv0 aj CIDv1:

const normalizeCID = (cid) => {
  if (cid.startsWith('Qm')) {
    // CIDv0 - can convert to CIDv1 if needed
    return cid;
  } else if (cid.startsWith('b') || cid.startsWith('f') || cid.startsWith('z')) {
    // CIDv1
    return cid;
  } else {
    throw new Error('Invalid CID format');
  }
};

3. Ukladajte CID mapovania do cache

Ak generujete CIDs často, zvážte cachovanie:

const cidCache = new Map();

const getCachedCID = (content) => {
  const contentHash = btoa(content);
  
  if (cidCache.has(contentHash)) {
    return cidCache.get(contentHash);
  }
  
  // Upload and cache result
  return uploadFile(content).then(cid => {
    cidCache.set(contentHash, cid);
    return cid;
  });
};

4. Používajte zmysluplné popisy

Pri nahrávaní obsahu zahrňte popisné metadáta:

const uploadWithMetadata = async (content, metadata) => {
  return fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_1234567890abcdef1234567890abcdef12345678',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa(content),
      description: metadata.name || 'Uploaded file',
      metadata: {
        filename: metadata.filename,
        contentType: metadata.contentType,
        uploadedAt: new Date().toISOString(),
        version: metadata.version || '1.0'
      }
    })
  });
};

Bežné prípady použitia CID

1. Nasadenie statickej webovej stránky

Nasadzujte celé webové stránky na IPFS a odkazujte na ne pomocou CID:

// Upload website directory structure
const deployWebsite = async (files) => {
  const uploads = await Promise.all(
    files.map(file => uploadFile(file.content, file.path))
  );
  
  // Root CID references entire site
  const rootCID = uploads.find(u => u.path === 'index.html').cid;
  console.log(`Website deployed: https://ipfs.ninja/ipfs/${rootCID}`);
  
  return rootCID;
};

Ak sa chcete dozvedieť viac o nasadení webových stránok, pozrite si nášho sprievodcu o tom, ako nahrať súbory na IPFS.

2. Ukladanie metadát NFT

Ukladajte NFT metadáta nemenne pomocou CIDs:

const nftMetadata = {
  name: "My Awesome NFT",
  description: "A unique digital collectible",
  image: "ipfs://bafkreibc5sgo2plmjkq2tzmhrn54bk3crhnqekiy7u66fqvqm37pu2e5gw",
  attributes: [
    { trait_type: "Color", value: "Blue" },
    { trait_type: "Rarity", value: "Epic" }
  ]
};

const metadataCID = await uploadFile(
  JSON.stringify(nftMetadata, null, 2), 
  'metadata.json'
);

// Use in smart contract
console.log(`Token URI: ipfs://${metadataCID}`);

3. Distribúcia obsahu

Používajte CIDs pre distribuované doručovanie obsahu:

// Upload once, access everywhere
const distributeContent = async (content) => {
  const cid = await uploadFile(content, 'content.txt');
  
  // Content available via multiple gateways
  const gateways = [
    `https://ipfs.ninja/ipfs/${cid}`,
    `https://ipfs.io/ipfs/${cid}`,
    `https://cloudflare-ipfs.com/ipfs/${cid}`
  ];
  
  return { cid, gateways };
};

Porozumenie IPFS pinningu s CIDs

CIDs sú v predvolenom nastavení dočasné — musia byť „pripnuté”, aby zostali dostupné. Dozviete sa viac o tomto kľúčovom koncepte v našom komplexnom sprievodcovi o tom, čo je IPFS pinning.

Pri výbere služby IPFS pinningu zvážte prečítanie nášho porovnania IPFS Ninja vs Pinata alebo preskúmajte náš prehľad najlepších služieb IPFS pinningu dostupných dnes.

Vytvorte svoj prvý CID za 30 sekúnd

Pripravení vygenerovať svoj prvý CID? Tu je rýchly príklad pomocou IPFS Ninja API:

# Using curl (replace with your actual API key)
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "SGVsbG8sIElQRlMgV29ybGQh",
    "description": "My first IPFS upload"
  }'
// Using JavaScript
const createFirstCID = async () => {
  const response = await fetch('https://api.ipfs.ninja/upload/new', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bws_YOUR_API_KEY_HERE',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      content: btoa('Hello, IPFS World!'), // Base64: "SGVsbG8sIElQRlMgV29ybGQh"
      description: 'My first IPFS upload'
    })
  });
  
  const result = await response.json();
  console.log('🎉 Your first CID:', result.cid);
  console.log('🌐 Access it at:', result.uris.url);
  
  return result;
};

createFirstCID();

Toto vráti niečo ako:

{
  "cid": "bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
  "sizeMB": 0.000017,
  "uris": {
    "ipfs": "ipfs://bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw",
    "url": "https://ipfs.ninja/ipfs/bafkreif2pall7dybz7vecqka3zo24irdwabf7rbiiweuhau7a2hjlqvfjw"
  }
}

Pre podrobnejšie API príklady si pozrite náš tutoriál IPFS upload API.

Záver

CIDs sú základom systému adresovania obsahu IPFS, poskytujúce nemennú, overiteľnú a decentralizovanú identifikáciu obsahu. Porozumenie tomu, ako fungujú — od technických detailov CIDv0 vs CIDv1 po praktické implementačné vzory — je nevyhnutné pre vytváranie robustných decentralizovaných aplikácií.

Kľúčové poznatky:

  • CIDs jedinečne identifikujú obsah, nie umiestnenia
  • CIDv0 poskytuje maximálnu kompatibilitu, CIDv1 ponúka flexibilitu
  • Adresovanie obsahu umožňuje overenie a deduplikáciu
  • Správne zaobchádzanie s CID je kľúčové pre produkčné aplikácie

Či už ukladáte NFT metadáta, nasadzujete decentralizované webové stránky alebo budujete systémy distribúcie obsahu, CIDs poskytujú spoľahlivý základ, ktorý potrebujete pre skutočne decentralizované aplikácie.

Pripravení začať pinovať? Vytvorte si bezplatný účet — 50 súborov, 1 GB úložiska, 2 GB šírka pásma/mesiac. Bez kreditnej karty.

Share:
Späť na Blog

Súvisiace články

Zobraziť všetky články »