· Nacho Coll · Guides  · 8 min čtení

IPFS CID vysvětlené: co to je a jak funguje adresování obsahu

Jasné technické vysvětlení IPFS Content Identifierů (CIDs). Jak funguje adresování obsahu, verze CID a jak vytvořit svůj první CID.

Jasné technické vysvětlení IPFS Content Identifierů (CIDs). Jak funguje adresování obsahu, verze CID a jak vytvořit svůj první CID.

Pokud jste někdy pracovali s IPFS (InterPlanetary File System), pravděpodobně jste narazili na řetězce jako QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG nebo bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Toto nejsou náhodné nesmysly — jsou to Content Identifiers (CIDs), páteř IPFS systému adresování obsahu.

Porozumění CIDs je zásadní pro každého, kdo staví na IPFS, ať už nahráváte soubory, vytváříte decentralizované aplikace nebo implementujete systémy distribuce obsahu. Tato příručka rozebere vše, co potřebujete vědět o IPFS CIDs, jak funguje adresování obsahu a jak je začít používat ve svých projektech.

IPFS Ninja

Co je IPFS CID?

Content Identifier (CID) je jedinečný otisk prstu, který reprezentuje kus obsahu na IPFS. Na rozdíl od tradičních webových URL, které ukazují na umístění (jako https://example.com/file.pdf), CIDs ukazují na samotný obsah, bez ohledu na to, kde je uložen.

Představte si to takto:

  • Adresování založené na umístění: “Jděte na Hlavní ulici 123 a požádejte o červenou knihu”
  • Adresování založené na obsahu: “Najděte knihu s ISBN 978-0-123456-78-9” (nezáleží na tom, která knihovna ji má)

CIDs fungují podobně — identifikují obsah na základě jeho kryptografického hashe, čímž činí obsah neměnným a ověřitelným. Pokud se v souboru změní byť jediný bajt, CID se změní zcela.

Proč na adresování obsahu záleží

Tradiční webová architektura se spoléhá na adresování založené na umístění. Když navštívíte https://example.com/image.jpg, věříte tomu, že:

  1. Majitel domény nezměnil obsah
  2. Server je online a přístupný
  3. Obsah nebyl manipulován

S adresováním obsahu pomocí CIDs:

  1. Neměnnost: CID zaručuje, že se obsah nezměnil
  2. Decentralizace: Obsah lze získat z jakéhokoli IPFS uzlu, který ho má
  3. Ověření: Můžete kryptograficky ověřit, že jste obdrželi správný obsah
  4. Efektivita: Identický obsah je automaticky deduplikován

Anatomie CID

Pojďme rozebrat typický CID, abychom pochopili jeho komponenty:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash obsahu (Base32 kódovaný)
  └─ Multibase předpona (označuje kódování)

CID obsahuje několik informací:

1. Multibase předpona

První znak označuje, jak je CID kódován:

  • Q = Base58 kódování (CIDv0)
  • b = Base32 kódování (CIDv1)
  • f = Base16/hexadecimální (CIDv1)
  • z = Base58 (CIDv1)

2. Verze CID

  • CIDv0: Vždy začíná Qm, používá SHA-256, omezeno na DAG-PB codec
  • CIDv1: Flexibilnější, podporuje více hashovacích funkcí a codeců

3. Multicodec

Specifikuje, jak je obsah strukturován (DAG-PB, DAG-CBOR, surové bajty atd.)

4. Multihash

Skutečný kryptografický hash obsahu, včetně:

  • Identifikátoru hashovací funkce (obvykle SHA-256)
  • Délky hashe
  • Hash digestu

CIDv0 vs CIDv1: Porozumění rozdílům

IPFS se vyvinul přes dvě hlavní verze CID, každá s odlišnými charakteristikami:

CIDv0: Původní formát

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

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Charakteristiky:

  • Pouze Base58 kódování
  • Pouze SHA-256 hashovací funkce
  • Pouze DAG-PB (Protobuf) codec
  • 46 znaků dlouhý
  • Zpětně kompatibilní se všemi IPFS implementacemi

Kdy použít CIDv0:

  • Maximální kompatibilita se staršími IPFS uzly
  • Práce se stávajícími systémy, které očekávají Qm předpony
  • Ukládání souborů (nejběžnější případ použití)

CIDv1: Moderní standard

CIDv1 CIDs jsou flexibilnější a mohou vypadat takto:

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

Charakteristiky:

  • Více kódovacích formátů (Base32, Base58, Base16)
  • Podpora různých hashovacích funkcí (SHA-256, SHA-512, BLAKE2 atd.)
  • Více codeců (Raw, DAG-CBOR, DAG-JSON atd.)
  • Sebepopisující formát
  • Necitlivý na velikost písmen při použití Base32

Kdy použít CIDv1:

  • Vytváření nových aplikací
  • Potřeba identifikátorů necitlivých na velikost písmen
  • Práce se strukturovanými daty (JSON, CBOR)
  • Použití alternativních hashovacích funkcí

Konverze mezi verzemi

Můžete převádět CIDs mezi verzemi při zachování stejného odkazu na obsah:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Jak funguje adresování obsahu

Adresování obsahu v IPFS sleduje deterministický proces, který zajišťuje, že stejný obsah vždy produkuje stejné CID:

1. Příprava obsahu

Když přidáte obsah do IPFS, nejprve se rozdělí:

  • Malé soubory: Uloženy jako jednotlivé bloky
  • Velké soubory: Rozděleny na bloky a organizovány v Merkle DAG (Directed Acyclic Graph)
  • Adresáře: Reprezentovány jako DAG struktury odkazující na soubory

2. Hashovací proces

Každý kus obsahu prochází:

  1. Serializace: Obsah je formátován podle svého codecu
  2. Hashování: Kryptografická hashovací funkce zpracovává serializovaná data
  3. Vytvoření Multihash: Hash je zabalen s informacemi o algoritmu a délce
  4. Sestavení CID: Verze, codec a multihash jsou kombinovány

3. Struktura Merkle DAG

IPFS organizuje obsah v Merkle DAG, kde:

  • Každý uzel má CID
  • Rodičovské uzly odkazují na potomky pomocí CID
  • Změny v jakémkoli uzlu se šíří stromem nahoru
  • Celé struktury lze kryptograficky ověřit
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktické příklady: Práce s CIDs

Pojďme prozkoumat, jak pracovat s CIDs v praxi pomocí IPFS Ninja API:

Nahrávání obsahu a získání 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

Připnutí stávajícího obsahu pomocí CID

Pokud již máte CID, můžete jej připnout, abyste zajistili dostupnost:

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');

Přístup k obsahu přes CID

Jakmile máte CID, můžete přistupovat k obsahu několika metodami:

// 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;
};

