Files

T

Egor Bugaev 9e15c3b96c Add rename-user SQL template; make batch transaction handling robust against non-Postgres backends

- New 'rename-user' template (templates / template rename-user <old> <new>):
  best-effort uid rename across core tables (oc_users, oc_preferences,
  oc_group_user, oc_group_admin, oc_ldap_user_mapping, oc_share, oc_mounts,
  oc_storages). Explicitly NOT a supported Nextcloud operation - the
  generated script carries an in-line warning (as leading SQL comments)
  that app-specific tables (Talk, Calendar, Contacts, Mail, 2FA/WebAuthn...)
  are not covered and that the data directory must be renamed on disk
  manually, followed by occ files:scan --all. Documented the same caveat
  in both READMEs.
- Hardened the round-2 transaction wrapping: beginTransaction()/commit()/
  rollBack() are now wrapped in try/catch. PostgreSQL (our backend) has
  fully transactional DDL so this wasn't actually broken here, but
  Nextcloud also supports MySQL/MariaDB via the same IDBConnection, where
  DDL implicitly commits - on that backend a DDL statement in the batch
  would make a later commit()/rollBack() throw 'no active transaction'
  and previously that exception was unhandled (HTTP 500 instead of a
  clean JSON response). Now: if rollBack() itself fails after an error,
  we report rollbackFailed+warning instead of falsely claiming rolledBack,
  since earlier statements in that batch may already be permanently
  applied. If commit() fails with nothing to commit (already
  auto-committed), that's logged only, since the effects are already
  durably persisted.

2026-07-06 19:52:05 +03:00

8.5 KiB

Raw Blame History

⚠️ Устарело ⚠️ OCCWeb terminal

Read in English.

Веб-терминал для администраторов для запуска occ-команд Nextcloud

⚠️ Устарело ⚠️

Поскольку Nextcloud не имеет встроенной поддержки асинхронных операций (из-за использования PHP), это приложение считается устаревшим и больше не будет поддерживать будущие версии Nextcloud (19+). Автору не удалось найти способ реализовать полноценную поддержку интерактивных и долгих occ-задач в веб-терминале без введения дополнительных зависимостей (например, через websockets), а отсутствие настоящей асинхронности может привести к серьёзным проблемам на больших инсталляциях. Этот issue объясняет, почему разработчик решил больше не поддерживать это приложение.

Установка

Сборка не нужна (чистый PHP + vanilla JS). Клонируйте прямо в apps/ целевого сервера и запустите установочный скрипт:

cd /var/www/nextcloud/apps
git clone https://github.com/fanategorius/occweb.git
bash occweb/install.sh

install.sh удаляет dev/CI-файлы, не нужные для работающей установки (tests/, .travis.yml, phpunit*.xml, composer.json, composer.lock, Makefile), выставляет chown -R на пользователя веб-сервера и выполняет occ app:enable. По умолчанию считает, что Nextcloud лежит в /var/www/nextcloud, а пользователь веб-сервера — www-data; если у вас иначе, передайте своими аргументами:

bash occweb/install.sh /path/to/nextcloud custom-web-user

occ app:enable сам корректно проставит версию приложения в базе, поэтому оговорки из раздела «Обновление кода на сервере» ниже к свежей установке не относятся — они актуальны только когда приложение уже включено и вы обновляете его на месте.

Перед установкой сверьте версию вашего Nextcloud с диапазоном в appinfo/info.xml (dependencies/nextcloud, min-version/max-version) — occ app:enable откажется включать приложение вне этого диапазона.

Учтите: install.sh удаляет файлы, отслеживаемые в git. Если планируете дальше обновлять эту установку через git pull, а не пере-клонированием — имейте в виду, что будущее изменение одного из удалённых файлов в апстриме может привести к отказу git pull смёржить изменения. Git сам сообщит об этом, и файл можно вернуть командой git checkout -- <file>.

Режим SQL-запросов

Введите sql в терминале, чтобы переключиться в режим SQL-запросов и выполнять произвольные SQL-запросы напрямую к базе данных Nextcloud (только для администраторов). Запросы разделяются ;. Используйте Shift+Enter для перехода на новую строку и Enter, чтобы отправить весь блок одним запросом — это важно для скриптов вида SET vars.x = 'value'; SELECT current_setting('vars.x');, так как все запросы, отправленные одним блоком, выполняются в рамках одного соединения (сессии) с базой данных. Введите occ, чтобы вернуться в обычный режим occ-команд.

⚠️ Для DELETE/UPDATE нет отмены — внимательно проверяйте, что вы собираетесь выполнить, желательно сначала на некритичной записи/пользователе.

⚠️ Предупреждения ⚠️

Это приложение не является настоящим интерактивным терминалом и не поддерживает долгие задачи. Поэтому на крупных инсталляциях команды вроде occ files:scan могут завершаться по таймауту с ошибкой.
Не используйте occ maintenance:mode --on, это очевидно...
Шаблон rename-user — это best-effort, а не официально поддерживаемая Nextcloud операция. Он обновляет только известные таблицы ядра (oc_users, oc_preferences, oc_group_user, oc_group_admin, oc_ldap_user_mapping, oc_share, oc_mounts, oc_storages), но не трогает таблицы сторонних приложений (Talk, Calendar, Contacts, Mail, двухфакторная аутентификация/WebAuthn и т.д.). Дополнительно нужно вручную переименовать каталог данных пользователя на диске (data/<старый> -> data/<новый>) при остановленном веб-сервере или в режиме обслуживания, а затем выполнить occ files:scan --all. Сначала сделайте бэкап базы и протестируйте на некритичном аккаунте.

Обновление кода на сервере

После того как новый код скопирован/спуллен в nextcloud/apps/occweb/, обязательно перезапустите PHP, иначе изменения не применятся. occ app:disable/app:enable не помогает — эта команда не сбрасывает opcode-кэш PHP, из-за чего может продолжать работать старая закэшированная версия кода (характерный симптом — маршруты внезапно отвечают 404). Перезапустите сам процесс PHP, например:

sudo systemctl restart php8.3-fpm   # укажите свою версию PHP
sudo systemctl restart apache2      # если PHP работает как модуль Apache

Если меняете `<version>` в `appinfo/info.xml`

Nextcloud хранит установленную версию каждого приложения в базе (installed_version в oc_appconfig) отдельно от <version> в info.xml. Если вы правите файлы на месте (копированием/git pull), а не через App Store или occ upgrade, эти два значения расходятся — и Nextcloud считает, что «инстансу нужен апгрейд», блокируя большинство occ-команд за CLI-визардом обновления, хотя само ядро Nextcloud никак не менялось. После бампа версии синхронизируйте её вручную:

sudo -u www-data php /var/www/nextcloud/occ config:app:set occweb installed_version --value="X.Y.Z"

(то же значение X.Y.Z, что и в новом <version>), затем перезапустите PHP, как описано выше. На свежую установку через occ app:enable это не распространяется — там версия проставляется корректно автоматически.

Планы (TODO):

См. открытые issues

8.5 KiB Raw Blame History Unescape Escape