Установка и базовая работа с Apache CouchDB на Debian 11

Коротко о CouchDB

Apache CouchDB — это открытая NoSQL СУБД, ориентированная на хранение документов в формате JSON и на доступ к ним через HTTP/REST API. Главные свойства:

• Документ — единица данных в CouchDB, хранится как JSON.
• База данных — набор документов.
• Узел — процесс CouchDB, работающий на сервере; несколько узлов могут объединяться в кластер.
• Fauxton — встроенная веб-административная панель CouchDB.
• _rev — ревизия документа; используется для согласованного обновления и удаления.

Определение в одну строку: CouchDB — документно-ориентированная база с HTTP API и встроенной репликацией.

Важно: CouchDB проектируется для устойчивой репликации и работы в распределённых средах, но прост в локальном использовании.

Содержание

• Требования
• Установка утилит
• Добавление репозитория CouchDB и установка
• Проверка установки и раскрытие портов
• Работа через Fauxton (GUI)
• Операции через командную строку (curl)
• Разворачивание публичного доступа через Caddy и HTTPS
• Рекомендации для продакшна: безопасность, бэкапы, мониторинг, кластеризация
• Критерии приёмки, чеклисты и отладка

Требования

• Сервер с Debian 11
• Установлен пакет sudo

$ apt install sudo

• Непользователь root с правами sudo
• Система обновлена

$ sudo apt update && sudo apt upgrade

• Полное доменное имя (FQDN), например couchdb.example.com, если хотите открыть интерфейс по HTTPS

Важно: для публичного доступа потребуется корректная DNS-запись A/AAAA и открытые порты в провайдерском брандмауэре.

Шаг 1 — Установка утилит

Установите вспомогательные пакеты, которые понадобятся в процессе:

$ sudo apt install -y curl apt-transport-https gnupg nano lsb-release

Примечание: apt-transport-https в новых версиях APT не обязателен, но команда сохраняет совместимость.

Шаг 2 — Добавление репозитория CouchDB

Импортируйте GPG-ключ репозитория CouchDB:

$ curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null 2>&1

Добавьте репозиторий в список источников:

$ echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ `lsb_release -cs` main" \
    | sudo tee /etc/apt/sources.list.d/couchdb.list >/dev/null

Обновите индекс пакетов:

$ sudo apt update

Совет: если у вас приватный прокси или корпоративный mirror, откорректируйте источник репозитория под вашу сеть.

Шаг 3 — Установка CouchDB

Установите пакет CouchDB:

$ sudo apt install couchdb -y

Инсталлятор попросит выбрать режим: одиночный узел или кластер. Для простого развертывания выбирайте “single node” (один сервер). Он также попросит задать Erlang cookie, адрес привязки (binding), и пароль для административного пользователя.

Ввод имени cookie Erlang (любой строкой):

Рекомендуем задать binding address 0.0.0.0 только если вы планируете доступ извне через защищённый прокси. В локальной установке безопаснее оставлять 127.0.0.1 и использовать обратный прокси.

Задайте надёжный пароль админа:

Подтвердите пароль:

Важно: храните пароль безопасно. Не отправляйте секреты в командной строке в незашифрованном виде для продакшна.

Шаг 4 — Проверка установки

Проверьте ответ сервера локально:

$ curl http://127.0.0.1:5984/

Вы получите JSON с информацией о версии и функциях. Пример формата ответа:

{
   "couchdb":"Welcome",
   "version":"3.2.2",
   "git_sha":"d5b746b7c",
   "uuid":"7a20b1eadd803f1c0d77fb9617c7f3de",
   "features":[
      "access-ready",
      "partitioned",
      "pluggable-storage-engines",
      "reshard",
      "scheduler"
   ],
   "vendor":{
      "name":"The Apache Software Foundation"
   }
}

Откройте порт в брандмауэре (пример для ufw):

$ sudo ufw allow 5984/tcp

