создан шаблон .env.example

.cursor/rules/version-and-docs.mdc

@@ -20,4 +20,4 @@ alwaysApply: true
 
 5. Не поднимать версию за косметические правки без изменения поведения.
 
-Текущая базовая версия: **1.0.1**.
+Текущая базовая версия: **1.0.2**.

.env.example

@@ -0,0 +1,126 @@
+# =============================================================================
+# Шаблон окружения для инстанса проекта.
+# Скопируйте в .env и заполните значения:
+#   cp .env.example .env
+# Генерация SECRET_KEY / WEBHOOK_SECRET:
+#   python tools/ops/genkey.py
+# =============================================================================
+
+# --- Общие настройки ---------------------------------------------------------
+SECRET_KEY=CHANGE_ME_hex_64_chars
+LOG_FILE=./logs/app.log
+
+# Режим работы: ZILANT | VOLK
+WORKMODE=ZILANT
+
+# Код сезона для deep link / callback подписок (zk2026_post_…, subscribe_zk2026_…)
+SEASON=zk2026
+
+# --- Telegram через internal_relay (retransbot) — обязательно ----------------
+# Схема http:// или https:// обязательна (иначе подставится http://)
+# Примеры: http://127.0.0.1:5100  |  https://relay.example.com
+RELAY_URL=http://127.0.0.1:5100
+
+# --- Webhook responder-бота --------------------------------------------------
+# WEBHOOK_URL — адрес локальной доставки апдейтов от relay к gunicorn-боту
+# (доступен с машины relay). Это не публичный URL для Telegram.
+# ZILANT (пример): http://bot.example.com:5005/testbot
+# VOLK   (пример): http://bot.example.com:5010/volk_bot
+WEBHOOK_URL=http://192.168.0.1:5005/testbot
+WEBHOOK_PORT=5005
+WEBHOOK_SECRET=CHANGE_ME_webhook_secret
+
+# Опционально: webhook poster-бота (если используется)
+# POSTHOOK_URL=https://bot.example.com/poster
+# POSTHOOK_PORT=5008
+# POSTHOOK_SECRET=CHANGE_ME
+
+# --- Веб-контроллер (db_edit) ------------------------------------------------
+# ZILANT (пример):
+WEBCTRL_URL=https://bot.example.com/testedit
+WEBCTRL_PORT=5006
+WEBCTRL_PREFIX=/testedit
+# VOLK (пример, раскомментировать при WORKMODE=VOLK):
+# WEBCTRL_URL=https://bot.example.com/volk
+# WEBCTRL_PORT=5009
+# WEBCTRL_PREFIX=/volk
+
+# Логин/пароль первого администратора веб-UI (создаётся ensure_db при пустой таблице users)
+DEFNM=admin
+DEFPW=CHANGE_ME_admin_password
+
+# --- VK API ------------------------------------------------------------------
+# ZILANT group (пример): -3342146
+# VOLK group   (пример): -58475527
+VK_GROUP_ID=-3342146
+VK_ACCESS_TOKEN=CHANGE_ME_vk_token
+VK_API_VERSION=5.131
+
+# --- MariaDB -----------------------------------------------------------------
+# ZILANT: zilant_2026 | tempzilant | testposts
+# VOLK:   volkdata | volk_test
+MDBASE=CHANGE_ME_database_name
+MDB_HOST=localhost
+MDB_USER=CHANGE_ME_db_user_name
+MDB_PW=CHANGE_ME_db_password
+
+# --- Telegram-боты -----------------------------------------------------------
+# Poster — публикация в канал
+POSTER_BOT_TOKEN=CHANGE_ME_poster_bot_token
+# Responder — подписки / webhook
+RESPONDER_BOT_TOKEN=CHANGE_ME_responder_bot_token
+RESPONDER_BOT_NAME=your_responder_bot_username
+
+# --- Канал -------------------------------------------------------------------
+# ZILANT debug: @posto1638 | production: @zilantkon
+# VOLK production: @VOLKinformer
+CHANNEL_ID=@your_channel
+
+MAX_CAPTION_LENGTH=1000
+MAX_TEXT_LENGTH=4000
+
+# --- Теги VK (ZILANT) --------------------------------------------------------
+# Org messages go without picture
+# to fit the long text into TG message limit
+ORG_MESSAGE_TAG=#оргинфаЗиланткона
+# VK posts with no repost tag are skipped by poster
+VK_NO_REPOST_TAG=#окоЗиланта
+
+# --- Публикация событий ------------------------------------------------------
+# Задержка перед публикацией события (минуты). В БД время в UTC.
+# Ближе к событию: 60; далеко: 1440
+EVENT_POST_DELAY=1440
+
+# --- Ссылки ZILANT (План Захвата / карточки событий) --------------------------
+# В конце обычно trailing slash; к URL добавляется номер события
+PZK_PREFIX=https://reg.konvent.ru/zk2026/draft/plan/api/add/
+EVT_PREFIX=https://reg.konvent.ru/zk2026/events/actions/api/
+DESC_PREFIX=https://reg.konvent.ru/zk2026/events/actions/
+
+# --- API VOLK (нужны при WORKMODE=VOLK) --------------------------------------
+# Раскомментируйте и заполните для режима VOLK:
+# VOLK_API_VERSION=1.0
+# VOLK_CATEGORY_LIST=https://base.volk-nn.ru/api/categories?event=volk26&form=volk26_event
+# VOLK_CATEGORY_DESC_PREFIX=https://base.volk-nn.ru/api/category?event=volk26&form=volk26_event&category=
+# VOLK_EVENT_LIST_PREFIX=https://base.volk-nn.ru/api/applications?event=volk26&form=volk26_event&apps_on_page=200&page=0&category=
+
+# --- Флаги поведения ---------------------------------------------------------
+# IS_EVENT=true - каждый пост в ВК считать пригодным для репоста в канал
+# AUTO_PUBLISH=true - автоматическая публикация потсов из ВК в канал
+# AUTO_PUB_EVT=true - автоматическая публикация событий в канал
+# PROCESS_EVENT_UPDATES=false - не репостить уже опубликованные события при обновлениях
+# PUBLISH_SILENTLY=true - публиковать в канал в режиме "без звука"
+# USE_SUBSCRIPTION_BOT=true - использовать бота подписок
+# LOG_DEBUG_DATA=false - не вести расширенного журналирования отладочных данных
+IS_EVENT=true
+AUTO_PUBLISH=true
+AUTO_PUB_EVT=true
+PROCESS_EVENT_UPDATES=false
+PUBLISH_SILENTLY=true
+USE_SUBSCRIPTION_BOT=true
+LOG_DEBUG_DATA=false
+
+# --- RouterAI (генерация shortname через «Назвать») ---------------------------
+RA_KEY=CHANGE_ME_routerai_key
+RA_MODEL=moonshotai/kimi-k2-thinking
+

