289 lines
9.8 KiB
Markdown
289 lines
9.8 KiB
Markdown
# Инструкция: перенос UI и загрузки файлов с ВМ на Flask (Штурвал)
|
||
|
||
**Дата:** 2026-07-14
|
||
**Основано на:** drhider v0.0.26 — проверено в бою
|
||
|
||
---
|
||
|
||
## Архитектура загрузки (drhider как образец)
|
||
|
||
```
|
||
Браузер (index.html)
|
||
│ JS: uploadFiles() — цикл по файлам
|
||
│ XHR POST /api/upload (FormData, по одному файлу)
|
||
▼
|
||
Flask (api_bp.py)
|
||
│ upload(): сохраняет в сессию → {session_id}
|
||
│ process_stream(): SSE — обработка с прогрессом
|
||
▼
|
||
Python (drhider/*.py)
|
||
│ obfuscate_files() — основная логика
|
||
▼
|
||
Flask → ZIP + CSV → браузеру
|
||
```
|
||
|
||
## Файлы, отвечающие за UI и загрузку
|
||
|
||
### 1. `site/templates/index.html` — весь фронтенд
|
||
|
||
**Ключевые элементы:**
|
||
|
||
```html
|
||
<!-- Файловый инпут — множественный выбор -->
|
||
<input type="file" id="fileInput" multiple accept=".docx,.pdf,.txt,.zip">
|
||
|
||
<!-- Таблица выбранных файлов -->
|
||
<table>
|
||
<tbody id="fileList"></tbody>
|
||
</table>
|
||
|
||
<!-- Статус-бар -->
|
||
<div class="status" id="status"></div>
|
||
|
||
<!-- Кнопки скачивания (скрыты до готовности) -->
|
||
<div class="dl-btns" id="dlBtns">
|
||
<button onclick="downloadZip()">📦 Скачать ZIP</button>
|
||
<button onclick="downloadCsv()">📋 Скачать CSV</button>
|
||
</div>
|
||
```
|
||
|
||
**Ключевые JS-функции:**
|
||
|
||
| Функция | Что делает |
|
||
|---------|------------|
|
||
| `resetAll()` | Сброс всего состояния (F5, между загрузками) |
|
||
| `rr()` | Перерисовка таблицы файлов |
|
||
| `uploadFiles()` | **Главная** — цикл загрузки + SSE-обработка |
|
||
| `ss(idx, html)` | Обновление ячейки статуса в таблице |
|
||
| `downloadZip()` / `downloadCsv()` | Скачивание результатов |
|
||
|
||
**Критичные исправления (v0.0.26 — v0.0.29):**
|
||
|
||
```javascript
|
||
// 1. Прогрев upstream при загрузке страницы — обязательно!
|
||
window.addEventListener('load', () => {
|
||
sf = []; fi.value = ''; rr();
|
||
fetch('/health').catch(() => {}); // ← обязательно! греет upstream
|
||
});
|
||
|
||
// 2. Abort предыдущих запросов перед новым
|
||
let activeES = null; // активный EventSource
|
||
let activeXHR = null; // активный XHR
|
||
|
||
// 3. Защита от F5 во время загрузки
|
||
window.addEventListener('beforeunload', () => resetAll());
|
||
|
||
// 4. Сохранение списка файлов до очистки
|
||
const files = sf.slice(); // копия перед resetAll()
|
||
|
||
// 5. Выбор файлов — ДОБАВЛЯЕТ в таблицу (не стирает, с дедупом)
|
||
fi.addEventListener('change', () => {
|
||
const incoming = Array.from(fi.files);
|
||
const seen = new Set(sf.map(f => f.name + '|' + f.size));
|
||
for (const f of incoming) {
|
||
if (!seen.has(f.name + '|' + f.size)) sf.push(f);
|
||
}
|
||
const d = new DataTransfer();
|
||
sf.forEach(f => d.items.add(f));
|
||
fi.files = d.files;
|
||
rr();
|
||
});
|
||
|
||
// 6. Цикл загрузки (fetch, не XHR — XHR давал RST на первом запросе)
|
||
for (let i = 0; i < total; i++) {
|
||
const fd = new FormData();
|
||
fd.append('files', f, f.name);
|
||
if (currentSid) fd.append('session', currentSid);
|
||
const resp = await fetch('/api/upload?_=' + Date.now(), { // ← fetch, не XHR
|
||
method: 'POST', body: fd
|
||
});
|
||
const data = await resp.json();
|
||
currentSid = data.session;
|
||
}
|
||
|
||
// 7. SSE-обработка
|
||
activeES = new EventSource('/api/process_stream/' + currentSid);
|
||
activeES.addEventListener('start', ...); // файл начат
|
||
activeES.addEventListener('done', ...); // файл готов
|
||
activeES.addEventListener('complete', ...); // всё готово
|
||
|
||
// 8. Скачивание ZIP/CSV — через fetch+Blob (не window.location!)
|
||
function downloadZip() {
|
||
if (!currentSid) return;
|
||
fetch('/api/download/' + currentSid)
|
||
.then(r => {
|
||
const disp = r.headers.get('Content-Disposition');
|
||
const m = disp && disp.match(/filename="?(.+?)"?$/);
|
||
return Promise.all([r.blob(), m ? m[1] : 'result.zip']);
|
||
})
|
||
.then(([blob, fname]) => {
|
||
const a = document.createElement('a');
|
||
a.href = URL.createObjectURL(blob);
|
||
a.download = fname;
|
||
document.body.appendChild(a);
|
||
a.click();
|
||
document.body.removeChild(a);
|
||
URL.revokeObjectURL(a.href);
|
||
});
|
||
}
|
||
```
|
||
|
||
### 2. `site/routes/api_bp.py` — API эндпоинты
|
||
|
||
```
|
||
POST /api/upload — загрузка одного файла → {session_id}
|
||
GET /api/process_stream/<sid> — SSE: обработка с прогрессом
|
||
POST /api/process/<sid> — обработка без SSE (legacy)
|
||
GET /api/download/<sid> — скачать ZIP
|
||
GET /api/csv/<sid> — скачать CSV отдельно
|
||
```
|
||
|
||
**Критичные заголовки для SSE:**
|
||
|
||
```python
|
||
return Response(
|
||
stream_with_context(generate()),
|
||
content_type="text/event-stream",
|
||
headers={
|
||
"Cache-Control": "no-cache",
|
||
"X-Accel-Buffering": "no" # ← без этого nginx буферизует SSE
|
||
}
|
||
)
|
||
```
|
||
|
||
**Критично: GeneratorExit в SSE-генераторе:**
|
||
|
||
```python
|
||
def generate():
|
||
for idx, (fname, content) in enumerate(files):
|
||
try:
|
||
yield f"event: start\ndata: ...\n\n"
|
||
except GeneratorExit:
|
||
return # клиент отключился — не обрабатываем дальше
|
||
|
||
# ... обработка файла ...
|
||
|
||
try:
|
||
yield f"event: done\ndata: ...\n\n"
|
||
except GeneratorExit:
|
||
return
|
||
```
|
||
|
||
### 3. `site/routes/health_bp.py` — liveness probe
|
||
|
||
```python
|
||
@health_bp.route("/health")
|
||
def health():
|
||
return jsonify({"ok": True, "version": "0.0.1"})
|
||
```
|
||
|
||
**Обязательно для Штурвала.**
|
||
|
||
### 4. `site/app.py` — точка входа
|
||
|
||
**Критичные настройки:**
|
||
|
||
```python
|
||
VERSION = "0.0.1"
|
||
|
||
def create_app():
|
||
app = Flask(__name__)
|
||
app.config["VERSION"] = VERSION
|
||
app.config["MAX_CONTENT_LENGTH"] = 200 * 1024 * 1024 # 200 MB
|
||
|
||
from routes import register_routes
|
||
register_routes(app)
|
||
|
||
@app.after_request
|
||
def no_cache(response):
|
||
response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
|
||
response.headers["Pragma"] = "no-cache"
|
||
response.headers["Expires"] = "0"
|
||
return response
|
||
|
||
return app
|
||
|
||
app = create_app()
|
||
```
|
||
|
||
---
|
||
|
||
## Пошаговая инструкция миграции
|
||
|
||
### Шаг 1: Скопировать скелет UI
|
||
|
||
Скопировать `site/templates/index.html` из drhider как основу.
|
||
Заменить:
|
||
- Заголовок (`<title>`, `.title`, `.card-header`)
|
||
- Текст описания
|
||
- `accept` в `<input type="file">` если другие форматы
|
||
- Логику в `uploadFiles()` — вызов своего API вместо `obfuscate_files`
|
||
|
||
### Шаг 2: Адаптировать API
|
||
|
||
Скопировать `site/routes/api_bp.py`, заменить:
|
||
- Название blueprint'а
|
||
- Логику в `process_stream()` — вызов своей функции вместо `obfuscate_files()`
|
||
- Формат SSE-событий если нужен другой
|
||
|
||
### Шаг 3: Health endpoint
|
||
|
||
Скопировать `site/routes/health_bp.py` как есть. Только версию поменять.
|
||
|
||
### Шаг 4: app.py
|
||
|
||
Скопировать `site/app.py`, заменить:
|
||
- `VERSION`
|
||
- `MAX_CONTENT_LENGTH` если нужен другой лимит
|
||
- Импорт своих blueprint'ов
|
||
|
||
### Шаг 5: session.py
|
||
|
||
Скопировать `site/session.py` как есть. Это in-memory хранилище загруженных файлов и результатов.
|
||
|
||
### Шаг 6: Интеграция бизнес-логики
|
||
|
||
Твоя функция обработки должна принимать тот же интерфейс что и `obfuscate_files`:
|
||
|
||
```python
|
||
def твоя_функция(files, **kwargs):
|
||
"""
|
||
Args:
|
||
files: list of (filename: str, content: bytes, mimetype: str)
|
||
Returns:
|
||
zip_bytes: bytes — ZIP-архив с результатами
|
||
csv_str: str — CSV с маппингом (или "")
|
||
"""
|
||
```
|
||
|
||
---
|
||
|
||
## Чек-лист перед деплоем
|
||
|
||
- [ ] `/health` возвращает `{"ok": true}`
|
||
- [ ] `MAX_CONTENT_LENGTH` достаточен для файлов
|
||
- [ ] `no_cache` after_request есть
|
||
- [ ] `X-Accel-Buffering: no` на SSE-эндпоинте
|
||
- [ ] `GeneratorExit` в каждом `yield` SSE-генератора
|
||
- [ ] `stream_with_context` оборачивает генератор
|
||
- [ ] `fetch('/health')` при загрузке страницы
|
||
- [ ] `beforeunload` → `resetAll()`
|
||
- [ ] `activeXHR` и `activeES` очищаются перед новым запуском
|
||
- [ ] `fetch` вместо XHR (XHR на первом запросе даёт RST)
|
||
- [ ] Выбор файлов — добавляет, не стирает (с дедупом)
|
||
- [ ] `Connection: close` — **НЕ ставить** (Waitress/PEP 3333 запрещает hop-by-hop)
|
||
|
||
---
|
||
|
||
## Ссылки на файлы-образцы
|
||
|
||
| Что | Где в drhider |
|
||
|-----|---------------|
|
||
| HTML/JS/CSS фронтенд | `site/templates/index.html` |
|
||
| API (upload + SSE + download) | `site/routes/api_bp.py` |
|
||
| Health probe | `site/routes/health_bp.py` |
|
||
| Точка входа Flask | `site/app.py` |
|
||
| In-memory сессии | `site/session.py` |
|
||
| Полная архитектура | `docs/ARCHITECTURE.md` |
|
||
| Решённые проблемы кластера | `PROBLEM-AND-SOLUTION.md` |
|