Теперь можно открыть в браузере http://<вашIPсервера>:5984 — в Firefox вы увидите форматированный JSON, в других браузерах — сырое тело ответа.

Шаг 5 — Доступ через Fauxton

Fauxton — веб-интерфейс CouchDB. Откройте:

http://<ваш_IP_сервера>:5984/_utils/

Войдите под admin и ранее заданным паролем.

После входа вы попадёте на панель мониторинга CouchDB.

Система по умолчанию создаёт базы _users и _replicator. _users хранит информацию о пользователях, _replicator — задания репликации.

Шаг 6 — Базовые операции через Fauxton

Fauxton поддерживает CRUD операции в удобном интерфейсе.

Создание базы данных

Нажмите Create Database, введите имя и создайте.

После создания откроется панель базы данных.

Создание документа

Нажмите Create Document. Форма предзаполнена JSON и сгенерированным _id.

Пример содержимого документа:

{
  "_id": "0b4ad0d607479c09bb9121b146007363",
  "Name": "Navjot Singh",
  "role": "writer",
  "skills": "linux"
}

После сохранения документ появится в списке All Documents.

Просмотр JSON документа через ссылку {} JSON.

Редактирование — значок карандаша или переключение на Metadata, затем Save Document.

Удаление документа

Отметьте галочкой документ и нажмите Delete в верхней панели.

Шаг 7 — Базовые операции через командную строку

Работа через curl эффективна для автоматизации.

Подготовка URL с учётными данными

Пример переменной окружения (в демонстрационных целях):

$ HOST="http://admin:[email protected]:5984"

Важно: хранить пароль в явном виде в переменных среды небезопасно для продакшна. Вместо этого используйте безопасные механизмы хранения секретов или .netrc. Рассмотрите использование client certificates или reverse proxy с аутентификацией.

Создание базы данных

$ curl -X PUT $HOST/another_db

Создание документа

$ curl -X POST -d '{"todo":"task 1", "done":false}' $HOST/another_db -H "Content-Type:application/json"

Ответ содержит ok, id и rev. Пример:

{"ok":true,"id":"0b4ad0d607479c09bb9121b14600c6ee","rev":"1-2fc1d70532433c39c9f61480607e3681"}

Если хотите задать свой id:

$ curl -X POST -d '{"_id":"random_task", "todo":"task 2", "done":false}' $HOST/another_db -H "Content-Type:application/json"

Вставка документов пачкой

$ curl -X POST -d '{"docs": [{"todo":"task 3", "done":false}, {"todo":"task 4", "done":false}]}' $HOST/another_db/_bulk_docs -H "Content-Type:application/json"

Запрос к _bulk_docs принимает объект с полем docs — массив документов.

Чтение документа

$ curl -X GET $HOST/another_db/random_task

В ответе обратите внимание на поле _rev — оно потребуется для следующих операций.

Редактирование документа

Для изменения требуется указать актуальное значение _rev и отправить весь документ целиком:

$ curl -X PUT -d '{"_rev":"1-bceeae3c4a9154c87db1649473316e44", "todo":"task 2", "done":true}' $HOST/another_db/random_task

Ответ содержит новое значение rev.

Удаление документа

$ curl -X DELETE $HOST/another_db/random_task?rev=2-4cc3dfb6e76befd665faf124b36b7f1c

Обязательно указывайте корректную ревизию.

Просмотр баз данных и документов

Список всех баз:

$ curl -X GET $HOST/_all_dbs

Список документов в базе:

$ curl -X GET $HOST/another_db/_all_docs

Шаг 8 — Установка Caddy

Caddy — лёгкий обратный прокси с автоматическим получением TLS сертификатов.

Установите требуемые пакеты:

$ sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https

Добавьте ключи и репозиторий Caddy:

$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
$ curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

Установите Caddy:

$ sudo apt update
$ sudo apt install caddy

