· Nacho Coll · Guides  · 8 мин четене

IPFS CID обяснен: какво е и как работи адресирането на съдържание

Ясно техническо обяснение на IPFS Content Identifiers (CIDs). Как работи адресирането на съдържание, версии на CID и как да създадете първия си CID.

Ясно техническо обяснение на IPFS Content Identifiers (CIDs). Как работи адресирането на съдържание, версии на CID и как да създадете първия си CID.

Ако някога сте работили с IPFS (InterPlanetary File System), вероятно сте срещали низове като QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG или bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi. Това не са случайни безсмислици — това са Content Identifiers (CIDs), гръбнакът на системата за адресиране на съдържание на IPFS.

Разбирането на CIDs е от решаващо значение за всеки, който изгражда върху IPFS, независимо дали качвате файлове, изграждате децентрализирани приложения или внедрявате системи за разпространение на съдържание. Това ръководство ще разложи всичко, което трябва да знаете за IPFS CIDs, как работи адресирането на съдържание и как да започнете да ги използвате във вашите проекти.

IPFS Ninja

Какво е IPFS CID?

Content Identifier (CID) е уникален пръстов отпечатък, който представлява парче съдържание в IPFS. За разлика от традиционните уеб URL адреси, които сочат към местоположение (като https://example.com/file.pdf), CIDs сочат към самото съдържание, независимо къде се съхранява.

Мислете за това така:

  • Адресиране, базирано на местоположение: „Отидете на Главна улица 123 и поискайте червената книга”
  • Адресиране, базирано на съдържание: „Намерете книгата с ISBN 978-0-123456-78-9” (няма значение коя библиотека я има)

CIDs работят по подобен начин — идентифицират съдържанието въз основа на неговия криптографски хеш, правейки съдържанието неизменно и проверимо. Ако един единствен байт се промени във файла, CID се променя напълно.

Защо има значение адресирането на съдържание

Традиционната уеб архитектура разчита на адресиране, базирано на местоположение. Когато посетите https://example.com/image.jpg, се доверявате, че:

  1. Собственикът на домейна не е променил съдържанието
  2. Сървърът е онлайн и достъпен
  3. Съдържанието не е било манипулирано

С адресиране на съдържание с помощта на CIDs:

  1. Неизменност: CID гарантира, че съдържанието не се е променило
  2. Децентрализация: Съдържанието може да бъде извлечено от всеки IPFS възел, който го има
  3. Проверка: Можете криптографски да проверите, че сте получили правилното съдържание
  4. Ефективност: Идентичното съдържание автоматично се дедупликира

Анатомия на CID

Нека разложим типичен CID, за да разберем неговите компоненти:

bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
└─┬─┘└─────────────────┬─────────────────────────────────┘
  │                   │
  │                   └─ Хеш на съдържание (Base32 кодиран)
  └─ Multibase префикс (показва кодирането)

CID съдържа няколко информационни части:

1. Multibase префикс

Първият знак показва как е кодиран CID:

  • Q = Base58 кодиране (CIDv0)
  • b = Base32 кодиране (CIDv1)
  • f = Base16/шестнадесетично (CIDv1)
  • z = Base58 (CIDv1)

2. Версия на CID

  • CIDv0: Винаги започва с Qm, използва SHA-256, ограничен до DAG-PB кодек
  • CIDv1: По-гъвкав, поддържа множество хеш функции и кодеци

3. Multicodec

Указва как е структурирано съдържанието (DAG-PB, DAG-CBOR, сурови байтове и т.н.)

4. Multihash

Действителният криптографски хеш на съдържанието, включително:

  • Идентификатор на хеш функцията (обикновено SHA-256)
  • Дължина на хеша
  • Хеш дайджест

CIDv0 vs CIDv1: Разбиране на разликите

IPFS се е развил през две основни версии на CID, всяка с различни характеристики:

CIDv0: Оригиналният формат

CIDv0 CIDs винаги започват с Qm и изглеждат така:

QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG

Характеристики:

  • Само Base58 кодиране
  • Само SHA-256 хеш функция
  • Само DAG-PB (Protobuf) кодек
  • 46 символа дължина
  • Обратно съвместим с всички IPFS реализации

Кога да използвате CIDv0:

  • Максимална съвместимост с по-стари IPFS възли
  • Работа със съществуващи системи, които очакват Qm префикси
  • Съхранение на файлове (най-често срещаният случай на употреба)

CIDv1: Съвременният стандарт

CIDv1 CIDs са по-гъвкави и могат да изглеждат така:

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

Характеристики:

  • Множество формати на кодиране (Base32, Base58, Base16)
  • Поддръжка за различни хеш функции (SHA-256, SHA-512, BLAKE2 и т.н.)
  • Множество кодеци (Raw, DAG-CBOR, DAG-JSON и т.н.)
  • Самоописващ се формат
  • Нечувствителен към главни/малки букви при използване на Base32

Кога да използвате CIDv1:

  • Изграждане на нови приложения
  • Нужда от идентификатори, нечувствителни към главни букви
  • Работа със структурирани данни (JSON, CBOR)
  • Използване на алтернативни хеш функции

Конвертиране между версии

Можете да конвертирате CIDs между версии, докато запазвате същата референция към съдържание:

// CIDv0
const cidv0 = "QmYwAPJzv5CZsnA625s3Xf2nemtYgPpHdWEz79ojWnPbdG";

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

// Both reference the same content!

Как работи адресирането на съдържание

Адресирането на съдържание в IPFS следва детерминистичен процес, който гарантира, че едно и също съдържание винаги произвежда един и същ CID:

1. Подготовка на съдържанието

Когато добавяте съдържание към IPFS, то първо се разделя:

  • Малки файлове: Съхранени като единични блокове
  • Големи файлове: Разделени на парчета и организирани в Merkle DAG (насочен ацикличен граф)
  • Директории: Представени като DAG структури, които се свързват с файлове

2. Процес на хеширане

Всяко парче съдържание преминава през:

  1. Сериализация: Съдържанието се форматира според неговия кодек
  2. Хеширане: Криптографската хеш функция обработва сериализираните данни
  3. Multihash създаване: Хешът се обвива с информация за алгоритъм и дължина
  4. CID сглобяване: Версията, кодекът и multihash се комбинират

3. Merkle DAG структура

IPFS организира съдържанието в Merkle DAG, където:

  • Всеки възел има CID
  • Родителските възли референцират дъщерните възли чрез CID
  • Промените във всеки възел се разпространяват нагоре в дървото
  • Цели структури могат да бъдат криптографски проверени
Root CID: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi
├── file1.txt (QmHash1...)
├── file2.jpg (QmHash2...)
└── subdirectory/
    ├── file3.pdf (QmHash3...)
    └── file4.mp4 (QmHash4...)

Практически примери: Работа с CIDs

Нека проучим как да работим с CIDs на практика с помощта на IPFS Ninja API:

Качване на съдържание и получаване на 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

Пиниране на съществуващо съдържание по CID

Ако вече имате CID, можете да го пинирате, за да осигурите достъпност:

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

Достъп до съдържание чрез CID

След като имате CID, можете да достъпите съдържанието чрез различни методи:

// 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 за разработчици

1. Винаги валидирайте CIDs

Преди да използвате CID във вашето приложение, валидирайте неговия формат:

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. Обработвайте и двете версии на CID

Вашето приложение трябва да работи както с CIDv0, така и с 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. Кеширайте CID мапинги

Ако генерирате CIDs често, помислете за кеширане:

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. Използвайте смислени описания

При качване на съдържание, включете описателни метаданни:

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

Често срещани случаи на употреба на CID

1. Разполагане на статичен уебсайт

Разполагайте цели уебсайтове в IPFS и ги референцирайте чрез 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;
};

