174 lines
13 KiB
Markdown
174 lines
13 KiB
Markdown
# 09. Ansible — общее описание репозитория
|
||
|
||
## 🎯 Цель репозитория
|
||
|
||
Автоматизированное развертывание и обслуживание всех сервисов домашнего мультимедиа центра.
|
||
Сервер стал полноценной частью семьи: дети смотрят мультфильмы, жена слушает аудиокниги, все общаются через голосовой чат или текстовые сообщения с друзьями.
|
||
Данный репозиторий создан для того, чтобы:
|
||
|
||
- В случае непредвиденной ситуации кто-то из близких мог разобраться в конфигурации и продолжить поддержку сервера.
|
||
- Я сам мог не помнить всех деталей настройки, которые делал несколько лет назад, и быстро находить нужную информацию.
|
||
- Воспроизводить развертывание сервисов на новом оборудовании при необходимости.
|
||
|
||
Вся конфигурация описана в виде кода (Infrastructure as Code) с использованием Ansible.
|
||
|
||
---
|
||
|
||
## 🖥️ Управляемые хосты
|
||
|
||
Хосты представляют собой LXC-контейнеры в Proxmox, каждый отвечает за свою группу сервисов.
|
||
Файл инвентаря: `inventories/hosts`
|
||
|
||
### Группы и хосты
|
||
|
||
| Группа | Хост | IP-адрес | Назначение |
|
||
|------------------|-----------|-------------|-----------------------------------------|
|
||
| `pve-server` | proxmox | 192.168.1.200 | Гипервизор Proxmox |
|
||
| `gateway-server` | gateway | 192.168.1.201 | Шлюз, VPN, роутинг |
|
||
| `data-server` | data | 192.168.1.202 | Хранилище данных, Samba |
|
||
| `media-server` | media | 192.168.1.203 | Медиасервисы (Jellyfin, Audiobookshelf)|
|
||
| `photo-server` | photo | 192.168.1.204 | Фото (Immich) |
|
||
| `talk-server` | talk | 192.168.1.206 | Коммуникации (Snikket, Mumble) |
|
||
| `games-server` | games | 192.168.1.207 | Игровые серверы (Minecraft) |
|
||
| `manage-server` | manage | 192.168.1.208 | Управление (Heimdall, NPM, Grafana) |
|
||
| `git-server` | git | 192.168.1.209 | GitLab |
|
||
| `ansible-server` | ansible | 192.168.1.210 | Хост, с которого запускается Ansible |
|
||
| `torrent-server` | torrent | 192.168.1.211 | Торренты (qBittorrent, TorrServer) |
|
||
|
||
Все хосты используют Python 3 как интерпретатор (`ansible_python_interpreter=/usr/bin/python3`).
|
||
|
||
---
|
||
|
||
## 🛠️ Технологии и подходы
|
||
|
||
- **Ansible** — управление конфигурацией.
|
||
- **Docker Compose** — все сервисы запускаются в контейнерах, конфигурация генерируется через шаблоны.
|
||
- **Jinja2** — шаблонизация конфигурационных файлов (docker-compose.yml, конфиги сервисов).
|
||
- **Handlers** — перезапуск сервисов только при изменении конфигурации.
|
||
- **Групповые переменные** — единый файл `group_vars/all.yml` для общих настроек.
|
||
- **Ansible Vault** — хранение секретов (пароли, токены) в `vault.yml`.
|
||
- **Модульность** — каждая роль отвечает за один сервис или задачу.
|
||
- **Идемпотентность** — повторный запуск плейбука не ломает существующую конфигурацию.
|
||
|
||
---
|
||
|
||
## 📂 Структура репозитория
|
||
|
||
| Каталог / файл | Описание |
|
||
|------------------------------|----------------------------------------------------------------------------------------|
|
||
| `arhive_roles/` | Роли, которые не используются активно (сохранены для истории) |
|
||
| `group_vars/` | Переменные для всех хостов (файл `all.yml`) |
|
||
| `inventories/` | Файлы инвентаря (хосты, группы) |
|
||
| `roles/` | Основные роли — каждый сервис или задача |
|
||
| `olimp-deploy.yml` | Главный плейбук, включающий все роли |
|
||
| `vault.yml` | Зашифрованный файл с секретами (редактируется через `ansible-vault`) |
|
||
|
||
### Основные роли (`roles/`)
|
||
|
||
| Роль | Назначение |
|
||
|-----------------------|-------------------------------------------------|
|
||
| ampache | Музыкальный стриминг-сервер |
|
||
| audiobookshelf | Сервер для аудиокниг и подкастов |
|
||
| base_setup | Базовая настройка системы (обновление, пакеты) |
|
||
| bitwarden | Менеджер паролей (Vaultwarden) |
|
||
| bookstack | Вики / база знаний |
|
||
| cadvisor | Мониторинг Docker-контейнеров |
|
||
| calibre-web | Веб-интерфейс для библиотеки Calibre |
|
||
| docker | Установка Docker и Docker Compose |
|
||
| flibusta | Зеркало библиотеки Флибуста (Z-Library) |
|
||
| gitlab | GitLab CE |
|
||
| grafana | Визуализация метрик (Grafana + VictoriaMetrics) |
|
||
| heimdall | Стартовая страница (дашборд) |
|
||
| immich | Фотогалерея / альтернатива Google Photos |
|
||
| jellyfin | Медиасервер (видео, музыка) |
|
||
| loki | Система сбора и хранения логов |
|
||
| mealie | Менеджер рецептов |
|
||
| meshcentral | Удалённое управление компьютерами |
|
||
| minecraft | Игровой сервер Minecraft |
|
||
| mumble | Голосовой чат (Mumble) |
|
||
| npm | Nginx Proxy Manager |
|
||
| promtail | Агент сбора логов для Loki |
|
||
| proxmox_base_setup | Базовая настройка хостов Proxmox |
|
||
| proxmox_monitoring | Мониторинг Proxmox (pve_exporter) |
|
||
| qbittorrent | Торрент-клиент |
|
||
| snikket | Коммуникационный сервер (XMPP) |
|
||
| system_cleanup | Очистка системы (логи, временные файлы) |
|
||
| teamspeak | Голосовой сервер TeamSpeak |
|
||
| torrserver | Торрент-стриминг (TorrServer) |
|
||
|
||
### Архивные роли (`arhive_roles/`)
|
||
|
||
| Роль | Описание |
|
||
|---------------------|-----------------------------------------------------|
|
||
| dashy | Альтернативный дашборд (не используется) |
|
||
| [delete]pve_monitoring | Старая версия мониторинга Proxmox (удалена) |
|
||
| matrix | Сервер Matrix (неактивен) |
|
||
|
||
---
|
||
|
||
## 📋 Требования к окружению
|
||
|
||
Для работы с репозиторием необходимы:
|
||
|
||
- **Ansible** (ядро): версия 2.18.10
|
||
- **Коллекции**: установлена `community.docker` 4.8.1 (используется для управления Docker Compose)
|
||
- **Python**: 3.12.3 на управляющем хосте
|
||
- **Jinja2**: 3.1.2
|
||
- **Доступ по SSH** ко всем хостам (настройки в `ansible.cfg` или через переменные)
|
||
- **Docker и Docker Compose** установлены на целевых хостах (обеспечивается ролью `docker`)
|
||
- **Ansible Vault** пароль для расшифровки `vault.yml` (должен быть доступен при запуске)
|
||
|
||
**Установленные пакеты Python:**
|
||
- `ansible` 11.11.0
|
||
- `docker` 7.1.0
|
||
|
||
**Команды для проверки:**
|
||
```bash
|
||
ansible --version
|
||
# ansible [core 2.18.10]
|
||
ansible-galaxy collection list | grep community.docker
|
||
# community.docker 4.8.1
|
||
pip list | grep -E "ansible|docker"
|
||
# ansible 11.11.0
|
||
# docker 7.1.0
|
||
```
|
||
|
||
---
|
||
|
||
## 👨🏫 Для новичков: что такое Ansible?
|
||
|
||
Если вы никогда раньше не работали с Ansible, вот краткое введение:
|
||
|
||
- **Ansible** — это инструмент автоматизации. Вы описываете желаемое состояние системы в YAML-файлах, а Ansible приводит систему к этому состоянию.
|
||
- **Плейбук** (playbook) — главный файл, который содержит список «пьес» (plays). Каждая пьеса выполняется на определённой группе хостов и включает набор задач (tasks).
|
||
- **Роль** (role) — набор задач, переменных, шаблонов и обработчиков, объединённых для решения одной задачи (например, установка Jellyfin). Это помогает организовать код.
|
||
- **Задача** (task) — конкретное действие: создать каталог, скопировать файл, запустить Docker-контейнер и т.д.
|
||
- **Модуль** — встроенная функция Ansible (например, `docker_compose`, `copy`, `file`).
|
||
- **Переменные** — хранят значения, которые могут меняться (пути, порты, имена пользователей). Определяются в `group_vars`, `host_vars`, внутри ролей или в плейбуке.
|
||
- **Шаблон Jinja2** — файл с расширением `.j2`, в который подставляются переменные. Используется для генерации конфигов.
|
||
- **Обработчик** (handler) — задача, которая выполняется только в том случае, если её уведомила другая задача (например, перезапуск сервиса после изменения конфига).
|
||
- **Ansible Vault** — шифрование секретных данных (паролей, ключей) в YAML-файлах.
|
||
|
||
**Базовые команды:**
|
||
|
||
```bash
|
||
# Проверка синтаксиса плейбука
|
||
ansible-playbook olimp-deploy.yml --syntax-check
|
||
|
||
# Запуск плейбука (с запросом пароля vault)
|
||
ansible-playbook olimp-deploy.yml --ask-vault-pass
|
||
|
||
# Запуск только определённой роли (тег)
|
||
ansible-playbook olimp-deploy.yml --tags jellyfin
|
||
|
||
# Проверка подключения ко всем хостам
|
||
ansible all -i inventories/hosts -m ping
|
||
```
|
||
|
||
В следующих разделах документации каждый элемент будет разобран подробно, с примерами и пояснениями.
|
||
|
||
---
|
||
|
||
## 📝 Статус
|
||
|
||
Документация актуальна на 23 марта 2026 года. По мере изменений в инфраструктуре разделы будут обновляться. |