nextcloud-server-ops
暂无简介
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-24
- Stars
- ★ 0
- Forks
- 0
02 资源文件 1
- 参考文档skill.json357 B
03 SKILL.md 正文
nextcloud-server-ops
Nextcloud Server Ops
Administer a self-hosted Nextcloud instance: occ commands, preview/thumbnail generation (esp. video), config, and diagnostics. This is server administration, not the client nextcloud skill (which covers WebDAV/CalDAV/Notes from outside).
When to Use
Trigger when the task is Nextcloud server-side: video/PDF thumbnails missing, occ config/preview commands, enabling preview providers, bulk preview regeneration, occ check/status diagnostics, or locating the NC container/VM on a Proxmox host. Do NOT use for client file/note/calendar sync — that is the nextcloud skill.
1. Locate the instance (Proxmox homelab)
Nextcloud is usually an LXC/CT or VM on the PVE host.
ssh root@<PVE_IP> "qm list; pct list"
# CT line e.g. "101 running nextcloud"
ssh root@<PVE_IP> "pct exec 101 -- occ status" # occ runs inside the CT
- The
occwrapper on the PVE host (/usr/bin/occ)sus into the CT as thenextclouduser and runs the realocc. Inside the CT,occis on PATH only in login shells —pct exec 101 -- occ ...works, but a nested$(occ ...)inside a non-login-csubshell loses PATH ("occ: command not found"). Fix: runoccas the direct command, or usebash -lc 'occ ...'. - Webroot may be
/usr/share/webapps/nextcloud(Arch) not/var/www/nextcloud. Datadir fromocc config:system:get datadirectory(often/var/lib/nextcloud/data).
2. Preview / video thumbnail fix (most common gap)
Symptom: images thumbnailed but MP4/MOV/MKV/WebM show no thumbnail (e.g. in the iPhone app).
Root cause: the OC\Preview\Movie provider is not enabled. enable_previews may be true but enabledPreviewProviders lacks the Movie class.
# verify
pct exec 101 -- occ config:system:get enable_previews # expect true
pct exec 101 -- occ config:app:get preview enabledPreviewProviders
# ffmpeg + php imagick/gd must exist:
pct exec 101 -- bash -c 'which ffmpeg; php -m | grep -iE "imagick|gd"'
Enable providers — ONE call with the FULL array (each config:app:set overwrites the key, so multiple calls leave only the last):
pct exec 101 -- bash -c 'occ config:app:set preview enabledPreviewProviders --value '"'"'["OC\\Preview\\Movie","OC\\Preview\\Image","OC\\Preview\\JPEG","OC\\Preview\\PNG","OC\\Preview\\GIF","OC\\Preview\\BMP","OC\\Preview\\HEIC","OC\\Preview\\TIFF","OC\\Preview\\PDF","OC\\Preview\\MP3","OC\\Preview\\MarkDown","OC\\Preview\\Office","OC\\Preview\\OpenDocument"]'"'"
Single-quoted bash preserves \\ → stored JSON [OC\Preview\Movie,...] (one backslash per class) → NC parses correctly. Do not pass --type json (unsupported in this occ version; it stores the string and NC decodes it).
3. Regenerate previews
# single file (proves the pipeline works)
pct exec 101 -- occ preview:generate "USER/files/path/to/video.mp4"
# all images (NC33): preview:generate-all [user]
# videos already uploaded have no thumbnail -> regenerate them:
For many videos, write a script (see references/regen.md) — a recursive scan over the whole data dir is slow; scope per-user with -maxdepth 5 and exclude appdata_*. Run long jobs in background:
pct exec 101 -- bash -c 'nohup bash /tmp/regen.sh > /tmp/regen.log 2>&1 &'
# poll: pct exec 101 -- bash -c 'tail -3 /tmp/regen.log; pgrep -f regen.sh >/dev/null && echo RUNNING || echo DONE'
A few old/short clips may FAIL (ffmpeg can't extract a frame) — non-critical.
4. Diagnostics
pct exec 101 -- occ check # empty output = clean, no errors/warnings
pct exec 101 -- occ status # version, needsDbUpgrade, maintenance
Previews are stored under appdata_<id>/preview/<fileid>/ (not under the user's files dir) — don't expect PNGs next to the source file.
5. Pitfalls
- Long inline commands get blocklisted by the agent command parser (heredocs/giant one-liners). Write the script to a file,
scpto PVE,pct push <CT> <src> <dst>, thenpct exec. (scp must go agent→PVE first;pct execstdin can't read the agent's filesystem.) - Recursive scan over
/var/lib/nextcloud/datatimes out on large libraries — scope with per-user-maxdepthand skipappdata_*. (Prefer thesearch_filestool for agent-host files; inside the CT use scopedfind.) - Don't edit user files — only config + generated preview blobs. Preview regeneration is non-destructive.
- NC cron.php must be run separately — The system crontab (
crontab -l) is NOT the Nextcloud cron. Add*/5 * * * * php -f /usr/share/webapps/nextcloud/cron.phpto thenextclouduser's crontab (crontab -u nextcloud -e) for background jobs (preview generation, file scanning, etc.). preview:generate-allskips hidden dirs — Videos in.vidfolders are never processed bypreview:generate-all. A separate explicit scan is required.
6. PHP-FPM + Nginx config (login/upload fixes)
See references/php-fpm-and-nginx-config.md. Pitfalls:
- Session dir missing = login fails silently. After a CT reinstall,
/var/tmp/nextcloudoften doesn't exist. PHP logssession_start(): open(/var/tmp/nextcloud/sess_..., O_RDWR) failed: No such file or directoryand login POST returns 303 (redirect) but no session is created — user appears to bounce back to login. Fix:mkdir -p /var/tmp/nextcloud && chown nextcloud:www-data /var/tmp/nextcloud && chmod 0750 /var/tmp/nextcloud. The session dir must be owned by thenextclouduser, not root. - PHP-FPM socket permissions — if nginx logs
Permission deniedconnecting to/run/nextcloud/fastcgi.sock, the socket mode is0660(root-only). Fix to0666in the FPM pool config (listen.mode = 0666). - PHP children OOM-killed —
exited on signal 9in php-fpm.log + low hostavailableRAM = scalepm.max_childrenDOWN, not up. The OOM killer eats workers and nginx returns 502. request_terminate_timeout = 0means children hang forever — PHP-FPM waits indefinitely for a slow request; nginx times out at 120s and returns 504. Set to300sin the FPM pool config.- Uploads capped at 1-2 MB — both PHP (
upload_max_filesize,post_max_size) and Nginx (client_max_body_size) default low; set both to the same limit (e.g. 16G). pm.max_childrentoo low = 502 under load — CT106 with 2GB RAM andpm.max_children=10causes OOM. Reduce to 5 and setrequest_terminate_timeout=300s.
6. Hidden .vid folders — the silent thumbnail gap
Videos stored under a .vid directory (e.g. USER/files/Videos/.vid/*.MP4)
are HIDDEN. A recursive preview regen scoped to files/ (without -hidden) SKIPS
them, so those clips never get thumbnails even after a full regen. The iPhone app
then shows placeholders for exactly those files.
- Diagnose:
occ preview:generate "USER/files/Videos/.vid/NAME.MP4"→ if it errorsNo preview generator available for file of type video/mp4but a normal video inUSER/files/...generates fine, the Movie provider is enabled (it was a scan-skip, not a config gap). Retry with-vvv— a transient cache miss can cause a spurious first failure;-vvvregenerates. - Fix: regenerate previews for
.vidcontents explicitly. Scan for.viddirs (find "$DATA/$u/files" -maxdepth 4 -type d -name '.vid') andocc preview:generateeach video. Background the job; a few clips may FAIL (ffmpeg can't extract a frame). - Periodic regen recommended: Add a cron job (every 6h) that scans
.viddirs and regenerates previews. New uploads to.vidare not caught bypreview:generate-all. - Script pattern (avoids timeout on large libraries):
# Use scripts/regen_vid.sh — push to CT, run via nohup # Or write your own scoped loop: for viddir in /var/lib/nextcloud/data/ncAdmin/files/Videos/.vid; do for f in "$viddir"/*.[Mm][Pp]4 "$viddir"/*.[Mm][Oo][Vv]; do [ -f "$f" ] || continue ncpath="ncAdmin/files${f#/var/lib/nextcloud/data/ncAdmin/files}" su - nextcloud -s /bin/bash -c "php -f /usr/share/webapps/nextcloud/occ preview:generate '$ncpath'" done done - Run as nextcloud user, not root —
occ preview:generatemust run as thenextclouduser, not root. Usesu - nextcloud -s /bin/bash -c "..."or add to nextcloud user's crontab. - NC cron must be separate — Add
*/5 * * * * php -f /usr/share/webapps/nextcloud/cron.phpto thenextclouduser's crontab (crontab -u nextcloud -e) for background jobs. The system crontab is NOT the Nextcloud cron.
7. occ upgrade leaves maintenance mode ON
After occ upgrade (e.g. NC 33.0.7→33.0.8), needsDbUpgrade becomes false but
maintenance stays true — NC stays down until you turn it off.
pct exec 101 -- occ maintenance:mode --off
pct exec 101 -- occ status # maintenance:false, needsDbUpgrade:false
pct exec 101 -- occ check # clean
Also: a stray find / debug probe can keep running inside the CT after its
command finished — pct exec 101 -- kill <pid> any leftover find before/after.
9. Docker in CT requires nesting
Unprivileged CTs cannot run Docker containers. To deploy Docker-based apps (NetworkOptimizer, etc.) on Proxmox CTs:
- Privileged CT (
--privileged 1): can run Docker directly, but reduces isolation. - Unprivileged CT with nesting (
--features nesting=1): required even for rootless Docker. The official install scripts often fail without a TTY — replicate manually withcurl+docker compose. systemctlis NOT available inside unprivileged CTs. Usepkill -f php-fpm; /usr/sbin/php-fpm85 --daemonizeandpkill nginx; /usr/sbin/nginx -c /etc/nginx/nginx.confdirectly.- When the official one-liner fails with
TERM environment variable not setor hangs on interactive prompts, read the script, extract the defaults, and replicate withpct create+ manualdocker compose up -d.
10. Mixed-OS container updates (PVE homelab)
CTs are not all Debian. Detect OS before mass-updating:
- Debian/Ubuntu:
apt update && apt full-upgrade -y. - Alpine:
apk upgrade(nextcloud + imagemagick come from here;apkbumps them, e.g. NC 33.0.7→33.0.8, imagemagick 7.1.2.27→7.1.2.30 — preview-relevant). pct listshows CT#/name/state; map names→roles (nextcloud, plex, hermes, …).- Reboot the PVE node only after CTs are stopped cleanly (
pct shutdown <id> --force, staggered); CTs withonboot:1auto-start on node reboot. Verify prod API + NC post-reboot (curl -s -o /dev/null -w '%{http_code}' https://api.cortexcloud.org/,occ status).