basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Конфиги серверов в git: /opt как репозиторий

    Все compose-файлы и конфиги сервера живут в приватном git-репозитории, корень которого — сам /opt. Правим на компьютере, на сервере — только git pull. Секреты и данные с сервера не уходят: .gitignore — белый список, а перед первым коммитом проверка ищет секреты, не показывая их.

    Как правка доезжает до сервера

    компьютер: правка → commit → push ──→ GitHub (приватный infra-<сервер>) ──→ сервер: cd /opt && git pull
                                                                                     docker compose up -d (изменённые стеки)

    Пять правил — их записываем в README каждого такого репозитория:

    1. Никогда git clean в /opt, особенно -fdx: он удаляет игнорируемые файлы, а это базы, сертификаты, acme.json, .env.
    2. Правим на компьютере, на сервере — только git pull. Срочную правку на сервере сразу коммитим оттуда.
    3. Секреты — только на сервере: /srv/secrets/<стек>/ или .env (600); в git — .env.example с именами («Секреты в Docker-стеках»).
    4. .gitignore — белый список: новый файл не попадёт в git, пока его не разрешат поимённо.
    5. Системные файлы вне /opt (systemd, cron, logrotate) лежат в папке host/ репозитория и ставятся на место командой из README.

    Стандарта, куда класть стеки, нет. По FHS /opt — для программ, которые ставятся одной папкой, /srv — для данных, которые сервер отдаёт наружу; подходят оба, на серверах с одним пользователем встречается и ~/docker. В /var/lib/docker свои файлы не кладём: это хранилище самого Docker, с образами и томами. Выбираем одно место на всех серверах и без нужды не переносим: имя проекта compose — имя каталога, и стек без name: после переноса получит новые пустые тома («Имя проекта compose»). Внутри — каталог на стек; скрипты всего сервера — в /opt/scripts/, скрипт одного стека — в каталоге стека.

    Подключаем сервер

    1. Опись — только пути

      hostname; git --version; docker compose version
      docker compose ls -a                               # проекты compose и пути к их файлам
      find / -xdev \( -path /proc -o -path /sys -o -path /var/lib/docker -o -path /var/lib/containerd -o -path /snap -o -path /usr \) -prune \
        -o -type f \( -name 'docker-compose*.y*ml' -o -name 'compose*.y*ml' \) -print 2>/dev/null
      find /opt -maxdepth 3 -name .git                   # вложенные git-клоны — их в репозиторий не берём
      find /opt -maxdepth 3 -not -path '*/.git/*' -not -path '*/.git' | sort | head -400

      По описи видно, где стеки, какие из них — отдельные репозитории, где рядом с compose лежат данные (db/, data/, *.db), ключи, .env.

    2. .gitattributes и .gitignore — белый список

      cd /opt
      printf '* text=auto eol=lf\n' > .gitattributes      # правки с Windows не ломают переводы строк

      В .gitignore запрещено всё, разрешено поимённо, плюс защита на любом уровне вложенности:

      /opt/.gitignore
      /*
      !/.gitignore
      !/.gitattributes
      !/README.md
      !/host/
      !/scripts/
      
      # Защита на любом уровне вложенности
      .env
      *.db
      *.db-*
      *.sqlite3*
      *.pem
      *.key
      *.txt
      acme.json
      
      # Стек: разрешить папку, запретить всё внутри, разрешить нужные файлы
      !/memos/
      /memos/*
      !/memos/docker-compose.yaml
      !/memos/.env.example
      
      # Стек с подпапкой конфигов
      !/crowdsec/
      /crowdsec/*
      !/crowdsec/docker-compose.yaml
      !/crowdsec/data/
      /crowdsec/data/*
      !/crowdsec/data/config/
      /crowdsec/data/config/*
      !/crowdsec/data/config/acquis.yaml
      !/crowdsec/data/config/acquis.d/
      !/crowdsec/data/config/profiles.yaml

      Порядок строк имеет значение: побеждает последнее подходящее правило.

    3. .env.example — только имена

      for e in */.env; do sed -nE 's/^(export[[:space:]]+)?([A-Za-z_][A-Za-z0-9_]*)=.*/\2=/p' "$e" > "$e.example"; done

      Только строки ИМЯ=, без значений и без комментариев: в комментариях бывают старые значения (#PASSWORD=старый).

    4. Пробный прогон

      git init -b main
      git add --dry-run .                                # что попадёт в git — список глазами
      git ls-files --others --exclude-standard -z | xargs -0r du -k | sort -n | tail -5   # самые крупные файлы

      Крупный файл в конфигах — почти всегда сгенерированный список или данные.

    5. Проверка секретов — без вывода значений

      Команда читает файлы, которые пойдут в git, и по каждой подозрительной строке печатает имя и вид значения: ${ИМЯ} (подставится из .env — хорошо), путь, заглушку, (пусто) — или <значение, N симв.>, и тогда в строке записано настоящее значение. Само значение не выводится, поэтому вывод можно показывать кому угодно.

      git ls-files --others --exclude-standard -z | xargs -0r awk '
      FILENAME == ".gitignore" { next }
      {
        l = tolower($0)
        if (l !~ /token|secret|pass([^t]|$)|key|private|bearer|basicauth|htpasswd|credential|salt|jwt|apr1|argon2|\$2[aby]\$|:\/\/[^\/ ]+:[^@ ]+@/) next
        s = $0; sub(/^[ \t-]+/, "", s)
        if (s ~ /^#/) c = "  [комментарий]"; else { c = ""; sub(/[ \t]+#.*$/, "", s) }
        if (match(s, /[=:]/)) { k = substr(s, 1, RSTART); v = substr(s, RSTART + 1) }
        else if (match(s, /[ \t]/)) { k = substr(s, 1, RSTART - 1); v = substr(s, RSTART + 1) }
        else { k = s; v = "" }
        gsub(/^[ \t"]+|[ \t";]+$/, "", v)
        if (v == "") t = "(пусто)"
        else if (v ~ /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/ || v ~ /^<[A-Z_]+>$/ || v ~ /^[.\/][A-Za-z0-9_.\/-]*$/) t = v
        else t = "<значение, " length(v) " симв.>"
        print FILENAME ":" FNR ": " k " " t c
      }'

      Ловит слова-секреты (token, secret, pass, key, credential…), хэши ($apr1$, $2y$, argon2) и пароль в адресе (://user:pass@). pass([^t]|$) пропускает passthrough. Пример вывода:

      mariadb/docker-compose.yaml:29: MYSQL_ROOT_PASSWORD: <значение, 20 симв.>     ← настоящий пароль: вынести в .env
      panel/docker-compose.yml:21: PANEL_CREDENTIALS: ${PANEL_CREDENTIALS}         ← хорошо
      traefik/docker-compose.yaml:26: CF_DNS_API_TOKEN_FILE: /run/secrets/cf_api_token
      crowdsec/data/config/profiles.yaml:11: # <значение, 112 симв.>  [комментарий]   ← стандартный комментарий
    6. Ключ доступа к одному репозиторию

      REPO=infra-<сервер>
      ssh-keygen -t ed25519 -f ~/.ssh/infra_deploy -N "" -C "$REPO@vps"
      cat ~/.ssh/infra_deploy.pub         # → GitHub: репозиторий → Settings → Deploy keys → Allow write access
      cat >> ~/.ssh/config <<'EOF'
      Host github-infra
        HostName github.com
        User git
        IdentityFile ~/.ssh/infra_deploy
        IdentitiesOnly yes
      EOF
      chmod 600 ~/.ssh/config
      ssh -T github-infra                 # Hi <user>/<repo>! You've successfully authenticated…

      При первом подключении сверяем отпечаток ключа GitHub с опубликованным на docs.github.com.

    7. Первый коммит — на сервере

      cd /opt
      git config user.name "<имя>"; git config user.email "<почта>"
      git add .
      git status --short                  # тот же список, что в пробном прогоне
      git commit -m "infra: конфиги стеков, без данных и секретов"
      git remote add origin "git@github-infra:<user>/$REPO.git"
      git push -u origin main

      На компьютере — git clone. Дальше — README репозитория: стеки, что где, чего нет в git и почему, правила.

    Как устроить: репозитории, первый коммит, список, ключ

    Решение Что даёт Цена
    один сервер — один репозиторий путь совпадает 1:1 (git pull кладёт файлы туда, где их ждёт Docker); ключ доступа к одному репозиторию — взлом сервера не раскрывает остальные несколько репозиториев; общее копируется руками
    один репозиторий на все серверы всё в одном месте на сервере нужен разрез (подкаталоги, sparse checkout); ключ видит все серверы
    первый коммит на сервере секреты не путешествуют; в истории — точный снимок до правок нужен доступ на запись с сервера
    скопировать файлы на компьютер не нужен ключ на сервере вместе с конфигами уедут .env и ключи; на сервере /opt не репозиторий — git pull упрётся в «файлы уже есть»
    белый список новый файл с секретом не попадёт в git случайно каждый новый файл приходится разрешать
    чёрный список (*.env, data/) меньше строк каждая новая база или ключ с непредусмотренным именем — в git
    deploy key (SSH, на один репозиторий) доступ ровно к одному репозиторию ключ на каждый сервер
    токен GitHub один на всё доступ ко всему аккаунту с каждого сервера

    Если не работает

    fatal: remote error: … is not a valid repository name

    Причина
    Лишний знак = при задании имени: REPO==infra-x вместо REPO=infra-x. Тогда git remote add получает имя =infra-x, начинающееся с =. Повторный remote add ответит remote origin already exists.
    Делаем
    git remote set-url origin git@github-infra:<user>/<repo>.git, проверяем git remote -v и делаем push.

    git pull отказывается: файл уже существует

    Причина
    Раньше файл был в .gitignore (например, конфиг с ключом), а теперь приходит из git.
    Делаем
    Сохраняем копию, удаляем файл и делаем git pull — одной командой. Копию держим до проверки.

    После удаления стека git status показывает удалённые файлы

    Причина
    Сначала сделали rm -rf, потом git pull, и git видит удалённые файлы как незакоммиченные изменения.
    Делаем
    Порядок такой: сначала git pull — git уберёт свои файлы, — потом rm -rf остатка: .env, данных.

    git pull конфликтует из-за сгенерированного файла

    Причина
    Список IP или кэш попал в git, а скрипт обновляет его на сервере, и рабочая копия всегда «грязная».
    Делаем
    Исключаем такой файл из git, а в README пишем, как его создать.

    На Windows вместо символической ссылки — текстовый файл с путём

    Причина
    Git хранит ссылку (например, на каталог сертификатов) как ссылку, и в клоне на Windows она становится файлом.
    Делаем
    Такие ссылки исключаем из git и описываем в README.

    В /opt вложенный git-клон

    Причина
    Стек, который сам по себе репозиторий, со своей историей.
    Делаем
    В репозиторий сервера его не берём.

    Скрипт переноса сделал копии .env в /tmp

    Причина
    /tmp читают все пользователи сервера.
    Делаем
    Удаляем сразу.

    После git pull контейнер не видит правки

    Причина
    Файл смонтирован в контейнер отдельно, не каталогом, а git pull подменил его новым.
    Делаем
    docker compose restart <сервис>, а лучше — монтирование каталогом («Монтирование отдельного файла»).

    Секрет уже в истории git

    Причина
    История хранит всё, что попало в коммит.
    Делаем
    Меняем значение («Секреты в Docker-стеках»).

    Как проверить

    cd /opt && git status --short          # пусто: сервер = репозиторий
    git log --oneline -3                   # последние коммиты те же, что на компьютере

    И время от времени — поиск секретов из шага 5 по всему репозиторию: git ls-files -z | xargs -0r awk '…'.