IPFS CID 2026: Turinio adresavimo vadovas

Jei kada nors dirbote su IPFS (InterPlanetary File System), tikriausiai susidūrėte su tokiomis eilutėmis kaip QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG arba bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Tai nėra atsitiktinė nesąmonė — tai yra Content Identifiers (CIDs), IPFS turinio adresavimo sistemos stuburas.

CIDs supratimas yra labai svarbus kiekvienam, kuris kuria ant IPFS, nesvarbu, ar jūs įkeliate failus, kuriate decentralizuotas programas, ar diegiate turinio platinimo sistemas. Šis vadovas paaiškins viską, ką jums reikia žinoti apie IPFS CIDs, kaip veikia turinio adresavimas ir kaip pradėti naudoti juos savo projektuose.

Sugeneruokite CID per 5 eilutes (Python)#

Štai kaip patys galite sugeneruoti CID:

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

Šį CID gali atkurti bet kas — paleiskite iš naujo su tais pačiais baitais bet kur pasaulyje ir gausite tą pačią eilutę. Tai ir yra turinio adresavimas.

Node.js atitikmuo:

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...

Kas yra IPFS CID?#

Content Identifier (CID) yra unikalus pirštų atspaudas, kuris reprezentuoja turinio gabalą IPFS. Skirtingai nuo tradicinių žiniatinklio URL adresų, kurie nukreipia į vietą (kaip https://example.com/file.pdf), CIDs nukreipia į patį turinį, nepriklausomai nuo to, kur jis saugomas.

Pagalvokite apie tai taip:

Adresavimas pagal vietą: „Eikite į Pagrindinę gatvę 123 ir paprašykite raudonos knygos”
Adresavimas pagal turinį: „Raskite knygą su ISBN 978-0-123456-78-9” (nesvarbu, kuri biblioteka ją turi)

CIDs veikia panašiai — jie identifikuoja turinį pagal jo kriptografinę hash reikšmę, todėl turinys tampa nekeičiamas ir patikrinamas. Jei pasikeičia net vienas baitas faile, CID visiškai pasikeičia.

Kodėl turinio adresavimas svarbus#

Tradicinė žiniatinklio architektūra remiasi adresavimu pagal vietą. Kai apsilankote https://example.com/image.jpg, jūs pasitikite, kad:

Domeno savininkas nepakeitė turinio
Serveris yra internete ir prieinamas
Turinys nebuvo manipuliuojamas

Naudojant turinio adresavimą su CIDs:

Nekeičiamumas: CID garantuoja, kad turinys nepasikeitė
Decentralizacija: Turinį galima gauti iš bet kurio IPFS mazgo, kuris jį turi
Patikrinimas: Galite kriptografiškai patikrinti, kad gavote tinkamą turinį
Efektyvumas: Identiškas turinys automatiškai dedupliuojamas

CID anatomija#

Suskaidykime tipišką CID, kad suprastume jo komponentus:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Turinio hash (Base32 koduotas)
  └─ Multibase priešdėlis (nurodo kodavimą)

CID turi keletą informacijos dalių:

1. Multibase priešdėlis#

Pirmasis simbolis nurodo, kaip yra koduotas CID:

Q = Base58 kodavimas (CIDv0)
b = Base32 kodavimas (CIDv1)
f = Base16/šešioliktainis (CIDv1)
z = Base58 (CIDv1)

2. CID versija#

CIDv0: Visada prasideda Qm, naudoja SHA-256, apribota DAG-PB codec
CIDv1: Lankstesnis, palaiko daugybę hash funkcijų ir codecs

3. Multicodec#

Nurodo, kaip turinys yra struktūrizuotas (DAG-PB, DAG-CBOR, neapdoroti baitai ir t. t.)

4. Multihash#

Faktinis kriptografinis turinio hash, įskaitant:

Hash funkcijos identifikatorių (paprastai SHA-256)
Hash ilgį
Hash digest

CIDv0 vs CIDv1: Skirtumų supratimas#

IPFS išsivystė per dvi pagrindines CID versijas, kiekviena su savitomis savybėmis:

CIDv0: Originalus formatas#

CIDv0 CIDs visada prasideda Qm ir atrodo taip:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Savybės:

Tik Base58 kodavimas
Tik SHA-256 hash funkcija
Tik DAG-PB (Protobuf) codec
46 simbolių ilgio
Suderinamas su visomis IPFS realizacijomis

Kada naudoti CIDv0:

Maksimalus suderinamumas su senesniais IPFS mazgais
Darbas su esamomis sistemomis, kurios tikisi Qm priešdėlių
Failų saugojimas (dažniausias naudojimo atvejis)

CIDv1: Modernus standartas#

CIDv1 CIDs yra lankstesni ir gali atrodyti taip:

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

Savybės:

Keli kodavimo formatai (Base32, Base58, Base16)
Palaiko skirtingas hash funkcijas (SHA-256, SHA-512, BLAKE2 ir t. t.)
Keli codecs (Raw, DAG-CBOR, DAG-JSON ir t. t.)
Save aprašantis formatas
Nejautrus didžiosioms/mažosioms raidėms naudojant Base32

Kada naudoti CIDv1:

Naujų programų kūrimas
Reikia identifikatorių, kurie nejautrūs raidžių dydžiui
Darbas su struktūrizuotais duomenimis (JSON, CBOR)
Naudoti alternatyvias hash funkcijas

Konversija tarp versijų#

CIDs galite konvertuoti tarp versijų išlaikydami tą pačią turinio nuorodą:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Kaip veikia turinio adresavimas#

Turinio adresavimas IPFS seka deterministinį procesą, kuris užtikrina, kad tas pats turinys visada generuoja tą patį CID:

1. Turinio paruošimas#

Kai pridedate turinį prie IPFS, jis pirmiausia išardomas:

Maži failai: Saugomi kaip atskiri blokai
Dideli failai: Padalinti į gabalus ir organizuoti į Merkle DAG (nukreiptas aciklinis grafikas)
Katalogai: Atvaizduojami kaip DAG struktūros, kurios jungia su failais

2. Hash procesas#

Kiekviena turinio dalis pereina:

Serializaciją: Turinys formatuojamas pagal jo codec
Hash: Kriptografinė hash funkcija apdoroja serializuotus duomenis
Multihash kūrimas: Hash apvyniojamas algoritmo ir ilgio informacija
CID sudarymas: Versija, codec ir multihash sujungiami

3. Merkle DAG struktūra#

IPFS organizuoja turinį Merkle DAG, kur:

Kiekvienas mazgas turi CID
Tėviniai mazgai per CID nurodo dukterinius mazgus
Pakeitimai bet kuriame mazge sklinda medžiu aukštyn
Visos struktūros gali būti kriptografiškai patikrintos

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

Praktiniai pavyzdžiai: Darbas su CIDs#

Panagrinėkime, kaip dirbti su CIDs praktikoje naudojant IPFS Ninja API:

Turinio įkėlimas ir CID gavimas#

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

Esamo turinio pin’inimas pagal CID#

Jei jau turite CID, galite jį pin’inti, kad užtikrintumėte prieinamumą:

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

Prieiga prie turinio per CID#

Kai turite CID, galite pasiekti turinį per įvairius metodus:

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

CID geriausi praktikos kūrėjams#

1. Visada validuokite CIDs#

Prieš naudodami CID jūsų programoje, patikrinkite jo 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. Tvarkykite abi CID versijas#

Jūsų programa turėtų veikti tiek su CIDv0, tiek su 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. Kaupkite CID atvaizdavimus#

Jei dažnai generuojate CIDs, apsvarstykite kaupimą:

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. Naudokite prasmingus aprašymus#

Įkeliant turinį, įtraukite aprašomuosius metaduomenis:

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

Įprasti CID naudojimo atvejai#

1. Statinių svetainių diegimas#

Diekite ištisas svetaines į IPFS ir nurodykite jas pagal 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;
};