За да научите повече за разполагане на уебсайтове, разгледайте нашето ръководство за това как да качвате файлове в IPFS.

2. Съхранение на NFT метаданни

Съхранявайте NFT метаданни неизменно с помощта на 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. Разпространение на съдържание

Използвайте CIDs за разпределена доставка на съдържание:

// 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 пиниране с CIDs

CIDs са временни по подразбиране — трябва да бъдат „пинирани”, за да останат достъпни. Научете повече за тази решаваща концепция в нашето изчерпателно ръководство за това какво е IPFS пиниране.

При избор на IPFS пиниране услуга, помислете дали да прочетете нашето сравнение IPFS Ninja vs Pinata или проучете нашето резюме на най-добрите IPFS пиниране услуги, достъпни днес.

Създайте първия си CID за 30 секунди

Готови ли сте да генерирате първия си CID? Ето бърз пример с помощта на 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();

Това ще върне нещо подобно:

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

За по-подробни API примери, вижте нашия tutorial IPFS upload API.

Заключение

CIDs са основата на системата за адресиране на съдържание на IPFS, предоставяща неизменна, проверима и децентрализирана идентификация на съдържание. Разбирането на това как работят — от техническите детайли на CIDv0 vs CIDv1 до практическите модели на реализация — е от съществено значение за изграждането на здрави децентрализирани приложения.

Ключови изводи:

  • CIDs идентифицират съдържанието уникално, не местоположенията
  • CIDv0 осигурява максимална съвместимост, CIDv1 предлага гъвкавост
  • Адресирането на съдържание позволява проверка и дедупликация
  • Правилното боравене с CID е от решаващо значение за производствените приложения

Независимо дали съхранявате NFT метаданни, разполагате децентрализирани уебсайтове или изграждате системи за разпространение на съдържание, CIDs предоставят надеждната основа, която ви е необходима за наистина децентрализирани приложения.

Готови ли сте да започнете пиниране? Създайте безплатен акаунт — 50 файла, 1 GB съхранение, 2 GB честотна лента/месец. Без кредитна карта.

Share:
Назад към Блога

Свързани статии

Вижте всички статии »