gitrusprusandCursor
6dff3c1c3d
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>
119 lines
4.0 KiB
Markdown
119 lines
4.0 KiB
Markdown
# Локальная разработка
|
||
|
||
## Требования
|
||
|
||
- 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)).
|