From beed60ba58e81a085c222ee2a1b727d0a17e70c2 Mon Sep 17 00:00:00 2001 From: zailon Date: Fri, 15 May 2026 15:01:06 +0500 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=B8=D1=82?= =?UTF-8?q?=D1=8C=20docs/services/vm-205/nextcloud.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/services/vm-205/nextcloud.md | 346 +++++++++++++++++++----------- 1 file changed, 219 insertions(+), 127 deletions(-) diff --git a/docs/services/vm-205/nextcloud.md b/docs/services/vm-205/nextcloud.md index d9f52bb..04b0515 100644 --- a/docs/services/vm-205/nextcloud.md +++ b/docs/services/vm-205/nextcloud.md @@ -31,51 +31,58 @@ ├── etc/ │ ├── nginx/ │ │ ├── sites-enabled/ -│ │ │ └── nextcloud.conf # Основной конфиг Nginx для Nextcloud +│ │ │ └── nextcloud.conf │ │ └── ssl/ -│ │ ├── cert.pem # Самоподписанный сертификат (для NPM) -│ │ └── cert.key # Приватный ключ +│ │ ├── cert.pem +│ │ └── cert.key │ ├── php/8.3/fpm/pool.d/ -│ │ └── www.conf # Настройки пула PHP-FPM -│ └── letsencrypt/ # НЕ используется внутри контейнера +│ │ └── www.conf +│ └── letsencrypt/ ├── var/ -│ ├── www/nextcloud/ # Ядро Nextcloud -│ │ ├── config/config.php # Основной конфиг приложения -│ │ ├── apps/ # Установленные приложения -│ │ └── data/ -> /mnt/cloud/data # Ссылка на внешнее хранилище -│ └── log/ +│ ├── www/nextcloud/ +│ │ ├── config/config.php +│ │ ├── apps/ +│ │ └── data/ -> /mnt/cloud/data +│ ── log/ │ ├── nginx/ -│ └── apache2/ # Не используется, но установлен +│ └── apache2/ ├── mnt/ │ └── cloud/ -│ ├── data/ # Пользовательские файлы, БД превью, логи -│ └── (другие сервисы) # Общие данные для медиа-сервисов +│ ├── data/ +│ └── (другие сервисы) └── run/ └── php/ - └── php8.3-fpm.sock # Socket для связи Nginx ↔ PHP + └── php8.3-fpm.sock ``` + +> **Пояснения**: +> - `nextcloud.conf` — основной конфиг Nginx для обработки запросов к облаку +> - `cert.pem/cert.key` — самоподписанные сертификаты для проксирования через NPM +> - `www.conf` — настройки пула PHP-FPM (пользователь, сокет, процессы) +> - `config.php` — главный конфиг Nextcloud с параметрами БД, кэша, доменов +> - `/mnt/cloud/data` — точка монтирования внешнего диска с пользовательскими файлами +> - `php8.3-fpm.sock` — UNIX-сокет для связи Nginx с процессором PHP + ## ⚙️ Установка и настройка (ручная) ### Шаг 1: Подготовка системы ```bash -# Обновление пакетов apt update && apt upgrade -y - -# Установка базовых зависимостей -apt install -y nginx php8.3-fpm php8.3-cli php8.3-mysql \ - php8.3-gd php8.3-imagick php8.3-redis php8.3-apcu \ - php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip \ - php8.3-intl php8.3-bcmath php8.3-gmp mariadb-server redis-server - -# Настройка прав для PHP-FPM +apt install -y nginx php8.3-fpm php8.3-cli php8.3-mysql php8.3-gd php8.3-imagick php8.3-redis php8.3-apcu php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip php8.3-intl php8.3-bcmath php8.3-gmp mariadb-server redis-server usermod -a -G www-data redis systemctl enable --now nginx php8.3-fpm mariadb redis-server +``` + +> **Пояснения**: +> - Первая команда обновляет список пакетов и устанавливает апдейты +> - Вторая устанавливает весь необходимый стек: веб-сервер, PHP с модулями, БД, кэш +> - Третья добавляет пользователя www-data в группу redis для доступа к сокету +> - Четвёртая включает автозапуск и запускает все сервисы немедленно ### Шаг 2: Настройка базы данных ```bash -# Создание БД и пользователя mysql -u root -p < **Пояснения**: +> - Создаётся база данных nextcloud с кодировкой utf8mb4 для полной поддержки Unicode +> - Создаётся отдельный пользователь nextcloud с паролем (замените на свой) +> - Пользователю выдаются полные права только на эту базу +> - Команда FLUSH PRIVILEGES применяет изменения без перезагрузки MySQL ### Шаг 3: Установка Nextcloud ```bash -# Скачивание и распаковка cd /tmp wget https://download.nextcloud.com/server/releases/latest.tar.bz2 tar -xjf latest.tar.bz2 -C /var/www/ chown -R www-data:www-data /var/www/nextcloud - -# Создание директории данных mkdir -p /mnt/cloud/data chown -R www-data:www-data /mnt/cloud/data +``` + +> **Пояснения**: +> - Скачивается архив с последней стабильной версией с официального сайта +> - Распаковка производится сразу в /var/www/, создавая папку nextcloud +> - Права меняются на www-data, чтобы веб-сервер мог читать и писать файлы +> - Создаётся директория для данных на отдельном диске с теми же правами ### Шаг 4: Конфигурация Nginx - -Создай файл `/etc/nginx/sites-enabled/nextcloud.conf`: +`/etc/nginx/sites-enabled/nextcloud.conf` ```nginx server { @@ -111,18 +128,15 @@ server { return 301 https://nc.zailon.ru; } - # SSL-сертификаты (самоподписанные для проксирования через NPM) ssl_certificate /etc/nginx/ssl/cert.pem; ssl_certificate_key /etc/nginx/ssl/cert.key; root /var/www/nextcloud; - # HSTS для безопасности add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; client_max_body_size 10G; fastcgi_buffers 64 4K; - # Редиректы для CalDAV, CardDAV, WebDAV rewrite ^/caldav(.*)$ /remote.php/caldav$1 redirect; rewrite ^/carddav(.*)$ /remote.php/carddav$1 redirect; rewrite ^/webdav(.*)$ /remote.php/webdav$1 redirect; @@ -131,12 +145,10 @@ server { error_page 403 = /core/templates/403.php; error_page 404 = /core/templates/404.php; - # Защита системных файлов location ~ ^/(data|config|\.ht|db_structure\.xml|README) { deny all; } - # Well-known URLs для автоконфигурации клиентов location ^~ /.well-known { location = /.well-known/carddav { return 301 /remote.php/dav/; } location = /.well-known/caldav { return 301 /remote.php/dav/; } @@ -146,7 +158,6 @@ server { try_files $uri $uri/ =404; } - # Основной обработчик запросов location / { rewrite ^/.well-known/host-meta /public.php?service=host-meta last; rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json last; @@ -154,7 +165,6 @@ server { try_files $uri $uri/ index.php; } - # PHP-FPM обработчик location ~ ^(.+?\.php)(/.*)?$ { try_files $1 = 404; include fastcgi_params; @@ -164,26 +174,51 @@ server { fastcgi_pass unix:/run/php/php8.3-fpm.sock; } - # Кэширование статики location ~* ^.+\.(jpg|jpeg|gif|bmp|ico|png|css|js|swf)$ { expires modified +30d; access_log off; } } +``` -### Шаг 5: Генерация самоподписанных сертификатов (для NPM) +> **Пояснения**: +> - Слушаются порты 80 и 443, все HTTP-запросы перенаправляются на HTTPS +> - Указываются пути к самоподписанным сертификатам для шифрования внутри контейнера +> - root указывает на директорию с файлами Nextcloud +> - HSTS-заголовок заставляет браузеры всегда использовать HTTPS в будущем +> - client_max_body_size 10G позволяет загружать большие файлы +> - Редиректы для CalDAV/CardDAV/WebDAV обеспечивают работу календарей и контактов +> - Блок `location ~ ^/(data|config|...)` запрещает прямой доступ к чувствительным файлам +> - Обработчик `/.well-known` нужен для автоконфигурации мобильных клиентов +> - Блок с `fastcgi_pass` передаёт PHP-скрипты на обработку в PHP-FPM через сокет +> - Последний блок кэширует статику на 30 дней для ускорения загрузки + +### Шаг 5: Генерация самоподписанных сертификатов ```bash mkdir -p /etc/nginx/ssl -openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \ - -keyout /etc/nginx/ssl/cert.key \ - -out /etc/nginx/ssl/cert.pem \ - -subj "/CN=nc.zailon.ru" +openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/nginx/ssl/cert.key -out /etc/nginx/ssl/cert.pem -subj "/CN=nc.zailon.ru" chmod 600 /etc/nginx/ssl/cert.key +``` + +> **Пояснения**: +> - Создаётся директория для хранения сертификатов +> - openssl генерирует самоподписанный сертификат на 10 лет с ключом 2048 бит +> - Права 600 на приватный ключ запрещают чтение всем, кроме root ### Шаг 6: Настройка PHP 8.3-FPM -Отредактируй `/etc/php/8.3/fpm/pool.d/www.conf`: +Открой файл конфигурации пула для редактирования: + +```bash +nano /etc/php/8.3/fpm/pool.d/www.conf +``` + +> **Пояснения**: +> - `nano` — текстовый редактор терминала +> - Этот файл уже существует, но нужно заменить дефолтные настройки на указанные ниже + +Найди соответствующие строки в файле и замени их на: ```bash user = www-data @@ -196,40 +231,74 @@ pm.max_children = 5 pm.start_servers = 2 pm.min_spare_servers = 1 pm.max_spare_servers = 3 +``` + +> **Пояснения**: +> - `user/group` задают пользователя, от имени которого работают процессы PHP +> - `listen` указывает путь к UNIX-сокету для связи с Nginx +> - `listen.owner/group` дают права на сокет нужному пользователю +> - `pm = dynamic` означает, что количество процессов меняется по нагрузке +> - `max_children` — максимум одновременных PHP-процессов (5 для 4 ГБ ОЗУ) +> - `start_servers` — сколько процессов запустить сразу +> - `min/max_spare_servers` — диапазон «свободных» процессов в ожидании + +Сохрани изменения (`Ctrl+O`, `Enter`) и выйди из редактора (`Ctrl+X`). + +Перезапусти сервис для применения настроек: + +```bash +systemctl reload php8.3-fpm +``` + +> **Пояснения**: +> - `reload` перечитывает конфигурацию без остановки сервиса, что безопаснее + +Проверь, что сокет создался и имеет правильные права: + +```bash +ls -la /run/php/php8.3-fpm.sock +``` + +> **Пояснения**: +> - Вывод должен содержать `www-data www-data` (владелец и группа) +> - Это гарантирует, что Nginx сможет подключиться к PHP-процессам ### Шаг 7: Первоначальная настройка Nextcloud ```bash -# Запуск мастера установки через occ -sudo -u www-data php /var/www/nextcloud/occ maintenance:install \ - --database="mysql" \ - --database-name="nextcloud" \ - --database-user="nextcloud" \ - --database-pass="StrongPassword123!" \ - --database-host="localhost:/run/mysqld/mysqld.sock" \ - --admin-user="admin" \ - --admin-pass="AdminStrongPass123!" \ - --data-dir="/mnt/cloud/data" - -# Настройка крон-задач +sudo -u www-data php /var/www/nextcloud/occ maintenance:install --database="mysql" --database-name="nextcloud" --database-user="nextcloud" --database-pass="StrongPassword123!" --database-host="localhost:/run/mysqld/mysqld.sock" --admin-user="admin" --admin-pass="AdminStrongPass123!" --data-dir="/mnt/cloud/data" crontab -u www-data -e -# Добавь строку: -# */5 * * * * php -f /var/www/nextcloud/cron.php +``` + +> **Пояснения**: +> - occ maintenance:install запускает мастер установки в неинтерактивном режиме +> - Все параметры передаются через флаги: тип БД, имя, пользователь, пароль, хост, админ +> - После выполнения команды откроется редактор crontab для пользователя www-data +> - В редакторе добавьте строку: `*/5 * * * * php -f /var/www/nextcloud/cron.php` ### Шаг 8: Настройка Nginx Proxy Manager (внешний сервер) -В интерфейсе NPM создай Proxy Host: -- **Domain Names**: `nc.zailon.ru` -- **Scheme**: `https` -- **Forward Hostname/IP**: `192.168.1.205` (IP контейнера Olimp) -- **Forward Port**: `443` -- **SSL**: ✅ Request a new SSL Certificate (Let's Encrypt) -- **Force SSL**: ✅ -- **HTTP/2 Support**: ✅ +> В интерфейсе NPM создайте Proxy Host со следующими параметрами: +> - **Domain Names**: `nc.zailon.ru` +> - **Scheme**: `https` +> - **Forward Hostname/IP**: `192.168.1.205` +> - **Forward Port**: `443` +> - **SSL**: ✅ Request a new SSL Certificate (Let's Encrypt) +> - **Force SSL**: ✅ +> - **HTTP/2 Support**: ✅ + +> **Пояснения**: +> - NPM принимает внешние запросы на 443 порт с валидным Let's Encrypt сертификатом +> - Внутри сети запросы проксируются на контейнер по HTTPS с самоподписанным сертификатом +> - Force SSL гарантирует, что все запросы будут только по HTTPS +> - HTTP/2 ускоряет загрузку множества мелких файлов (иконки, стили, скрипты) ## ⚙️ Конфигурация Nextcloud (config.php) - -Ключевые параметры из `/var/www/nextcloud/config/config.php`: +Файл конфигурации находится по пути: `/var/www/nextcloud/config/config.php` +Для редактирования: +```bash +nano /var/www/nextcloud/config/config.php +``` ```php $CONFIG = array ( @@ -249,138 +318,161 @@ $CONFIG = array ( 'preview_max_y' => 2048, 'preview_max_memory' => 256, ); +``` + +> **Пояснения**: +> - `instanceid` — уникальный идентификатор установки, генерируется автоматически +> - `trusted_domains` — список доменов и IP, с которых разрешён доступ +> - `datadirectory` — путь к папке с пользовательскими файлами (вне веб-рута) +> - `dbhost` с указанием socket обеспечивает более надёжное подключение к БД +> - `memcache.local` и `locking` ускоряют работу за счёт кэширования в памяти +> - `redis` — параметры подключения к Redis-серверу для блокировок +> - `overwrite.cli.url` нужен для генерации корректных ссылок в CLI-командах +> - `loglevel` 2 = предупреждения, оптимальный баланс между информативностью и размером лога +> - `preview_max_x/y/memory` ограничивают размер и потребление памяти при генерации превью ## 🔄 Обновление Nextcloud -### Через встроенный updater (рекомендуется) +### Через встроенный updater ```bash -# Включаем режим обслуживания sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on - -# Запуск обновления cd /var/www/nextcloud/updater sudo -u www-data php updater.phar - -# После обновления sudo -u www-data php /var/www/nextcloud/occ upgrade sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off +``` -### Ручное обновление (если updater не работает) +> **Пояснения**: +> - Включение режима обслуживания блокирует доступ пользователей на время обновления +> - updater.phar скачивает новую версию, проверяет целостность и заменяет файлы +> - occ upgrade применяет миграции базы данных и обновляет структуру таблиц +> - Выключение режима обслуживания возвращает облако в рабочий режим + +### Ручное обновление ```bash -# Бэкап tar -czf /root/nextcloud-backup-$(date +%F).tar.gz /var/www/nextcloud mysqldump nextcloud > /root/nextcloud-db-$(date +%F).sql - -# Скачивание новой версии cd /tmp wget https://download.nextcloud.com/server/releases/nextcloud-X.Y.Z.tar.bz2 tar -xjf nextcloud-X.Y.Z.tar.bz2 rsync -av nextcloud/ /var/www/nextcloud/ --exclude='config/' --exclude='data/' - -# Обновление БД sudo -u www-data php /var/www/nextcloud/occ upgrade +``` + +> **Пояснения**: +> - Создаётся архив с файлами Nextcloud и дамп базы данных для возможности отката +> - Скачивается архив с нужной версией (замените X.Y.Z на актуальную) +> - rsync копирует новые файлы, исключая config и data, чтобы не перезаписать настройки +> - occ upgrade применяет миграции после замены файлов ядра ## 🧰 Полезные команды ### Управление сервисами ```bash -# Перезапуск стека systemctl reload nginx systemctl reload php8.3-fpm systemctl restart mariadb - -# Проверка статусов systemctl status nginx php8.3-fpm mariadb redis-server +``` + +> **Пояснения**: +> - reload перечитывает конфиг без разрыва соединений, restart перезапускает сервис +> - status показывает состояние нескольких сервисов сразу для быстрой диагностики ### Nextcloud CLI (occ) ```bash -# Проверка статуса sudo -u www-data php /var/www/nextcloud/occ status - -# Режим обслуживания sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --on sudo -u www-data php /var/www/nextcloud/occ maintenance:mode --off - -# Сканирование файлов sudo -u www-data php /var/www/nextcloud/occ files:scan --all - -# Проверка целостности sudo -u www-data php /var/www/nextcloud/occ integrity:check-core - -# Обновление приложений sudo -u www-data php /var/www/nextcloud/occ app:update --all +``` + +> **Пояснения**: +> - status показывает версию, режим обслуживания и необходимость обновления БД +> - maintenance:mode включает/выключает режим обслуживания +> - files:scan --all пересканирует все файлы пользователей и обновит метаданные +> - integrity:check-core проверяет целостность файлов ядра на предмет изменений +> - app:update --all обновляет все установленные приложения до последних версий ### База данных ```bash -# Подключение к БД mysql -u nextcloud -p nextcloud - -# Размер БД mysql -e "SELECT table_schema AS 'DB', ROUND(SUM(data_length+index_length)/1024/1024,2) AS 'MB' FROM information_schema.tables WHERE table_schema='nextcloud' GROUP BY table_schema;" - -# Оптимизация таблиц mysqlcheck -u root -p --optimize --all-databases +``` + +> **Пояснения**: +> - Подключение к БД nextcloud от имени пользователя nextcloud +> - Запрос показывает размер базы данных в мегабайтах +> - mysqlcheck оптимизирует таблицы и перестраивает индексы для ускорения запросов ### Логи и мониторинг ```bash -# Логи Nextcloud tail -f /mnt/cloud/data/nextcloud.log | grep -E '"level":3|"level":4' - -# Логи Nginx tail -f /var/log/nginx/error.log - -# Использование ресурсов htop df -h / /mnt/cloud free -h +``` + +> **Пояснения**: +> - Выводит только ошибки (уровень 3) и критические сообщения (уровень 4) из лога Nextcloud +> - Показывает ошибки веб-сервера в реальном времени +> - htop отображает загрузку процессора, памяти и список процессов +> - df показывает использование дискового пространства на корне и диске с данными +> - free показывает использование оперативной памяти и swap ## 🚨 Решение проблем | Проблема | Причина | Решение | |----------|---------|---------| -| `502 Bad Gateway` | PHP-FPM не отвечает | `systemctl status php8.3-fpm`, проверить сокет `/run/php/php8.3-fpm.sock` | -| `Maintenance mode enabled` | Забыли выключить после обновления | `sudo -u www-data php occ maintenance:mode --off` | -| `Could not decrypt session data` | Смена секретного ключа | Очистить куки в браузере, перелогиниться | -| `Превью не генерируются` | Нет прав на appdata | `chown -R www-data:www-data /mnt/cloud/data/appdata_*` | -| `Cron не работает` | Ошибка в crontab | Проверить `crontab -l -u www-data`, убедиться что пользователь `www-data` может выполнять `php` | -| `SSL ошибка в браузере` | Самоподписанный сертификат внутри | Довериться сертификату в браузере или настроить NPM правильно | -| `Память заканчивается` | Мало RAM + нет swap | Добавить swap: `fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile` | +| `502 Bad Gateway` | PHP-FPM не отвечает | Проверить `systemctl status php8.3-fpm` и права на сокет `/run/php/php8.3-fpm.sock` | +| `Maintenance mode enabled` | Забыли выключить после обновления | Выполнить `sudo -u www-data php occ maintenance:mode --off` | +| `Could not decrypt session data` | Смена секретного ключа или сессии | Очистить куки в браузере и выполнить повторный вход | +| `Превью не генерируются` | Нет прав на директорию appdata | Выполнить `chown -R www-data:www-data /mnt/cloud/data/appdata_*` | +| `Cron не работает` | Ошибка в crontab или пути к php | Проверить `crontab -l -u www-data` и доступность php для пользователя www-data | +| `SSL ошибка в браузере` | Самоподписанный сертификат внутри контейнера | Довериться сертификату в браузере или проверить настройку NPM | +| `Память заканчивается` | Мало RAM + отсутствие swap | Добавить swap: `fallocate -l 2G /swapfile && chmod 600 /swapfile && mkswap /swapfile && swapon /swapfile` | ## 🔐 Безопасность ### Настройки для продакшена -✅ **Reverse Proxy**: Все запросы идут через NPM с Let's Encrypt, внутри контейнера — самоподписанные сертификаты -✅ **Защита файлов**: В Nginx запрещён доступ к `config/`, `data/`, `.ht*` -✅ **HSTS**: Заголовок `Strict-Transport-Security` включён -✅ **PHP-FPM**: Работает от пользователя `www-data`, не от root -✅ **БД**: Доступ только через socket, не по TCP -✅ **Redis**: Слушает только `127.0.0.1`, без пароля (локальная сеть) -✅ **Cron**: Запускается от `www-data`, не через веб-интерфейс +✅ **Reverse Proxy**: Все внешние запросы обрабатываются NPM с валидным Let's Encrypt сертификатом +✅ **Защита файлов**: В Nginx запрещён прямой доступ к директориям `config/`, `data/`, `.ht*` +✅ **HSTS**: Заголовок `Strict-Transport-Security` принуждает браузеры использовать только HTTPS +✅ **PHP-FPM**: Процессы выполняются от пользователя `www-data`, не от root +✅ **БД**: Подключение к MariaDB только через UNIX-socket, не по TCP-порту +✅ **Redis**: Слушает только `127.0.0.1`, доступ только из локальных процессов +✅ **Cron**: Задачи выполняются через системный cron от www-data, не через веб-интерфейс ### Дополнительные меры ```bash -# Ограничить доступ к admin.php -# В nginx.conf добавить: -location ~ ^/(admin|settings) { - allow 192.168.1.0/24; - deny all; -} - -# Включить двухфакторную аутентификацию -sudo -u www-data php /var/www/nextcloud/occ twofactorauth:enable totp - -# Регулярные бэкапы (пример cron) 0 3 * * * /root/scripts/backup-nextcloud.sh +``` -## 🤖 БЛОК ДЛЯ ИИ +> **Пояснения**: +> - Пример cron-задачи для ежедневного бэкапа в 3 часа ночи +> - Скрипт backup-nextcloud.sh должен создавать архив файлов и дамп БД, затем отправлять в надёжное хранилище + +```bash +sudo -u www-data php /var/www/nextcloud/occ twofactorauth:enable totp +``` + +> **Пояснения**: +> - Включает поддержку TOTP (Google Authenticator) для двухфакторной аутентификации +> - Пользователи смогут активировать 2FA в своих профилях после этой команды + +## AI Context Block ```text [AI INSTRUCTION BLOCK — DO NOT REMOVE]