Nejlepší postupy CID pro vývojáře

1. Vždy validujte CIDs

Před použitím CID ve vaší aplikaci ověřte 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. Zpracujte obě verze CID

Vaše aplikace by měla pracovat s CIDv0 i 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. Ukládejte CID mapování do mezipaměti

Pokud generujete CIDs často, zvažte mezipaměťování:

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žívejte smysluplné popisy

Při nahrávání obsahu zahrňte popisná metadata:

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'
      }
    })
  });
};

Běžné případy použití CID

1. Nasazení statického webu

Nasazujte celé weby na IPFS a odkazujte na ně pomocí 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;
};

Chcete-li se dozvědět více o nasazení webu, podívejte se na našeho průvodce o tom, jak nahrát soubory na IPFS.

2. Ukládání metadat NFT

Ukládejte NFT metadata neměnně pomocí 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. Distribuce obsahu

Používejte CIDs pro distribuovanou dodávku 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 };
};

Porozumění IPFS pinningu pomocí CIDs

CIDs jsou ve výchozím nastavení dočasné — musí být “připnuté”, aby zůstaly dostupné. Dozvíte se více o tomto klíčovém konceptu v naší komplexní příručce o tom, co je IPFS pinning.

Při výběru služby IPFS pinningu zvažte přečtení našeho srovnání IPFS Ninja vs Pinata nebo prozkoumejte náš přehled nejlepších služeb IPFS pinningu dostupných dnes.

Vytvořte svůj první CID za 30 sekund

Jste připraveni vygenerovat svůj první CID? Zde je rychlý příklad pomocí 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átí něco jako:

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

Pro podrobnější příklady API se podívejte na náš tutoriál IPFS upload API.

Závěr

CIDs jsou základem IPFS systému adresování obsahu, poskytujícím neměnnou, ověřitelnou a decentralizovanou identifikaci obsahu. Porozumění tomu, jak fungují — od technických detailů CIDv0 vs CIDv1 po praktické implementační vzory — je zásadní pro vytváření robustních decentralizovaných aplikací.

Klíčové poznatky:

  • CIDs jedinečně identifikují obsah, ne umístění
  • CIDv0 poskytuje maximální kompatibilitu, CIDv1 nabízí flexibilitu
  • Adresování obsahu umožňuje ověření a deduplikaci
  • Správné zacházení s CID je zásadní pro produkční aplikace

Ať už ukládáte NFT metadata, nasazujete decentralizované weby nebo budujete systémy distribuce obsahu, CIDs poskytují spolehlivý základ, který potřebujete pro skutečně decentralizované aplikace.

Připraveni začít pinovat? Vytvořte bezplatný účet — 50 souborů, 1 GB úložiště, 2 GB šířka pásma/měsíc. Bez kreditní karty.

Share:
Zpět na Blog

Související články

Zobrazit všechny články »