Merge dev: virtual node UX polish + critical fixes

Author: ddddeadispose

index.js

@@ -475,6 +475,23 @@ async function startServer() {
             // Index already dropped or never existed — safe to ignore
         }
 
+        // Migration: rebuild compound {ip, type} unique index when it exists
+        // without a partial filter expression. Virtual nodes have ip=null, so the
+        // unique constraint must skip non-string ip values; Mongoose will not
+        // rewrite an existing index with new options on its own.
+        try {
+            const indexes = await mongoose.connection.collection('hynodes').indexes();
+            const ipType = indexes.find(idx => idx.name === 'ip_1_type_1');
+            if (ipType && !ipType.partialFilterExpression) {
+                await mongoose.connection.collection('hynodes').dropIndex('ip_1_type_1');
+                logger.info('[Migration] Dropped legacy ip_1_type_1 (non-partial) index');
+                await HyNode.syncIndexes();
+                logger.info('[Migration] Recreated hynodes indexes with partialFilterExpression');
+            }
+        } catch (e) {
+            logger.warn(`[Migration] hynodes index sync skipped: ${e.message}`);
+        }
+
         // Migration: ensure all users have xrayUuid (for Xray VLESS support)
         const usersWithoutUuid = await HyUser.find({
             $or: [{ xrayUuid: { $exists: false } }, { xrayUuid: null }, { xrayUuid: '' }]

src/docs/i18n.js

@@ -17,7 +17,8 @@ module.exports = {
 3. Получить общую статистику через \`GET /stats\` и статус ноды через \`GET /nodes/{id}/status\`.
 4. Отключить истёкшего пользователя через \`POST /users/{userId}/disable\` и очистить устройства через \`DELETE /users/{userId}/devices\`.
 5. Собрать multi-hop маршрут через \`POST /cascade/links\`, затем развернуть цепочку через \`POST /cascade/chain/deploy\`.
-6. Автоматизировать действия панели через MCP: \`POST /mcp\` и \`tools/list\`.
+6. Объединить несколько реальных нод в один авто-балансировщик через \`POST /nodes\` (\`type=virtual\`); HAPP/Xray-core клиенты получат Xray balancer + observatory профиль, sing-box/Clash — \`urltest\`/\`url-test\` группу.
+7. Автоматизировать действия панели через MCP: \`POST /mcp\` и \`tools/list\`.
 
 ## Аутентификация
 
@@ -181,23 +182,28 @@ JSON-эндпоинты возвращают ошибки в таком форм
             },
             'POST /nodes': {
                 summary: 'Создать ноду',
-                description: 'Создаёт Hysteria или Xray ноду; `statsSecret` генерируется сервером. 409 — если на том же IP уже есть нода того же `type`. Требуется скоуп `nodes:write`.',
+                description: `Создаёт **Hysteria**, **Xray** или **Virtual** (балансировщик) ноду. \`statsSecret\` генерируется сервером.
+
+- \`type=hysteria\` (по умолчанию) / \`type=xray\` — обязателен \`ip\`. 409, если на том же IP уже есть нода того же \`type\`.
+- \`type=virtual\` — логический балансировщик поверх реальных соседних нод. **Не передавайте** \`ip\` или \`ssh\`; передайте объект \`virtual\` с \`sources\` (или \`sourceGroup\`) и \`strategy\`. Виртуальные ноды не запускают setup, health-check, traffic collection и restart — они появляются только в подписках.
+
+Требуется скоуп \`nodes:write\`.`,
             },
             'GET /nodes/{id}': {
                 summary: 'Получить ноду по ID',
                 description: 'Возвращает ноду с группами и количеством активных пользователей. Требуется скоуп `nodes:read`.',
             },
             'PUT /nodes/{id}': {
                 summary: 'Обновить ноду',
-                description: 'Частично обновляет настройки ноды и планирует отправку конфига при изменениях. Требуется скоуп `nodes:write`.',
+                description: 'Частично обновляет настройки ноды и планирует отправку конфига при изменениях. При смене `type` на `virtual` нужно передать корректный объект `virtual`; `ip` будет автоматически очищен. При результирующем `type ≠ virtual` поле `ip` (унаследованное или переданное) должно быть непустым. Требуется скоуп `nodes:write`.',
             },
             'DELETE /nodes/{id}': {
                 summary: 'Удалить ноду',
                 description: 'Удаляет ноду и убирает её из назначений пользователей. Требуется скоуп `nodes:write`.',
             },
             'GET /nodes/check-ip': {
                 summary: 'Проверить соседние ноды по IP',
-                description: 'Возвращает Hysteria/Xray ноды на том же IP. Используется интерфейсом при добавлении ноды.',
+                description: 'Возвращает Hysteria/Xray ноды на том же IP. Используется интерфейсом при добавлении ноды. Виртуальные ноды не имеют IP и в выдаче не появляются.',
             },
             'GET /nodes/{id}/status': {
                 summary: 'Получить сохранённый статус ноды',
@@ -213,11 +219,11 @@ JSON-эндпоинты возвращают ошибки в таком форм
             },
             'POST /nodes/{id}/sync': {
                 summary: 'Синхронизировать конкретную ноду',
-                description: 'Отправляет актуальный конфиг на ноду через SSH.',
+                description: 'Отправляет актуальный конфиг на ноду через SSH. Виртуальные ноды возвращают **400** — у них нет удалённого сервиса.',
             },
             'POST /nodes/{id}/setup': {
                 summary: 'Автонастройка ноды через SSH',
-                description: 'Настройка через SSH: для Hysteria — установка бинарника, конфиг, port hopping, перезапуск `hysteria-server`; для Xray — setup агента (из body используется только `restartService`). Обычно 30 секунд — 2 минуты; таймаут клиента ≥ 3 минуты. Нужны SSH-данные на ноде. Успех: `{ success, logs }`, ошибка: `500` с `{ success: false, error, logs }`.',
+                description: 'Настройка через SSH: для Hysteria — установка бинарника, конфиг, port hopping, перезапуск `hysteria-server`; для Xray — setup агента (из body используется только `restartService`). Виртуальные ноды возвращают **400** — у них нет удалённого сервиса для настройки. Обычно 30 секунд — 2 минуты; таймаут клиента ≥ 3 минуты. Нужны SSH-данные на ноде. Успех: `{ success, logs }`, ошибка: `500` с `{ success: false, error, logs }`.',
             },
             'GET /nodes/{id}/config': {
                 summary: 'Получить сгенерированный конфиг ноды',