Більшість платформ документації поставляються як стек. Ви отримуєте Node.js-додаток, базу даних PostgreSQL, кеш Redis, кластер Elasticsearch для пошуку та зворотний проксі Nginx, щоб зв’язати все разом. П’ять сервісів, п’ять точок відмови, п’ять речей для моніторингу, патчінгу та оновлення.

DocPlatform поставляється як один файл. Завантажте, запустіть, готово.

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

Типовий стек документації

Подивімось, що ви насправді розгортаєте, коли налаштовуєте сучасну платформу документації:

┌─────────────┐
│   Nginx     │  ← зворотний проксі, термінація TLS
├─────────────┤
│   Node.js   │  ← сервер додатку
├─────────────┤
│  PostgreSQL │  ← зберігання контенту
├─────────────┤
│    Redis    │  ← кеш сесій, черга завдань
├─────────────┤
│Elasticsearch│  ← повнотекстовий пошук
└─────────────┘

Це п’ять процесів, кожен зі своїми конфігураційними файлами, вимогами до версій та режимами відмов. Docker Compose допомагає керувати оркестрацією, але не зменшує площу атаки. Вам все ще потрібно:

  • Моніторити кожен сервіс на аварії та використання ресурсів
  • Запускати міграції бази даних при оновленнях
  • Налаштовувати розміри купи Elasticsearch та параметри індексів
  • Обробляти політики витіснення Redis при заповненні пам’яті
  • Ротувати журнали Nginx та оновлювати TLS-сертифікати

Для компанії з Fortune 500 із платформенною командою це рутина. Для стартапу з 10 осіб, що просто хоче внутрішню документацію, це накладні витрати без кінця.

Як виглядає один бінарний файл

Ось розгортання DocPlatform:

┌──────────────────────────┐
│      docplatform          │  ← один бінарний файл на Go
│  ┌────────┐ ┌──────────┐ │
│  │ SQLite │ │  Bleve   │ │
│  │  (БД)  │ │ (пошук)  │ │
│  └────────┘ └──────────┘ │
└──────────────────────────┘

Один бінарний файл. Одна директорія даних. SQLite обробляє зберігання контенту, сесії та конфігурацію. Bleve обробляє повнотекстовий пошук. Обидві — вбудовані бібліотеки, скомпільовані безпосередньо в бінарний файл — жодних зовнішніх процесів, жодних мережевих викликів між сервісами.

Встановлення займає 30 секунд:

curl -fsSL https://get.valoryx.org | sh
docplatform serve

Ось і все. Жодного docker-compose up, жодної ініціалізації бази даних, жодних змінних середовища для рядків підключення. Бінарний файл створює директорію даних при першому запуску та починає обслуговувати на порті 3000.

Більше варіантів встановлення див. у посібнику зі встановлення.

Чому Go робить це можливим

Ми обрали Go саме тому, що він уможливлює цю архітектуру. Важливі три властивості:

Статична компіляція

Go компілюється в один статично зв’язаний бінарний файл. Жодних залежностей середовища виконання, жодних спільних бібліотек, жодного JVM, жодного node_modules. Бінарний файл працює на голому сервері Linux без нічого іншого встановленого.

# Крос-компіляція для Linux з будь-якої ОС
GOOS=linux GOARCH=amd64 go build -o docplatform ./cmd/server/

Одна ця команда створює бінарний файл, який ви можете scp на сервер і запустити. Порівняйте це з розгортанням Node.js-додатку, де потрібно встановити Node, запустити npm install, сподіватися, що нативні залежності правильно скомпілюються на цільовій архітектурі, та налаштувати менеджер процесів.

Goroutine для конкурентності

Платформа документації повинна одночасно обробляти конкурентні запити (перегляди сторінок, пошукові запити, збереження з редактора), виконувати фонові завдання (git sync, індексація пошуку) та керувати WebSocket-з’єднаннями (спільна робота в реальному часі).

Goroutine в Go роблять це дешевим. Кожне WebSocket-з’єднання отримує власну goroutine, що коштує приблизно 2 КБ пам’яті. Node.js-серверу для обробки тих самих з’єднань потрібно керувати ними на одному event loop або перекладати на worker threads зі складністю спільної пам’яті.