Norėdami sužinoti daugiau apie svetainių diegimą, peržiūrėkite mūsų vadovą apie kaip įkelti failus į IPFS.

2. NFT metaduomenų saugojimas#

Saugokite NFT metaduomenis nekeičiamai naudodami 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. Turinio platinimas#

Naudokite CIDs paskirstytam turinio pristatymui:

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

IPFS pinning supratimas su CIDs#

CIDs pagal numatytuosius nustatymus yra laikini — jie turi būti „pinami”, kad išliktų prieinami. Sužinokite daugiau apie šią svarbią koncepciją mūsų išsamiame vadove apie tai, kas yra IPFS pinning.

Renkantis IPFS pinning paslaugą, apsvarstykite galimybę perskaityti mūsų palyginimą IPFS Ninja vs Pinata arba peržiūrėkite mūsų geriausių IPFS pinning paslaugų apžvalgą.

Sukurkite pirmąjį savo CID per 30 sekundžių#

Pasiruošę sukurti pirmąjį savo CID? Štai greitas pavyzdys naudojant 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();

Tai grąžins kažką panašaus į:

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

Daugiau išsamių API pavyzdžių rasite mūsų IPFS įkėlimo API vadove.

Išvada#

CIDs yra IPFS turinio adresavimo sistemos pamatas, suteikiantis nekeičiamą, patikrinamą ir decentralizuotą turinio identifikavimą. Suprasti, kaip jie veikia — nuo CIDv0 vs CIDv1 techninių detalių iki praktinių diegimo modelių — yra būtina kuriant tvirtas decentralizuotas programas.

Pagrindinės išvados:

CIDs unikaliai identifikuoja turinį, ne vietas
CIDv0 suteikia maksimalų suderinamumą, CIDv1 siūlo lankstumą
Turinio adresavimas leidžia patikrinimą ir dedupliciją
Tinkamas CID tvarkymas yra labai svarbus gamybinėms programoms

Nesvarbu, ar saugote NFT metaduomenis, diegiate decentralizuotas svetaines, ar kuriate turinio platinimo sistemas, CIDs suteikia patikimą pagrindą, kurio jums reikia tikrai decentralizuotoms programoms.

Pasiruošę pradėti pin’inti? Sukurkite nemokamą paskyrą — 50 failų, 1 GB saugyklos, 2 GB pralaidumo/mėn. Be kredito kortelės.