Document platform architecture and Telegram proxy local setup.

Add developer docs for CA/CP/PI flows and wire cp-workers to the host SOCKS proxy so local Telegram auth and parsing work reliably. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-15 22:57:07 +03:00
parent 5f8ed25759
commit 6dff3c1c3d
11 changed files with 1046 additions and 12 deletions
@@ -0,0 +1,118 @@
+# Локальная разработка
+
+## Требования
+
+- Docker + Docker Compose
+- Файл `.env` (из `.env.example`)
+- Для Telegram: `data/telegram.session` + `TELEGRAM_API_ID` / `TELEGRAM_API_HASH`
+- Опционально: `DEEPSEEK_API_KEY` для `extract_mode: llm`
+
+## Быстрый старт
+
+```bash
+cp .env.example .env
+# заполнить TELEGRAM_* (и при необходимости DEEPSEEK_*)
+
+mkdir -p data
+# положить telegram.session в data/
+
+docker compose up --build
+```
+
+UI: http://localhost:8080  
+Health: `curl http://localhost:8080/api/health`
+
+## Сервисы
+
+| Сервис | Порт снаружи | Когда нужен |
+|--------|--------------|-------------|
+| `ca-frontend` | 8080 | всегда (UI) |
+| `ca-api` | внутренний 8000 | всегда |
+| `ca-db` / `redis` | — | всегда |
+| `cp-workers` | — | Telegram |
+| `cp-workers-web` | — | Crawl4AI |
+| `cp-workers-nlp` | — | VIINA |
+
+Пересборка одного воркера:
+
+```bash
+docker compose up --build cp-workers-web
+```
+
+Проверка compose-файла:
+
+```bash
+docker compose config
+```
+
+## Telegram-сессия
+
+- Путь в контейнере: `/data/telegram.session` (`TELEGRAM_SESSION_PATH`)
+- Локально: `./data` монтируется в `cp-workers`
+- Файл **не** коммитить (`.gitignore`)
+- API id/hash в `.env` должны совпадать с теми, под которыми создавалась сессия
+
+### Создать / обновить сессию (локальный прокси)
+
+1. Остановите Telegram-воркер, чтобы не делить session-файл:
+   `docker compose stop cp-workers`
+2. В `.env`: `TELEGRAM_PROXY_TYPE=socks5`, `TELEGRAM_PROXY_HOST=127.0.0.1`, `TELEGRAM_PROXY_PORT=10808` (Happ/xray).
+3. Проброс SOCKS в Docker (xray слушает только `127.0.0.1:10808`):
+   ```bash
+   socat TCP-LISTEN:11080,bind=0.0.0.0,fork,reuseaddr TCP:127.0.0.1:10808 &
+   ```
+   В compose у `cp-workers`: `TELEGRAM_PROXY_HOST=host.docker.internal`, порт `11080`.
+4. Авторизация (интерактивно, код из Telegram):
+   ```bash
+   docker run --rm -it --network host \
+     --env-file .env \
+     -e TELEGRAM_SESSION_PATH=/data/telegram.session \
+     -e TELEGRAM_PROXY_HOST=127.0.0.1 \
+     -v "$PWD/data:/data" \
+     -v "$PWD/scripts:/scripts:ro" \
+     mapmil-cp-workers \
+     python /scripts/telegram_auth.py
+   ```
+5. `docker compose up -d cp-workers`
+
+Без сессии batch/listener Telegram не авторизуются; остальные адаптеры могут работать.
+
+## Полезные curl
+
+Создать telegram-парсер:
+
+```bash
+curl -X POST http://localhost:8080/admin/jobs \
+  -H 'Content-Type: application/json' \
+  -d '{"source_type":"telegram","source_config":{"channel":"example","limit":50}}'
+```
+
+Срез ПИ (подставьте ключ из seed / UI):
+
+```bash
+curl -H "Authorization: Bearer test-pi-api-key-change-me" \
+  "http://localhost:8080/api/v1/events"
+```
+
+## Логи
+
+```bash
+docker compose logs -f ca-api
+docker compose logs -f cp-workers
+docker compose logs -f cp-workers-web
+```
+
+## Типичные проблемы
+
+| Проблема | Действие |
+|----------|----------|
+| Frontend 000 / нет контейнеров | `docker compose up -d` (без `--build`, если registry недоступен, но образы уже есть) |
+| Job не берётся | Смотреть `ENABLED_ADAPTERS` / `WORKER_FAMILIES` нужного сервиса |
+| LLM не работает | `DEEPSEEK_API_KEY` в `.env`, перезапуск `cp-workers` / `cp-workers-web` |
+| Изменения UI не видны | Пересобрать `ca-frontend` |
+
+## Границы при разработке
+
+- Не добавлять прямой доступ к БД из CP workers.
+- Не коммитить `.env`, `data/`, API-ключи.
+- Изменение формы данных — через `contracts/` (см. [contracts.md](contracts.md)).