Files

T

gitrusprusandCursor 6dff3c1c3d 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

4.0 KiB

Raw Blame History

Локальная разработка

Требования

Docker + Docker Compose
Файл .env (из .env.example)
Для Telegram: data/telegram.session + TELEGRAM_API_ID / TELEGRAM_API_HASH
Опционально: DEEPSEEK_API_KEY для extract_mode: llm

Быстрый старт

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

Пересборка одного воркера:

docker compose up --build cp-workers-web

Проверка compose-файла:

docker compose config

Telegram-сессия

Путь в контейнере: /data/telegram.session (TELEGRAM_SESSION_PATH)
Локально: ./data монтируется в cp-workers
Файл не коммитить (.gitignore)
API id/hash в .env должны совпадать с теми, под которыми создавалась сессия

Создать / обновить сессию (локальный прокси)

Остановите Telegram-воркер, чтобы не делить session-файл: docker compose stop cp-workers
В .env: TELEGRAM_PROXY_TYPE=socks5, TELEGRAM_PROXY_HOST=127.0.0.1, TELEGRAM_PROXY_PORT=10808 (Happ/xray).
Проброс SOCKS в Docker (xray слушает только 127.0.0.1:10808):
```
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.

Авторизация (интерактивно, код из Telegram):

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

docker compose up -d cp-workers

Без сессии batch/listener Telegram не авторизуются; остальные адаптеры могут работать.

Полезные curl

Создать telegram-парсер:

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):

curl -H "Authorization: Bearer test-pi-api-key-change-me" \
  "http://localhost:8080/api/v1/events"

Логи

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).

4.0 KiB Raw Blame History Unescape Escape