Рушій git sync, що опитує та узгоджує зміни між веб-редактором і git-репозиторіями, працює як набір goroutine в тому ж процесі. Жодного окремого worker-сервісу, жодної черги завдань, жодного Redis.

Вбудовані бази даних

І SQLite, і Bleve написані на C та Go відповідно, і обидві компілюються безпосередньо в бінарний файл через cgo (SQLite) та чистий Go (Bleve). Це означає:

  • Жодного серверу бази даних для встановлення, налаштування чи моніторингу
  • Жодної мережевої затримки між додатком і його даними
  • Резервні копії — це копіювання файлів: cp data.db data.db.bak
  • Оновлення автоматично зберігають дані — новий бінарний файл читає старі файли даних

SQLite обробляє мільярди рядків у продакшені в компаніях, значно більших за нашу. Для платформи документації, що обслуговує сотні конкурентних користувачів, цього більш ніж достатньо.

Операційна перевага

Підхід одного бінарного файлу дає дивіденди в операціях:

Оновлення — це заміна одного файлу. Зупиніть старий бінарний файл, скопіюйте новий, запустіть. Жодних міграцій бази даних — додаток обробляє зміни схеми при запуску.

Резервні копії — це копіювання двох файлів: бази даних SQLite та індексу Bleve. Або лише бази даних — пошуковий індекс можна перебудувати з контенту.

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

Використання ресурсів передбачуване. Один процес, один об’єм пам’яті. Жодних несподіваних стрибків пам’яті від JVM-купи Elasticsearch чи Redis, що накопичує ключі.

Площа безпеки мінімальна. Один бінарний файл, один порт для прослуховування. Жодної міжсервісної комунікації для захисту, жодного Redis, відкритого на мережевому порті, жодного кластера Elasticsearch з власним рівнем автентифікації. Див. нашу документацію з безпеки для повної моделі.

Компроміси, які ми приймаємо

Ця архітектура має обмеження, і ми чесні щодо них:

Лише вертикальне масштабування. SQLite працює на одній машині. Ви не можете розподілити базу даних між кластером. Для більшості випадків використання документації — навіть великих із тисячами сторінок — один сучасний сервер легко справляється з навантаженням. Але якщо вам потрібне горизонтальне масштабування між центрами обробки даних, це не та архітектура.

Один writer для SQLite. SQLite підтримує конкурентне читання, але серіалізує записи. На практиці платформи документації важкі на читання (багато переглядів сторінок, мало редагувань), тому це рідко стає вузьким місцем. Але команда з 200 людей, що одночасно зберігають сторінки, побачить деяку конкуренцію за запис.

Немає заміни компонентів. Ви не можете замінити Bleve на Elasticsearch, якщо хочете більш просунуті функції пошуку. Пошуковий рушій вбудований, а не замінний. Ми вважаємо, що компроміс вартий того — Bleve підтримує стемінг, нечітке зіставлення та підсилення полів, що покриває потреби пошуку документації.

Приклади розгортання

Один бінарний файл працює скрізь, де може працювати процес Linux/macOS/Windows:

Bare metal або VM:

# Завантажте, запустіть, готово
curl -fsSL https://get.valoryx.org | sh
docplatform serve --port 3000

Systemd-сервіс:

[Unit]
Description=DocPlatform
After=network.target

[Service]
ExecStart=/opt/docplatform/bin/docplatform serve
WorkingDirectory=/opt/docplatform
Restart=always

[Install]
WantedBy=multi-user.target

Docker (якщо потрібно):

FROM scratch
COPY docplatform /docplatform
ENTRYPOINT ["/docplatform", "serve"]

Зверніть увагу на FROM scratch — оскільки бінарний файл не має залежностей, Docker-образ містить буквально нічого, крім самого бінарного файлу. Розмір образу менше 30 МБ.

Детальніше про варіанти розгортання див. у посібнику з розгортання бінарного файлу.

Що це означає для вашої команди

Кожен додатковий сервіс у вашому стеку — це сервіс, який хтось повинен розуміти, моніторити та виправляти о 2 годині ночі, коли він зламається. Інфраструктура документації повинна відійти на задній план — це те, що ви налаштовуєте один раз і забуваєте.

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

Встановіть DocPlatform за 30 секунд і переконайтеся самі. Community Edition безкоштовний — без обмежень на користувачів, сторінки та без часових лімітів.