Newer
Older
gnexus-book / 90-maintenance / pending-changes / 20261017122848-0efb0ff6.json
{
  "id": "20261017122848-0efb0ff6",
  "kind": "doc",
  "target": "10-systems/hosts/tgclientmcp.md",
  "summary": "tgclientmcp: blackout 2026-10-17 note; netplan static .171 restored (50-static.yaml, cloud-init disabled); TGCLIENT_SYNAPSE_URL rolled back to .172:8013; nginx upstream back to .171:8710",
  "reason": "После блэкаута 2026-10-16/17 VM получила DHCP-адрес .24; по решению владельца возвращена на .171 через netplan-статику внутри гостя (cloud-init network config отключён), TGCLIENT_SYNAPSE_URL откатан на .172:8013, nginx-апстрим на .171:8710 — health 200, 2/2 аккаунта connected",
  "payload": {
    "content": "---\ntitle: \"VPS tgclientmcp (tgclient-mcp)\"\ntype: host\nip: \"192.168.1.171\"\npurpose: \"tgclient-mcp — мульти-аккаунтный Telegram-клиент (Telethon) + MCP-сервер + SPA-админка в home LAN\"\nowner: gmikcon\nstatus: active\nconfidence: \"90\"\nlast_reviewed: \"2026-10-17\"\nreview_interval: \"90d\"\nsource_of_truth: \"ssh-host-and-owner-confirmed\"\n---\n\n# VPS tgclientmcp (tgclient-mcp)\n\n## Overview\n\nHome LAN VPS (KVM/QEMU guest). Выделен владельцем 2026-10-05 из свободного\nдиапазона 192.168.1.170–180 (скан nmap: свободны были .171/.174/.180).\nХостит **tgclient-mcp** — Telegram-клиент формата MCP для экосистемы Gnexus:\nмульти-аккаунтный MTProto юзер-клиент (Telethon), MCP-сервер для ИИ-агентов\n(`/mcp-protocol/`) и SPA-админка с персональными MCP-токенами.\n\n## Technical Details\n\n- **IP:** 192.168.1.171 (статический, netplan внутри гостя с 2026-10-17)\n- **Hostname:** tgclientmcp\n- **MAC:** 52:54:00:6d:8d:86 (virsh, bserv)\n- **OS:** Ubuntu 22.04.5 LTS\n- **Platform:** KVM guest, 1.9 GiB RAM, 15G root disk (47% занято на деплой)\n- **User:** ubuntu (SSH + sudo, пароль getroot88)\n- **Firewall:** ufw не активен\n- **Docker:** 29.1.3 (предустановлен), docker compose plugin 2.40.3 (пакет\n  docker-compose-v2 установлен 2026-10-05 navi rei)\n\n## tgclient-mcp (deployed 2026-10-05, updated 2026-10-06 ×4, 2026-10-07)\n\n- **Repo:** /home/ubuntu/tgclient-mcp\n  (https://git.gnexus.space/git/root/tgclient-mcp.git), branch `master`,\n  HEAD df2492b (обновлено 2026-10-07 navi rei; история обновлений:\n  2026-10-06 — edbd2e2 QR-вход, f4b1da9 фиксы логина, 0fc015e SPA-табы\n  логин-визарда, ac8b764 SPA-фиксы; 2026-10-07 — e269bfb+5cc14e3\n  MCP runtime-аудит, 004db72 фикс _touch, df2492b фильтр аккаунтов;\n  все — git pull --ff-only + sudo docker compose up -d --build, health ok)\n- **Stack:** docker compose, один сервис `tgclient` (multi-stage build:\n  SPA node:22-slim → backend python:3.12-slim + uvicorn), volume `data:/data`\n  (SQLite aiosqlite WAL — единственное состояние)\n- **Port:** 8710 (host) → 8000 (container), 0.0.0.0\n- **Public URL:** https://tgclientmcp.gnexus.space (TLS на internal-proxy-vps\n  .183, отдельный LE-сертификат до 2027-01-03; upstream http://192.168.1.171:8710)\n- **Endpoints:**\n  - SPA: https://tgclientmcp.gnexus.space/ (200 text/html)\n  - health: https://tgclientmcp.gnexus.space/api/v1/health →\n    `{\"status\":\"ok\",\"version\":\"0.1.0\",\"accounts\":{...},\"db\":\"ok\"}`\n  - MCP: https://tgclientmcp.gnexus.space/mcp-protocol/ (streamable HTTP,\n    stateless + json_response; initialize без токена → 200 с serverInfo\n    tgclient; тулы требуют Bearer `mcp_*` или admin-токен)\n- **Config:** /home/ubuntu/tgclient-mcp/.env (chmod 600, из .env.example).\n  - **Telegram API заполнены 2026-10-05** (владелец получил на my.telegram.org,\n    физлицо, бесплатно; апка-регистрация старая — CONAssistantApp, ~8 лет,\n    это нормально: api_id идентифицирует приложение, не аккаунт):\n    TGCLIENT_API_ID=24357013, TGCLIENT_API_HASH — в .env и в gnexus-creds\n    secret \"tgclient-mcp Telegram API (api_id/api_hash)\"\n    (id d5d70390-a058-4399-add8-539d71c9e1de). Один набор на деплой.\n  - **SSO gnexus-auth настроен 2026-10-05** (креды выдал владелец):\n    TGCLIENT_AUTH_BASE_URL=https://auth.gnexus.space,\n    TGCLIENT_AUTH_CLIENT_ID=gnx_207OcTjCYgqSQJwuTO2V5ks0EB1GftA0,\n    TGCLIENT_AUTH_REDIRECT_URI=https://tgclientmcp.gnexus.space/auth/callback,\n    client_secret и webhook secret — в .env и в gnexus-creds secret\n    \"tgclient-mcp SSO gnexus-auth (OAuth client)\"\n    (id 935a3ff1-f9c5-4738-9da5-83fdafb5fd70).\n    TGCLIENT_AUTH_ALLOWLIST пуст — пускается любой залогиненный gnexus-auth.\n  - **Synapse-репортер настроен 2026-10-07** (см. «Интеграция с Synapse»).\n  - Всё ещё НЕ заполнен: TGCLIENT_ADMIN_TOKEN.\n  - GOTCHA: `TGCLIENT_API_ID=` пустая строка ломает pydantic int — при\n    ротации не оставлять строку пустой, комментировать или вписывать число.\n- **Креды хоста:** gnexus-creds secret \"tgclient-mcp host SSH (192.168.1.171)\"\n  (id 70fb91b3-85f0-479c-9ecb-ba009299417f).\n\n## Аккаунты (2026-10-06)\n\n- **Аккаунт владельца залогинен 2026-10-06 через QR-вход** (edbd2e2):\n  phone +380632912932, username sukhodolskiy, display_name\n  «Eugene Suhodolskiy», status active, id 1 в БД. Первая попытка QR\n  («произошла ошибка» на Android при скане) не прошла — вероятная причина:\n  скан протухшего токена (TTL ~30 с) или гонка первой попытки; повторный\n  QR-логин через свежий POST /accounts/logins/qr прошёл успешно.\n- **Аккаунт Navi (id 2)**: phone +380939126548, display_name «Navi»,\n  tg_user_id 8781031814, status active — бот-аккаунт для агентских сценариев.\n- Клиент пула подключается лениво при первом использовании — health\n  показывает connected: 0 до первой операции с аккаунтом, это норма\n  (после логина владельца показывает connected: 1).\n\n## SSO flow (verified 2026-10-05)\n\n- `GET /auth/login` → 302 на\n  `https://auth.gnexus.space/oauth/authorize?response_type=code&client_id=…&redirect_uri=https%3A%2F%2Ftgclientmcp.gnexus.space%2Fauth%2Fcallback&state=…&code_challenge=…&code_challenge_method=S256&scope=openid+email+profile+roles+permissions&return_to=/`\n  (PKCE S256; gnexus-auth показывает страницу Sign in — клиент принят).\n- `GET /auth/callback?code&state` — обмен кода (client_secret + PKCE\n  verifier), сессия в cookie (secure, т.к. redirect_uri https), redirect на\n  return_to. Фейковый state → 400 «Invalid or expired OAuth state».\n- `POST /webhooks/gnexus-auth` (+ вариант с trailing slash) — события\n  gnexus-auth (HMAC-подпись через TGCLIENT_AUTH_WEBHOOK_SECRET); без подписи\n  → 401 «invalid webhook signature».\n- Внутренние httpx-запросы к gnexus-auth идут с verify=False (сервис в LAN,\n  TLS терминируется на internal-proxy) — это осознанное решение из кода репо.\n- Подключение агента: `claude mcp add --transport http tgclient\n  https://tgclientmcp.gnexus.space/mcp-protocol/ --header \"Authorization: Bearer mcp_...\"`\n\n## Deploy fixes & features (2026-10-05, rei) — закоммичены в репо\n\n1. **backend/Dockerfile:** `COPY frontend/package.json frontend/.npmrc ./` —\n   не копировался `package-lock.json`, `npm ci` падал. Исправлено:\n   `COPY frontend/package.json frontend/package-lock.json frontend/.npmrc ./`.\n2. **backend/app/tg/manager.py:** `NameError: TelegramClient` — класс\n   используется в аннотациях, но не импортирован. Исправлено:\n   `from telethon import TelegramClient, errors`.\n3. **backend/app/mcp/server.py:** FastMCP (mcp-sdk 1.30.0) при дефолтном\n   host=127.0.0.1 автоматически включает DNS-rebinding защиту с\n   allowed_hosts только 127.0.0.1/localhost/[::1] — любой запрос через\n   домен получал 421 «Invalid Host header». Исправлено: в конструктор\n   FastMCP добавлен\n   `transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False)`\n   (сервис за nginx с собственным гардом require_mcp — защита не нужна).\n4. **backend/app/tg/login_flow.py:** `AttributeError:\n   'TelegramClientWithSession' object has no attribute 'session'` — враппер\n   логин-клиента не экспонировал `.session`, `_finalize` падал сразу после\n   успешного sign_in (Telegram авторизацию засчитывал, сессия терялась,\n   аккаунт не записывался в БД). Исправлено: добавлен\n   `@property session → self._client.session`. Попутно добавлен\n   диагностический лог `[login] send_code_request ok: sent=…` (тип доставки\n   кода от Telegram — SentCodeTypeApp/SentCodeTypeSms/Call).\n5. **Фича: автоотмена зависших логинов** (запрос владельца: «если через\n   15 минут начала процесса входа сессия так и не была создана — отменить»).\n   Фоновый sweeper `login_sweeper_loop` (main.py, интервал 30 с, таск в\n   lifespan с graceful cancel) каждые 30 с вызывает\n   `login_flow.purge_stale_logins()`: pending-логины старше\n   `TGCLIENT_LOGIN_STALE_MINUTES` (config.py, default 15) минут от\n   `created_at` отменяются как ручная DELETE — `_cleanup` (строка в БД +\n   disconnect-логика, иначе зомби-коннект к Telegram), лог\n   `[login] auto-cancel stale login <id> (age > 15m, step=…)`.\n   `auth.purge_expired` больше НЕ удаляет login_sessions — sweeper\n   единственный владелец их очистки (GC по expires_at disconnect не делал).\n   Верифицировано живым тестом: тестовая строка с created_at=now-20min\n   вычищена sweeper'ом за 40 с, лог подтверждён.\n\nВсе пять изменений закоммичены в репо 2026-10-05: 77bded2 (деплой-фиксы +\nsweeper), 7d64d8a (отмена логина инвалидирует код у Telegram через\nauth.cancelCode, а не только чистит строку; sweeper отменяет так же; фронт —\nошибка отмены не глотается: тост + модалка не закрывается на неудаче).\nРабочая копия на хосте чистая, `git pull --ff-only` проходит без конфликтов\n(проверено всеми обновлениями 2026-10-06 и 2026-10-07).\n\n## Обновления 2026-10-06 (задеплоены navi rei)\n\n**День — edbd2e2, QR-вход:**\n- Новый эндпоинт/MCP-тул `account_login_qr_start` + SPA «Вход по QR» —\n  вход через QR-код (telethon qr_login), коды Telegram не используются —\n  обходит PHONE_CODE_FLOOD.\n- Резидентный waiter qr.wait/recreate; 2FA — через обычный password-шаг;\n  отмена/сгорание QR чистят waiter.\n\n**Вечер — f4b1da9, ревью логина (4 коммита):**\n- b00ec83: cancelCode/qr.recreate под wait_for (5с/10с) — DELETE отмены на\n  полумёртвом MTProto-коннекте висел вечно, кнопка «Отменить логин»\n  выглядела мёртвой ровно тогда, когда код не приходил.\n- de74028: лимит 3 pending-логина считает только живые (expires_at>now) —\n  истёкшие зомби-строки больше не лочат новый вход 409-ом на 15 минут.\n- 3323cc4: ревью логина — 3 фатальных бага + честные терминальные шаги.\n- f4b1da9: README — терминальные шаги логина (done/error) + раздел Тесты.\n- В репо появились тесты: backend/tests/test_login_flow.py (484 строки) +\n  conftest.py; pyproject.toml дополнен.\n\n**Поздний вечер — 0fc015e, SPA: табы логин-визарда:**\n- Входная часть логин-визарда — табы «SMS-код / QR» (LoginWizard.vue,\n  i18n en/ru/uk). Только фронт, бэкенд не менялся.\n\n**Ночь — ac8b764, SPA-фиксы:**\n- Фикс пустой иконки disconnect (AccountsPage.vue) + дублированный инпут\n  имени ключа (McpKeysPage.vue), мелочь в AdminPage.vue. Только фронт.\n\n## Обновления 2026-10-07 (задеплоены navi rei)\n\n**e269bfb + 5cc14e3 — MCP runtime-аудит тулов:**\n- e269bfb: boundary тулов ловит реальные классы «диалог не найден»\n  (backend/app/mcp/tools.py).\n- 5cc14e3: runtime-аудит — None-offsets в messages_history и video=None\n  в звонках (backend/app/mcp/tools.py, backend/app/tg/calls.py).\n- Новые тесты: backend/tests/test_mcp_tools.py (407 строк) +\n  test_tool_boundary.py (64 строки). Только бэкенд, SPA не менялся.\n\n**004db72 — фикс AccountManager._touch (19:26):**\n- `get_client` вызывал `await self._touch(account_id)`, но метода в классе\n  не было — warmup падал с AttributeError ДО регистрации слушателей\n  (register_listeners), клиенты оставались закэшированными: отправка\n  работала, а message/*-события не рождались. Исправлено: добавлен метод\n  `_touch` (UPDATE accounts SET last_used_at = now). Живой тест после\n  фикса — message/received дошёл до Synapse и Navi.\n\n**df2492b — фильтр аккаунтов TGCLIENT_NOTIFY_ACCOUNTS (19:37):**\n- Запрос владельца: «чтоб только с аккаунта Navi сообщения приходили в\n  Navi, зачем ей мои». Реализовано: config.py `notify_accounts: str` (csv\n  id аккаунтов, пусто = все) + гейт `_allowed()` в events.py\n  (`_report_message` и `_on_deleted`). .env: TGCLIENT_NOTIFY_ACCOUNTS=2\n  (бэкап .env.bak-notifyacc-20261007), .env.example дополнен.\n- Живой тест: сообщение с акка 1 → Navi (акк 2) → ровно одно событие\n  message/received от account-2 (68a5c24f), от account-1 ничего — фильтр\n  работает. Наблюдение: исходящее сообщение через MCP-тул (out=true)\n  событие не порождает — NewMessage-хендлер ловит только входящие\n  (out=false); для сценария «Navi реагирует на входящие» это корректно.\n\n## Интеграция с Synapse (2026-10-07, navi rei)\n\n- Репортер `backend/app/synapse_report.py` включён: 10 типов событий\n  (account/logged_in|logged_out|auth_lost|login_failed, api/flood_wait,\n  token/issued|revoked, message/received|edited|deleted), fire-and-forget,\n  dedup по UTC-дню для account/api-событий, ttl 24ч (сообщения — 1ч).\n- Synapse: source `tgclient` (id 2) + 10 зарегистрированных типов + API-ключ\n  (key id 2, hint 0b7b) — plaintext в gnexus-creds secret\n  \"tgclient-mcp Synapse reporter API key (syn_…)\"\n  (id 98284541-d320-4bc4-b691-09295d22dba3).\n- .env: TGCLIENT_SYNAPSE_URL=http://192.168.1.172:8013,\n  TGCLIENT_SYNAPSE_API_KEY=syn_…0b7b,\n  **TGCLIENT_SYNAPSE_DEFAULT_SOURCE=tgclient** (ВАЖНО: имя источника в\n  Synapse — `tgclient`, а не `tgclient-mcp`; с дефолтом из .env.example\n  Synapse отвечает 403 «Поле source не совпадает с источником ключа»),\n  TGCLIENT_SYNAPSE_TIMEOUT=10. Бэкап: .env.bak-synapse-20261007.\n- **Пуш-события сообщений ВКЛЮЧЕНЫ 2026-10-07 19:22** (решение владельца —\n  доставлять сообщения через Synapse): TGCLIENT_NOTIFY_MESSAGES=1 в .env\n  (бэкап .env.bak-notify-20261007), контейнер пересоздан. Живой тест:\n  сообщение с аккаунта Navi (id 2) владельцу (id 1) → message/received\n  8093aa27 в Synapse → delivery s2s navi-rei delivered (1 попытка) →\n  synapse.delivery_accepted на Navi. Реальный трафик (message/edited из\n  новостных каналов) тоже течёт. Слушатели вешаются при подключении\n  клиента (manager.py, гейт notify_messages читается на get_client).\n- **Фильтр аккаунтов (19:37):** TGCLIENT_NOTIFY_ACCOUNTS=2 — в Synapse\n  пушатся только сообщения аккаунта Navi (id 2); переписки аккаунта\n  владельца (id 1, новостные каналы и личные чаты) не покидают tgclient.\n  Пусто = все аккаунты (прошлое поведение).\n- E2E проверено 2026-10-07: POST /api/v1/events с syn_-ключом с .171 → 202,\n  событие done в Synapse (c9837953).\n- **Маршрутизация (фаза 2, 2026-10-07 19:02):** правило 2\n  «tgclient → navi-rei (s2s)» (conditions: source=tgclient) → s2s-цель\n  navi-rei (id 3, endpoint http://192.168.1.168:8099/webhooks/synapse,\n  token_ref navi-rei). Доставки работают — проверено живыми событиями\n  token/issued|revoked и message/received|edited.\n\n## MCP-токены (2026-10-07, navi rei)\n\nПерсональные MCP-ключи `mcp_*` — таблица mcp_tokens в tgclient.db, выпускаются\nна странице «MCP-ключи» SPA (plaintext показывается один раз), роль\nsuperadmin у владельца (user_id=1, goldmikki@gmail.com):\n\n- id 1 «Navi» (hint wBmQadiq) — активен, создан 2026-10-07 12:36 UTC.\n- id 2 «Navi started» (hint NvFzVdNS) — активен, создан 2026-10-07 13:51 UTC.\n- id 3 «synapse-e2e-test» (hint 8_E65tXn) — создан и отозван 2026-10-07\n  19:13 UTC (полный жизненный цикл за 200 мс, last_used_at NULL) —\n  программный E2E-тест выпуска/отзыва токена. События token/issued +\n  token/revoked ушли в Synapse и доставлены в s2s-цель navi-rei (правило 2);\n  реакционная сессия navi rei отработала событие token/revoked\n  (75374a28-8ba6-4b6f-859e-7fbaabc66298) — инцидента нет, оба рабочих ключа\n  активны, аккаунты active/connected, health ok.\n\n## Telegram login notes (2026-10-05)\n\n- Свежесозданному api_id Telegram может молча не доставлять код (сервер\n  отвечает SentCodeTypeApp «отправил», но в чат 777000 ничего не приходит) —\n  антиабьюз-прогрев, лечится временем (~час). После прогрева код приходит\n  в приложение (чат «Telegram»/777000), SMS не используется. Наблюдение\n  2026-10-05: 6 отправок подряд — доставилась 1; троттлинг на уровне\n  api_id, завершение сессий аккаунта с телефона на него не влияет.\n- Повторный POST /logins на неистёкшую pending-сессию того же user+phone\n  возвращает её БЕЗ повторной send_code (защита от флуда) — для реотправки\n  сначала DELETE /accounts/logins/{id}.\n- **Автоотмена (фича #5):** pending-логин старше 15 мин от created_at\n  вычищается sweeper'ом (30-секундный цикл). Критерий — created_at, НЕ\n  expires_at: продление expires_at в БД вручную больше не спасает сессию\n  от автоотмены. Для нового логина после автоотмены — свежий\n  POST /accounts/logins (новая send_code).\n- **QR-вход (2026-10-06, живой опыт):** токен QR живёт ~30 с, waiter\n  ротирует его через recreate; SPA перерисовывает QR при смене qr_url.\n  Первая попытка скана дала «произошла ошибка» на Android — повторная через\n  свежий QR прошла. При отмене код-логина наблюдался\n  `[login] cancel_code(...): TypeError — чистим локально` (обработано\n  грейсfully, но TypeError от auth.cancelCode стоит глянуть в репо).\n- Диагностическая сессия для API-вызовов без браузера: строка в таблице\n  sessions (id hex, user_id='1', expires_at +1h) + заголовок\n  `Cookie: tgclient_session=<id>` (имя cookie — SESSION_COOKIE в auth.py).\n\n## 2026-10-17: блэкаут, возврат на .171 (navi rei)\n\n- Ночной блэкаут 2026-10-16/17: VM погашена владельцем, утром 2026-10-17\n  запущена заново. Netplan-статика на момент блэкаута ещё не была настроена\n  (файл был cloud-init DHCP) — VM получила от pfSense временный адрес\n  `192.168.1.24`, старый `.171` освободился.\n- Временный фикс (утро): `TGCLIENT_SYNAPSE_URL=http://192.168.1.29:8013`\n  (synapse тоже временно на .29), nginx-апстрим на internal-proxy (.183) →\n  `http://192.168.1.24:8710`.\n- Возврат (решение владельца, день 2026-10-17): netplan-статика\n  `192.168.1.171/24` (gateway `192.168.1.1`, DNS `192.168.1.1` + `1.1.1.1`),\n  cloud-init network config disabled, `50-cloud-init.yaml` удалён, создан\n  `50-static.yaml`; `TGCLIENT_SYNAPSE_URL` откатан на\n  `http://192.168.1.172:8013`, контейнер пересоздан; nginx-апстрим на\n  internal-proxy откатан на `.171:8710`. Проверено: health 200 (2/2\n  аккаунта connected), MCP tgclient connected.\n- Открытый пункт: Kea-резервация на pfSense (MAC `52:54:00:6d:8d:86` →\n  `.171`) не требуется, пока в госте статика; при отказе от статики —\n  добавить резервацию (нужен админ-доступ к pfSense).\n\n## Pending\n\n- TGCLIENT_ADMIN_TOKEN пуст — статический супер-токен для скриптов (роль\n  superadmin) не задан; персональные MCP-ключи `mcp_*` выпускаются на\n  странице «MCP-ключи» SPA (plaintext показывается один раз).\n- Разобраться в TypeError от auth.cancelCode при отмене логина (лог\n  `[login] cancel_code(...): TypeError — чистим локально`, 2026-10-06) —\n  кандидат на фикс в репо.\n\n## Listening ports (TCP, verified 2026-10-05)\n\n- 22 — sshd\n- 8710 — tgclient docker (0.0.0.0)\n\n## Notes\n\n- Обновление сервиса: `cd /home/ubuntu/tgclient-mcp && git pull --ff-only &&\n  sudo docker compose up -d --build` (docker только через sudo — ubuntu не в\n  docker-группе; сборка ~1 мин; после pull проверить, что локальных\n  незакоммиченных изменений нет: `git status --short`).\n- nginx-сайт на internal-proxy (.183): /etc/nginx/sites-available/tgclientmcp.gnexus.space\n  (:80 + :443, client_max_body_size 32m, на /mcp-protocol/ proxy_buffering\n  off + proxy_read_timeout 300s)."
  },
  "status": "applied",
  "created_at": "2026-10-17T12:28:48Z",
  "updated_at": "2026-10-17T12:28:49Z",
  "applied_at": "2026-10-17T12:28:49Z",
  "validation": {
    "status": "ok",
    "issue_count": 0,
    "issues": []
  }
}