· 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 на практиці, використовуючи API IPFS Ninja:

Завантаження вмісту та отримання 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 pinning з CIDs

CIDs за замовчуванням тимчасові — їх потрібно «закріпити», щоб вони залишалися доступними. Дізнайтеся більше про цю важливу концепцію в нашому всеосяжному посібнику про те, що таке IPFS pinning.

Вибираючи службу IPFS pinning, розгляньте можливість прочитати наше порівняння IPFS Ninja vs Pinata або вивчіть наш огляд найкращих служб IPFS pinning, доступних сьогодні.

Створіть свій перший CID за 30 секунд

Готові згенерувати свій перший CID? Ось швидкий приклад використання 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();

Це поверне щось схоже на:

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

Для більш детальних прикладів API див. наш туторіал API завантаження IPFS.

Висновок

CIDs є фундаментом системи адресації вмісту IPFS, забезпечуючи незмінну, перевіряну та децентралізовану ідентифікацію вмісту. Розуміння того, як вони працюють — від технічних деталей CIDv0 vs CIDv1 до практичних шаблонів реалізації — необхідне для побудови надійних децентралізованих додатків.

Ключові висновки:

  • CIDs унікально ідентифікують вміст, а не розташування
  • CIDv0 забезпечує максимальну сумісність, CIDv1 пропонує гнучкість
  • Адресація вмісту дозволяє перевірку та дедуплікацію
  • Правильна обробка CID має критичне значення для виробничих додатків

Чи зберігаєте ви метадані NFT, розгортаєте децентралізовані вебсайти, чи будуєте системи розповсюдження вмісту, CIDs забезпечують надійну основу, яка вам потрібна для дійсно децентралізованих додатків.

Готові почати pinning? Створіть безкоштовний обліковий запис — 50 файлів, 1 ГБ сховища, 2 ГБ трафіку/місяць. Без кредитної картки.

Share:
Назад до Блогу

Схожі статті

Усі статті »