обновление документации

2026-06-24 09:25:56 +03:00 · 2026-06-24 09:25:56 +03:00 · 12c8e7a106
commit 12c8e7a106
parent 45b8317707
2 changed files with 246 additions and 41 deletions
--- a/README.md
+++ b/README.md
@ -1,39 +1,98 @@
 # Nextcloud — скрипты развёртывания

-| Способ | Каталог | Когда выбирать |
-|--------|---------|----------------|
-| **Docker** | [`docker/`](docker/) | Быстрый старт, изоляция, простые обновления |
-| **Нативная** | [`native/`](native/) | Полная установка в ОС (LAMP) |
+| Способ | Каталог | Статус |
+|--------|---------|--------|
+| **Docker** | [`docker/`](docker/) | Основной, отлажен и используется |
+| **Нативная** | [`native/`](native/) | Экспериментальная, **не отлаживалась** |

-📖 **[Recommendation.md](Recommendation.md)** — настройки, хранилище, HTTPS, приложения.
+📖 **[Recommendation.md](Recommendation.md)** — настройки, хранилище, HTTPS, приложения, переустановка.

-## Структура
+---
+
+## Структура репозитория

 ```
 nextcloud_install/
 ├── README.md
 ├── Recommendation.md
-├── docker/                 # Nextcloud в Docker
-│   ├── install.sh
+├── lib/
+│   └── common.sh              # Общая логика Docker, config, compose, права
+├── docker/                    # Nextcloud в Docker (основной способ)
+│   ├── install.sh             # Установка стека
+│   ├── setup-env.sh           # Генерация .env с паролями
+│   ├── install-docker.sh      # Установка Docker Engine (sudo)
+│   ├── start.sh / stop.sh / status.sh
+│   ├── backup.sh / restore.sh
+│   ├── restore-config.sh      # Починка / сброс config.php
+│   ├── uninstall.sh           # Остановка; --purge удаляет volumes
 │   ├── enable-docker-ssl.sh   # HTTPS :8443 (cert в контейнере)
-│   ├── add-user.sh
-│   ├── docker-compose.yml
-│   └── certs/                 # fullchain.pem, privkey.pem
+│   ├── disable-docker-ssl.sh
+│   ├── add-user.sh            # Создание пользователя через occ
+│   ├── docker-compose.yml     # MariaDB + Redis + app + cron
+│   ├── docker-compose.ssl.yml # Overlay HTTPS (подключается автоматически)
+│   ├── Dockerfile.ssl         # Образ Apache + mod_ssl
+│   ├── .env.example           # Шаблон переменных (копируется в .env)
+│   ├── config.defaults/       # Шаблоны фрагментов config (не runtime-данные)
+│   ├── templates/             # Шаблон Apache SSL
+│   └── certs/                 # fullchain.pem, privkey.pem (не в git)
 ├── register-ui/               # Самoregистрация пользователей (:3001)
 ├── admin-ui/                  # Управление пользователями (:3000)
-└── native/                    # Установка в систему
+└── native/                    # Установка в ОС (LAMP) — см. ниже
 ```

+**Важно:** каталог `nextcloud_install` содержит только скрипты и шаблоны.  
+Все данные Nextcloud (config, файлы, appdata) лежат **вне** репозитория — пути задаются в `docker/.env`.
+
 ---

-## Docker — порты
+## Docker — подкаталог `docker/`
+
+### Сервисы (docker-compose.yml)
+
+| Сервис | Контейнер | Назначение |
+|--------|-----------|------------|
+| `db` | `nextcloud-db` | MariaDB |
+| `redis` | `nextcloud-redis` | Кэш и блокировки |
+| `app` | `nextcloud-app` | Nextcloud (Apache + PHP) |
+| `cron` | `nextcloud-cron` | Фоновые задачи |
+
+### Порты

 | Порт | Протокол | Назначение |
 |------|----------|------------|
 | **8080** | HTTP | `NEXTCLOUD_PORT` |
 | **8443** | HTTPS | `./enable-docker-ssl.sh` + cert в `docker/certs/` |

