Продвинутый

Реальные инженерные навыки личные из .agents

Алексей Кузнецов
Алексей Кузнецов
Системный администратор1 ноября 2026 г.11 мин чтения

Коллекция практических навыков для инженеров, собранных в .agents. Настройка, контейнеризация, мониторинг и автоматизация — всё, что нужно реальному инженеру.

ai-agents
self-hosting
домашняя-лаборатория
infrastructure
monitoring

Реальные инженерные навыки личные из .agents

Коллекция практических навыков для инженеров, собранных в .agents. Настройка, контейнеризация, мониторинг и автоматизация — всё, что нужно реальному инженеру.

Введение

Введение

В современных домашних лабораториях инженеры часто сталкиваются с ситуацией, когда каждый проект требует нового подхода "с нуля". Настройка нового сервера, развёртывание контейнеров, мониторинг инфраструктуры — всё это повторяющиеся рутинные задачи, которые отнимают время у важных разработок.

Реальный инженер не ищет волшебных кнопок, а хочет системный подход: один раз настроил, и решение работает предсказуемо. Именно поэтому в экосистеме домашних серверов появился проект .agents — коллекция практических навыков, собранных в единое целое.

Чем отличается профессиональный подход от любительского? Тем, что профессионал не гасит пожар, а выясняет почему загорелось. .agents даёт именно этот системный инструментарий — от базовой настройки до автоматизации рутинных операций.

Проблема

Проблема: Разрозненные знания

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

bash
# Пример из практики: поиск конфига после переустановки
$ find /etc -name "nginx.conf" 2>/dev/null
/etc/nginx/nginx.conf
$ grep -A5 "server {" /etc/nginx/nginx.conf
server {
    listen 80;
    server_name example.com;
    root /var/www/html;
}

Такие поиски отнимают время, создают зависимость от конкретной машине и приводят к дублированию конфигураций.

Проблема: Отсутствие повторяемости

Когда решение работает "на коленке", оно редко учитывает будущее масштабирование. Настроил Nginx под один сайт — через полгода приходит новый клиент, а конфиг уже не подходит. Приходится переделывать, искать обходные пути, снова и снова.

yaml
# Пример плохой практики: хардкодированные значения
services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html

Такие конфигурации не приживаются, их сложно передавать коллегам, и они быстро устаревают.

Концепция .agents

Концепция .agents: Единая база инженерных навыков

.agents — это не просто набор команд, а системный подход к инфраструктуре. Проект собирает в себе:

  • Базовые настройки — от сетевых параметров до базовой безопасности
  • Контейнеризация — шаблоны для Docker Compose и Docker Swarm
  • Мониторинг — конфигурации Prometheus, Grafana, Alertmanager
  • Автоматизация — Ansible playbooks, скрипты для рутинных операций

Все компоненты написаны руками, а не взяты из GUI. Как сказал один опытный инженер: "GUI для тех, кто не знает, где лежит конфиг".

yaml
# Пример .agents конфигурации для базового сервера
version: '3.8'
services:
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx:/etc/nginx:ro
      - ./html:/usr/share/nginx/html:ro
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus:ro
      - prometheus_data:/prometheus
    restart: unless-stopped

Концепция .agents: Предсказуемость и документация

Каждая конфигурация в .agents сопровождается подробными комментариями, объясняющими почему используется именно такой параметр. Это позволяет не только настраивать, но и понимать принятое решение.

nginx
# Пример конфига с комментариями
# Сетевое взаимодействие: прослушиваем все интерфейсы
# Заменяем стандартные значения на предсказуемые
events {
    worker_connections 1024;
}

http {
    # Базовая безопасность: отключаем ненужные модули
    include       mime.types;
    default_type  application/octet-stream;
    
    # Журналирование: записываем в файл с ротацией
    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log main;
}

Концепция .agents: Интегрированный мониторинг

Без мониторинга даже идеально настроенная инфраструктура — слепое растение. .agents включает готовые конфигурации для сбора метрик и алертинга.

yaml
# Пример конфига Prometheus
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'nginx'
    static_configs:
      - targets: ['nginx:80']
    metrics_path: /nginx_metrics

Заключение

.agents — это не волшебная палочка, а системный подход к инженерной практике. Проект позволяет инженеру сосредоточиться на важных задачах, а рутинную работу — автоматизировать и документировать.

В следующей статье мы рассмотрим конкретные примеры настройки .agents на домашнем сервере, включая интеграцию с Docker, мониторинг и автоматизацию рутинных операций.

Официальная документация .agents

Навыки агентов

AI-агенты

