· Nacho Coll · Guides  · 8 min czytania

IPFS CID wyjaśnione: czym jest i jak działa adresowanie treści

Przejrzyste techniczne wyjaśnienie identyfikatorów treści IPFS (CIDs). Jak działa adresowanie treści, wersje CID i jak stworzyć swój pierwszy CID.

Przejrzyste techniczne wyjaśnienie identyfikatorów treści IPFS (CIDs). Jak działa adresowanie treści, wersje CID i jak stworzyć swój pierwszy CID.

Jeśli kiedykolwiek pracowałeś z IPFS (InterPlanetary File System), prawdopodobnie spotkałeś się z ciągami takimi jak QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG lub bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. To nie są przypadkowe ciągi znaków — to Identyfikatory Treści (CIDs), kręgosłup systemu adresowania treści IPFS.

Zrozumienie CIDs jest kluczowe dla każdego, kto buduje na IPFS, niezależnie od tego, czy przesyła pliki, buduje zdecentralizowane aplikacje, czy implementuje systemy dystrybucji treści. Ten przewodnik wyjaśni wszystko, co musisz wiedzieć o CIDs IPFS, jak działa adresowanie treści i jak zacząć ich używać w swoich projektach.

IPFS Ninja

Czym jest IPFS CID?

Identyfikator Treści (CID) to unikalny odcisk palca reprezentujący kawałek treści w IPFS. W przeciwieństwie do tradycyjnych adresów URL, które wskazują na lokalizację (jak https://example.com/file.pdf), CIDs wskazują na samą treść, niezależnie od tego, gdzie jest przechowywana.

Pomyśl o tym w ten sposób:

  • Adresowanie oparte na lokalizacji: „Idź na Główną 123 i poproś o czerwoną książkę”
  • Adresowanie oparte na treści: „Znajdź książkę o ISBN 978-0-123456-78-9” (nie ma znaczenia, która biblioteka ją ma)

CIDs działają podobnie — identyfikują treść na podstawie jej kryptograficznego hasha, czyniąc ją niezmienną i weryfikowalną. Jeśli pojedynczy bajt w pliku się zmieni, CID zmienia się całkowicie.

Dlaczego adresowanie treści ma znaczenie

Tradycyjna architektura web opiera się na adresowaniu opartym na lokalizacji. Gdy odwiedzasz https://example.com/image.jpg, ufasz, że:

  1. Właściciel domeny nie zmienił treści
  2. Serwer jest online i dostępny
  3. Treść nie została zmanipulowana

Przy adresowaniu treści za pomocą CIDs:

  1. Niezmienność: CID gwarantuje, że treść się nie zmieniła
  2. Decentralizacja: Treść można pobrać z dowolnego węzła IPFS, który ją posiada
  3. Weryfikacja: Możesz kryptograficznie zweryfikować, że otrzymałeś właściwą treść
  4. Wydajność: Identyczna treść jest automatycznie deduplikowana

Anatomia CID

Rozłóżmy typowy CID, aby zrozumieć jego komponenty:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Hash treści (zakodowany w Base32)
  └─ Prefiks Multibase (wskazuje kodowanie)

CID zawiera kilka informacji:

1. Prefiks Multibase

Pierwszy znak wskazuje, jak CID jest zakodowany:

  • Q = Kodowanie Base58 (CIDv0)
  • b = Kodowanie Base32 (CIDv1)
  • f = Base16/szesnastkowe (CIDv1)
  • z = Base58 (CIDv1)

2. Wersja CID

  • CIDv0: Zawsze zaczyna się od Qm, używa SHA-256, ograniczona do kodeka DAG-PB
  • CIDv1: Bardziej elastyczna, obsługuje wiele funkcji hashujących i kodeków

3. Multicodec

Określa, jak treść jest zorganizowana (DAG-PB, DAG-CBOR, surowe bajty itp.)

4. Multihash

Rzeczywisty kryptograficzny hash treści, zawierający:

  • Identyfikator funkcji haszującej (zwykle SHA-256)
  • Długość hasha
  • Skrót hasha

CIDv0 vs CIDv1: Zrozumienie różnic

IPFS przeszedł przez dwie główne wersje CID, każda z odrębnymi cechami:

CIDv0: Pierwotny format

CIDs CIDv0 zawsze zaczynają się od Qm i wyglądają tak:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Cechy:

  • Tylko kodowanie Base58
  • Tylko funkcja hashująca SHA-256
  • Tylko kodek DAG-PB (Protobuf)
  • 46 znaków długości
  • Wstecznie kompatybilne ze wszystkimi implementacjami IPFS

Kiedy używać CIDv0:

  • Maksymalna kompatybilność ze starszymi węzłami IPFS
  • Praca z istniejącymi systemami oczekującymi prefiksów Qm
  • Przechowywanie plików (najczęstszy przypadek użycia)

CIDv1: Współczesny standard

CIDs CIDv1 są bardziej elastyczne i mogą wyglądać tak:

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

Cechy:

  • Wiele formatów kodowania (Base32, Base58, Base16)
  • Obsługa różnych funkcji hashujących (SHA-256, SHA-512, BLAKE2 itp.)
  • Wiele kodeków (Raw, DAG-CBOR, DAG-JSON itp.)
  • Format samoopisujący
  • Niewrażliwy na wielkość liter w Base32

Kiedy używać CIDv1:

  • Budowanie nowych aplikacji
  • Potrzeba identyfikatorów niewrażliwych na wielkość liter
  • Praca ze strukturyzowanymi danymi (JSON, CBOR)
  • Używanie alternatywnych funkcji haszujących

Konwersja między wersjami

Możesz konwertować CIDs między wersjami, zachowując to samo odwołanie do treści:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Jak działa adresowanie treści

Adresowanie treści w IPFS przebiega według deterministycznego procesu, który zapewnia, że ta sama treść zawsze daje ten sam CID:

1. Przygotowanie treści

Gdy dodajesz treść do IPFS, jest najpierw rozkładana:

  • Małe pliki: Przechowywane jako pojedyncze bloki
  • Duże pliki: Dzielone na chunki i organizowane w Merkle DAG (Directed Acyclic Graph)
  • Katalogi: Reprezentowane jako struktury DAG łączące pliki

2. Proces haszowania

Każdy fragment treści przechodzi przez:

  1. Serializacja: Treść jest formatowana zgodnie z jej kodekiem
  2. Haszowanie: Kryptograficzna funkcja hashująca przetwarza zserializowane dane
  3. Tworzenie Multihash: Hash jest opakowany informacjami o algorytmie i długości
  4. Złożenie CID: Wersja, kodek i multihash są połączone

3. Struktura Merkle DAG

IPFS organizuje treści w Merkle DAG, gdzie:

  • Każdy węzeł ma CID
  • Węzły nadrzędne odwołują się do węzłów potomnych poprzez CID
  • Zmiany w dowolnym węźle propagują się w drzewie
  • Całe struktury można kryptograficznie zweryfikować
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktyczne przykłady: Praca z CIDs

Zobaczmy, jak pracować z CIDs w praktyce, używając API IPFS Ninja:

Przesyłanie treści i otrzymywanie 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

Przypinanie istniejącej treści po CID

Jeśli już masz CID, możesz go przypiąć, aby zapewnić dostępność:

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

Dostęp do treści przez CID

Gdy już masz CID, możesz uzyskać dostęp do treści różnymi 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;
};

