v4.1.21: Реструктуризация проекта для Synology ARM
- Реструктуризация: src/ разбит на middleware/, utils/, repositories/ (удалены), routes/ (удалены) - Добавлен src/original-html.ts — полный HTML с reportModal - Добавлен src/index.tsx.backup — React-компонент с reportModal - Миграции переименованы (0001_initial_schema.sql) - Добавлена миграция 0018 (удалена позже) - Docker: multi-stage build, wrangler.toml - Frontend: public/static/app.js + style.css - seed.sql добавлен - Документация: CHANGELOG, CHANGES_v4.1.0-4.1.9, PROJECT_STRUCTURE
This commit is contained in:
Deploy Bot
629
DOCKER_GUIDE.md
Normal file
629
DOCKER_GUIDE.md
Normal file
@@ -0,0 +1,629 @@
|
||||
# 🐳 Docker Guide - AKNAPROFF Tootmine
|
||||
|
||||
## 📋 Оглавление
|
||||
1. [Быстрый старт](#быстрый-старт)
|
||||
2. [Структура файлов](#структура-файлов)
|
||||
3. [Development режим](#development-режим)
|
||||
4. [Production режим](#production-режим)
|
||||
5. [База данных](#база-данных)
|
||||
6. [Команды Docker](#команды-docker)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### Prerequisite
|
||||
Установите Docker и Docker Compose:
|
||||
- **Docker**: https://docs.docker.com/get-docker/
|
||||
- **Docker Compose**: обычно идёт в комплекте с Docker Desktop
|
||||
|
||||
### Development режим (с локальной БД)
|
||||
|
||||
```bash
|
||||
# 1. Клонировать проект (или быть в папке проекта)
|
||||
cd /path/to/webapp
|
||||
|
||||
# 2. Запустить Docker Compose
|
||||
docker-compose up
|
||||
|
||||
# 3. Открыть браузер
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
**✅ БД будет храниться в `.wrangler/state/v3/d1/` внутри проекта!**
|
||||
|
||||
---
|
||||
|
||||
## 📁 Структура файлов
|
||||
|
||||
### Созданные Docker файлы:
|
||||
|
||||
```
|
||||
webapp/
|
||||
├── docker-compose.yml # Development конфигурация
|
||||
├── docker-compose.prod.yml # Production конфигурация
|
||||
├── Dockerfile # Production образ
|
||||
├── .dockerignore # Исключения для Docker build
|
||||
└── DOCKER_GUIDE.md # Эта инструкция
|
||||
```
|
||||
|
||||
### Где хранится БД:
|
||||
|
||||
#### Development режим (docker-compose.yml):
|
||||
```
|
||||
./ # Корень проекта
|
||||
└── .wrangler/
|
||||
└── state/
|
||||
└── v3/
|
||||
└── d1/
|
||||
└── webapp-production.sqlite # ✅ БД здесь!
|
||||
```
|
||||
|
||||
#### Production режим (docker-compose.prod.yml):
|
||||
```
|
||||
./ # Корень проекта
|
||||
└── data/
|
||||
└── db/
|
||||
└── webapp-production.sqlite # ✅ БД здесь!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Development режим
|
||||
|
||||
### Запуск
|
||||
|
||||
```bash
|
||||
# Запустить в foreground (видеть логи)
|
||||
docker-compose up
|
||||
|
||||
# Запустить в background (daemon)
|
||||
docker-compose up -d
|
||||
|
||||
# Посмотреть логи
|
||||
docker-compose logs -f
|
||||
```
|
||||
|
||||
### Особенности Development режима:
|
||||
|
||||
1. **Hot reload**: Изменения в коде сразу видны (bind mount)
|
||||
2. **Локальная БД**: Хранится в `.wrangler/state/v3/d1/`
|
||||
3. **Автоматический rebuild**: При изменении `package.json`
|
||||
4. **Debug режим**: Все логи в консоль
|
||||
|
||||
### Структура docker-compose.yml:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
# Весь проект монтируется
|
||||
- ./:/app
|
||||
# node_modules остаются в контейнере
|
||||
- /app/node_modules
|
||||
```
|
||||
|
||||
**Почему это работает:**
|
||||
- ✅ Весь проект доступен в контейнере
|
||||
- ✅ `.wrangler/` создаётся внутри проекта
|
||||
- ✅ БД физически на вашем диске в проекте
|
||||
- ✅ Можно бэкапить вместе с проектом
|
||||
|
||||
### Остановка
|
||||
|
||||
```bash
|
||||
# Остановить контейнеры
|
||||
docker-compose down
|
||||
|
||||
# Остановить и удалить volumes (НЕ УДАЛЯЕТ ЛОКАЛЬНЫЕ ФАЙЛЫ)
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Production режим
|
||||
|
||||
### Build и запуск
|
||||
|
||||
```bash
|
||||
# 1. Создать директорию для БД
|
||||
mkdir -p data/db data/logs
|
||||
|
||||
# 2. Build образа
|
||||
docker-compose -f docker-compose.prod.yml build
|
||||
|
||||
# 3. Запуск
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
|
||||
# 4. Проверить логи
|
||||
docker-compose -f docker-compose.prod.yml logs -f
|
||||
```
|
||||
|
||||
### Особенности Production режима:
|
||||
|
||||
1. **Multi-stage build**: Оптимизированный образ
|
||||
2. **Non-root user**: Безопасность
|
||||
3. **Health checks**: Автоматическая проверка
|
||||
4. **Resource limits**: CPU и Memory limits
|
||||
5. **Локальная БД**: Хранится в `./data/db/`
|
||||
|
||||
### Структура docker-compose.prod.yml:
|
||||
|
||||
```yaml
|
||||
volumes:
|
||||
# Только БД монтируется локально
|
||||
- ./data/db:/app/.wrangler/state/v3/d1
|
||||
- ./data/logs:/app/logs
|
||||
```
|
||||
|
||||
**Почему отдельная папка `data/`:**
|
||||
- ✅ Чистое разделение данных и кода
|
||||
- ✅ Легко бэкапить: `tar -czf backup.tar.gz data/`
|
||||
- ✅ Можно смонтировать на отдельный диск
|
||||
- ✅ Безопасность: права доступа только к `data/`
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ База данных
|
||||
|
||||
### Где находится БД
|
||||
|
||||
#### Development:
|
||||
```bash
|
||||
# Путь к БД
|
||||
./webapp/.wrangler/state/v3/d1/webapp-production.sqlite
|
||||
|
||||
# Посмотреть БД
|
||||
sqlite3 .wrangler/state/v3/d1/webapp-production.sqlite
|
||||
```
|
||||
|
||||
#### Production:
|
||||
```bash
|
||||
# Путь к БД
|
||||
./webapp/data/db/webapp-production.sqlite
|
||||
|
||||
# Посмотреть БД
|
||||
sqlite3 data/db/webapp-production.sqlite
|
||||
```
|
||||
|
||||
### Бэкап БД
|
||||
|
||||
#### Автоматический бэкап (рекомендуется):
|
||||
|
||||
```bash
|
||||
# Создать скрипт backup.sh
|
||||
cat > backup.sh << 'EOF'
|
||||
#!/bin/bash
|
||||
DATE=$(date +%Y%m%d_%H%M%S)
|
||||
BACKUP_DIR="./backups"
|
||||
mkdir -p $BACKUP_DIR
|
||||
|
||||
# Development БД
|
||||
if [ -f ".wrangler/state/v3/d1/webapp-production.sqlite" ]; then
|
||||
cp .wrangler/state/v3/d1/webapp-production.sqlite \
|
||||
$BACKUP_DIR/webapp-dev-$DATE.sqlite
|
||||
echo "✅ Dev DB backed up: $BACKUP_DIR/webapp-dev-$DATE.sqlite"
|
||||
fi
|
||||
|
||||
# Production БД
|
||||
if [ -f "data/db/webapp-production.sqlite" ]; then
|
||||
cp data/db/webapp-production.sqlite \
|
||||
$BACKUP_DIR/webapp-prod-$DATE.sqlite
|
||||
echo "✅ Prod DB backed up: $BACKUP_DIR/webapp-prod-$DATE.sqlite"
|
||||
fi
|
||||
EOF
|
||||
|
||||
chmod +x backup.sh
|
||||
|
||||
# Запустить бэкап
|
||||
./backup.sh
|
||||
```
|
||||
|
||||
#### Ручной бэкап:
|
||||
|
||||
```bash
|
||||
# Development
|
||||
cp .wrangler/state/v3/d1/webapp-production.sqlite \
|
||||
webapp-backup-$(date +%Y%m%d).sqlite
|
||||
|
||||
# Production
|
||||
cp data/db/webapp-production.sqlite \
|
||||
webapp-backup-$(date +%Y%m%d).sqlite
|
||||
```
|
||||
|
||||
### Восстановление БД
|
||||
|
||||
```bash
|
||||
# Development
|
||||
cp webapp-backup-20251128.sqlite \
|
||||
.wrangler/state/v3/d1/webapp-production.sqlite
|
||||
|
||||
# Production
|
||||
cp webapp-backup-20251128.sqlite \
|
||||
data/db/webapp-production.sqlite
|
||||
|
||||
# Перезапустить контейнер
|
||||
docker-compose restart # Development
|
||||
docker-compose -f docker-compose.prod.yml restart # Production
|
||||
```
|
||||
|
||||
### Сброс БД
|
||||
|
||||
```bash
|
||||
# Зайти в контейнер
|
||||
docker-compose exec webapp sh
|
||||
|
||||
# Внутри контейнера
|
||||
npm run db:reset
|
||||
|
||||
# Или снаружи
|
||||
docker-compose exec webapp npm run db:reset
|
||||
```
|
||||
|
||||
### Миграции
|
||||
|
||||
```bash
|
||||
# Применить миграции
|
||||
docker-compose exec webapp npm run db:migrate:local
|
||||
|
||||
# Залить seed данные
|
||||
docker-compose exec webapp npm run db:seed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📦 Команды Docker
|
||||
|
||||
### Базовые команды
|
||||
|
||||
```bash
|
||||
# Запустить
|
||||
docker-compose up
|
||||
|
||||
# Запустить в background
|
||||
docker-compose up -d
|
||||
|
||||
# Остановить
|
||||
docker-compose down
|
||||
|
||||
# Остановить и удалить volumes
|
||||
docker-compose down -v
|
||||
|
||||
# Перезапустить
|
||||
docker-compose restart
|
||||
|
||||
# Посмотреть логи
|
||||
docker-compose logs -f
|
||||
|
||||
# Посмотреть логи конкретного сервиса
|
||||
docker-compose logs -f webapp
|
||||
```
|
||||
|
||||
### Управление контейнерами
|
||||
|
||||
```bash
|
||||
# Список контейнеров
|
||||
docker-compose ps
|
||||
|
||||
# Зайти в контейнер
|
||||
docker-compose exec webapp sh
|
||||
|
||||
# Выполнить команду в контейнере
|
||||
docker-compose exec webapp npm run build
|
||||
|
||||
# Посмотреть использование ресурсов
|
||||
docker stats aknaproff-webapp
|
||||
```
|
||||
|
||||
### Build и образы
|
||||
|
||||
```bash
|
||||
# Build заново
|
||||
docker-compose build
|
||||
|
||||
# Build без кэша
|
||||
docker-compose build --no-cache
|
||||
|
||||
# Посмотреть образы
|
||||
docker images | grep webapp
|
||||
|
||||
# Удалить неиспользуемые образы
|
||||
docker image prune -a
|
||||
```
|
||||
|
||||
### Logs и debugging
|
||||
|
||||
```bash
|
||||
# Все логи
|
||||
docker-compose logs
|
||||
|
||||
# Последние 100 строк
|
||||
docker-compose logs --tail=100
|
||||
|
||||
# Follow (live)
|
||||
docker-compose logs -f
|
||||
|
||||
# Только ошибки
|
||||
docker-compose logs | grep ERROR
|
||||
|
||||
# Экспорт логов в файл
|
||||
docker-compose logs > webapp-logs.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Troubleshooting
|
||||
|
||||
### Проблема: Контейнер не запускается
|
||||
|
||||
**Симптомы:**
|
||||
```
|
||||
Error: Cannot find module 'hono'
|
||||
```
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Удалить node_modules и пересобрать
|
||||
docker-compose down -v
|
||||
docker-compose build --no-cache
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Проблема: Порт 3000 занят
|
||||
|
||||
**Симптомы:**
|
||||
```
|
||||
Error: bind: address already in use
|
||||
```
|
||||
|
||||
**Решение 1: Убить процесс на порту 3000**
|
||||
```bash
|
||||
# Linux/Mac
|
||||
lsof -ti:3000 | xargs kill -9
|
||||
|
||||
# Или
|
||||
fuser -k 3000/tcp
|
||||
```
|
||||
|
||||
**Решение 2: Изменить порт в docker-compose.yml**
|
||||
```yaml
|
||||
ports:
|
||||
- "3001:3000" # Host:Container
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Проблема: БД не создаётся
|
||||
|
||||
**Симптомы:**
|
||||
```
|
||||
Error: no such table: users
|
||||
```
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# Зайти в контейнер
|
||||
docker-compose exec webapp sh
|
||||
|
||||
# Сбросить БД
|
||||
npm run db:reset
|
||||
|
||||
# Выйти
|
||||
exit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Проблема: БД пропала после перезапуска
|
||||
|
||||
**Причина:** Использовали `docker-compose down -v` (удаляет volumes)
|
||||
|
||||
**Решение:**
|
||||
```bash
|
||||
# НЕ используйте -v если нужно сохранить данные
|
||||
docker-compose down # ✅ Правильно
|
||||
|
||||
# Используйте -v только для полной очистки
|
||||
docker-compose down -v # ❌ Удалит volumes
|
||||
```
|
||||
|
||||
**Но в нашем случае:**
|
||||
- ✅ БД хранится в `./` или `./data/` (bind mount)
|
||||
- ✅ `docker-compose down -v` НЕ удалит файлы на хосте
|
||||
- ✅ Безопасно использовать `-v`
|
||||
|
||||
---
|
||||
|
||||
### Проблема: Изменения в коде не видны
|
||||
|
||||
**Development режим:**
|
||||
```bash
|
||||
# Проверить bind mount
|
||||
docker-compose exec webapp ls -la /app
|
||||
|
||||
# Если bind mount не работает, перезапустить
|
||||
docker-compose down
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
**Production режим:**
|
||||
```bash
|
||||
# Production требует rebuild
|
||||
docker-compose -f docker-compose.prod.yml build
|
||||
docker-compose -f docker-compose.prod.yml up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Проблема: Недостаточно памяти
|
||||
|
||||
**Симптомы:**
|
||||
```
|
||||
JavaScript heap out of memory
|
||||
```
|
||||
|
||||
**Решение: Увеличить memory limit**
|
||||
```yaml
|
||||
# docker-compose.prod.yml
|
||||
deploy:
|
||||
resources:
|
||||
limits:
|
||||
memory: 1G # Было 512M
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Мониторинг
|
||||
|
||||
### Использование ресурсов
|
||||
|
||||
```bash
|
||||
# Real-time статистика
|
||||
docker stats aknaproff-webapp
|
||||
|
||||
# Вывод:
|
||||
# CONTAINER CPU % MEM USAGE / LIMIT MEM %
|
||||
# aknaproff... 0.5% 120MB / 512MB 23%
|
||||
```
|
||||
|
||||
### Health checks
|
||||
|
||||
```bash
|
||||
# Проверить health status
|
||||
docker-compose ps
|
||||
|
||||
# Вывод:
|
||||
# NAME STATUS
|
||||
# aknaproff-webapp Up (healthy)
|
||||
```
|
||||
|
||||
### Логи приложения
|
||||
|
||||
```bash
|
||||
# Live логи
|
||||
docker-compose logs -f webapp
|
||||
|
||||
# Ошибки
|
||||
docker-compose logs webapp | grep ERROR
|
||||
|
||||
# Экспорт в файл
|
||||
docker-compose logs webapp > logs.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
### 1. Регулярные бэкапы
|
||||
|
||||
```bash
|
||||
# Добавить в cron (каждый день в 3:00)
|
||||
0 3 * * * cd /path/to/webapp && ./backup.sh
|
||||
```
|
||||
|
||||
### 2. Мониторинг дискового пространства
|
||||
|
||||
```bash
|
||||
# Проверить размер БД
|
||||
du -sh .wrangler/state/v3/d1/
|
||||
du -sh data/db/
|
||||
|
||||
# Проверить свободное место
|
||||
df -h
|
||||
```
|
||||
|
||||
### 3. Обновление образов
|
||||
|
||||
```bash
|
||||
# Обновить base образы
|
||||
docker-compose pull
|
||||
|
||||
# Rebuild с новыми образами
|
||||
docker-compose build --no-cache
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
### 4. Безопасность
|
||||
|
||||
```bash
|
||||
# Использовать .env для секретов
|
||||
echo "CLOUDFLARE_API_TOKEN=your_token" > .env
|
||||
|
||||
# Добавить в .gitignore
|
||||
echo ".env" >> .gitignore
|
||||
|
||||
# В docker-compose.yml
|
||||
env_file:
|
||||
- .env
|
||||
```
|
||||
|
||||
### 5. Логирование
|
||||
|
||||
```bash
|
||||
# Ротация логов (добавить в docker-compose.yml)
|
||||
logging:
|
||||
driver: "json-file"
|
||||
options:
|
||||
max-size: "10m"
|
||||
max-file: "3"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Полезные ссылки
|
||||
|
||||
- **Docker Docs**: https://docs.docker.com/
|
||||
- **Docker Compose**: https://docs.docker.com/compose/
|
||||
- **Cloudflare Workers**: https://developers.cloudflare.com/workers/
|
||||
- **Wrangler CLI**: https://developers.cloudflare.com/workers/wrangler/
|
||||
- **Hono Framework**: https://hono.dev/
|
||||
|
||||
---
|
||||
|
||||
## ✅ Проверочный чек-лист
|
||||
|
||||
### Development:
|
||||
- [ ] `docker-compose up` запускается без ошибок
|
||||
- [ ] Приложение доступно на http://localhost:3000
|
||||
- [ ] БД создалась в `.wrangler/state/v3/d1/`
|
||||
- [ ] Демо-данные загрузились (5 записей за январь 2025)
|
||||
- [ ] Hot reload работает (изменения видны)
|
||||
- [ ] Health check: `docker-compose ps` → `(healthy)`
|
||||
|
||||
### Production:
|
||||
- [ ] `docker-compose -f docker-compose.prod.yml build` успешно
|
||||
- [ ] `docker-compose -f docker-compose.prod.yml up -d` запустился
|
||||
- [ ] Приложение доступно на http://localhost:3000
|
||||
- [ ] БД создалась в `./data/db/`
|
||||
- [ ] Демо-данные загрузились
|
||||
- [ ] Health check: `(healthy)`
|
||||
- [ ] Бэкап работает: `./backup.sh`
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Готово!
|
||||
|
||||
**AKNAPROFF Tootmine теперь работает в Docker с локальной БД!**
|
||||
|
||||
**Production URL (Docker):**
|
||||
http://localhost:3000
|
||||
|
||||
**Demo Accounts:**
|
||||
- `admin` / `demo123`
|
||||
- `aknaproff` / `demo123`
|
||||
- **Public User** (без логина)
|
||||
|
||||
**База данных:**
|
||||
- **Development**: `.wrangler/state/v3/d1/webapp-production.sqlite`
|
||||
- **Production**: `./data/db/webapp-production.sqlite`
|
||||
|
||||
**Бэкап:**
|
||||
```bash
|
||||
./backup.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*Создано: 28.11.2025*
|
||||
*Версия проекта: v4.0.13*
|
||||
Reference in New Issue
Block a user