IPFS CID-d 2026: Sisuaadresseerimise juhend

Kui olete kunagi töötanud IPFS-iga (InterPlanetary File System), olete tõenäoliselt kohanud stringe nagu QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG või bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Need ei ole juhuslikud rumalused — need on Content Identifierid (CIDs), IPFS-i sisuaadressimissüsteemi selgroog.

CIDs mõistmine on oluline kõigile, kes ehitavad IPFS-i peale, olgu siis tegemist failide üleslaadimise, detsentraliseeritud rakenduste ehitamise või sisulevisüsteemide rakendamisega. See juhend lahkab kõike, mida peate teadma IPFS CIDs-i, kuidas sisuaadressimine töötab ja kuidas neid oma projektides kasutama hakata.

Genereeri CID 5 reaga (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

Selle CID-i saab taasesitada igaüks — käivita sama kood samade baitidega ükskõik kus maailmas ja saad sama stringi. See ongi sisuaadresseerimine.

Node.js vaste:

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

Mis on IPFS CID?#

Content Identifier (CID) on unikaalne sõrmejälg, mis esindab sisu tükki IPFS-il. Erinevalt traditsioonilistest veebi-URLidest, mis osutavad asukohale (nagu https://example.com/file.pdf), osutavad CIDid sisule endale, sõltumata sellest, kus seda hoitakse.

Mõelge sellele nii:

Asukohapõhine aadressimine: „Minge Peatänavale 123 ja küsige punast raamatut”
Sisupõhine aadressimine: „Leia raamat ISBN-iga 978-0-123456-78-9” (pole tähtis, milline raamatukogu seda omab)

CIDs töötavad sarnaselt — nad identifitseerivad sisu selle krüptograafilise räsi alusel, muutes sisu muutmatuks ja kontrollitavaks. Kui failis muutub kasvõi üks bait, muutub CID täielikult.

Miks on sisuaadressimine oluline#

Traditsiooniline veebi arhitektuur tugineb asukohapõhisele aadressimisele. Kui külastate https://example.com/image.jpg, usaldate, et:

Domeeni omanik ei ole sisu muutnud
Server on online ja kättesaadav
Sisu ei ole manipuleeritud

Sisuaadressimisega kasutades CIDs:

Muutmatus: CID garanteerib, et sisu ei ole muutunud
Detsentraliseerimine: Sisu saab tuua mis tahes IPFS-i sõlmest, millel see on
Kontroll: Saate krüptograafiliselt kontrollida, et saite õige sisu
Tõhusus: Identne sisu deduplitseeritakse automaatselt

CID anatoomia#

Lahkame tüüpilist CIDi, et mõista selle komponente:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Sisu räsi (Base32 kodeeritud)
  └─ Multibase eesliide (näitab kodeeringut)

CID sisaldab mitut tükki teavet:

1. Multibase eesliide#

Esimene märk näitab, kuidas CID on kodeeritud:

Q = Base58 kodeering (CIDv0)
b = Base32 kodeering (CIDv1)
f = Base16/heksadetsimaalne (CIDv1)
z = Base58 (CIDv1)

2. CID versioon#

CIDv0: Algab alati Qm-iga, kasutab SHA-256, piiratud DAG-PB codeciga
CIDv1: Paindlikum, toetab mitut räsifunktsiooni ja codeci

3. Multicodec#

Määrab, kuidas sisu on struktureeritud (DAG-PB, DAG-CBOR, toored baidid jne)

4. Multihash#

Sisu tegelik krüptograafiline räsi, sealhulgas:

Räsifunktsiooni identifikaator (tavaliselt SHA-256)
Räsi pikkus
Räsi digest

CIDv0 vs CIDv1: Erinevuste mõistmine#

IPFS on arenenud läbi kahe peamise CID versiooni, igal ühel on eraldi omadused:

CIDv0: Algupärane formaat#

CIDv0 CIDs algavad alati Qm-iga ja näevad välja nii:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Omadused:

Ainult Base58 kodeering
Ainult SHA-256 räsifunktsioon
Ainult DAG-PB (Protobuf) codec
46 märki pikk
Tagasiühilduv kõigi IPFS-i implementatsioonidega

Millal kasutada CIDv0:

Maksimaalne ühilduvus vanemate IPFS-i sõlmedega
Töötamine olemasolevate süsteemidega, mis ootavad Qm eesliidet
Failide salvestamine (kõige levinum kasutusjuht)

CIDv1: Tänapäevane standard#

CIDv1 CIDs on paindlikumad ja võivad välja näha nii:

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

Omadused:

Mitu kodeerimisformaati (Base32, Base58, Base16)
Toetus erinevatele räsifunktsioonidele (SHA-256, SHA-512, BLAKE2 jne)
Mitu codeci (Raw, DAG-CBOR, DAG-JSON jne)
Iseennast kirjeldav formaat
Tähetundetu Base32 kasutamisel

Millal kasutada CIDv1:

Uute rakenduste ehitamine
Vajadus tähetundetute identifikaatorite järele
Töötamine struktureeritud andmetega (JSON, CBOR)
Alternatiivsete räsifunktsioonide kasutamine

Versioonide vaheline konversioon#

Saate CIDe versioonide vahel konverteerida, säilitades sama sisu viite:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Kuidas sisuaadressimine töötab#

Sisuaadressimine IPFS-is järgib deterministlikku protsessi, mis tagab, et sama sisu toodab alati sama CIDi:

1. Sisu ettevalmistamine#

Kui lisate sisu IPFS-i, lagundatakse see esmalt:

Väikesed failid: Salvestatud üksikute plokkidena
Suured failid: Jagatud tükkideks ja korraldatud Merkle DAGis (suunatud atsükliline graaf)
Kataloogid: Esindatud DAG struktuuridena, mis viitavad failidele

2. Räsimisprotsess#

Iga sisu tükk läbib:

Serialiseerimise: Sisu vormindatakse vastavalt selle codecile
Räsimise: Krüptograafiline räsifunktsioon töötleb seerialiseeritud andmeid
Multihashi loomise: Räsi pakitakse algoritmi ja pikkuse teabega
CID koostamise: Versioon, codec ja multihash kombineeritakse

3. Merkle DAG struktuur#

IPFS korraldab sisu Merkle DAGis, kus:

Igal sõlmel on CID
Vanemsõlmed viitavad lapsesõlmedele CIDi kaudu
Muudatused mis tahes sõlmes levivad puus üles
Terveid struktuure saab krüptograafiliselt kontrollida

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

Praktilised näited: Töö CIDsidega#

Uurime, kuidas CIDsidega praktikas töötada, kasutades IPFS Ninja API-t:

Sisu üleslaadimine ja CID-i saamine#

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

Olemasoleva sisu kinnitamine CID-i alusel#

Kui teil on juba CID, saate selle kinnitada, et tagada saadavus:

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

Sisu juurdepääs CID kaudu#

Kui teil on CID, saate sisule juurde pääseda erinevate meetoditega:

// 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 parimad praktikad arendajatele#

1. Valideerige CIDs alati#

Enne CIDi kasutamist oma rakenduses valideerige selle formaat:

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. Käsitlege mõlemat CID versiooni#

Teie rakendus peaks töötama nii CIDv0 kui ka CIDv1-ga:

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. Hoidke CID kaardistused vahemällu#

Kui te genereerite CIDe sageli, kaaluge vahemälu kasutamist:

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. Kasutage mõtekaid kirjeldusi#

Sisu üleslaadimisel lisage kirjeldavad metaandmed:

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

Tavalised CID kasutusjuhud#

1. Staatilise veebisaidi juurutamine#

Juurutage terveid veebisaite IPFS-i ja viidake neile CIDi kaudu:

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

Et rohkem teada saada veebisaidi juurutamise kohta, vaadake meie juhendit selle kohta, kuidas laadida faile IPFS-i.

2. NFT metaandmete salvestamine#

Salvestage NFT metaandmed muutmatult, kasutades CIDsisid:

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. Sisu levitamine#

Kasutage CIDsid hajutatud sisu kohaletoimetamiseks:

// 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 pinninguga mõistmine koos CIDsidega#

CIDs on vaikimisi ajutised — need tuleb „kinnitada”, et need jääksid kättesaadavaks. Lisateavet selle olulise kontseptsiooni kohta leiate meie põhjalikust juhendist, mis on IPFS pinning.

IPFS pinningu teenuse valimisel kaaluge meie võrdluse IPFS Ninja vs Pinata lugemist või uurige meie ülevaadet parimatest IPFS pinningu teenustest, mis on tänapäeval saadaval.

Looge oma esimene CID 30 sekundi jooksul#

Kas olete valmis oma esimest CIDi looma? Siin on kiire näide, kasutades IPFS Ninja API-t:

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

See tagastab midagi sellist:

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

Üksikasjalikumate API näidete jaoks vaadake meie IPFS üleslaadimise API õpetust.

Järeldus#

CIDs on IPFS-i sisuaadressimissüsteemi alus, mis pakub muutmatut, kontrollitavat ja detsentraliseeritud sisuidentifitseerimist. Mõistmine, kuidas need töötavad — alates CIDv0 vs CIDv1 tehnilistest üksikasjadest kuni praktiliste rakendusmustriteni — on hädavajalik tugevate detsentraliseeritud rakenduste ehitamiseks.

Põhipunktid:

CIDs identifitseerivad sisu unikaalselt, mitte asukohti
CIDv0 pakub maksimaalset ühilduvust, CIDv1 pakub paindlikkust
Sisuaadressimine võimaldab kontrolli ja deduplitseerimist
Korrektne CID käsitsemine on tootmisrakenduste jaoks kriitiline

Olgu te NFT metaandmete salvestamisel, detsentraliseeritud veebisaitide juurutamisel või sisulevisüsteemide ehitamisel, CIDs pakuvad usaldusväärset alust, mida vajate tõeliselt detsentraliseeritud rakendusteks.

Kas olete valmis alustama kinnitamist? Loo tasuta konto — 50 faili, 1 GB salvestusruumi, 2 GB ribalaius/kuu. Krediitkaarti pole vaja.