Initial commit: local_machine docs and scripts
This commit is contained in:
ahauimix
214
docs/cursor/README.md
Normal file
214
docs/cursor/README.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Cursor IDE — работа из РФ и обход PING timeout
|
||||
|
||||
> **Проблема:** из России Cursor показывает `PING timed out`, Agent не отвечает.
|
||||
> **Временный обход:** Disable Http2 в настройках — помогает, но всё сильно замедляется.
|
||||
> **Рекомендуемое решение:** SOCKS-прокси через SSH-туннель на сервер с нормальным доступом (DO / RU VPS), без отключения HTTP/2.
|
||||
|
||||
**Связанные гайды:** [PROXY_GUIDE.md](../../connectivity/PROXY_GUIDE.md), [BUILD_AAB_FROM_RUSSIA_GUIDE.md](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md) — тот же паттерн «туннель через прокси-сервер».
|
||||
|
||||
---
|
||||
|
||||
## Содержание
|
||||
|
||||
1. [Симптомы и причина](#-симптомы-и-причина)
|
||||
2. [Обход 1: Disable Http2 (простой, но медленный)](#-обход-1-disable-http2-простой-но-медленный)
|
||||
3. [Обход 2: SOCKS через SSH-туннель (рекомендуется)](#-обход-2-socks-через-ssh-туннель-рекомендуется)
|
||||
4. [Проверка и диагностика](#-проверка-и-диагностика)
|
||||
5. [Troubleshooting](#-troubleshooting)
|
||||
6. [Ссылки](#-ссылки)
|
||||
|
||||
---
|
||||
|
||||
## Симптомы и причина
|
||||
|
||||
### Что видно в Cursor
|
||||
|
||||
- В чате с Agent: **Request ID: … [unavailable] PING timed out**, `_he: [unavailable] PING timed out`.
|
||||
- Стек указывает на `workbench.desktop.main.js`, `streamFromAgentBackend` / `getAgentStreamResponse` — обрыв связи с бэкендом агента.
|
||||
|
||||
### Почему так происходит
|
||||
|
||||
1. **HTTP/2 и маршрутизация**
|
||||
Cursor использует HTTP/2 для стриминга к `*.cursor.sh` (в т.ч. `agent.api5.cursor.sh`). В части сетей (в т.ч. из РФ) запросы уходят в CDN (например Cloudflare) с неудачной конфигурацией SSL/HTTP2 или блокировкой по DPI, из‑за чего соединение обрывается или уходит в таймаут.
|
||||
|
||||
2. **Disable Http2**
|
||||
Отключение HTTP/2 переводит трафик на HTTP/1.1 и часто убирает обрывы, но увеличивает нагрузку и задержки — «всё становится медленным», возможны дополнительные таймауты агента.
|
||||
|
||||
3. **Идея нормального обхода**
|
||||
Пропускать только трафик Cursor через сервер с хорошим доступом к Cursor API (VPS в DO, РФ и т.п.). До этого сервера — SSH (обычно не режется). От сервера до `*.cursor.sh` — уже «нормальный» канал, HTTP/2 работает без костылей.
|
||||
|
||||
---
|
||||
|
||||
## Обход 1: Disable Http2 (простой, но медленный)
|
||||
|
||||
Если нужно быстро восстановить работу без настройки туннеля:
|
||||
|
||||
1. **Cursor → Settings** (Cmd+, / Ctrl+,).
|
||||
2. Поиск: **HTTP**.
|
||||
3. Включить **Cursor > General: Disable Http2**.
|
||||
|
||||
Минус: выше задержки и нагрузка, возможны таймауты агента при длинных ответах. Для постоянной работы из РФ предпочтительно [Обход 2](#-обход-2-socks-через-ssh-туннель-рекомендуется).
|
||||
|
||||
---
|
||||
|
||||
## Обход 2: SOCKS через SSH-туннель (рекомендуется)
|
||||
|
||||
Трафик Cursor идёт в интернет через ваш VPS. До VPS — SSH (один порт), с VPS — обычный доступ к Cursor API, HTTP/2 остаётся включённым.
|
||||
|
||||
### Схема
|
||||
|
||||
```
|
||||
Cursor (macOS) → SOCKS 127.0.0.1:10809 → SSH-туннель → VPS (DO/RU)
|
||||
↓
|
||||
HTTPS/HTTP2 → *.cursor.sh
|
||||
```
|
||||
|
||||
На VPS не нужны отдельные прокси-сервисы — достаточно SSH (как в [PROXY_GUIDE](../../connectivity/PROXY_GUIDE.md) и [BUILD_AAB_FROM_RUSSIA_GUIDE](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md)).
|
||||
|
||||
### Предположения
|
||||
|
||||
- Есть VPS с нормальным доступом к интернету (например, тот же, что для ru.hunab.app: **149.154.64.19**, доступ по `ssh hsites-ahau` или аналог).
|
||||
- Локально свободен порт для SOCKS (ниже — **10809**, чтобы не пересекаться с другими прокси).
|
||||
|
||||
### Шаг 1: Поднять SOCKS-туннель
|
||||
|
||||
```bash
|
||||
# Убить старый туннель на порту 10809 (если был)
|
||||
pkill -f "ssh.*-D 10809" 2>/dev/null
|
||||
|
||||
# Запуск SOCKS5 на 127.0.0.1:10809 через ваш VPS
|
||||
ssh -D 10809 -f -N hsites-ahau
|
||||
```
|
||||
|
||||
Если используете другой хост (например, hunab-prod):
|
||||
|
||||
```bash
|
||||
ssh -D 10809 -f -N hunab-prod
|
||||
```
|
||||
|
||||
Проверка: туннель держится, пока сессия не разорвана; можно проверить доступ через SOCKS (см. [Проверка и диагностика](#-проверка-и-диагностика)).
|
||||
|
||||
### Шаг 2: Настроить Cursor на использование SOCKS
|
||||
|
||||
1. **Cursor → Settings** (Cmd+, / Ctrl+,), поиск: **proxy**.
|
||||
2. Заполнить:
|
||||
- **Http: Proxy** — `socks5://127.0.0.1:10809`
|
||||
- **Http: Proxy Strict SSL** — при необходимости отключить только если заведомо знаете, что за прокси (для одного своего VPS обычно не требуется).
|
||||
|
||||
Или в `settings.json` (Cursor: Open User Settings (JSON)):
|
||||
|
||||
```json
|
||||
{
|
||||
"http.proxy": "socks5://127.0.0.1:10809",
|
||||
"https.proxy": "socks5://127.0.0.1:10809"
|
||||
}
|
||||
```
|
||||
|
||||
### Шаг 3: Не отключать HTTP/2
|
||||
|
||||
**Cursor > General: Disable Http2** — выключить (оставить HTTP/2 включённым). Весь трафик к Cursor API пойдёт с VPS, где HTTP/2 работает нормально.
|
||||
|
||||
### Шаг 4: Запуск Cursor при уже поднятом туннеле
|
||||
|
||||
Порядок каждый раз:
|
||||
|
||||
1. В терминале: `ssh -D 10809 -f -N hsites-ahau` (или ваш хост).
|
||||
2. Запуск Cursor как обычно.
|
||||
|
||||
Чтобы не забывать туннель, можно завести скрипт запуска (см. [Скрипт запуска с туннелем](#скрипт-запуска-с-туннелем)).
|
||||
|
||||
---
|
||||
|
||||
## Проверка и диагностика
|
||||
|
||||
### Туннель поднят
|
||||
|
||||
```bash
|
||||
# Должен слушать 10809
|
||||
lsof -i :10809
|
||||
# или
|
||||
nc -z 127.0.0.1 10809 && echo "OK"
|
||||
```
|
||||
|
||||
### Доступ к Cursor API через SOCKS (curl)
|
||||
|
||||
```bash
|
||||
curl -x socks5h://127.0.0.1:10809 -sI https://agent.api5.cursor.sh 2>&1 | head -5
|
||||
```
|
||||
|
||||
Успех: в ответе есть HTTP/2 или заголовки от сервера. Ошибка соединения или таймаут — туннель не работает или порт занят.
|
||||
|
||||
### Логи Cursor
|
||||
|
||||
При проблемах с подключением:
|
||||
|
||||
- **macOS:** `~/Library/Application Support/Cursor/logs/main.log`
|
||||
- Искать по `ERROR`, `PING`, `timeout`, `HTTP2`, `ECONNREFUSED`, `ETIMEDOUT`.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### После включения прокси Cursor вообще не подключается
|
||||
|
||||
- Убедиться, что туннель запущен: `lsof -i :10809`.
|
||||
- Проверить доступ через SOCKS: `curl -x socks5h://127.0.0.1:10809 -sI https://agent.api5.cursor.sh`.
|
||||
- Временно в настройках Cursor убрать `http.proxy` / `https.proxy` и проверить без прокси (например, с Disable Http2) — если так работает, проблема в туннеле или порте.
|
||||
|
||||
### PING timed out остаётся даже через прокси
|
||||
|
||||
- Перезапустить туннель и Cursor (полностью закрыть приложение и открыть снова).
|
||||
- В настройках Cursor убедиться, что **Disable Http2** выключен (HTTP/2 включён).
|
||||
- Проверить, что в настройках указан именно `socks5://127.0.0.1:10809` (без опечаток, порт совпадает с `-D 10809`).
|
||||
|
||||
### Порт 10809 занят
|
||||
|
||||
Выбрать другой порт, например 10810:
|
||||
|
||||
```bash
|
||||
ssh -D 10810 -f -N hsites-ahau
|
||||
```
|
||||
|
||||
И в настройках Cursor указать `socks5://127.0.0.1:10810`.
|
||||
|
||||
### Туннель рвётся при долгой неактивности
|
||||
|
||||
Поддерживать соединение помогут опции SSH:
|
||||
|
||||
```bash
|
||||
ssh -D 10809 -f -N -o ServerAliveInterval=30 -o ServerAliveCountMax=6 hsites-ahau
|
||||
```
|
||||
|
||||
При необходимости можно вынести эту команду в скрипт или systemd/supervisor на стороне клиента.
|
||||
|
||||
---
|
||||
|
||||
## Скрипт запуска туннеля
|
||||
|
||||
В репозитории есть скрипт для поднятия/остановки SOCKS-туннеля:
|
||||
|
||||
```bash
|
||||
# Из корня репо
|
||||
./docs/cursor/scripts/cursor-socks-tunnel.sh start # поднять туннель
|
||||
./docs/cursor/scripts/cursor-socks-tunnel.sh status # проверить
|
||||
./docs/cursor/scripts/cursor-socks-tunnel.sh stop # остановить
|
||||
```
|
||||
|
||||
Переменные окружения: `CURSOR_SOCKS_PORT` (по умолчанию 10809), `CURSOR_TUNNEL_HOST` (по умолчанию `hsites-ahau`).
|
||||
|
||||
**Запуск Cursor после туннеля (macOS):** после `./docs/cursor/scripts/cursor-socks-tunnel.sh start` откройте Cursor как обычно; при настроенных `http.proxy`/`https.proxy` трафик пойдёт через SOCKS.
|
||||
|
||||
---
|
||||
|
||||
## Ссылки
|
||||
|
||||
| Документ | Назначение |
|
||||
|----------|------------|
|
||||
| [PROXY_GUIDE.md](../../connectivity/PROXY_GUIDE.md) | Прокси ru.hunab.app, SSH ProxyCommand для scp/ssh на прод |
|
||||
| [BUILD_AAB_FROM_RUSSIA_GUIDE.md](../../connectivity/BUILD_AAB_FROM_RUSSIA_GUIDE.md) | Сборка AAB из РФ через Maven proxy + SSH-туннель |
|
||||
| [Cursor Forum — HTTP/2 network error](https://forum.cursor.com/t/http2-network-error-with-cursor-ide-and-cursor-cli/147318) | Обсуждение ошибок HTTP/2 и региональной маршрутизации |
|
||||
| [Cursor Forum — Agent timeouts when HTTP2 disabled](https://forum.cursor.com/t/agent-timeouts-much-more-when-http2-disabled/76517) | Таймауты агента при отключённом HTTP/2 |
|
||||
|
||||
---
|
||||
|
||||
*Последнее обновление: 2026-03-08*
|
||||
45
docs/cursor/scripts/cursor-socks-tunnel.sh
Executable file
45
docs/cursor/scripts/cursor-socks-tunnel.sh
Executable file
@@ -0,0 +1,45 @@
|
||||
#!/usr/bin/env bash
|
||||
# Поднимает SOCKS5-туннель для Cursor (обход PING timeout из РФ).
|
||||
# Использование: ./cursor-socks-tunnel.sh [start|stop|status]
|
||||
# См. docs/cursor/README.md
|
||||
|
||||
set -e
|
||||
CURSOR_SOCKS_PORT="${CURSOR_SOCKS_PORT:-10809}"
|
||||
SSH_HOST="${CURSOR_TUNNEL_HOST:-hsites-ahau}"
|
||||
|
||||
start() {
|
||||
if lsof -i :"$CURSOR_SOCKS_PORT" -sTCP:LISTEN -t >/dev/null 2>&1; then
|
||||
echo "SOCKS already listening on 127.0.0.1:$CURSOR_SOCKS_PORT"
|
||||
return 0
|
||||
fi
|
||||
ssh -D "$CURSOR_SOCKS_PORT" -f -N \
|
||||
-o ServerAliveInterval=30 \
|
||||
-o ServerAliveCountMax=6 \
|
||||
"$SSH_HOST"
|
||||
echo "SOCKS tunnel started: 127.0.0.1:$CURSOR_SOCKS_PORT -> $SSH_HOST"
|
||||
}
|
||||
|
||||
stop() {
|
||||
pkill -f "ssh.*-D $CURSOR_SOCKS_PORT.*$SSH_HOST" 2>/dev/null || true
|
||||
echo "Tunnel stopped (if it was running)."
|
||||
}
|
||||
|
||||
status() {
|
||||
if lsof -i :"$CURSOR_SOCKS_PORT" -sTCP:LISTEN -t >/dev/null 2>&1; then
|
||||
echo "SOCKS listening on 127.0.0.1:$CURSOR_SOCKS_PORT"
|
||||
lsof -i :"$CURSOR_SOCKS_PORT" -sTCP:LISTEN
|
||||
else
|
||||
echo "No SOCKS listener on port $CURSOR_SOCKS_PORT"
|
||||
fi
|
||||
}
|
||||
|
||||
case "${1:-start}" in
|
||||
start) start ;;
|
||||
stop) stop ;;
|
||||
status) status ;;
|
||||
*)
|
||||
echo "Usage: $0 {start|stop|status}"
|
||||
echo "Env: CURSOR_SOCKS_PORT=$CURSOR_SOCKS_PORT, CURSOR_TUNNEL_HOST=$SSH_HOST"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
Reference in New Issue
Block a user