Проверьте версию:

$ caddy version
v2.5.1 h1:bAWwslD1jNeCzDa+jDCNwb8M3UJ2tPa8UZFFzPVmGKs=

Шаг 9 — Настройка Caddy

Откройте Caddyfile:

$ sudo nano /etc/caddy/Caddyfile

Пример конфигурации обратного прокси для CouchDB:

couchdb.example.com {
        reverse_proxy localhost:5984

        tls [email protected]

        log {
                output file /var/log/caddy/couchdb.log
        }
}

Сохраните файл. Проверка конфигурации:

$ caddy validate --adapter caddyfile --config /etc/caddy/Caddyfile

Если форматирование некорректно, выполните:

$ sudo caddy fmt --overwrite /etc/caddy/Caddyfile

Перезапустите сервис:

$ sudo systemctl restart caddy

Теперь доступ по адресу:

https://couchdb.example.com/_utils/

Важно: у Caddy должен быть доступ к сети для получения сертификата ACME. Убедитесь, что DNS для couchdb.example.com указывает на IP сервера.

Рекомендации для продакшн-развертывания

Ниже — практические рекомендации для повышения надёжности и безопасности.

Безопасность

• Не оставляйте CouchDB слушающим 0.0.0.0 без фронтального прокси. В продакшне лучше выставить binding 127.0.0.1 и проксировать трафик через Caddy/NGINX.
• Используйте TLS на границе (Caddy автоматизирует это).
• Храните админ-пароли в защищённом хранилище (Vault, Secret Manager). Избегайте явных паролей в переменных окружения.
• Ограничьте доступ брандмауэром по IP, если возможно.
• Включите и настройте аудит логов.
• Периодически меняйте секреты и применяйте ротацию.

Резервное копирование и восстановление

Варианты бэкапа:

• Репликация на удалённый узел CouchDB. Репликация — штатный механизм, удобен для переноса и горячего бэкапа.
• Экспорт документов через _all_docs и include_docs для создания дампа JSON (скрипт на Python/Node/Perl).
• При остановке сервиса — файловая копия каталога данных (FS-level snapshot) на уровне LVM/ZFS для консистентности.

Советы:

• Для восстановления важно точно знать версию CouchDB и движок хранения. Тестируйте процедуру восстановления заранее.
• Для больших объёмов данных репликация на второй кластер обычно проще и надёжнее, чем массовый экспорт/импорт.

Мониторинг и логирование

• Логи CouchDB доступны через systemd journal и/или файлы логов, если настроено. Мониторьте ошибки записи, переполнения диска и длительные задержки.
• Экспорт метрик в Prometheus возможен через плагины или внешние экспортеры.
• Отслеживайте: использование диска, I/O latency, количество open file descriptors, статус репликаций, количество активных подключений.

Производительность

• Для интенсивной записи выбирайте SSD.
• Настройка файловой системы и параметров I/O имеет значение (aio, fsync). Тестируйте нагрузку на staging.
• Размеры пулов Erlang могут влиять на производительность. Корректируйте с учётом оперативной памяти и нагрузки.

Кластеризация

• Кластер полезен при росте данных и необходимости отказоустойчивости.
• Планируйте размер кластера заранее: число шард и реплик. Репликация по умолчанию настраивается через _replicator.
• Erlang cookie должен совпадать на всех узлах для связи внутри кластера.

Критерии приёмки

• CouchDB отвечает на запрос curl http://127.0.0.1:5984/ и возвращает couchdb: “Welcome”.
• Fauxton доступен по внутреннему адресу и/или по https://couchdb.example.com/_utils/.
• Создание, чтение, обновление и удаление документов проходит успешно через curl и через Fauxton.
• Резервное копирование протестировано и восстановление данных успешно.
• Пароли заданы и не хранятся в скриптах в открытом виде.

Чеклист ролей

Администратор:

• Создал пользователя admin с надёжным паролем
• Настроил брандмауэр и binding
• Настроил обратный прокси и TLS

Разработчик:

• Протестировал CRUD через curl и библиотеку клиента
• Подготовил миграционные скрипты и бэкап/рестор инструкции

Оператор:

• Настроил мониторинг и алерты
• Настроил резервное копирование и проверил восстановление

Отладка — распространённые проблемы и решения

Проблема: не получается получить TLS-сертификат от Let’s Encrypt

• Проверьте, что DNS A запись указывает на сервер.
• Убедитесь, что порт 80 доступен для валидации.

Проблема: 401 Unauthorized при доступе

• Проверьте, что используете правильные учётные данные.
• Если вы проксируете через Caddy, убедитесь, что заголовки авторизации не удаляются.

Проблема: “address already in use” при старте CouchDB

• Проверьте, не занят ли порт 5984 другим процессом. Используйте netstat или ss.

Проблема: невозможность обновить документ — конфликт ревизий

• Перед PUT получите актуальный документ и используйте поле _rev в теле запроса.

Альтернативные подходы

• Вместо Caddy можно использовать Nginx или Traefik как обратный прокси с TLS. Все обеспечивают аналогичные возможности; Caddy упрощает автоматический TLS out-of-the-box.
• Для крупных распределённых систем рассмотрите Couchbase или MongoDB, если нужен другой набор trade-off (встраиваемая индексация, запросный язык и т.д.).

Модель мышления при выборе CouchDB

• Выбирайте CouchDB, если нужен простой HTTP-интерфейс, оффлайн-репликация и конфликт-устойчивые репликации.
• CouchDB хорошо подходит для приложений с распределённой синхронизацией и мобильными клиентами.
• Если вам важны транзакции ACID на уровне нескольких документов — рассмотрите реляционные БД.

Короткая методология развертывания

1. Подготовьте сервер и домен.
2. Установите CouchDB и задайте админа.
3. Протестируйте локально CRUD.
4. Настройте обратный прокси с TLS.
5. Настройте бэкап и мониторинг.
6. Тестируйте восстановление и нагрузку.

SOP для резервного копирования (микро-плейбук)

1. Ежедневная репликация на горячий узел в другом дата-центре.
2. Недельный снимок файловой системы (LVM/ZFS) для полной точки восстановления.
3. Ежемесячная проверка восстановления на тестовом окружении.
4. Логируйте успешные/ошибочные операции бэкапа.

Безопасность и конфиденциальность

• Пользовательские данные, которые попадают в CouchDB, подпадают под общие требования GDPR, если это персональные данные граждан ЕС. Обеспечьте права доступа, шифрование в движении и контроль хранения.
• Для передачи секретов используйте безопасные хранилища, не включайте пароли в публичные репозитории.

Короткая анонс-версия (под соцсети, 100–200 слов)

Сегодня мы показали пошаговое руководство по установке Apache CouchDB на Debian 11: от добавления репозитория и установки до создания баз и документов через веб-интерфейс Fauxton и curl. Также показано, как сделать доступ к административной панели публичным и защищённым через Caddy с автоматическим TLS. В статье включены практические советы по безопасности, резервному копированию, мониторингу и базовой отладке — всё для безопасного выхода в продакшн. Если вы разрабатываете распределённые приложения с необходимостью репликации и офлайн-синхронизации, CouchDB — практичный выбор.

Краткое резюме

• CouchDB — документная база с REST API и встроенной репликацией.
• Установка на Debian 11 проходит через официальный репозиторий CouchDB.
• Fauxton даёт удобный GUI, curl — гибкий путь автоматизации.
• Для публичного доступа используйте обратный прокси и TLS (Caddy).
• Обязательно настройте бэкапы, мониторинг и безопасное хранение паролей.

Спасибо за чтение. Если остались вопросы — задавайте, и я помогу с конкретными шагами для вашего окружения.