gitrusprusandCursor
5811ecb134
Persist settings in CA, expose /admin/vpn and /internal/vpn, and route Telegram (and optional web/nlp) traffic through mihomo SOCKS when enabled. Co-authored-by: Cursor <cursoragent@cursor.com>
134 lines
5.0 KiB
Markdown
134 lines
5.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` (воркеры) и Generate профиля на `ca-api`
|
||
|
||
## Быстрый старт
|
||
|
||
```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 |
|
||
| `cp-vpn` | внутренний 1080 | SOCKS из subscription (вкладка VPN) |
|
||
|
||
Пересборка одного воркера:
|
||
|
||
```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` должны совпадать с теми, под которыми создавалась сессия
|
||
|
||
## VPN / прокси (вкладка VPN)
|
||
|
||
Основной путь: UI → **VPN** (`/vpn`).
|
||
|
||
1. Включите «Прокси включён».
|
||
2. Способ **Subscription URL** — вставьте ссылку подписки (не коммитьте её в git).
|
||
3. Отметьте источники (`telegram`, при необходимости `crawl4ai` / `viina`).
|
||
4. Сохраните. Сервис `cp-vpn` (mihomo) подтянет подписку и отдаст SOCKS на `cp-vpn:1080`; воркеры читают `/internal/vpn`.
|
||
|
||
Режимы **SOCKS5** / **HTTP** задают host:port напрямую (без `cp-vpn` для Telegram).
|
||
|
||
### Fallback: локальный Happ/xray (без вкладки VPN)
|
||
|
||
Если VPN в UI выключен, воркеры используют `TELEGRAM_PROXY_*` из `.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 &
|
||
```
|
||
Для auth из контейнера с host-сетью: `TELEGRAM_PROXY_HOST=127.0.0.1`.
|
||
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` |
|
||
| Generate профиля 503 | `DEEPSEEK_API_KEY` в `.env` + `env_file` у `ca-api`, перезапуск `ca-api` |
|
||
| Изменения UI не видны | Пересобрать `ca-frontend` |
|
||
|
||
## Границы при разработке
|
||
|
||
- Не добавлять прямой доступ к БД из CP workers.
|
||
- Не коммитить `.env`, `data/`, API-ключи.
|
||
- Изменение формы данных — через `contracts/` (см. [contracts.md](contracts.md)).
|