docs: enhance README and CI workflow to clarify Docker image build conditions and Gitea Container Registry usage, including new job flags for OpenAPI and code changes

2026-04-05 18:20:18 +07:00
parent f1b33b9daf
commit c6687b2c91
9 changed files with 134 additions and 27 deletions
@@ -2,7 +2,16 @@

 В репозитории включён workflow [workflows/ci.yaml](workflows/ci.yaml).

-Job **openapi** (Redocly) запускается только если в коммите или PR изменились `docs/openapi.yaml` или `redocly.yaml`; иначе шаг пропускается. Остальные jobs (`go`, `bird2`) выполняются как раньше.
+Job **changes** вычисляет два флага:
+
+- **`openapi`** — в диффе есть `docs/openapi.yaml` или `redocly.yaml` → запускается **openapi** (Redocly lint).
+- **`code`** — в диффе есть **хотя бы один файл вне «только документация»** → запускаются **go**, **bird2** и при push в main/master **docker-images**.
+
+Если изменены **только** файлы из списка ниже, **`code=false`**: Go-тесты, bird2 и сборка образов **не** запускаются; при необходимости всё ещё выполняется **openapi**, если трогали OpenAPI или `redocly.yaml`.
+
+**Список путей «только документация» (без полной сборки):** всё под `docs/`, корневой `README.md`, `web/README.md`, `.gitea/README.md`, `redocly.yaml`.
+
+Любой другой путь (в т.ч. `.gitea/workflows/ci.yaml`, `go.mod`, `web/package.json`, `deploy/**`, `**/*.go`) включает полный пайплайн.

 Требования к runner:

