Skip to content

fozzepe/cross

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
.github/workflows
.github/workflows
 
 
backend
backend
 
 
docker
docker
 
 
frontend
frontend
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
env.example
env.example
 
 

Repository files navigation

Crossposta

Telegram Mini App для автоматического кросспостинга из Telegram-каналов в Threads.

Возможности

  • Автоматический кросспостинг — посты из Telegram каналов публикуются в Threads
  • AI-трансформации — перевод, добавление хуков, суммаризация через OpenAI
  • Гибкие фильтры — пропуск репостов, рекламы, фильтрация по ключевым словам
  • Отложенная публикация — настраиваемая задержка перед публикацией
  • Медиа поддержка — фото, видео, карусели
  • Статистика — история постов и детальная аналитика
  • Аватарки — автоматическая загрузка и обновление аватарок каналов и пользователей

Скриншоты

Mini App работает прямо в Telegram — доступен как на мобильных устройствах, так и на ПК.

Технологии

Backend

  • FastAPI — REST API
  • aiogram 3 — Telegram Bot API
  • PostgreSQL — основная БД
  • SQLAlchemy 2.0 — ORM с async поддержкой
  • Alembic — миграции БД
  • Redis — кэширование и брокер задач
  • Celery — асинхронные задачи (публикация, обновление токенов)
  • S3/MinIO — хранение медиафайлов
  • OpenAI API — AI-трансформации текста

Frontend

  • React 18 — UI библиотека
  • TypeScript — типизация
  • Vite — сборка
  • shadcn/ui — компоненты
  • Tailwind CSS — стили
  • TanStack Query — управление состоянием
  • Telegram WebApp SDK — интеграция с Telegram

Инфраструктура

  • Docker Compose — оркестрация
  • Prometheus — метрики
  • Grafana — дашборды
  • Sentry — мониторинг ошибок
  • GitHub Actions — CI/CD

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

Требования

  • Docker + Docker Compose v2
  • Node.js 20+ (для локальной разработки frontend)
  • Python 3.12+ (для локальной разработки backend)

1. Клонирование и настройка

# Клонируем репозиторий
git clone https://github.com/fozzepe/cross.git
cd cross

# Копируем конфиг окружения
cp env.example .env

2. Настройка переменных окружения

Отредактируйте .env файл:

# Telegram Bot (получить у @BotFather)
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_WEBAPP_URL=https://your-domain.com

# Threads/Meta App (https://developers.facebook.com)
THREADS_APP_ID=your_app_id
THREADS_APP_SECRET=your_app_secret
THREADS_REDIRECT_URI=https://your-domain.com/api/v1/oauth/threads/callback

# Ключ шифрования (сгенерировать ниже)
ENCRYPTION_KEY=your_fernet_key

# OpenAI (опционально, для AI-трансформаций)
OPENAI_API_KEY=sk-your-key

3. Генерация ключа шифрования

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

4. Запуск

# Запускаем все сервисы
docker compose up -d

# Проверяем статус
docker compose ps

# Смотрим логи
docker compose logs -f backend

5. Настройка Telegram бота

  1. Откройте @BotFather в Telegram
  2. Выберите вашего бота → Bot Settings → Menu Button
  3. Установите URL вашего Mini App: https://your-domain.com

Настройка Threads OAuth

  1. Создайте приложение на Meta for Developers
  2. Добавьте продукт "Threads API"
  3. В настройках OAuth добавьте redirect URI: https://your-domain.com/api/v1/oauth/threads/callback
  4. Скопируйте App ID и App Secret в .env

Необходимые разрешения:

  • threads_basic
  • threads_content_publish
  • threads_manage_insights

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

Backend

cd backend

# Создаём виртуальное окружение
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# или .venv\Scripts\activate  # Windows

# Устанавливаем зависимости
pip install -r requirements.txt -r requirements-dev.txt

# Запускаем миграции
alembic upgrade head

# Запускаем сервер
uvicorn app.main:app --reload --port 8000

Frontend

cd frontend

# Устанавливаем зависимости
npm install

# Запускаем dev сервер
npm run dev

Celery Worker

cd backend
celery -A app.tasks.celery_app worker --loglevel=info

Celery Beat (планировщик)

cd backend
celery -A app.tasks.celery_app beat --loglevel=info

API Endpoints

Health

Метод Путь Описание
GET /health Базовый health check
GET /health/ready Readiness check (БД, Redis)
GET /health/live Liveness check

Profile

Метод Путь Описание
GET /api/v1/profile/me Профиль текущего пользователя
GET /api/v1/profile/me/photo Аватарка пользователя

Channels

Метод Путь Описание
GET /api/v1/channels Список каналов пользователя
GET /api/v1/channels/{id} Канал по ID
GET /api/v1/channels/{id}/photo Аватарка канала
PATCH /api/v1/channels/{id} Обновление канала
DELETE /api/v1/channels/{id} Удаление канала

Accounts (Threads)

