Initial parser admin implementation

2026-06-15 21:14:07 +05:00
commit 59c899dc9c
51 changed files with 7052 additions and 0 deletions
@@ -0,0 +1,199 @@
+# VK Parser New Core
+
+Первый чистый слой проекта:
+
+- админка с источниками, пользователями, воркерами и raw-лентой;
+- VK parser worker;
+- VK storage uploader worker;
+- PostgreSQL job queue.
+
+Старый проект лежит в `original_project/` как справочник. Новый код живёт в `src/vk_parser_app/`.
+
+## Что нужно на сервере
+
+Ubuntu 22.04/24.04:
+
+```bash
+sudo apt update
+sudo apt install -y python3 python3-venv python3-pip postgresql postgresql-contrib nginx git curl
+```
+
+Для будущей работы с видео:
+
+```bash
+sudo apt install -y ffmpeg
+```
+
+## БД
+
+Пример:
+
+```bash
+sudo -u postgres psql
+```
+
+```sql
+CREATE DATABASE vk_parser;
+CREATE USER vk_parser_user WITH PASSWORD 'CHANGE_ME';
+GRANT ALL PRIVILEGES ON DATABASE vk_parser TO vk_parser_user;
+\c vk_parser
+GRANT ALL ON SCHEMA public TO vk_parser_user;
+```
+
+## Установка проекта
+
+```bash
+cd /opt
+sudo git clone <repo-url> vk-parser
+sudo chown -R $USER:$USER /opt/vk-parser
+cd /opt/vk-parser
+
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+```
+
+Заполнить `.env`:
+
+```env
+APP_SECRET_KEY=long-random-string
+ADMIN_BOOTSTRAP_LOGIN=admin
+ADMIN_BOOTSTRAP_PASSWORD=long-admin-password
+
+DB_HOST=localhost
+DB_PORT=5432
+DB_NAME=vk_parser
+DB_USER=vk_parser_user
+DB_PASSWORD=...
+
+VK_ACCESS_TOKEN=...
+VK_STORAGE_GROUP_ID=239548476
+```
+
+Важно: для `wall.post`, `wall.edit`, `photos.saveWallPhoto` нужен VK user token пользователя с правами в storage-группе. Community token для этого контура не подходит.
+
+## Миграции
+
+```bash
+PYTHONPATH=src .venv/bin/python scripts/apply_migrations.py
+```
+
+Первый админ создаётся из `ADMIN_BOOTSTRAP_LOGIN` / `ADMIN_BOOTSTRAP_PASSWORD` при старте админки.
+
+## Проверка VK storage
+
+Без фото:
+
+```bash
+PYTHONPATH=src .venv/bin/python scripts/vk_storage_spike.py
+```
+
+С фото:
+
+```bash
+cp /path/to/photo.jpg sample_photo.jpg
+PYTHONPATH=src .venv/bin/python scripts/vk_storage_spike.py
+```
+
+Скрипт должен вывести ссылку вида:
+
+```text
+https://vk.com/wall-239548476_123
+```
+
+После этого надо руками проверить:
+
+- пост создан от имени storage-группы;
+- админ/редактор группы может открыть и отредактировать пост;
+- вложенное фото видно в браузере.
+
+## Запуск локально
+
+Админка:
+
+```bash
+PYTHONPATH=src .venv/bin/uvicorn vk_parser_app.admin:app --host 0.0.0.0 --port 8080
+```
+
+Парсер:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m vk_parser_app.workers.parser
+```
+
+VK storage uploader:
+
+```bash
+PYTHONPATH=src .venv/bin/python -m vk_parser_app.workers.vk_storage_uploader
+```
+
+## systemd units
+
+Минимальный `vk-admin.service`:
+
+```ini
+[Unit]
+Description=VK Parser Admin
+After=network.target postgresql.service
+
+[Service]
+WorkingDirectory=/opt/vk-parser
+Environment=PYTHONPATH=/opt/vk-parser/src
+ExecStart=/opt/vk-parser/.venv/bin/uvicorn vk_parser_app.admin:app --host 0.0.0.0 --port 8080
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`vk-parser.service`:
+
+```ini
+[Unit]
+Description=VK Parser Worker
+After=network.target postgresql.service
+
+[Service]
+WorkingDirectory=/opt/vk-parser
+Environment=PYTHONPATH=/opt/vk-parser/src
+ExecStart=/opt/vk-parser/.venv/bin/python -m vk_parser_app.workers.parser
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+`vk-storage-uploader.service`:
+
+```ini
+[Unit]
+Description=VK Storage Uploader Worker
+After=network.target postgresql.service
+
+[Service]
+WorkingDirectory=/opt/vk-parser
+Environment=PYTHONPATH=/opt/vk-parser/src
+ExecStart=/opt/vk-parser/.venv/bin/python -m vk_parser_app.workers.vk_storage_uploader
+Restart=always
+RestartSec=10
+
+[Install]
+WantedBy=multi-user.target
+```
+
+## Текущий pipeline
+
+```text
+sources(vk)
+  -> vk-parser
+  -> raw_posts + raw_post_media
+  -> jobs(type='vk.storage.copy')
+  -> vk-storage-uploader
+  -> wall.post в storage-группе
+  -> raw_posts.storage_post_url
+```
+
+Фото копируются в storage-группу. Видео в первой версии сохраняются как `link_only`/исходное VK-вложение, чтобы сначала стабилизировать основной контур.