@@ -56,6 +65,8 @@ git.shts.su/<owner_lowercase>/<имя>:<тег>
 docker pull git.shts.su/myuser/evobgp-api:latest
 ```

+Полная таблица образов, тегов, ссылок на страницы пакетов в Gitea и минимальный `docker run` для сервера без сборки — в [docs/quickstart.md](../docs/quickstart.md) (раздел «Готовые образы без сборки»).
+
 Убедитесь, что в **Gitea** включены пакеты (Container Registry) и у токена есть права на создание/обновление образов. Другой хост реестра — правьте **`registry:`** и префикс **`IMG=`** в [ci.yaml](workflows/ci.yaml).

 ### Примечания
@@ -10,43 +10,77 @@ jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
-      openapi: ${{ steps.openapi.outputs.changed }}
+      openapi: ${{ steps.detect.outputs.openapi }}
+      code: ${{ steps.detect.outputs.code }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
-      - id: openapi
-        name: Detect OpenAPI-related file changes
+      - id: detect
+        name: Detect changed paths (OpenAPI vs doc-only vs code)
        run: |
          set -euo pipefail
-          PATHS="docs/openapi.yaml redocly.yaml"
-          changed=false
+
+          openapi=false
+          code=true

          if [ "${{ github.event_name }}" = "pull_request" ]; then
            base="${{ github.event.pull_request.base.sha }}"
            head="${{ github.event.pull_request.head.sha }}"
-            if git diff --name-only "$base" "$head" -- $PATHS | grep -q .; then
-              changed=true
-            fi
+            FILES="$(git diff --name-only "$base" "$head")"
          else
            before="${{ github.event.before }}"
            after="${{ github.sha }}"
            if [ -n "$before" ] && [ "$before" != "0000000000000000000000000000000000000000" ]; then
-              if git diff --name-only "$before" "$after" -- $PATHS | grep -q .; then
-                changed=true
-              fi
+              FILES="$(git diff --name-only "$before" "$after")"
            elif git rev-parse --verify HEAD~1 >/dev/null 2>&1; then
-              if git diff --name-only HEAD~1 HEAD -- $PATHS | grep -q .; then
-                changed=true
-              fi
+              FILES="$(git diff --name-only HEAD~1 HEAD)"
            else
-              # Нет родителя (первый коммит / тонкий clone) — линт OpenAPI выполняем один раз
-              changed=true
+              # Нет родителя (первый коммит / тонкий clone) — полный пайплайн + OpenAPI
+              openapi=true
+              code=true
+              echo "openapi=$openapi" >> "$GITHUB_OUTPUT"
+              echo "code=$code" >> "$GITHUB_OUTPUT"
+              echo "No parent commit: openapi=true code=true"
+              exit 0
            fi
          fi

-          echo "changed=$changed" >> "$GITHUB_OUTPUT"
-          echo "OpenAPI lint will run: $changed"
+          # Пустой diff (редко) — не отключаем сборку из осторожности
+          if [ -z "$(printf '%s' "$FILES" | tr -d '[:space:]')" ]; then
+            openapi=false
+            code=true
+            echo "openapi=$openapi" >> "$GITHUB_OUTPUT"
+            echo "code=$code" >> "$GITHUB_OUTPUT"
+            echo "Empty diff: openapi=false code=true"
+            exit 0
+          fi
+
+          if printf '%s\n' "$FILES" | grep -qE '^docs/openapi\.yaml$|^redocly\.yaml$'; then
+            openapi=true
+          fi
+
+          doc_only_all=true
+          while IFS= read -r f || [ -n "${f:-}" ]; do
+            [ -z "${f:-}" ] && continue
+            if [[ "$f" == "README.md" || "$f" == ".gitea/README.md" || "$f" == "web/README.md" || "$f" == "redocly.yaml" || "$f" == docs/* ]]; then
+              continue
+            fi
+            doc_only_all=false
+            break
+          done <<< "$FILES"
+
+          if $doc_only_all; then
+            code=false
+          else
+            code=true
+          fi
+
+          echo "openapi=$openapi" >> "$GITHUB_OUTPUT"
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+          echo "Changed files (first 20):"
+          printf '%s\n' "$FILES" | head -n 20
+          echo "openapi=$openapi code=$code"

  openapi:
    needs: [changes]
@@ -61,6 +95,8 @@ jobs:
        run: npx --yes @redocly/cli@1 lint docs/openapi.yaml

  go:
+    needs: [changes]
+    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
@@ -1,5 +1,5 @@
 # BIRD 2 alongside evobgp-agent; share /etc/bird with the agent container (plan §4.1).
-FROM debian:bookworm-slim
+FROM public.ecr.aws/docker/library/debian:bookworm-slim
 RUN apt-get update && apt-get install -y --no-install-recommends bird2 \
    && rm -rf /var/lib/apt/lists/*
 COPY deploy/bird/bird.conf /etc/bird/bird.conf
@@ -1,11 +1,12 @@
 # evobgp-agent CLI (parse-check, birdc configure); install bird2 so `bird -p` matches bird2 image (plan §13).
-FROM golang:1.22-bookworm AS build
+# См. gobinary/Dockerfile — ECR Public вместо прямого pull с Docker Hub (устойчивость CI).
+FROM public.ecr.aws/docker/library/golang:1.22-bookworm AS build
 WORKDIR /src
 COPY go.mod go.sum ./
 COPY . .
 RUN go build -trimpath -ldflags="-s -w" -o /out/evobgp-agent ./cmd/evobgp-agent

-FROM debian:bookworm-slim
+FROM public.ecr.aws/docker/library/debian:bookworm-slim
 RUN apt-get update && apt-get install -y --no-install-recommends bird2 ca-certificates \
    && rm -rf /var/lib/apt/lists/*
 COPY --from=build /out/evobgp-agent /usr/local/bin/evobgp-agent
@@ -1,11 +1,12 @@
 # Статическая панель EvoBGP (SvelteKit) + nginx как reverse-proxy к evobgp-api (/v1, /metrics).
-FROM node:22-alpine AS build
+# ECR Public — то же содержимое, что library/node и library/nginx на Docker Hub.
+FROM public.ecr.aws/docker/library/node:22-alpine AS build
 WORKDIR /web
 COPY web/package.json web/package-lock.json ./
 RUN npm ci
 COPY web/ ./
 RUN npm run build

-FROM nginx:1.27-alpine
+FROM public.ecr.aws/docker/library/nginx:1.27-alpine
 COPY deploy/docker/evobgp-web/nginx.conf /etc/nginx/conf.d/default.conf
 COPY --from=build /web/build /usr/share/nginx/html
@@ -1,6 +1,7 @@
 # Универсальная сборка бинаря из cmd/* (ARG BIN=evobgp-api | evobgp-all).
 # INSTALL_BIRDC=1 ставит bird2 в рантайм-образ для EVOBGP_BIRDC_SOCKET (poll метрик birdc).
-FROM golang:1.22-bookworm AS build
+# Базовые образы из ECR Public (официальное зеркало library/*), чтобы CI не зависел от auth.docker.io.
+FROM public.ecr.aws/docker/library/golang:1.22-bookworm AS build
 WORKDIR /src
 COPY go.mod go.sum ./
 RUN go mod download
@@ -8,7 +9,7 @@ COPY . .
 ARG BIN=evobgp-api
 RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/evobgp ./cmd/${BIN}

-FROM debian:bookworm-slim
+FROM public.ecr.aws/docker/library/debian:bookworm-slim
 ARG INSTALL_BIRDC=0
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates \
  && if [ "$INSTALL_BIRDC" = "1" ]; then apt-get install -y --no-install-recommends bird2; fi \
@@ -13,7 +13,7 @@
 | Раздел | Описание |
 |--------|----------|
 | [overview.md](overview.md) | Ключевые возможности системы |
-| [quickstart.md](quickstart.md) | Быстрый запуск: Docker, локальный Go, веб |
+| [quickstart.md](quickstart.md) | Быстрый запуск: готовые образы из `git.shts.su`, Docker Compose, локальный Go, веб |
 | [architecture.md](architecture.md) | Компоненты, потоки данных, пакеты |
 | [api.md](api.md) | REST: префикс `/v1`, публичные маршруты, ссылки на OpenAPI |
 | [access.md](access.md) | Выдача доступа: API-ключи, роли, нода, CORS |
@@ -65,6 +65,7 @@ CLI `evobgp-node` поддерживает `pull-bundle`, `verify-bundle`, `appl

 ## Связанные документы

