IPFS CID-ji 2026: Vodnik po vsebinskem naslavljanju

Če ste kdaj delali z IPFS (InterPlanetary File System), ste verjetno naleteli na nize, kot so QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG ali bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. To niso naključne neumnosti — to so Content Identifierji (CIDs), hrbtenica sistema vsebinskega naslavljanja IPFS.

Razumevanje CIDs je ključno za vsakogar, ki gradi na IPFS, ne glede na to, ali nalagate datoteke, gradite decentralizirane aplikacije ali izvajate sisteme distribucije vsebin. Ta vodnik bo razčlenil vse, kar morate vedeti o IPFS CIDs, kako deluje vsebinsko naslavljanje in kako jih začeti uporabljati v svojih projektih.

Ustvarite CID v 5 vrsticah (Python)#

import hashlib, base58

def cidv0(content: bytes) -> str:
    sha256 = hashlib.sha256(content).digest()
    return base58.b58encode(b"\x12\x20" + sha256).decode()

print(cidv0(b"hello world"))
# QmaozNR7DZHQK1ZcU9p7QdrshMvXqWK6gpvBw3cWE69N3T

Ta CID je ponovljiv za vsakogar — znova ga zaženite z istimi bajti kjer koli na svetu in dobite isti niz. To je vsebinsko naslavljanje.

Ekvivalent v Node.js:

import { sha256 } from 'multiformats/hashes/sha2';
import { CID } from 'multiformats/cid';

const bytes = new TextEncoder().encode('hello world');
const hash = await sha256.digest(bytes);
const cid = CID.create(1, 0x55, hash); // version 1, raw codec
console.log(cid.toString());
// bafkreif7l7mvyofhyo6fgs6mjf5gguvm5jcahzgvfb3o7t5lmhz3...

Kaj je IPFS CID?#

Content Identifier (CID) je edinstven prstni odtis, ki predstavlja kos vsebine na IPFS. Za razliko od tradicionalnih spletnih URL-jev, ki kažejo na lokacijo (kot https://example.com/file.pdf), CIDs kažejo na samo vsebino, ne glede na to, kje je shranjena.

Razmislite o tem takole:

Naslavljanje na podlagi lokacije: »Pojdite na Glavno ulico 123 in vprašajte za rdečo knjigo«
Naslavljanje na podlagi vsebine: »Poiščite knjigo z ISBN 978-0-123456-78-9« (ni pomembno, katera knjižnica jo ima)

CIDs delujejo podobno — vsebino identificirajo na podlagi njenega kriptografskega zgoščenja, zaradi česar je vsebina nespremenljiva in preverljiva. Če se v datoteki spremeni en sam bajt, se CID popolnoma spremeni.

Zakaj je vsebinsko naslavljanje pomembno#

Tradicionalna spletna arhitektura se zanaša na naslavljanje na podlagi lokacije. Ko obiščete https://example.com/image.jpg, zaupate, da:

Lastnik domene ni spremenil vsebine
Strežnik je na spletu in dostopen
Vsebina ni bila manipulirana

Z vsebinskim naslavljanjem z uporabo CIDs:

Nespremenljivost: CID jamči, da se vsebina ni spremenila
Decentralizacija: Vsebino lahko pridobite z vsakega vozlišča IPFS, ki jo ima
Preverjanje: Kriptografsko lahko preverite, da ste prejeli pravilno vsebino
Učinkovitost: Identična vsebina se samodejno deduplicira

Anatomija CID#

Razčlenimo tipičen CID, da bomo razumeli njegove komponente:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Zgoščenje vsebine (Base32 kodirano)
  └─ Multibase predpona (označuje kodiranje)

CID vsebuje več informacijskih kosov:

1. Multibase predpona#

Prvi znak označuje, kako je CID kodiran:

Q = Base58 kodiranje (CIDv0)
b = Base32 kodiranje (CIDv1)
f = Base16/šestnajstiško (CIDv1)
z = Base58 (CIDv1)

2. Različica CID#

CIDv0: Vedno se začne z Qm, uporablja SHA-256, omejen na DAG-PB codec
CIDv1: Bolj prilagodljiv, podpira več funkcij zgoščenja in codeces

3. Multicodec#

Določa, kako je vsebina strukturirana (DAG-PB, DAG-CBOR, surovi bajti itd.)

4. Multihash#

Dejansko kriptografsko zgoščenje vsebine, vključno z:

Identifikatorjem funkcije zgoščenja (običajno SHA-256)
Dolžino zgoščenja
Hash digestom

CIDv0 vs CIDv1: Razumevanje razlik#

IPFS se je razvil skozi dve glavni različici CID, vsaka s svojimi značilnostmi:

CIDv0: Izvirni format#

CIDv0 CIDs se vedno začnejo z Qm in izgledajo takole:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Značilnosti:

Samo Base58 kodiranje
Samo SHA-256 funkcija zgoščenja
Samo DAG-PB (Protobuf) codec
Dolžina 46 znakov
Vzvratno združljiv z vsemi IPFS implementacijami

Kdaj uporabiti CIDv0:

Maksimalna združljivost s starejšimi IPFS vozlišči
Delo z obstoječimi sistemi, ki pričakujejo predpone Qm
Shranjevanje datotek (najpogostejši primer uporabe)

CIDv1: Sodobni standard#

CIDv1 CIDs so bolj prilagodljivi in lahko izgledajo takole:

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

Značilnosti:

Več formatov kodiranja (Base32, Base58, Base16)
Podpora za različne funkcije zgoščenja (SHA-256, SHA-512, BLAKE2 itd.)
Več codeces (Raw, DAG-CBOR, DAG-JSON itd.)
Samoopisni format
Neobčutljiv na velike/male črke pri Base32 uporabi

Kdaj uporabiti CIDv1:

Gradnja novih aplikacij
Potreba po identifikatorjih neobčutljivih na velike črke
Delo s strukturiranimi podatki (JSON, CBOR)
Uporaba alternativnih funkcij zgoščenja

Pretvorba med različicami#

CIDs lahko pretvarjate med različicami, medtem ko ohranjate isto referenco vsebine:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Kako deluje vsebinsko naslavljanje#

Vsebinsko naslavljanje v IPFS sledi determinističnemu procesu, ki zagotavlja, da ista vsebina vedno proizvede isti CID:

1. Priprava vsebine#

Ko dodate vsebino v IPFS, se najprej razčleni:

Majhne datoteke: Shranjene kot posamezni bloki
Velike datoteke: Razdeljene na koščke in organizirane v Merkle DAG (usmerjen acikličen graf)
Mape: Predstavljene kot DAG strukture, ki povezujejo datoteke

2. Proces zgoščenja#

Vsak kos vsebine gre skozi:

Serializacijo: Vsebina se oblikuje v skladu s svojim codecem
Zgoščenje: Kriptografska funkcija zgoščenja obdela serializirane podatke
Multihash ustvarjanje: Zgoščenje se ovije z informacijami o algoritmu in dolžini
CID sestavljanje: Različica, codec in multihash se kombinirajo

3. Merkle DAG struktura#

IPFS organizira vsebino v Merkle DAG, kjer:

Vsako vozlišče ima CID
Nadrejena vozlišča se sklicujejo na podrejena vozlišča prek CID-a
Spremembe v katerem koli vozlišču se širijo navzgor po drevesu
Celotne strukture je mogoče kriptografsko preveriti

Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Praktični primeri: Delo z CIDs#

Raziščimo, kako delati z CIDs v praksi z uporabo IPFS Ninja API:

Nalaganje vsebine in pridobitev 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

Pinanje obstoječe vsebine po CID#

Če že imate CID, ga lahko pinjate, da zagotovite razpoložljivost:

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

Dostop do vsebine prek CID#

Ko imate CID, lahko do vsebine dostopate prek različnih metod:

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

Najboljše prakse CID za razvijalce#

1. Vedno validirajte CIDs#

Pred uporabo CID v vaši aplikaciji potrdite njegov 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. Obravnavajte obe različici CID#

Vaša aplikacija bi morala delovati tako s CIDv0 kot s 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. Predpomnite CID preslikave#

Če pogosto ustvarjate CIDs, razmislite o predpomnjenju:

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. Uporabljajte smiselne opise#

Pri nalaganju vsebine vključite opisne metapodatke:

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

Pogosti primeri uporabe CID#

1. Uvajanje statičnih spletnih strani#

Uvajajte celotne spletne strani na IPFS in se nanje sklicujte prek 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;
};

