seedex-agent

Эта страница описывает, как устроен репозиторий seedex-agent и как его собирать и линтить.

Требования

  • Go 1.22 для сборки Link API.
  • shfmt 3.13 и shellcheck 0.11 для линта.
  • Сервер на Ubuntu 24.04 или новее, чтобы установить сборку.

Структура проекта

  • sdx: команда: диспетчер, статус, help и firewall.
  • lib/common.sh: общие вспомогательные функции: файрвол, systemd и логирование.
  • lib/vpn.sh, lib/proxy.sh и lib/link.sh: по библиотеке на сервис. vpn.sh загружает модули протоколов из lib/vpn/ и передаёт им действия.
  • lib/vpn/awg.sh и lib/vpn/wg.sh: модули VPN-протоколов. Каждый определяет функции vpn_<proto>_<action>; оба опираются на lib/wireguard.sh, общий код семейства WireGuard, а awg.sh добавляет параметры обфускации и установку из PPA.
  • link/main.go: Link API: GET /v1/configs и POST /v1/run.
  • install.sh: скрипт, который запускают пользователи. Он скачивает релиз, если запущен не из клона.
  • version: версия.

Сборка

Выполните команду:

make build

Команда собирает seedex-link для amd64 и arm64 в build/ вместе с архивом релиза и checksums.txt.

Чтобы установить сборку на сервер, скопируйте sdx, version, lib, install.sh и build на сервер и выполните там bash install.sh files. Режим files обновляет скрипты и бинарник существующей установки.

Линт

make lint прогоняет shfmt и shellcheck по shell-файлам, а gofmt и go vet — по коду на Go.

Участие

Сообщения об ошибках, предложения и пул-реквесты приветствуются. Оригинал этого раздела на английском — CONTRIBUTING.md в репозитории.

Сообщить об ошибке

Откройте issue и укажите:

  • Версию Ubuntu.
  • Вывод sdx version, sdx, а также лог затронутого сервиса: journalctl -u seedex-vpn-awg, -u seedex-vpn-wg, -u sing-box или -u seedex-link.
  • Что вы сделали, чего ожидали и что произошло вместо этого.

Перед публикацией уберите из вывода ключи, токены, отпечатки сертификатов и публичные IP-адреса.

Предложить изменение

Для небольшого исправления откройте пул-реквест. Для новой функции или изменения поведения сначала откройте issue, чтобы договориться о подходе до того, как вы потратите на него время.

Стиль кода

  • Shell-код — bash, он выполняется только на сервере.
  • Форматирование задают shfmt, gofmt и .editorconfig: табы, строки до 100 символов.
  • Каждый shell-файл проходит shellcheck с правилами из .shellcheckrc. Не добавляйте # shellcheck disable, чтобы заглушить предупреждение, которое можно исправить.
  • Link API в link/ — Go только со стандартной библиотекой. Так и оставьте: это один бинарник, который скачивает установщик.
  • Следуйте окружающему коду: именованию, плотности комментариев и способу сообщать об ошибках.

Проверка

Перед пушем запустите make lint (см. Линт); CI выполняет ту же цель на каждый push и пул-реквест. Автоматических тестов нет: соберите через make build, установите на сервер через bash install.sh files, проверьте изменение: затронутые команды sdx, а также соединённый роутер, если оно касается того, что отдаёт Link API. Напишите в пул-реквесте, что вы проверили.

Коммиты

  • Одна тема на коммит. Последующие исправления складывайте в тот коммит, который они исправляют, а не добавляйте вторым.
  • Заголовок — строчными буквами, в настоящем времени, начинается с области: proxy: start without protocols is a no-op, link: run sdx over the API, vpn: protocol modules, wg and awg. Области — сервисы (vpn, proxy, link), install, lint и docs.
  • Не меняйте version. Мейнтейнеры поднимают версию через make bump при релизе; тег v* собирает релиз.

Пул-реквесты

  • Целевая ветка — main; изменение должно быть достаточно небольшим, чтобы его можно было просмотреть за один раз.
  • Опишите, что делает изменение и зачем. Если есть issue, сошлитесь на него.
  • Изменение видимого пользователю поведения меняет и документацию: README в репозитории и страницы в seedex-docs, где русская версия зеркальна английской.
  • CI должен проходить.

Лицензия

Вклад принимается на условиях лицензии проекта AGPL-3.0. Название и логотип Seedex регулируются политикой товарных знаков, а не лицензией.

Последнее обновление