+- [quickstart.md](quickstart.md) — Docker Compose, **готовые образы из Container Registry** (`docker pull git.shts.su/...`) без сборки на сервере.
 - [api.md](api.md) — как вызывать API на практике.
 - [architecture.md](architecture.md) — из каких процессов и пакетов это собрано.
 - [evobgp-api-sketches.md](evobgp-api-sketches.md) — ранние таблицы эндпоинтов (черновик).
@@ -9,6 +9,62 @@
 - **Node.js** и npm — для разработки веб-интерфейса в `web/`.
 - **PostgreSQL** — если запускаете API вне Compose; строка подключения в `EVOBGP_DATABASE_URL`.

+## Готовые образы без сборки (Container Registry Gitea)
+
+После успешного CI (push в `main` или `master`) образы публикуются в **Container Registry** вашего Gitea. В workflow зафиксирован хост реестра **`git.shts.su`**; имя владельца в пути образа — **в нижнем регистре**, как у `github.repository_owner` в CI (например, пользователь `Denozord` → префикс `denozord`).
+
+### Шаблон имени и теги
+
+```text
+git.shts.su/<owner>/<имя_образа>:<тег>
+```
+
+**Теги:** `latest`, короткий SHA коммита (7 символов), `sha-<полный_sha>` — см. [.gitea/README.md](../.gitea/README.md).
+
+**Платформа образов из CI:** `linux/amd64` (на другой архитектуре pull пройдёт, но запуск может быть невозможен без своей сборки).
+
+### Вход в реестр (если пакеты не публичные)
+
+На сервере или в PowerShell перед `docker pull`:
+
+```powershell
+docker login git.shts.su
+```
+
+Укажите учётную запись Gitea и **PAT / пароль приложения** с правом чтения пакетов (или токен, который принимает ваш реестр).
+
+### Ссылки и команды `docker pull`
+
+Ниже пример для владельца **`denozord`** — замените сегмент пути на своего владельца репозитория в нижнем регистре. В веб-интерфейсе все контейнерные пакеты можно открыть разом: [список пакетов `denozord` на git.shts.su](https://git.shts.su/denozord/-/packages). Если прямая ссылка на версию `latest` не открывается (зависит от версии Gitea), откройте общий список пакетов и выберите нужный образ по имени.
+
+| Образ | Назначение | Страница пакета (пример) | Pull |
+|--------|------------|--------------------------|------|
+| `evobgp-api` | HTTP API (с `birdc` в образе) | [packages/…/evobgp-api](https://git.shts.su/denozord/-/packages/container/evobgp-api/latest) | `docker pull git.shts.su/denozord/evobgp-api:latest` |
+| `evobgp-all` | Монолит microVPS: API + заглушки воркеров в одном процессе | [packages/…/evobgp-all](https://git.shts.su/denozord/-/packages/container/evobgp-all/latest) | `docker pull git.shts.su/denozord/evobgp-all:latest` |
+| `evobgp-scheduler` | Планировщик (reference) | [packages/…/evobgp-scheduler](https://git.shts.su/denozord/-/packages/container/evobgp-scheduler/latest) | `docker pull git.shts.su/denozord/evobgp-scheduler:latest` |
+| `evobgp-ingest` | Ingest CDN / ETag | [packages/…/evobgp-ingest](https://git.shts.su/denozord/-/packages/container/evobgp-ingest/latest) | `docker pull git.shts.su/denozord/evobgp-ingest:latest` |
+| `evobgp-render` | Render | [packages/…/evobgp-render](https://git.shts.su/denozord/-/packages/container/evobgp-render/latest) | `docker pull git.shts.su/denozord/evobgp-render:latest` |
+| `evobgp-deploy` | Deploy | [packages/…/evobgp-deploy](https://git.shts.su/denozord/-/packages/container/evobgp-deploy/latest) | `docker pull git.shts.su/denozord/evobgp-deploy:latest` |
+| `evobgp-node` | Нода на площадке | [packages/…/evobgp-node](https://git.shts.su/denozord/-/packages/container/evobgp-node/latest) | `docker pull git.shts.su/denozord/evobgp-node:latest` |
+| `evobgp-web` | Статика UI + nginx | [packages/…/evobgp-web](https://git.shts.su/denozord/-/packages/container/evobgp-web/latest) | `docker pull git.shts.su/denozord/evobgp-web:latest` |
+| `evobgp-agent` | Агент (bird2 в образе) | [packages/…/evobgp-agent](https://git.shts.su/denozord/-/packages/container/evobgp-agent/latest) | `docker pull git.shts.su/denozord/evobgp-agent:latest` |
+| `evobgp-bird2` | Только BIRD2 | [packages/…/evobgp-bird2](https://git.shts.su/denozord/-/packages/container/evobgp-bird2/latest) | `docker pull git.shts.su/denozord/evobgp-bird2:latest` |
+
+На **Linux-сервере** команды `docker pull` и `docker login` такие же (выполняйте в обычном shell).
+
+### Запуск контейнера с готового образа (минимум)
+
+После pull, например только API (порты и переменные подставьте свои):
+
+```powershell
+docker run --rm -p 8080:8080 `
+  -e EVOBGP_DATABASE_URL="postgres://user:pass@host:5432/evobgp?sslmode=disable" `
+  -e EVOBGP_HTTP_ADDR=":8080" `
+  git.shts.su/denozord/evobgp-api:latest
+```
+
+Для полного стека удобнее **Compose** из репозитория: по умолчанию он собирает из исходников (`--build`). Чтобы использовать **уже скачанные** образы из реестра, задайте в override-файле или правке `deploy/compose/docker-compose.yaml` у сервисов поле **`image:`** вместо **`build:`** с тем же префиксом `git.shts.su/<owner>/...` и тегом (`:latest` или зафиксированный `:sha-...` для воспроизводимости). Подробности CI и имён — [.gitea/README.md](../.gitea/README.md).
+
 ## Вариант 1: Docker, профиль microvps

 Один процесс `evobgp-all` (HTTP API + in-process заглушки воркеров), PostgreSQL, BIRD2, `evobgp-agent`.