Для меня AI-агенты — это не просто модный тренд, а инструмент, который должен быть предсказуемым и надежным в production. В своей домашней лаборатории я использую AI-агентов для рутинных задач, чтобы сосредоточиться на действительно важных проблемах инфраструктуры.

Базовый агент для мониторинга логов

yaml
# ~/.agents/monitoring-agent.yaml
agent:
  name: log-monitor
  image: myhome/log-monitor:latest
  restart: unless-stopped
  environment:
    - LOG_LEVEL=info
    - ALERT_THRESHOLD=5
  volumes:
    - /var/log:/var/log:ro
    - ./configs:/etc/agent
  command: >
    python3 -m monitor
    --config /etc/agent/monitor.conf
    --output loki://loki.home:3100

Этот агент работает как системный даemons, отслеживая критические ошибки в /var/log. Конфигурация использует loki для хранения логов, что обеспечивает хорошую корреляцию с остальной системой мониторинга.

Агент для автоматического бэкапа

bash
# ~/scripts/backup-agent.sh
#!/bin/bash
set -euo pipefail

# Конфигурация агента
BACKUP_DIR="/mnt/backup"
RETENTION_DAYS=30
LOG_FILE="$BACKUP_DIR/agent.log"

# Функция для безопасного создания директории
safe_mkdir() {
    mkdir -p "$1" || { echo "Не удалось создать $1" >> "$LOG_FILE"; return 1; }
}

# Основной цикл агента
while true; do
    TIMESTAMP=$(date +%Y%m%d_%H%M%S)
    BACKUP_PATH="$BACKUP_DIR/backup_$TIMESTAMP.tar.gz"
    
    echo "[$TIMESTAMP] Начинаю резервное копирование..." >> "$LOG_FILE"
    
    # Копируем важные конфигурации
    safe_mkdir "$BACKUP_DIR/configs"
    tar -czf "$BACKUP_PATH" \
        /etc/nginx \
        /etc/systemd/system \
        /home/alexey/.agents \
        --exclude='*.cache' >> "$LOG_FILE" 2>&1
    
    # Очистка старых бэкапов
    find "$BACKUP_DIR" -name "backup_*.tar.gz" -mtime +$RETENTION_DAYS -delete
    
    sleep 3600  # Ждем час
done

Этот скрипт работает как cron-задача, создавая бэкапы каждые час. Он предсказуем в своем поведении — всегда создает дамп конфигураций и логирует каждый шаг.

Самостоятельное размещение

Самостоятельное размещение для меня — это не просто установка Docker на VPS, а системный подход к созданию инфраструктуры, которая работает сама по себе. В своей лаборатории я использую несколько принципов, которые обеспечивают предсказуемость и надежность.

Основная конфигурация Docker Compose

yaml
# docker-compose.prod.yaml
version: '3.8'

services:
  nginx-proxy:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./nginx:/etc/nginx/conf.d
      - ./logs/nginx:/var/log/nginx
    restart: unless-stopped

  nextcloud:
    image: nextcloud:latest
    container_name: nextcloud
    volumes:
      - nextcloud_data:/var/www/html
      - ./nextcloud/config:/var/www/html/config
      - ./nextcloud/apps:/var/www/html/apps
    environment:
      - MYSQL_HOST=mysql
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=${NEXTCLOUD_DB_PASS}
      - VIRTUAL_HOST=nextcloud.local
    depends_on:
      - mysql
    restart: unless-stopped

  mysql:
    image: mariadb:10.6
    container_name: mysql
    volumes:
      - mysql_data:/var/lib/mysql
      - ./mysql/init:/docker-entrypoint-initdb.d
    environment:
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASS}
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=${NEXTCLOUD_DB_PASS}
    restart: unless-stopped

  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus:/etc/prometheus
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
    restart: unless-stopped

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASS}
    restart: unless-stopped

volumes:
  nextcloud_data:
  mysql_data:
  prometheus_data:
  grafana_data:

Эта конфигурация демонстрирует системный подход: каждый сервис автономен, но взаимодействует через nginx-proxy. Использование переменных окружения для паролей обеспечивает предсказуемость — конфигурация может быть реплицирована без изменений.

Prometheus конфигурация для мониторинга контейнеров

yaml
# prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'nginx'
    static_configs:
      - targets: ['nginx-proxy:80']
    metrics_path: '/nginx_status'

  - job_name: 'node'
    static_configs:
      - targets: ['host.docker.internal:9100']

  - job_name: 'docker'
    scrape_interval: 5s
    docker_sd_configs:
      - host: unix:///var/run/docker.sock
    relabel_configs:
      - source_labels: [__meta_docker_container_name]
        target_label: instance
        regex: '/(.+)'
      - source_labels: [__meta_docker_container_id]
        target_label: __metrics_path__
        regex: '/(.+)'
        replacement: '/metrics'

Для мониторинга контейнеров я использую node exporter на хосте и Docker SD (service discovery). Это обеспечивает полную видимость без ручного редактирования конфигурации.

Systemd unit для автономного агента

ini
# /etc/systemd/system/backup-agent.service
[Unit]
Description=Backup Agent for Home Lab
After=network.target
Wants=network.target

[Service]
Type=simple
User=alexey
Group=alexey
ExecStart=/home/alexey/scripts/backup-agent.sh
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

# Безопасность
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ReadWritePaths=/mnt/backup /home/alexey/.agents

[Install]
WantedBy=multi-user.target

Этот unit демонстрирует подход "сделай правильно с первого раза": он использует безопасные параметры systemd, логирует в journal и имеет защиту от изменений конфигурации.

В своей практике я убедился, что самостоятельное размещение работает только при условии предсказуемости конфигураций, автоматизации рутинных задач и системного подхода к мониторингу. AI-агенты дополняют этот подход, автоматизируя задачи, которые требуют постоянного внимания.

Практическая реализация

Docker и контейнеры

Docker — это как IKEA для инфраструктуры: всё готовое, но свои нюансы. В .agents я храню базовые паттерны, которые реально работают годами.

yaml
# docker-compose.yml — сервис с мониторингом и резервным копированием
version: '3.8'
services:
  app:
    image: myapp:1.2.3
    restart: unless-stopped
    environment:
      - TZ=Europe/Moscow
    labels:
      - "prometheus-scrape=true"
      - "prometheus-port=9090"
    depends_on:
      - db
      - redis

  db:
    image: postgres:15-alpine
    restart: unless-stopped
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=myapp
      - POSTGRES_USER=myapp
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data

volumes:
  db_data:
  redis_data:

Почему это важно: явные restart: unless-stopped и healthcheck — это предсказуемость, а не добрые пожелания. Без них сервисы умирают в ночную смену.

bash
# Быстрая проверка работоспособности стека
docker compose up -d --build
docker compose exec app sh -c "curl -f http://localhost:8080/health || exit 1"
docker compose logs --tail=20 app

Совет: всегда запускайте healthcheck в CI-пайплайне. Если он не проходит — сборка невалидна.

Proxmox и виртуализация

Proxmox VE — это как мастерская для виртуальных машин: всё под контролем, но без лишней графической мороки. В .agents я храню шаблоны, которые реально работают.

bash
# Создание шаблона Debian для быстрого развёртывания
qm create 200 --name debian-template --memory 2048 --cores 2 \
  --net0 virtio,bridge=vmbr0,firewall=0
qm set 200 --boot c --bootdisk virtio0 \
  --scsihw virtio-scsi-pci --ide2 local:snippets/debian-12-template
qm set 200 --agent 1 --hotplug cpu,disk,network
qm template 200

Почему это важно: шаблон с включённым QEMU-агентом (--agent 1) позволяет делать снимки и перекладывать ВМ между узлами без перезапуска — предсказуемость в действии.

bash
# Применение шаблона через Ansible (только конфигурация, без деплоя)
---
- name: Развернуть шаблон Debian
  hosts: pve
  become: yes
  tasks:
    - name: Проверить наличие шаблона
      command: "qm list | grep debian-template"
      register: template_check
      failed_when: false

    - name: Создать шаблон, если отсутствует
      command: |
        qm create 200 --name debian-template --memory 2048 --cores 2 \
          --net0 virtio,bridge=vmbr0,firewall=0
        qm set 200 --boot c --bootdisk virtio0 \
          --scsihw virtio-scsi-pci --ide2 local:snippets/debian-12-template
        qm set 200 --agent 1 --hotplug cpu,disk,network
        qm template 200
      when: template_check.rc != 0

Совет: храните конфигурации в .agents как код — это предсказуемость и повторяемость. Без графического интерфейса, только читаемые YAML и bash-скрипты.

Вывод: реальные инженерные навыки — это не набор из модных инструментов, а набор предсказуемых паттернов, которые работают в продакшене годами. Docker и Proxmox — лишь два примера из коллекции .agents, где каждая конфигурация протестирована в реальных условиях и документирована для будущих поколений.

Мониторинг и автоматизация

Prometheus и Grafana

Базовая установка

bash
# Установка через package manager
sudo apt update && sudo apt install -y prometheus grafana

# Создание директории для конфигурации
mkdir -p ~/agents/monitoring/{prometheus,grafana}

Основная конфигурация Prometheus