-Reverse proxy **не используется** — Nextcloud напрямую.
+Reverse proxy **не используется** — Nextcloud доступен напрямую на этих портах.
+
+### Хранение данных (в `.env`, вне репозитория)
+
+| Переменная | Назначение | По умолчанию |
+|---|---|---|
+| `NEXTCLOUD_CONFIG_DIR` | config.php, фрагменты config | `/var/nextcloud/config` |
+| `NEXTCLOUD_DATADIR` | Файлы пользователей | `/mnt/hgfs/nextcloud_data` |
+| `NEXTCLOUD_APPDATA` | App Store, превью | `/var/nextcloud/appdata` |
+| `NEXTCLOUD_CUSTOM_APPS` | Приложения из магазина | `/var/nextcloud/custom_apps` |
+| `NEXTCLOUD_BACKUP_DIR` | Бэкапы `./backup.sh` | `/var/nextcloud/backups` |
+| `NEXTCLOUD_INSTANCEID` | ID для mount `appdata_*` | генерируется в `.env` |
+
+Docker volumes (удаляются при `./uninstall.sh --purge`): `nextcloud_db_data`, `nextcloud_app_data`, `nextcloud_redis_data`.
+
+### Скрипты
+
+| Скрипт | Назначение |
+|--------|------------|
+| `./setup-env.sh [домен]` | Создать `.env` с паролями и trusted domains |
+| `./install.sh [домен]` | Полная установка (спросит пути хранения) |
+| `./start.sh` / `./stop.sh` / `./status.sh` | Управление стеком |
+| `./backup.sh` / `./restore.sh` | Резервное копирование / восстановление |
+| `./restore-config.sh` | Починка config; `--force` — сброс и occ install |
+| `./uninstall.sh` | Остановка; `--purge` — удаление volumes |
+| `./enable-docker-ssl.sh` | HTTPS на :8443 |
+| `./disable-docker-ssl.sh` | Вернуть HTTP-only |
+| `./add-user.sh` | Создать пользователя через CLI |
+
+Все docker-скрипты запускайте **без `sudo`**. Скрипт сам запросит sudo только для каталогов вроде `/var/nextcloud/*`.

 ### Установка

