AGENT SKILL

nextcloud-server-ops

暂无简介

License 许可
Apache-2.0
最近更新
2026-10-24
Stars
★ 0
Forks
0

02 资源文件 1

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 occ wrapper on the PVE host (/usr/bin/occ) sus into the CT as the nextcloud user and runs the real occ. Inside the CT, occ is on PATH only in login shells — pct exec 101 -- occ ... works, but a nested $(occ ...) inside a non-login -c subshell loses PATH ("occ: command not found"). Fix: run occ as the direct command, or use bash -lc 'occ ...'.
  • Webroot may be /usr/share/webapps/nextcloud (Arch) not /var/www/nextcloud. Datadir from occ 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, scp to PVE, pct push <CT> <src> <dst>, then pct exec. (scp must go agent→PVE first; pct exec stdin can't read the agent's filesystem.)
  • Recursive scan over /var/lib/nextcloud/data times out on large libraries — scope with per-user -maxdepth and skip appdata_*. (Prefer the search_files tool for agent-host files; inside the CT use scoped find.)
  • 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.php to the nextcloud user's crontab (crontab -u nextcloud -e) for background jobs (preview generation, file scanning, etc.).
  • preview:generate-all skips hidden dirs — Videos in .vid folders are never processed by preview: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/nextcloud often doesn't exist. PHP logs session_start(): open(/var/tmp/nextcloud/sess_..., O_RDWR) failed: No such file or directory and 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 the nextcloud user, not root.
  • PHP-FPM socket permissions — if nginx logs Permission denied connecting to /run/nextcloud/fastcgi.sock, the socket mode is 0660 (root-only). Fix to 0666 in the FPM pool config (listen.mode = 0666).
  • PHP children OOM-killed — exited on signal 9 in php-fpm.log + low host available RAM = scale pm.max_children DOWN, not up. The OOM killer eats workers and nginx returns 502.
  • request_terminate_timeout = 0 means children hang forever — PHP-FPM waits indefinitely for a slow request; nginx times out at 120s and returns 504. Set to 300s in 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_children too low = 502 under load — CT106 with 2GB RAM and pm.max_children=10 causes OOM. Reduce to 5 and set request_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 errors No preview generator available for file of type video/mp4 but a normal video in USER/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; -vvv regenerates.
  • Fix: regenerate previews for .vid contents explicitly. Scan for .vid dirs (find "$DATA/$u/files" -maxdepth 4 -type d -name '.vid') and occ preview:generate each 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 .vid dirs and regenerates previews. New uploads to .vid are not caught by preview: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:generate must run as the nextcloud user, not root. Use su - 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.php to the nextcloud user'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 with curl + docker compose.
  • systemctl is NOT available inside unprivileged CTs. Use pkill -f php-fpm; /usr/sbin/php-fpm85 --daemonize and pkill nginx; /usr/sbin/nginx -c /etc/nginx/nginx.conf directly.
  • When the official one-liner fails with TERM environment variable not set or hangs on interactive prompts, read the script, extract the defaults, and replicate with pct create + manual docker 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; apk bumps them, e.g. NC 33.0.7→33.0.8, imagemagick 7.1.2.27→7.1.2.30 — preview-relevant).
  • pct list shows 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 with onboot:1 auto-start on node reboot. Verify prod API + NC post-reboot (curl -s -o /dev/null -w '%{http_code}' https://api.cortexcloud.org/, occ status).

04 同仓库更多 Skills