orohi
609 lines
17 KiB
Markdown
609 lines
17 KiB
Markdown
# PhotoHost — Подробная инструкция по установке
|
||
|
||
**Версия:** 1.0.0-beta
|
||
|
||
PhotoHost — фотохостинг на Next.js 15 с PostgreSQL. Ниже описаны все способы установки: через Docker (рекомендуется), локальная разработка и production-деплой на сервер.
|
||
|
||
---
|
||
|
||
## Содержание
|
||
|
||
1. [Требования](#1-требования)
|
||
2. [Получение исходного кода](#2-получение-исходного-кода)
|
||
3. [Установка через Docker (рекомендуется)](#3-установка-через-docker-рекомендуется)
|
||
4. [Локальная разработка без Docker](#4-локальная-разработка-без-docker)
|
||
5. [Настройка переменных окружения](#5-настройка-переменных-окружения)
|
||
6. [Production-деплой на сервер](#6-production-деплой-на-сервер)
|
||
7. [Проверка работоспособности](#7-проверка-работоспособности)
|
||
8. [Обновление](#8-обновление)
|
||
9. [Резервное копирование](#9-резервное-копирование)
|
||
10. [Устранение неполадок](#10-устранение-неполадок)
|
||
|
||
---
|
||
|
||
## 1. Требования
|
||
|
||
### Для установки через Docker (минимальный набор)
|
||
|
||
| Компонент | Минимальная версия |
|
||
|-----------|-------------------|
|
||
| Docker | 24.0+ |
|
||
| Docker Compose | 2.20+ |
|
||
| Свободная RAM | 1 ГБ |
|
||
| Свободное место на диске | 2 ГБ |
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
docker --version
|
||
docker compose version
|
||
```
|
||
|
||
### Для локальной разработки (дополнительно)
|
||
|
||
| Компонент | Минимальная версия |
|
||
|-----------|-------------------|
|
||
| Node.js | 20.x или 22.x |
|
||
| npm | 10.x+ |
|
||
| PostgreSQL | 16.x (или Docker только для БД) |
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
node --version
|
||
npm --version
|
||
```
|
||
|
||
### Сетевые порты
|
||
|
||
| Порт | Назначение |
|
||
|------|------------|
|
||
| `3000` | Веб-приложение PhotoHost |
|
||
| `5432` | PostgreSQL (только при локальной разработке или если проброшен наружу) |
|
||
|
||
Убедитесь, что порты свободны:
|
||
|
||
```bash
|
||
# Linux / macOS
|
||
ss -tlnp | grep -E '3000|5432'
|
||
|
||
# Windows PowerShell
|
||
netstat -ano | findstr ":3000"
|
||
netstat -ano | findstr ":5432"
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Получение исходного кода
|
||
|
||
### Из Git-репозитория
|
||
|
||
```bash
|
||
git clone https://git.evilfox.cc/test2/hosting-files.git photohost
|
||
cd photohost
|
||
```
|
||
|
||
### Из архива релиза
|
||
|
||
Скачайте архив с [страницы релиза v1.0.0-beta](https://git.evilfox.cc/test2/hosting-files/releases/tag/v1.0.0-beta) и распакуйте:
|
||
|
||
```bash
|
||
# Linux / macOS
|
||
tar -xzf hosting-files-1.0.0-beta.tar.gz
|
||
cd hosting-files
|
||
|
||
# Windows PowerShell
|
||
Expand-Archive hosting-files-1.0.0-beta.zip -DestinationPath photohost
|
||
cd photohost
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Установка через Docker (рекомендуется)
|
||
|
||
Самый простой способ — один контейнер с приложением и один с PostgreSQL. База данных и загруженные файлы сохраняются в Docker volumes.
|
||
|
||
### Шаг 1. Перейдите в каталог проекта
|
||
|
||
```bash
|
||
cd photohost
|
||
```
|
||
|
||
### Шаг 2. (Опционально) Измените пароль БД
|
||
|
||
По умолчанию используются учётные данные из `docker-compose.yml`:
|
||
|
||
| Параметр | Значение по умолчанию |
|
||
|----------|----------------------|
|
||
| Пользователь БД | `photohost` |
|
||
| Пароль БД | `photohost_secret` |
|
||
| Имя базы | `photohost` |
|
||
|
||
Для production **обязательно** смените пароль. Откройте `docker-compose.yml` и измените:
|
||
|
||
```yaml
|
||
environment:
|
||
POSTGRES_PASSWORD: ваш_надёжный_пароль
|
||
```
|
||
|
||
И в секции `app`:
|
||
|
||
```yaml
|
||
environment:
|
||
DATABASE_URL: postgresql://photohost:ваш_надёжный_пароль@db:5432/photohost?schema=public
|
||
```
|
||
|
||
### Шаг 3. Сборка и запуск
|
||
|
||
```bash
|
||
docker compose up --build -d
|
||
```
|
||
|
||
Флаги:
|
||
- `--build` — пересобрать образ приложения
|
||
- `-d` — запуск в фоновом режиме
|
||
|
||
Первый запуск занимает 2–5 минут (скачивание образов, установка npm-зависимостей, сборка Next.js).
|
||
|
||
### Шаг 4. Проверка статуса контейнеров
|
||
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
|
||
Ожидаемый результат:
|
||
|
||
```
|
||
NAME STATUS PORTS
|
||
photohost-app Up 0.0.0.0:3000->3000/tcp
|
||
photohost-db Up (healthy) 0.0.0.0:5432->5432/tcp
|
||
```
|
||
|
||
### Шаг 5. Просмотр логов (при необходимости)
|
||
|
||
```bash
|
||
# Все сервисы
|
||
docker compose logs -f
|
||
|
||
# Только приложение
|
||
docker compose logs -f app
|
||
|
||
# Только база данных
|
||
docker compose logs -f db
|
||
```
|
||
|
||
### Шаг 6. Откройте в браузере
|
||
|
||
```
|
||
http://localhost:3000
|
||
```
|
||
|
||
### Управление сервисами
|
||
|
||
```bash
|
||
# Остановить
|
||
docker compose stop
|
||
|
||
# Запустить снова
|
||
docker compose start
|
||
|
||
# Остановить и удалить контейнеры (данные в volumes сохранятся)
|
||
docker compose down
|
||
|
||
# Остановить и удалить всё, включая volumes (УДАЛИТ ДАННЫЕ!)
|
||
docker compose down -v
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Локальная разработка без Docker
|
||
|
||
Подходит для разработки и отладки. PostgreSQL можно запустить в Docker, а приложение — локально через Node.js.
|
||
|
||
### Шаг 1. Установите Node.js
|
||
|
||
Скачайте LTS-версию с [nodejs.org](https://nodejs.org/) (рекомендуется 22.x).
|
||
|
||
### Шаг 2. Создайте файл `.env`
|
||
|
||
```bash
|
||
# Linux / macOS
|
||
cp .env.example .env
|
||
|
||
# Windows PowerShell
|
||
Copy-Item .env.example .env
|
||
```
|
||
|
||
Содержимое `.env`:
|
||
|
||
```env
|
||
DATABASE_URL="postgresql://photohost:photohost_secret@localhost:5432/photohost?schema=public"
|
||
```
|
||
|
||
### Шаг 3. Запустите PostgreSQL
|
||
|
||
**Вариант A — PostgreSQL в Docker (рекомендуется):**
|
||
|
||
```bash
|
||
docker compose up db -d
|
||
```
|
||
|
||
**Вариант B — локально установленный PostgreSQL:**
|
||
|
||
```sql
|
||
CREATE USER photohost WITH PASSWORD 'photohost_secret';
|
||
CREATE DATABASE photohost OWNER photohost;
|
||
```
|
||
|
||
### Шаг 4. Установите зависимости
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
### Шаг 5. Примените схему базы данных
|
||
|
||
```bash
|
||
npx prisma db push
|
||
```
|
||
|
||
Команда создаст таблицу `Photo` в PostgreSQL согласно `prisma/schema.prisma`.
|
||
|
||
### Шаг 6. Создайте каталог для загрузок
|
||
|
||
```bash
|
||
# Linux / macOS
|
||
mkdir -p public/uploads
|
||
|
||
# Windows PowerShell
|
||
New-Item -ItemType Directory -Force -Path public\uploads
|
||
```
|
||
|
||
### Шаг 7. Запустите dev-сервер
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
Приложение будет доступно на [http://localhost:3000](http://localhost:3000) с hot-reload.
|
||
|
||
### Полезные команды для разработки
|
||
|
||
```bash
|
||
npm run build # Production-сборка
|
||
npm run start # Запуск production-сборки локально
|
||
npm run lint # Проверка ESLint
|
||
npm run db:push # Синхронизация схемы БД
|
||
npm run db:generate # Перегенерация Prisma Client
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Настройка переменных окружения
|
||
|
||
| Переменная | Обязательная | Описание | Пример |
|
||
|------------|-------------|----------|--------|
|
||
| `DATABASE_URL` | Да | Строка подключения к PostgreSQL | `postgresql://user:pass@host:5432/photohost?schema=public` |
|
||
| `NODE_ENV` | Нет | Режим работы (`development` / `production`) | `production` |
|
||
|
||
### Формат DATABASE_URL
|
||
|
||
```
|
||
postgresql://[пользователь]:[пароль]@[хост]:[порт]/[база]?schema=public
|
||
```
|
||
|
||
Примеры:
|
||
|
||
```env
|
||
# Docker Compose (app → db)
|
||
DATABASE_URL="postgresql://photohost:photohost_secret@db:5432/photohost?schema=public"
|
||
|
||
# Локальная разработка
|
||
DATABASE_URL="postgresql://photohost:photohost_secret@localhost:5432/photohost?schema=public"
|
||
|
||
# Внешний PostgreSQL-сервер
|
||
DATABASE_URL="postgresql://photohost:secret@192.168.1.100:5432/photohost?schema=public"
|
||
```
|
||
|
||
> **Важно:** файл `.env` не коммитится в Git. Никогда не публикуйте пароли в репозитории.
|
||
|
||
---
|
||
|
||
## 6. Production-деплой на сервер
|
||
|
||
### 6.1. Подготовка сервера (Linux)
|
||
|
||
```bash
|
||
# Ubuntu / Debian
|
||
sudo apt update && sudo apt install -y git docker.io docker-compose-plugin
|
||
|
||
# Запуск Docker
|
||
sudo systemctl enable docker
|
||
sudo systemctl start docker
|
||
|
||
# Добавить пользователя в группу docker (перелогиньтесь после)
|
||
sudo usermod -aG docker $USER
|
||
```
|
||
|
||
### 6.2. Клонирование и настройка
|
||
|
||
```bash
|
||
git clone https://git.evilfox.cc/test2/hosting-files.git /opt/photohost
|
||
cd /opt/photohost
|
||
```
|
||
|
||
Измените пароль БД в `docker-compose.yml` (см. раздел 3, шаг 2).
|
||
|
||
### 6.3. Запуск
|
||
|
||
```bash
|
||
docker compose up --build -d
|
||
```
|
||
|
||
### 6.4. Reverse proxy (Nginx)
|
||
|
||
Для доступа по домену и HTTPS настройте Nginx как прокси:
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name photos.example.com;
|
||
|
||
client_max_body_size 10M;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:3000;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection 'upgrade';
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
proxy_cache_bypass $http_upgrade;
|
||
}
|
||
}
|
||
```
|
||
|
||
Получите SSL-сертификат через Certbot:
|
||
|
||
```bash
|
||
sudo apt install certbot python3-certbot-nginx
|
||
sudo certbot --nginx -d photos.example.com
|
||
```
|
||
|
||
### 6.5. Автозапуск при перезагрузке сервера
|
||
|
||
Docker Compose с `restart: unless-stopped` (уже настроено в `docker-compose.yml`) автоматически перезапускает контейнеры после reboot.
|
||
|
||
Проверка:
|
||
|
||
```bash
|
||
sudo reboot
|
||
# после перезагрузки:
|
||
docker compose ps
|
||
```
|
||
|
||
### 6.6. Firewall
|
||
|
||
```bash
|
||
# UFW (Ubuntu)
|
||
sudo ufw allow 80/tcp
|
||
sudo ufw allow 443/tcp
|
||
sudo ufw enable
|
||
|
||
# Порт 5432 НЕ открывайте наружу — база доступна только внутри Docker-сети
|
||
```
|
||
|
||
Для production рекомендуется убрать проброс порта `5432` из `docker-compose.yml`:
|
||
|
||
```yaml
|
||
# Удалите или закомментируйте:
|
||
# ports:
|
||
# - "5432:5432"
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Проверка работоспособности
|
||
|
||
### 7.1. Веб-интерфейс
|
||
|
||
Откройте `http://localhost:3000` (или ваш домен). Должна отображаться главная страница с зоной загрузки.
|
||
|
||
### 7.2. Загрузка тестового изображения
|
||
|
||
1. Перетащите JPG/PNG файл в зону загрузки (или нажмите для выбора).
|
||
2. Дождитесь сообщения «Фото загружено!».
|
||
3. Скопируйте полученную ссылку и откройте в новой вкладке — изображение должно отображаться.
|
||
|
||
### 7.3. API
|
||
|
||
```bash
|
||
# Список фото
|
||
curl http://localhost:3000/api/photos
|
||
|
||
# Загрузка файла
|
||
curl -X POST http://localhost:3000/api/upload \
|
||
-F "file=@/path/to/image.jpg"
|
||
```
|
||
|
||
### 7.4. База данных
|
||
|
||
```bash
|
||
docker compose exec db psql -U photohost -d photohost -c "SELECT id, \"originalName\", \"createdAt\" FROM \"Photo\" ORDER BY \"createdAt\" DESC LIMIT 5;"
|
||
```
|
||
|
||
### 7.5. Файлы на диске
|
||
|
||
```bash
|
||
docker compose exec app ls -la /app/public/uploads/
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Обновление
|
||
|
||
### Docker-установка
|
||
|
||
```bash
|
||
cd /opt/photohost # или ваш каталог
|
||
|
||
# Получить новую версию
|
||
git pull origin main
|
||
|
||
# Пересобрать и перезапустить
|
||
docker compose up --build -d
|
||
```
|
||
|
||
### Локальная разработка
|
||
|
||
```bash
|
||
git pull origin main
|
||
npm install
|
||
npx prisma db push
|
||
npm run build # для production
|
||
```
|
||
|
||
---
|
||
|
||
## 9. Резервное копирование
|
||
|
||
### База данных
|
||
|
||
```bash
|
||
# Создать дамп
|
||
docker compose exec db pg_dump -U photohost photohost > backup_$(date +%Y%m%d).sql
|
||
|
||
# Восстановить из дампа
|
||
cat backup_20260606.sql | docker compose exec -T db psql -U photohost photohost
|
||
```
|
||
|
||
### Загруженные файлы
|
||
|
||
Файлы хранятся в Docker volume `uploads_data`:
|
||
|
||
```bash
|
||
# Узнать имя volume
|
||
docker volume ls | grep uploads
|
||
|
||
# Скопировать файлы из volume
|
||
docker run --rm -v hosting_uploads_data:/data -v $(pwd):/backup alpine \
|
||
tar czf /backup/uploads_backup.tar.gz -C /data .
|
||
```
|
||
|
||
### Автоматический бэкап (cron)
|
||
|
||
```bash
|
||
# crontab -e
|
||
0 3 * * * cd /opt/photohost && docker compose exec -T db pg_dump -U photohost photohost | gzip > /backups/photohost_$(date +\%Y\%m\%d).sql.gz
|
||
```
|
||
|
||
---
|
||
|
||
## 10. Устранение неполадок
|
||
|
||
### Приложение не запускается
|
||
|
||
```bash
|
||
docker compose logs app
|
||
```
|
||
|
||
**Частые причины:**
|
||
- База данных ещё не готова — подождите 10–15 секунд и проверьте `docker compose ps`
|
||
- Ошибка сборки — убедитесь, что достаточно RAM (минимум 1 ГБ)
|
||
|
||
### Ошибка подключения к БД
|
||
|
||
```
|
||
Error: P1001: Can't reach database server
|
||
```
|
||
|
||
**Решение:**
|
||
1. Проверьте, что контейнер `photohost-db` в статусе `healthy`:
|
||
```bash
|
||
docker compose ps
|
||
```
|
||
2. Проверьте `DATABASE_URL` — хост должен быть `db` внутри Docker, `localhost` при локальной разработке.
|
||
3. Перезапустите сервисы:
|
||
```bash
|
||
docker compose restart
|
||
```
|
||
|
||
### Порт 3000 занят
|
||
|
||
```bash
|
||
# Linux / macOS — найти процесс
|
||
lsof -i :3000
|
||
|
||
# Windows
|
||
netstat -ano | findstr ":3000"
|
||
```
|
||
|
||
Измените порт в `docker-compose.yml`:
|
||
|
||
```yaml
|
||
ports:
|
||
- "8080:3000" # доступ через http://localhost:8080
|
||
```
|
||
|
||
### Загрузка файлов не работает
|
||
|
||
1. Проверьте права на каталог `public/uploads/`
|
||
2. Убедитесь, что файл — изображение (JPG, PNG, GIF, WebP) и меньше 10 МБ
|
||
3. При использовании Nginx проверьте `client_max_body_size 10M;`
|
||
|
||
### Ошибка Prisma при первом запуске
|
||
|
||
```bash
|
||
# Вручную применить схему
|
||
docker compose exec app npx prisma db push
|
||
```
|
||
|
||
### Полный сброс (удалить все данные)
|
||
|
||
```bash
|
||
docker compose down -v
|
||
docker compose up --build -d
|
||
```
|
||
|
||
> **Внимание:** команда `-v` удалит все загруженные фото и данные из базы.
|
||
|
||
---
|
||
|
||
## Структура проекта
|
||
|
||
```
|
||
photohost/
|
||
├── docker-compose.yml # Оркестрация: app + PostgreSQL
|
||
├── Dockerfile # Сборка production-образа
|
||
├── .env.example # Шаблон переменных окружения
|
||
├── package.json # Зависимости Node.js
|
||
├── prisma/
|
||
│ └── schema.prisma # Схема базы данных
|
||
├── public/
|
||
│ ├── icon.svg # Иконка сайта
|
||
│ └── uploads/ # Загруженные изображения
|
||
├── src/
|
||
│ ├── app/
|
||
│ │ ├── api/
|
||
│ │ │ ├── upload/ # POST — загрузка фото
|
||
│ │ │ └── photos/ # GET — список фото
|
||
│ │ ├── globals.css # Стили
|
||
│ │ ├── layout.tsx # Корневой layout
|
||
│ │ └── page.tsx # Главная страница
|
||
│ ├── components/ # UI-компоненты
|
||
│ └── lib/
|
||
│ └── prisma.ts # Клиент Prisma
|
||
├── CHANGELOG.md
|
||
├── INSTALL.md # Эта инструкция
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## Поддержка
|
||
|
||
- Репозиторий: https://git.evilfox.cc/test2/hosting-files
|
||
- Релизы: https://git.evilfox.cc/test2/hosting-files/releases
|