Міграція з Bitly на Elido: технічний посібник

Міграція інфраструктури посилань - це справа з високими ставками. Кожне коротке посилання, яке ви коли-небудь друкували, вставляли у футер листа або наносили на QR-код, тепер є залежністю. Необережний перехід призведе до помилок 404 для значної частини вхідного трафіку протягом тижнів, перш ніж хтось це помітить.

Цей посібник охоплює перехід з Bitly на Elido. Припускається, що ви вже вирішили змінити платформу - зазвичай через резидентність даних в ЄС, чистіший інтерфейс безкоштовного тарифу, можливість перепродажу під власним брендом або доступ до API, який не потребує тарифу Premium ($199/місяць щорічно або $300/місяць щомісяця станом на травень 2026 року). Якщо ви все ще оцінюєте варіанти, сторінка порівняння за адресою /compare/vs-bitly буде кращою відправною точкою.

Що насправді потрібно мігрувати#

Переносяться три речі; ніщо інше на рівні протоколів не має значення.

1. Активні короткі посилання. Слаг, цільова URL-адреса, необов’язкові теги та папки, а також кастомний домен (якщо є).
2. DNS кастомного домену. Запис CNAME, що вказує на edge-вузол Bitly, має вказувати на Elido.
3. Історія кліків. Агреговані лічильники Bitly - не сирі події (вони не підлягають експорту).

Все інше - дашборди Bitly Sights, брендовані QR-коди, конфігурації глибоких посилань (deep links) - це налаштування з нуля на Elido, а не міграція. Не намагайтеся їх портувати; створіть їх заново на новому стеку.

Крок 1: Інвентаризація#

Bitly обмежує експорт історичних даних залежно від тарифного плану. Експорт CSV через панель керування працює приблизно до 10 000 посилань; після цього виникають таймаути або проблеми з пагінацією. Для більших обсягів використовуйте API безпосередньо:

curl -H "Authorization: Bearer $BITLY_TOKEN" \
  "https://api-ssl.bitly.com/v4/groups/$GROUP_GUID/bitlinks?size=100"

Використовуйте пагінацію через URL pagination.next у кожній відповіді. Максимальний розмір сторінки - 100. Зберігайте результати у форматі JSONL - одне посилання на рядок - щоб ви могли відновити процес, якщо експорт зупиниться.

Те, що вам потрібно з кожного рядка:

• link - повне коротке посилання (https://bit.ly/abc або https://yourdomain.com/abc)
• long_url - цільова адреса
• tags, archived, created_at
• link_clicks (загальна кількість за весь час) - єдина історія кліків, яку ви отримаєте від Bitly

Відфільтруйте архівовані посилання, якщо у вас немає причин їх залишати. Більшість команд виявляють, що 30–50% їхнього інвентарю - це «мертві» посилання (старі кампанії, разові публікації), і міграція - найкращий час, щоб позбутися цього мотлоху.

Крок 2: Попереднє створення на Elido#

Перш ніж змінювати DNS, зарезервуйте кожне посилання на Elido під тим самим кастомним доменом і слагом.

Для великих обсягів використовуйте links.bulkCreate замість створення кожного посилання окремо. Вам знадобиться ID вашого робочого простору Elido та числовий ID домену (спочатку знайдіть домен за допомогою workspaceDomains.list(workspaceId)):

import { ElidoApi } from "@elido/sdk";

const api = new ElidoApi({ apiKey: process.env.ELIDO_API_KEY! });

// Resolve your custom domain's numeric ID once, before the import loop
const { items: domains } = await api.workspaceDomains.list(WORKSPACE_ID);
const domain = domains.find((d) => d.hostname === "links.yourbrand.com");
if (!domain) throw new Error("Domain not registered in workspace");

// Batch the JSONL into chunks of 100 (the bulk endpoint maximum)
async function migrateChunk(rows: BitlyRow[]) {
  return api.links.bulkCreate(
    WORKSPACE_ID,
    {
      domain_id: domain.id,
      links: rows.map((row) => ({
        slug: row.slug,
        destination_url: row.long_url,
        tags: [
          ...row.tags,
          `bitly-migrated`, // tag for filtering in analytics
        ],
        title: row.title ?? undefined,
      })),
    },
    { idempotencyKey: `mig-batch-${rows[0].slug}` },
  );
}

Ендпоінт links.bulkCreate (POST /v1/workspaces/{workspace_id}/links/bulk) приймає до 100 посилань за один виклик і повертає статус успіху/помилки для кожного елемента, тому часткова помилка не перериває всю партію. Для імпорту поодиноких посилань links.create(workspaceId, input, { idempotencyKey }) приймає ті самі поля domain_id / slug / destination_url / tags та необов’язковий ключ ідемпотентності, щоб можна було безпечно відновити роботу скрипта.

Кілька речей, які варто знати перед запуском скрипта:

• Спочатку реєстрація домену. domain_id у тілі запиту має посилатися на домен, уже зареєстрований у вашому робочому просторі. Зареєструйте та підтвердьте домен через процес кастомних доменів перед початком імпорту. Домен ще не обов'язково має бути активним - ви можете зареєструвати його в Elido до перемикання DNS.
• Ліміти тарифних планів. Elido застосовує ліміти на кількість посилань на рівні робочого простору залежно від тарифу. Для попереднього створення 100 000 посилань потрібен план Business.
• Ліміти частоти запитів. Масове створення підпадає під ті самі ліміти робочого простору, що й створення окремих посилань. Міграція 50 000 посилань займає приблизно 10 хвилин, якщо ви обробляєте по 100 посилань за виклик із помірним паралелізмом. Використовуйте послідовне виконання або невелику кількість паралельних процесів з одного раннера, щоб лог аудиту відображав чистий блок імпорту.

Крок 3: Переспрямування кастомного домену#

Це момент перемикання. Все, що було до цього, можна скасувати; все, що після - працює наживо.

Зменште TTL для існуючого CNAME Bitly принаймні за 24 години до вікна перемикання:

links.yourbrand.com.  300  IN  CNAME  cname.bitly.com.

Якщо ваш TTL роками становив 86400, «зменшення TTL» - це 24-годинне очікування, а не п’ятихвилинне завдання. Врахуйте це у плані.

Коли відкриється вікно змін, змініть ціль:

links.yourbrand.com.  300  IN  CNAME  edge.elido.me.

Edge-вузол Elido використовує автоматичний TLS на вимогу. Перший запит після розповсюдження DNS ініціює видачу сертифіката Let's Encrypt - зазвичай затримка для цього єдиного запиту становить 1–3 секунди, після чого сертифікат кешується, а наступні запити обслуговуються з edge-вузла в регіоні ЄС із затримкою в кілька мілісекунд. Сертифікат видається автоматично через автоматичний TLS на вимогу; ручний крок запиту сертифіката відсутній.

Перевірте за допомогою dig з кількох мереж, перш ніж оголошувати перемикання завершеним. Розповсюдження DNS відбувається нерівномірно; перевірка лише з вашого ноутбука означає, що ви перевірили тільки один резолвер.

Крок 4: Узгодження історії кліків#

Bitly не експортує сирі події кліків. Не плануйте час на «імпорт історії» - це неможливо, і будь-який інструмент, який це обіцяє, просто зчитує агреговані дані та називає їх подіями.

Те, що ви отримуєте - це лічильник link_clicks для кожного посилання з експорту API Bitly. Збережіть його там, де ви зможете об’єднати його з інвентарем посилань Elido - в окремому стовпці набору даних Metabase або в тегу, якщо ви хочете бачити це безпосередньо. Elido починає відлік із нуля після перемикання.

Для рівня звітності формула виглядає так: total_clicks = elido_clicks + bitly_lifetime_clicks. API аналітики надає дані про кліки Elido за адресою /v1/analytics/workspaces/{workspace_id}/timeseries; запит у Metabase або Hex на 20 рядків об’єднає ці два числа, якщо ви зберегли базовий показник Bitly.

Якщо вам потрібна детальна історична аналітика - розподіл за географією по місяцях, тренди реферерів - ці дані не повернуться. Будуйте звіти на основі сирого логу подій Elido у майбутньому; міграція - це чітка межа розподілу даних.

П'ять пасток, які дають про себе знати на другому тижні#

1. Жорстко закодовані посилання bit.ly у статичних ресурсах. PDF-файли, друковані матеріали, фрагменти коду в вітальних листах. Вони вказують на домен Bitly, а не на ваш кастомний. Вони продовжуватимуть працювати, поки ви тримаєте акаунт Bitly активним; вони зламаються в момент скасування підписки. Або залиште безкоштовний акаунт Bitly як «цвинтар» лише для редиректів, або змиріться з втратою і не скасовуйте акаунт принаймні протягом року.

2. Подвійний редирект CDN. Якщо ви використовуєте Cloudflare для свого домену в режимі проксі (помаранчева хмара), рукостискання SSL з Elido може конфліктувати з Universal SSL від Cloudflare. Встановіть налаштування SSL у Cloudflare на "Full (Strict)" і видаліть будь-які Page Rules, які посилалися на стару ціль Bitly. Або тимчасово переведіть запис у режим «сірої хмари» на час вікна перемикання.

3. Обрізання UTM-міток при експорті. Bitly іноді показує скорочену цільову URL-адресу в панелі керування, але зберігає канонічну повну адресу. Експорт CSV зазвичай містить повну URL-адресу; перегляд у панелі керування може її не містити. Якщо ви будете збирати дані з панелі керування замість використання API, ви втратите UTM-мітки. Завжди використовуйте API.

4. Ліміти API Bitly на читання. API Bitly агресивно обмежує частоту запитів (throttle) на GET /bitlinks для акаунтів з великим обсягом даних. Наївне послідовне зчитування 1 мільйона посилань може зайняти дні. Використовуйте паралельну пагінацію (4–8 паралельних процесів), але стежте за помилками 429; робіть паузу (back off), якщо вони виникають.

5. Область видимості на рівні акаунта Bitly проти рівня групи. Групи Bitly - це не робочі простори. Один акаунт Bitly може володіти кількома групами, кожна з яких має власну конфігурацію кастомних доменів. Якщо ваша команда роками додавала домени в різні групи, експорт має охоплювати всі групи, а не лише стандартну. Пропустіть групу - і цей домен не буде мігровано.

Комплаєнс: чому більшість команд насправді змінюють платформу#

Міграція зазвичай зумовлена вимогами комплаєнсу, а не функціональністю. Сценарій такий:

• DPO позначає Bitly як субпроцесора, що базується в США; використання на основі Data Privacy Framework отримує зауваження під час аудиту.
• Відділ закупівель просить список субпроцесорів; у Bitly він налічує понад 20 вендорів.
• BAA у плані Premium ($300/місяць при щомісячній оплаті або $199/місяць при річній підписці станом на травень 2026 року - перевірте поточні ціни) стає вимогою для клієнтів, пов’язаних зі сферою охорони здоров’я, і перехід на вищий тариф стає тригером.

Хостинг Elido в ЄС за замовчуванням - події кліків маршрутизуються через регіон ЄС, а US East та Азійсько-Тихоокеанський регіон доступні як опціональні регіони для тарифу Business+. Список субпроцесорів налічує п’ять вендорів і опублікований за адресою /legal/subprocessors. Сертифікат ISO 27001 актуальний; SOC 2 Type II перебуває в процесі аудиту. BAA доступний на тарифі Business+. Schrems II не є проблемою в стандартній конфігурації, оскільки дані не залишають EEA, якщо тільки робочий простір явно не прив’язаний до регіону за межами ЄС.

Якщо рушієм є комплаєнс, план міграції має включати порівняльну діаграму потоків даних: де події кліків жили раніше і де вони живуть зараз. Ця діаграма - це те, що захоче бачити ваш аудитор під час наступної перевірки.

Self-host як альтернатива#

Для команд, чия політика безпеки виключає використання будь-яких SaaS-скорочувачів - фінансові послуги, державний сектор, охорона здоров’я - Elido надає Helm-чарт під ліцензією Apache 2.0. Ті самі бінарні файли, що працюють у регіоні ЄС, розгортаються у вашому VPC, використовують ваш KMS для шифрування, без сторонніх субпроцесорів. Міграція виглядає ідентично, за винятком кроку 3 (DNS), де вказується ваш внутрішньокластерний ingress замість edge.elido.me.

Інструкція з self-host охоплює встановлення через Helm, налаштування секретів та підключення автентифікації Kratos; розгортання «з нуля» на існуючому кластері k8s займає приблизно півдня.

Робочий процес розробника після міграції#

Після переходу на Elido API стає основним інтерфейсом для будь-якої команди, що створює більше кількох посилань на тиждень. Специфікація OpenAPI 3.1 доступна за адресою /help; пакет @elido/sdk охоплює API для TypeScript, а Go SDK постачається в packages/sdk-go.

Для робочих процесів на основі агентів відкритий MCP-сервер підключає Elido до Claude, Cursor або будь-якого клієнта, що підтримує MCP:

{
  "mcpServers": {
    "elido": {
      "command": "npx",
      "args": ["-y", "@elido/mcp-server"],
      "env": { "ELIDO_API_KEY": "elido_pk_..." }
    }
  }
}

Тільки для читання за замовчуванням - агенти можуть запитувати аналітику та шукати посилання без права запису. Надання прав на запис - це свідоме налаштування для кожного окремого робочого простору.

Фінальний чек-лист перед перемиканням#

• Токен API Bitly має доступ до всіх груп, а не лише до стандартної
• Інвентар експортовано у форматі JSONL, архівовані посилання відфільтровано, кількість звірена з панеллю керування Bitly
• Усі слаги попередньо створені на Elido під правильним кастомним доменом; скрипт повернув 100% успіху під час тестового запуску (dry-run)
• Кастомний домен зареєстровано та підтверджено в робочому просторі Elido перед зміною DNS
• TTL DNS для існуючого CNAME Bitly зменшено до 300с принаймні за 24 години до перемикання
• Режим проксі Cloudflare та налаштування SSL перевірено на сумісність із edge-вузлом Elido
• Загальна кількість кліків Bitly за весь час зафіксована в годину перемикання та збережена для звітності
• Принаймні одне тестове посилання надруковано та відскановано для підтвердження повноцінної роботи
• Акаунт Bitly заплановано залишити активним протягом 90 днів після перемикання як страховку для жорстко закодованих посилань bit.ly

Якщо все зроблено правильно, зміни для користувачів будуть непомітними. Якщо ж помилитися - доведеться два тижні відповідати на тікети «чому bit.ly не працює?» від тих, хто не розуміє, що це не їхня провина.

Технічна робота зрозуміла. Дисципліна полягає у підготовці.

Схоже у блозі#

• Міграція з Bitly без розриву посилань: збірник сценаріїв помилок
• Міграція з Rebrandly: передача брендованого домену без втрати слагів
• Резидентність даних в ЄС для маркетингових інструментів: що насправді запитує ваш DPO
• Налаштування брендованих коротких посилань: оберіть домен, запустіть за вечір