dinlo
125 lines
8.4 KiB
Markdown
125 lines
8.4 KiB
Markdown
# Readeck Importer
|
|
|
|
Локальное веб-приложение для добавления статей и файлов в [Readeck](https://readeck.org/) — self-hosted сервис «прочитать позже».
|
|
|
|
Readeck импортирует материалы по URL. Приложение подготавливает контент, временно публикует его по доступному в локальной сети адресу и создаёт закладку через Readeck API. Поэтому в библиотеку можно отправлять и локальные файлы.
|
|
|
|
## Возможности
|
|
|
|
- Импорт статьи по URL с извлечением основного содержания (`trafilatura`).
|
|
- Загрузка файлов `.txt`, `.html`, `.htm`, `.md`, `.markdown`, включая drag & drop.
|
|
- Автоопределение UTF-8 и Windows-1251 для локальных файлов.
|
|
- Форматы содержимого: HTML, Markdown и простой текст.
|
|
- Перевод через Google Translate с разбиением длинного текста на безопасные части.
|
|
- Автозаполнение метаданных: заголовок, автор, описание, дата и сайт.
|
|
- Предпросмотр итоговой статьи перед отправкой.
|
|
- Санитизация HTML перед публикацией (`bleach`).
|
|
- Проверка соединения с Readeck в настройках.
|
|
- Локальная библиотека: отдельное окно для просмотра файлов из выбранной папки.
|
|
- Отправка открытого в Локальной библиотеке файла в основное окно для последующей отправки в Readeck.
|
|
- Светлая и тёмная темы, автосохранение черновика, счётчики символов и слов.
|
|
- Интерфейс на русском, английском и казахском языках.
|
|
|
|
## Требования
|
|
|
|
- Python 3.9+ (проект проверялся на Python 3.12).
|
|
- Доступный сервер Readeck и API-токен.
|
|
- Сетевой доступ Readeck к машине с этим приложением, если Readeck расположен на другом хосте.
|
|
|
|
## Установка
|
|
|
|
### Windows: быстрый запуск
|
|
|
|
В каталоге проекта есть `run.bat`. Он запускает приложение через `.venv\Scripts\python.exe` и очищает унаследованные `PYTHONPATH` / `PYTHONHOME`.
|
|
|
|
Перед первым запуском создайте виртуальное окружение и установите зависимости:
|
|
|
|
```bat
|
|
py -3.12 -m venv .venv
|
|
.venv\Scripts\python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
|
|
run.bat
|
|
```
|
|
|
|
### Универсальный запуск
|
|
|
|
```bash
|
|
python -m pip install fastapi uvicorn pydantic beautifulsoup4 lxml httpx deep-translator markdown bleach trafilatura python-multipart
|
|
python main.py
|
|
```
|
|
|
|
Сервис слушает `0.0.0.0:8142`, а браузер автоматически открывает `http://127.0.0.1:8142`.
|
|
|
|
## Первоначальная настройка
|
|
|
|
При первом запуске откроется окно **Настройки**. Укажите:
|
|
|
|
- **Readeck URL** — адрес Readeck, например `http://192.168.1.10:8000`.
|
|
- **API Токен** — токен Readeck; приложение передаёт его в заголовке `Authorization: Bearer …`.
|
|
- **Ваш LAN IP** — IP машины с приложением, доступный для Readeck. Он используется в callback-ссылке с материалом.
|
|
- **Папка локальной библиотеки** — папка, в которой нужно искать файлы для чтения.
|
|
- **Язык интерфейса**.
|
|
|
|
Нажмите **Проверить подключение**, затем **Сохранить**. Настройки записываются в `config.json`.
|
|
|
|
## Работа с материалами
|
|
|
|
1. В основном окне вставьте текст, загрузите файл или введите URL статьи.
|
|
2. При необходимости выберите формат и переведите содержимое.
|
|
3. Заполните метаданные вручную либо используйте **Автозаполнение**.
|
|
4. Добавьте теги и нужные флаги Readeck.
|
|
5. Откройте предпросмотр и нажмите **Создать закладку**.
|
|
|
|
### Локальная библиотека
|
|
|
|
1. Откройте **Локальная библиотека** в шапке основного окна.
|
|
2. В отдельном окне появится список поддерживаемых файлов из выбранной папки и всех её подпапок.
|
|
3. Нажмите **Открыть**, чтобы перейти в режим чтения. Файлы не загружаются целиком на странице списка, поэтому библиотека остаётся отзывчивой и с крупными каталогами.
|
|
4. На странице чтения используйте **Отправить в Readeck**. Содержимое и заголовок будут переданы в главное окно приложения.
|
|
5. Проверьте метаданные и создайте закладку обычным способом.
|
|
|
|
Поддерживаются `.txt`, `.md`, `.markdown`, `.html` и `.htm`. Переход за пределы выбранной директории заблокирован.
|
|
|
|
## Тестирование
|
|
|
|
Регрессионные тесты не требуют сети или настоящего Readeck:
|
|
|
|
```bash
|
|
# Windows Git Bash / POSIX shell
|
|
PYTHONPATH= PYTHONHOME= .venv/Scripts/python.exe -m unittest tests.test_reader -v
|
|
|
|
# Windows cmd.exe
|
|
set PYTHONPATH=
|
|
set PYTHONHOME=
|
|
.venv\Scripts\python.exe -m unittest tests.test_reader -v
|
|
```
|
|
|
|
Проверяются настройки Локальной библиотеки, безопасное открытие файлов, передача текста в основное окно и наличие общей дизайн-системы интерфейса.
|
|
|
|
## Структура проекта
|
|
|
|
- `main.py` — FastAPI-бэкенд, API и встроенный интерфейс Vue 3 / Tailwind.
|
|
- `run.bat` — запуск приложения в Windows.
|
|
- `config.json` — локальные настройки подключения и Локальной библиотеки. **Не храните здесь рабочие токены в репозитории.**
|
|
- `lang/` — локализации интерфейса.
|
|
- `tests/test_reader.py` — автоматические тесты Локальной библиотеки и UI.
|
|
- `LOCALIZATION.md` — сведения о локализации.
|
|
|
|
## Локализация
|
|
|
|
Доступны:
|
|
|
|
- English
|
|
- Русский
|
|
- Қазақша
|
|
|
|
Чтобы добавить язык, создайте `lang/<код>.json`, скопируйте структуру `lang/en.json` или `lang/ru.json`, переведите значения без изменения ключей и перезапустите приложение.
|
|
|
|
Подробнее: `lang/README.md` и `LOCALIZATION.md`.
|
|
|
|
## Безопасность
|
|
|
|
- `config.json` содержит API-токен в открытом виде. Не публикуйте реальный токен и перевыпустите его при утечке.
|
|
- Сервис доступен в локальной сети на порту `8142`, без собственной аутентификации.
|
|
- Импорт по URL загружает произвольный адрес, то есть потенциально допускает SSRF. Не публикуйте приложение в интернете без ограничения доступа и дополнительной защиты.
|
|
- Readeck должен иметь возможность обратиться по callback-адресу к указанному LAN IP и порту `8142`.
|