.gitignore

@@ -1,3 +1,8 @@
 __pycache__/
 *.py[cod]
 *$py.class
+
+# Секреты инстанса — только шаблон .env.example в репозитории
+.env
+.env.local
+.env.*.local

README.md

@@ -1,6 +1,6 @@
 # Zilant / VOLK — Telegram poster и подписки
 
-**Версия:** 1.0.1 ([`VERSION`](VERSION))
+**Версия:** 1.0.2 ([`VERSION`](VERSION))
 
 Автоматическая публикация постов и событий в Telegram-канал, веб-редактор, бот подписок с сезонными deep link.
 
@@ -23,7 +23,9 @@ sudo systemctl status testedit-git.service  # UI  :5006
 sudo systemctl status runner.timer          # hourly pipeline
 ```
 
-Конфигурация — `.env` (не коммитится). Ключевые переменные: `RELAY_URL`, `WEBHOOK_URL`, `SEASON`, `MDB_*`.
+Конфигурация — скопируйте [`.env.example`](.env.example) в `.env` и заполните значения
+(файл `.env` в git не коммитится). Ключевые переменные: `WORKMODE`, `RELAY_URL`, `WEBHOOK_URL`, `SEASON`, `MDB_*`.
+Генерация секретов: `python tools/ops/genkey.py`.
 
 ## Пайплайн (ZILANT)
 

VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

docs/ARCHITECTURE.md

@@ -76,6 +76,13 @@
 
 ## Конфигурация (.env)
 
+Шаблон для нового инстанса: [`.env.example`](../.env.example).
+
+```bash
+cp .env.example .env
+# заполнить CHANGE_ME_*; секреты: python tools/ops/genkey.py
+```
+
 | Переменная | Назначение |
 |------------|------------|
 | `WORKMODE` | `ZILANT` или `VOLK` |
@@ -84,6 +91,9 @@
 | `WEBHOOK_URL`, `WEBHOOK_SECRET` | Доставка апдейтов боту |
 | `MDB_*`, `MDBASE` | MariaDB |
 | `POSTER_BOT_TOKEN`, `RESPONDER_BOT_TOKEN` | Токены ботов |
+| `PZK_PREFIX`, `EVT_PREFIX`, `DESC_PREFIX` | Ссылки ZILANT |
+| `VOLK_*` | API VOLK (при `WORKMODE=VOLK`) |
+| `RA_KEY`, `RA_MODEL` | RouterAI для shortname |
 
 ## Карта файлов
 

docs/CHANGELOG.md

@@ -3,6 +3,17 @@
 Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/).
 Версия проекта — в файле [`VERSION`](../VERSION) (SemVer).
 
+## [1.0.2] - 2026-08-30
+
+### Added
+
+- Шаблон окружения [`.env.example`](../.env.example) для ZILANT и VOLK (секреты — плейсхолдеры).
+- `.env` добавлен в [`.gitignore`](../.gitignore).
+
+### Documentation
+
+- README и `docs/ARCHITECTURE.md`: копирование `.env.example` → `.env` при настройке инстанса.
+
 ## [1.0.1] - 2026-08-30
 
 ### Changed

docs/volk-mode.md

@@ -1,6 +1,6 @@
 # Режим VOLK
 
-Режим включается в `.env`:
+Режим включается в `.env` (скопируйте из [`.env.example`](../.env.example)):
 
 ```env
 WORKMODE = "VOLK"