@ -43,27 +102,23 @@ chmod +x *.sh
 ./install.sh your.domain
 ```

-Запускайте **без `sudo`**. Скрипт сам попросит sudo только для создания каталогов вроде `/var/nextcloud/*`.
+HTTPS (после установки):

-Скрипт спросит пути (все **вне** `nextcloud_install`):
-
-| Переменная | Назначение | По умолчанию |
-|---|---|---|
-| `NEXTCLOUD_CONFIG_DIR` | config.php, настройки | `/var/nextcloud/config` |
-| `NEXTCLOUD_DATADIR` | Файлы пользователей | `/mnt/hgfs/nextcloud_data` |
-| `NEXTCLOUD_APPDATA` | App Store, превью | `/var/nextcloud/appdata` |
-| `NEXTCLOUD_CUSTOM_APPS` | Приложения из магазина | `/var/nextcloud/custom_apps` |
-| `NEXTCLOUD_BACKUP_DIR` | Бэкапы | `/var/nextcloud/backups` |
-
-`nextcloud_install` — только скрипты, compose, шаблоны (`config.defaults/`).
+```bash
+cp /path/to/fullchain.pem certs/
+cp /path/to/privkey.pem   certs/
+./enable-docker-ssl.sh your.domain
+# https://your.domain:8443
+```

 Переустановка:

 ```bash
-./uninstall.sh --purge   # удалит контейнеры и Docker volumes, backup старого config.php
+./uninstall.sh --purge   # yes
 rm -f .env
 ./setup-env.sh your.domain
 ./install.sh your.domain
+./enable-docker-ssl.sh your.domain
 ```

 Если видите ошибку про `CAN_INSTALL` или права на config:
@ -72,13 +127,27 @@ rm -f .env
 ./restore-config.sh --force
 ```

-HTTPS:
+### Ручные команды `docker compose`
+
+Скрипты сами подключают SSL-overlay, если есть файл `.ssl-enabled`.  
+При ручном запуске **обязательно** работайте из `docker/`:

 ```bash
-./enable-docker-ssl.sh your.domain
-# https://your.domain:8443
+cd nextcloud_install/docker
+export COMPOSE_FILE="$(pwd)/docker-compose.yml:$(pwd)/docker-compose.ssl.yml"   # если SSL включён
+
+docker compose ps
+docker compose exec -u www-data app php occ status
 ```

+Без `cd` или `COMPOSE_FILE` появится ошибка: `no configuration file provided: not found`.
+
+### config.defaults/ и certs/
+
+- **`config.defaults/`** — шаблоны фрагментов (`redis.config.php`, `reverse-proxy.config.php` и т.д.). При установке копируются в `NEXTCLOUD_CONFIG_DIR`.
+- **`certs/`** — сертификаты для `enable-docker-ssl.sh`. Файлы `*.pem` не попадают в git.
+- **`.ssl-enabled`** — маркер включённого HTTPS; скрипты автоматически добавляют `docker-compose.ssl.yml`.
+
 ---

 ## Самoregистрация пользователей
@ -92,10 +161,13 @@ chmod +x start.sh
 Откройте **http://ваш-сервер:3001** — пользователи создают аккаунт сами.

 В `register-ui/.env`:
- `NEXTCLOUD_URL=https://host:8443`
- `REGISTRATION_ADMIN_USER=admin`
- `REGISTRATION_ADMIN_PASSWORD=...` (из `docker/.env`)
- `DEFAULT_QUOTA=5GB`
+
+| Переменная | Пример |
+|---|---|
+| `NEXTCLOUD_URL` | `https://host:8443` |
+| `REGISTRATION_ADMIN_USER` | `admin` |
+| `REGISTRATION_ADMIN_PASSWORD` | из `docker/.env` |
+| `DEFAULT_QUOTA` | `5GB` |

 Отключить регистрацию: `REGISTRATION_ENABLED=false`

@ -114,15 +186,40 @@ CLI: `docker/add-user.sh`

 ---

-## Native
+## Native (LAMP в системе)
+
+> **Статус: не отлаживалось.**  
+> Скрипты в `native/` написаны как альтернатива Docker (Apache + MariaDB + PHP + Redis на Ubuntu/Debian), но в этом репозитории **не тестировались** на реальном окружении.  
+> Для production рекомендуется **`docker/`**.
+
+Что есть в `native/`:
+
+| Файл | Назначение |
+|------|------------|
+| `install.sh` | Установка пакетов, БД, Nextcloud в `/var/www/nextcloud` |
+| `setup-env.sh` | Генерация `.env` |
+| `start.sh` / `stop.sh` / `status.sh` | Управление сервисами |
+| `backup.sh` / `restore.sh` | Бэкапы |
+| `uninstall.sh` | Удаление |
+| `templates/` | Шаблоны Apache, PHP, cron |

 ```bash
 cd nextcloud_install/native
-./install.sh
+sudo ./install.sh your.domain
 ```

+Ожидаемые отличия от Docker (могут потребовать ручной доработки):
+
+- SSL настраивается в Apache на хосте, не через `enable-docker-ssl.sh`
+- Нет встроенного Redis/MariaDB в контейнерах — всё в системе
+- Пути хранения другие (`NEXTCLOUD_INSTALL_DIR`, не `NEXTCLOUD_DATADIR`)
+- Collabora, Talk HPB, register-ui/admin-ui — настраиваются вручную
+
+Подробнее см. [Recommendation.md § Native](Recommendation.md#13-native-экспериментально).
+
 ---

 ## Документация

+- [Recommendation.md](Recommendation.md) — практические рекомендации
 - [Nextcloud Admin Manual](https://docs.nextcloud.com/server/latest/admin_manual/)
--- a/Recommendation.md
+++ b/Recommendation.md
@ -19,6 +19,8 @@
 10. [HTTPS и свой SSL-сертификат](#10-https-docker--напрямую-на-портах-8080--8443)
 11. [Переустановка (Docker)](#11-переустановка-docker)
 12. [Самoregистрация пользователей](#12-самoregистрация-пользователей)
+13. [Native (экспериментально)](#13-native-экспериментально)
+14. [Collabora и Talk](#14-collabora-и-talk)

 ---

@ -33,6 +35,18 @@ cd nextcloud_install/docker
 docker compose exec -u www-data app php occ status
 ```

+**Ручной `docker compose`:** работайте из каталога `docker/` или задайте `COMPOSE_FILE`.  
+Если включён HTTPS (есть файл `.ssl-enabled`), нужны оба compose-файла:
+
+```bash
+cd nextcloud_install/docker
+export COMPOSE_FILE="$(pwd)/docker-compose.yml:$(pwd)/docker-compose.ssl.yml"
+docker compose exec -u www-data app php occ status
+```
+
+Без этого — ошибка `no configuration file provided: not found`.  
+Скрипты (`install.sh`, `start.sh`, …) подставляют `COMPOSE_FILE` автоматически.
+
 **Native:**
 ```bash
 cd nextcloud_install/native
@ -520,6 +534,8 @@ cp /path/to/privkey.pem   certs/

 ### Native (без Docker)

+> См. [§13 Native (экспериментально)](#13-native-экспериментально) — вариант не отлаживался в этом репозитории.
+
 SSL настраивается в Apache на хосте — см. [example_ubuntu](https://docs.nextcloud.com/server/latest/admin_manual/installation/example_ubuntu.html).

 ---
@ -691,14 +707,106 @@ chmod +x start.sh

 ---

+## 13. Native (экспериментально)
+
+Каталог **`native/`** — установка Nextcloud напрямую в ОС (Apache + MariaDB + PHP + Redis на Ubuntu/Debian).
+
+> **В этом репозитории native-вариант не отлаживался.**  
+> Скрипты могут работать, но не проходили полный цикл тестирования, переустановки и интеграции с Collabora/Talk/register-ui.  
+> Для production используйте **`docker/`**.
+
+### Что есть
+
+| Скрипт | Назначение |
+|--------|------------|
+| `native/install.sh` | Установка пакетов, БД, Nextcloud |
+| `native/setup-env.sh` | Генерация `.env` |
+| `native/backup.sh` / `restore.sh` | Бэкапы |
+| `native/uninstall.sh` | Удаление |
+| `native/templates/` | Apache vhost/subdir, PHP, cron |
+
+### Ожидаемые отличия от Docker
+
+| Аспект | Docker | Native |
+|--------|--------|--------|
+| Запуск | `./install.sh` без sudo | `sudo ./install.sh` |
+| HTTPS | `./enable-docker-ssl.sh` (:8443) | Apache + certbot/Let's Encrypt на хосте |
+| Данные | Пути в `docker/.env` | `NEXTCLOUD_INSTALL_DIR` (по умолчанию `/var/www/nextcloud`) |
+| БД / Redis | Контейнеры | Системные сервисы |
+| occ | `docker compose exec -u www-data app php occ …` | `sudo -u www-data php /var/www/nextcloud/occ …` |
+
+### Если всё же используете native
+
+1. Прочитайте `native/.env.example` и задайте `NEXTCLOUD_DOMAIN`, `APACHE_MODE` (`vhost` / `subdir`).
+2. SSL — по [официальной инструкции Ubuntu](https://docs.nextcloud.com/server/latest/admin_manual/installation/example_ubuntu.html).
+3. После установки проверьте cron, Redis, trusted domains — как в §1.
+4. `register-ui` / `admin-ui` — укажите `NEXTCLOUD_URL` на ваш Apache URL.
+
+При проблемах рекомендуется перейти на **`docker/`** — там описаны типичные ошибки и recovery-скрипты (§11).
+
+---
+
+## 14. Collabora и Talk
+
+Эти компоненты **не входят** в базовую установку и настраиваются отдельно.
+
+### Collabora (Nextcloud Office)
+
+Приложения: `richdocuments` + `richdocumentscode` (Built-in CODE server).
+
+После установки проверьте WOPI URL — он должен совпадать с тем, как пользователи заходят в Nextcloud:
+
+```bash
+cd nextcloud_install/docker
+docker compose exec -u www-data app php occ config:app:get richdocuments wopi_url
+```
+
+Пример для HTTPS на :8443:
+
+```bash
+docker compose exec -u www-data app php occ config:app:set richdocuments wopi_url \
+  --value="https://cloud.example.com:8443/custom_apps/richdocumentscode/proxy.php?req="
+docker compose exec -u www-data app php occ richdocuments:activate-config
+```
+
+**appdata** (`NEXTCLOUD_APPDATA`) должен быть на локальном диске, не на hgfs/NFS — иначе App Store и Collabora могут падать.
+
+### Talk — High Performance Backend (HPB)
+
+Сообщение «Еще не настроен сервер высокой нагрузки для talk» — это предупреждение, не ошибка.  
+Talk работает и без HPB, но для групповых звонков (4+ участников) нужен отдельный сервис:
+
+- образ `ghcr.io/nextcloud-releases/aio-talk:latest`
+- поддомен signaling (например `signal.example.com`) с WebSocket
+- порты `3478/tcp+udp` (TURN) снаружи
+
+Настройка в **Настройки → Администрирование → Talk** или через `occ config:app:set spreed …`.
+
+Для HPB нужен **один стабильный canonical URL** Nextcloud (`overwrite.cli.url`), даже если обычный веб-доступ идёт по IP или другому имени.
+
+### Circles / «Личная информация»
+
+Ошибка `FederatedUser is not complete` на странице профиля обычно лечится корректным `overwrite.cli.url`:
+
+```bash
+docker compose exec -u www-data app php occ config:system:set overwrite.cli.url \
+  --value="https://cloud.example.com:8443"
+docker compose exec -u www-data app php occ maintenance:repair
+```
+
+---

 ## Связанные файлы репозитория

-| Файл | Назначение |
-|------|------------|
-| [README.md](README.md) | Установка Docker / Native |
-| `docker/.env` | Порт, домены, PHP-лимиты |
-| `native/.env` | Путь установки, домен Apache |
+| Файл / каталог | Назначение |
+|----------------|------------|
+| [README.md](README.md) | Установка Docker / Native, структура `docker/` |
+| `lib/common.sh` | Общая логика compose, config, прав |
+| `docker/.env` | Порт, домены, пути хранения, пароли |
+| `docker/config.defaults/` | Шаблоны фрагментов config |
+| `docker/docker-compose.yml` | MariaDB + Redis + app + cron |
+| `docker/docker-compose.ssl.yml` | Overlay HTTPS (:8443) |
+| `native/.env` | Путь установки, домен Apache (**не отлажено**) |
 | `docker/backup.sh` / `native/backup.sh` | Резервные копии |
 | `docker/restore-config.sh` | Восстановление config после сбоя |
 | `docker/uninstall.sh --purge` | Удаление стека (см. §11) |