Najlepsze praktyki CID dla deweloperów

1. Zawsze waliduj CIDs

Zanim użyjesz CID w swojej aplikacji, zweryfikuj jego format:

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. Obsługuj obie wersje CID

Twoja aplikacja powinna działać zarówno z CIDv0, jak 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. Cachuj mapowania CID

Jeśli często generujesz CIDs, rozważ cachowanie:

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. Używaj znaczących opisów

Przy przesyłaniu treści dołączaj opisowe metadane:

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

Typowe przypadki użycia CID

1. Wdrożenie statycznych stron

Wdrażaj całe strony internetowe na IPFS i odwołuj się do nich przez 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;
};

Aby dowiedzieć się więcej o wdrażaniu stron, sprawdź nasz przewodnik o tym, jak przesyłać pliki do IPFS.

2. Przechowywanie metadanych NFT

Przechowuj metadane NFT niezmienne, używając 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. Dystrybucja treści

Używaj CIDs do rozproszonej dostawy treści:

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

Zrozumienie przypinania IPFS z CIDs

CIDs są domyślnie tymczasowe — muszą być „przypięte”, aby pozostały dostępne. Dowiedz się więcej o tej kluczowej koncepcji w naszym kompleksowym przewodniku o tym, czym jest przypinanie IPFS.

Wybierając usługę przypinania IPFS, rozważ zapoznanie się z naszym porównaniem IPFS Ninja vs Pinata lub zapoznaj się z naszym przeglądem najlepszych usług przypinania IPFS dostępnych dzisiaj.

Stwórz swój pierwszy CID w 30 sekund

Gotowy na wygenerowanie swojego pierwszego CID? Oto szybki przykład z API IPFS Ninja:

# 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();

Zwróci to coś takiego:

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

Aby zobaczyć bardziej szczegółowe przykłady API, zobacz nasz tutorial API przesyłania IPFS.

Podsumowanie

CIDs to fundament systemu adresowania treści IPFS, zapewniający niezmienną, weryfikowalną i zdecentralizowaną identyfikację treści. Zrozumienie, jak działają — od szczegółów technicznych CIDv0 vs CIDv1 po praktyczne wzorce implementacji — jest niezbędne do budowania solidnych zdecentralizowanych aplikacji.

Najważniejsze wnioski:

  • CIDs jednoznacznie identyfikują treść, a nie lokalizacje
  • CIDv0 zapewnia maksymalną kompatybilność, CIDv1 oferuje elastyczność
  • Adresowanie treści umożliwia weryfikację i deduplikację
  • Właściwa obsługa CID jest kluczowa dla aplikacji produkcyjnych

Niezależnie od tego, czy przechowujesz metadane NFT, wdrażasz zdecentralizowane strony, czy budujesz systemy dystrybucji treści, CIDs zapewniają niezawodną podstawę, której potrzebujesz dla prawdziwie zdecentralizowanych aplikacji.

Gotowy zacząć przypinać? Załóż darmowe konto — 50 plików, 1 GB pamięci, 2 GB przepustowości/miesiąc. Bez karty kredytowej.

Share:
Wróć do Bloga

Powiązane Artykuły

Zobacz Wszystkie Artykuły »