Метод Путь Описание
GET /api/v1/accounts Список Threads аккаунтов
GET /api/v1/accounts/{id} Аккаунт по ID
PATCH /api/v1/accounts/{id} Обновление аккаунта
DELETE /api/v1/accounts/{id} Удаление аккаунта

Flows

Метод Путь Описание
GET /api/v1/flows Список потоков кросспостинга
POST /api/v1/flows Создание потока
GET /api/v1/flows/{id} Поток по ID
PATCH /api/v1/flows/{id} Обновление потока
DELETE /api/v1/flows/{id} Удаление потока

Posts

Метод Путь Описание
GET /api/v1/posts История постов
GET /api/v1/posts/stats Статистика
GET /api/v1/posts/{id} Детали поста

OAuth

Метод Путь Описание
GET /api/v1/oauth/threads/authorize Начало OAuth flow
GET /api/v1/oauth/threads/callback Callback после авторизации

Структура проекта

crossposta/
├── backend/
│   ├── app/
│   │   ├── api/              # FastAPI роуты
│   │   │   ├── channels.py   # Управление каналами
│   │   │   ├── accounts.py   # Threads аккаунты
│   │   │   ├── flows.py      # Потоки кросспостинга
│   │   │   ├── posts.py      # История постов
│   │   │   ├── profile.py    # Профиль пользователя
│   │   │   ├── oauth.py      # OAuth Threads
│   │   │   └── deps.py       # Зависимости (auth)
│   │   ├── bot/              # Telegram бот
│   │   │   ├── handlers.py   # Обработчики команд
│   │   │   └── middlewares.py
│   │   ├── core/             # Ядро приложения
│   │   │   ├── config.py     # Настройки
│   │   │   ├── database.py   # Подключение к БД
│   │   │   └── security.py   # Шифрование
│   │   ├── integrations/     # Внешние сервисы
│   │   │   ├── threads/      # Threads API
│   │   │   └── openai/       # OpenAI API
│   │   ├── models/           # SQLAlchemy модели
│   │   ├── services/         # Бизнес-логика
│   │   │   ├── media_service.py  # Работа с медиа
│   │   │   └── post_service.py   # Публикация постов
│   │   └── tasks/            # Celery задачи
│   │       ├── publish_task.py   # Публикация в Threads
│   │       ├── refresh_tokens.py # Обновление токенов
│   │       └── update_channel_photos.py
│   ├── alembic/              # Миграции БД
│   └── tests/
├── frontend/
│   ├── src/
│   │   ├── components/       # React компоненты
│   │   │   ├── ui/           # shadcn/ui компоненты
│   │   │   ├── common/       # Layout, ErrorBoundary
│   │   │   └── flows/        # Компоненты потоков
│   │   ├── hooks/            # Custom hooks
│   │   │   ├── useChannels.ts
│   │   │   ├── useAccounts.ts
│   │   │   ├── useFlows.ts
│   │   │   └── useTelegram.ts
│   │   ├── pages/            # Страницы приложения
│   │   └── types/            # TypeScript типы
│   └── index.html
├── docker/
│   ├── grafana/              # Grafana дашборды
│   └── prometheus/           # Prometheus конфиг
├── .github/workflows/        # CI/CD
├── docker-compose.yml
└── env.example

Мониторинг

Prometheus метрики

Доступны на /metrics:

  • http_requests_total — количество HTTP запросов
  • http_request_duration_seconds — время ответа
  • posts_published_total — опубликованные посты
  • posts_failed_total — ошибки публикации

Grafana

Дашборд доступен на http://localhost:3000 (admin/admin).

Включает:

  • Статус сервисов
  • Количество постов
  • Время ответа API
  • Ошибки

Разработка

Линтеры

# Backend
cd backend
ruff check .
ruff format .
mypy app/

# Frontend
cd frontend
npm run lint
npm run type-check

Тесты

# Backend
cd backend
pytest

# С покрытием
pytest --cov=app --cov-report=html

Миграции

cd backend

# Создать миграцию
alembic revision --autogenerate -m "description"

# Применить миграции
alembic upgrade head

# Откатить последнюю
alembic downgrade -1

Деплой

Docker Compose (production)

# Используйте production compose файл
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

Переменные для production

# Обязательно установите
DEBUG=false
SECRET_KEY=strong-random-key
SENTRY_DSN=your-sentry-dsn

# CORS и домены
CORS_ORIGINS=https://your-domain.com
TELEGRAM_WEBAPP_URL=https://your-domain.com

Troubleshooting

Бот не видит посты из канала

  1. Убедитесь что бот добавлен как администратор канала
  2. Бот должен иметь право "Post Messages"
  3. Проверьте логи: docker compose logs -f backend

OAuth Threads не работает

  1. Проверьте что redirect URI совпадает с настройками в Meta
  2. Приложение должно быть в режиме "Live" для production
  3. Проверьте что добавлены все необходимые разрешения

Медиа не загружается

  1. Проверьте настройки S3/MinIO в .env
  2. Убедитесь что bucket создан и доступен
  3. Проверьте CORS настройки MinIO

Лицензия

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages