Инструкция по добавлению сайтов

RU версия

1) Массовое добавление сайтов в систему

Рабочая схема: готовите CSV/JSON, валидируете домены, отправляете батчами по API, затем ретраите только ошибки.

curl -X POST "https://YOUR_PANEL_HOST/api/sites/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sites":[{"domain":"example.com","type":"WORDPRESS"}]}'

1.1) Альтернатива: управление сайтами через MCP

Если вы работаете через AI-бота (Codex/Claude Code), можно подключить MCP-сервер и выполнять те же операции по сайтам/проектам из диалога.

Пошаговое подключение: FAQ: MCP подключение.

Важно: MCP использует тот же backend API. На Starter/Trial MCP работает только в режиме чтения, полный MCP-доступ доступен с Pro+. Проверка: link_manager_mcp_status → mcp_tier. Актуальные лимиты: /pricing.

2) WordPress: как обновлять плагин массово

Плагин сам публикует метаданные обновлений, но фактическую установку делает WordPress: вручную через Plugins/Updates, через auto-updates WordPress или через WP-CLI. Для массовых обновлений используйте WP-CLI.

2.1) Какие права нужны WordPress-пользователю

Обычный single-site: роль Administrator.
WordPress Multisite: Super Admin.
Если роль кастомная, у неё должны быть как минимум capability: manage_options, activate_plugins, update_plugins.

Почему: в самом плагине страница настроек и admin-AJAX требуют manage_options, notice о миграции проверяет activate_plugins, а экран обновлений WordPress использует update_plugins.

2.2) Какие права нужны системному пользователю сервера

Запускайте wp от того же Unix-пользователя, который владеет файлами сайта.
Не используйте root и --allow-root как стандартный сценарий, если сайт не принадлежит root целиком.
wp-content/plugins и временная директория WordPress должны быть доступны на запись этому пользователю.

chown -R <system_user>:<system_user> /path/to/site
find /path/to/site -type d -exec chmod 755 {} \;
find /path/to/site -type f -exec chmod 644 {} \;

Если WordPress во время обновления просит FTP-доступ, почти всегда проблема в owner/group или в том, что PHP/WP-CLI работают от другого системного пользователя.

2.3) Массовое обновление через WP-CLI

Формат файла sites-paths.tsv: /absolute/path/to/site[TAB]system_user.

while IFS=$'\t' read -r SITE_PATH SITE_USER; do
  [ -n "$SITE_PATH" ] || continue

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" core is-installed || {
    echo "skip: $SITE_PATH (not a WP install)"
    continue
  }

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin install /opt/releases/link-manager-widget.zip --force --activate
  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin is-active link || \
    sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin activate link

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin list | grep -Ei "^(link|link-manager-widget)\\s"
done < sites-paths.tsv

При желании можно сразу включить будущие автообновления WordPress:

sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin auto-updates enable link

2.4) Разовая миграция со старой папки плагина

Для старых сайтов с версией <= 2.8.19 возможен one-time переход из /wp-content/plugins/link-manager-widget/ в /wp-content/plugins/link/.

Если после обновления WordPress показывает две копии плагина, активируйте копию из link/.
Проверьте настройки, API-связь и публичный рендер виджета.
После проверки удалите старую неактивную папку link-manager-widget/.

3) Разбивка ссылок по нескольким виджетам

Для суммарного вывода 10 ссылок используйте схему 3 + 3 + 4 между блоками сайдбара.

wp --path="$SITE_PATH" widget list sidebar-1

4) Статичные сайты

Публикуйте сайты как STATIC, подключайте общий include/snippet и проверяйте HTTP-ответы страниц/картинок после выкладки.

6) Ошибки, которые проверять первыми

Неверный token/просроченный token/нет прав у токена.
Неправильный --path в WP-CLI (команда выполняется не в том сайте).
Дубликат домена в системе.
Старая версия из кеша (object/page/CDN).
Недостаточно прав записи у системного пользователя.
WordPress просит FTP-учётку вместо прямого обновления.
После апдейта остались одновременно link/ и link-manager-widget/.