yaml
# ~/agents/monitoring/prometheus.yml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['192.168.1.10:9100', '192.168.1.11:9100']
    
  - job_name: 'docker'
    static_configs:
      - targets: ['192.168.1.10:9323']
    
  - job_name: 'kubernetes'
    static_configs:
      - targets: ['192.168.1.10:8080']

Настройка данных Grafana

ini
# ~/agents/monitoring/grafana.ini
[servers]
root_url = https://grafana.home.lab

[users]
allow_sign_up = false

[security]
admin_user = admin
admin_password = ${GRAFANA_PASSWORD}

Визуализация важных метрик

bash
# Создание дашборда для CPU и памяти
curl -X POST "http://admin:${GRAFANA_PASSWORD}@192.168.1.10:3000/api/dashboards/db" \
  -H "Content-Type: application/json" \
  -d @dashboard_cpu_mem.json

Реальный кейс: Автоматическое масштабирование при превышении CPU

python
# ~/agents/scripts/autoscale.py
import subprocess
import time
from prometheus_api_client import PrometheusConnect

prom = PrometheusConnect(url='http://192.168.1.10:9090')

while True:
    cpu_usage = prom.get_current_metric_value('cpu_usage_seconds_total')
    if cpu_usage > 80:
        subprocess.run(['systemctl', 'restart', 'web-service'])
        time.sleep(300)  # Ждать 5 минут

Ansible и скрипты

Основной плейбук для мониторинга

yaml
# ~/agents/ansible/monitoring.yml
---
- hosts: monitoring_servers
  become: yes
  
  tasks:
    - name: Установить node exporter
      shell: |
        wget https://github.com/prometheus/node_exporter/releases/download/v1.6.1/node_exporter-1.6.1.linux-amd64.tar.gz
        tar -xzf node_exporter-1.6.1.linux-amd64.tar.gz
        mv node_exporter-1.6.1.linux-amd64 /opt/node_exporter
        cp /opt/node_exporter/node_exporter /usr/local/bin/
        rm -f node_exporter-1.6.1.linux-amd64.tar.gz

    - name: Создать systemd unit
      copy:
        dest: /etc/systemd/system/node-exporter.service
        content: |
          [Unit]
          Description=Node Exporter
          After=network.target
          
          [Service]
          ExecStart=/usr/local/bin/node_exporter
          Restart=on-failure
          
          [Install]
          WantedBy=multi-user.target

Скрипт алертинга

bash
#!/bin/bash
# ~/agents/scripts/alert_email.sh

ALERT_THRESHOLD=90
CURRENT_CPU=$(mpstat 1 2 | tail -n1 | awk '{print 100 - $NF}')

if (( $(echo "$CURRENT_CPU > $ALERT_THRESHOLD" | bc -l) )); then
    echo "CPU usage critical: $CURRENT_CPU%" | \
    mail -s "Alert: High CPU on $(hostname)" admin@home.lab
fi

Планировщик для регулярных проверок

bash
# ~/agents/crontab
# Добавить в crontab: */5 * * * * /home/alexey/agents/scripts/alert_email.sh
# Ежедневная очистка старых логов
0 2 * * * find /var/log/monitoring -name "*.log" -mtime +30 -delete

Скрипт автоматической настройки Grafana

python
# ~/agents/scripts/setup_grafana.py
import requests
import json

def create_alert_rule():
    alert_config = {
        "name": "HighCPU",
        "message": "CPU usage above 80% on {{ $labels.instance }}",
        "conditions": [
            {
                "type": "query",
                "query": "cpu_usage > 80",
                "duration": "5m"
            }
        ]
    }
    
    response = requests.post(
        "http://admin:password@192.168.1.10:3000/api/alert-rules",
        json=alert_config
    )
    return response.status_code == 200

if __name__ == "__main__":
    create_alert_rule()

Интеграция с внешними системами мониторинга

yaml
# ~/agents/ansible/external_integrations.yml
---
- hosts: monitoring_servers
  become: yes
  
  tasks:
    - name: Настроить интеграцию с Slack
      copy:
        dest: /etc/prometheus/slack_alerts.yml
        content: |
          slack_configs:
            - channel: '#alerts'
              api_url: ${SLACK_WEBHOOK_URL}
              send_resolved: true
              title: "{{ '{{' }} template 'slack_title' . {{ '}}' }}"
              text: "{{ '{{' }} template 'slack_text' . {{ '}}' }}"

Эти инструменты обеспечивают полную прозрачность инфраструктуры и быструю реакцию на изменения. Prometheus собирает метрики, Grafana визуализирует данные, а Ansible автоматизирует рутинные операции — всё это работает предсказуемо и без лишнего шума.

Поделиться:TelegramX / TwitterVK