Če želite izvedeti več o uvajanju spletnih strani, preverite naš vodič o tem, kako nalagati datoteke na IPFS.

2. Shranjevanje NFT metapodatkov#

Shranjujte NFT metapodatke nespremenljivo z uporabo 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. Distribucija vsebine#

Uporabite CIDs za porazdeljeno dostavo vsebine:

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

Razumevanje IPFS pinninga s CIDs#

CIDs so privzeto začasni — »pinjati« jih je treba, da ostanejo na voljo. Več o tem ključnem konceptu izveste v našem celovitem vodiču o tem, kaj je IPFS pinning.

Pri izbiri storitve IPFS pinninga razmislite o branju naše primerjave IPFS Ninja vs Pinata ali raziščite naš pregled najboljših IPFS pinning storitev, ki so na voljo danes.

Ustvarite svoj prvi CID v 30 sekundah#

Pripravljeni ustvariti svoj prvi CID? Tukaj je hiter primer z uporabo 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();

To bo vrnilo nekaj kot:

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

Za podrobnejše primere API-ja si oglejte naš vadnico IPFS upload API.

Zaključek#

CIDs so temelj sistema vsebinskega naslavljanja IPFS, ki zagotavlja nespremenljivo, preverljivo in decentralizirano identifikacijo vsebine. Razumevanje, kako delujejo — od tehničnih podrobnosti CIDv0 vs CIDv1 do praktičnih vzorcev implementacije — je bistveno za gradnjo robustnih decentraliziranih aplikacij.

Ključne ugotovitve:

CIDs edinstveno identificirajo vsebino, ne lokacij
CIDv0 zagotavlja maksimalno združljivost, CIDv1 ponuja prilagodljivost
Vsebinsko naslavljanje omogoča preverjanje in dedupliciranje
Pravilno ravnanje s CID je ključno za produkcijske aplikacije

Ne glede na to, ali shranjujete NFT metapodatke, uvajate decentralizirane spletne strani ali gradite sisteme distribucije vsebine, CIDs zagotavljajo zanesljiv temelj, ki ga potrebujete za resnično decentralizirane aplikacije.

Pripravljeni začeti pinning? Ustvarite brezplačen račun — 50 datotek, 1 GB shrambe, 2 GB pasovne širine/mesec. Brez kreditne kartice.