Для массовых операций фиксируйте лог в формате: domain + request_id + status + error_message. Это ускоряет повторные отправки и разбор инцидентов.

EN version

1) Bulk site onboarding

Use CSV/JSON input, validate domains first, submit in batches, then retry failed records only.

curl -X POST "https://YOUR_PANEL_HOST/api/sites/bulk" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sites":[{"domain":"example.com","type":"WORDPRESS"}]}'

1.1) Alternative: site operations via MCP

If you operate through an AI bot (Codex/Claude Code), connect MCP server and manage site/project workflows from chat.

Step-by-step setup: FAQ: MCP setup.

Important: MCP uses the same backend API. On Starter/Trial, MCP is read-only; full MCP is available from Pro+. Check with link_manager_mcp_status → mcp_tier. Current limits: /pricing.

2) WordPress: how to update the plugin in bulk

The plugin publishes update metadata, but the actual installation is still performed by WordPress: manually from Plugins/Updates, via WordPress auto-updates, or via WP-CLI. For bulk operations, use WP-CLI.

2.1) Required WordPress user permissions

Regular single-site WordPress: Administrator.
WordPress Multisite: Super Admin.
If you use a custom role, it should include at least manage_options, activate_plugins, and update_plugins.

Why: the plugin settings page and admin AJAX require manage_options, the install-dir migration notice checks activate_plugins, and the native WordPress update UI relies on update_plugins.

2.2) Required server-side filesystem permissions

Run wp as the same Unix user that owns the site files.
Do not normalize on root or --allow-root unless the whole site is actually owned by root.
wp-content/plugins and the WordPress temp/upgrade directory must be writable by that user.

chown -R <system_user>:<system_user> /path/to/site
find /path/to/site -type d -exec chmod 755 {} \;
find /path/to/site -type f -exec chmod 644 {} \;

If WordPress prompts for FTP credentials during an update, the most likely cause is wrong ownership/group or PHP/WP-CLI running under a different system user.

2.3) Bulk update via WP-CLI

Use a sites-paths.tsv file with /absolute/path/to/site[TAB]system_user per line.

while IFS=$'\t' read -r SITE_PATH SITE_USER; do
  [ -n "$SITE_PATH" ] || continue

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" core is-installed || {
    echo "skip: $SITE_PATH (not a WP install)"
    continue
  }

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin install /opt/releases/link-manager-widget.zip --force --activate
  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin is-active link || \
    sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin activate link

  sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin list | grep -Ei "^(link|link-manager-widget)\\s"
done < sites-paths.tsv

If you want future releases to install automatically through WordPress itself, optionally enable plugin auto-updates afterwards:

sudo -u "$SITE_USER" wp --path="$SITE_PATH" plugin auto-updates enable link

2.4) One-time legacy install-dir migration

Older sites on <= 2.8.19 may hit a one-time move from /wp-content/plugins/link-manager-widget/ to /wp-content/plugins/link/.

If WordPress shows two plugin entries after the update, activate the copy from link/.
Verify settings, API connectivity, and public widget rendering.
After verification, remove the old inactive link-manager-widget/ copy.

3) Sidebar widget split (total 10 links)

Recommended split across existing sidebar blocks: 3 + 3 + 4.

wp --path="$SITE_PATH" widget list sidebar-1

4) Static sites

6) First checks for failures

invalid/expired token or missing token scopes,
wrong WordPress root in --path,
duplicate domain,
cache serving stale output,
insufficient write permissions,
WordPress asking for FTP credentials instead of updating directly,
both link/ and link-manager-widget/ still present after update.

Keep operational logs with domain + request_id + status + error_message to make incident triage and retries deterministic.

Инструкция: массовое добавление сайтов (WordPress + статичные сайты)

Guide: Bulk Site Onboarding (WordPress + Static)