故障排查步骤:

1. 收集信息
   ├── 查看 Nextcloud 日志
   ├── 查看 Web 服务器日志
   ├── 查看 PHP-FPM 日志
   ├── 查看数据库日志
   └── 查看系统日志 (journalctl)

2. 定位问题
   ├── 确定错误类型（500/502/503/504）
   ├── 确定触发条件（用户/操作/时间）
   └── 确定影响范围（单用户/全站）

3. 解决问题
   ├── 应用已知修复方案
   ├── 修改配置
   └── 升级/降级组件

4. 验证修复
   ├── 确认问题不再复现
   └── 监控系统状态

# 1. 系统状态检查
sudo -u www-data php /var/www/nextcloud/occ status

# 2. 系统警告检查
sudo -u www-data php /var/www/nextcloud/occ maintenance:repair

# 3. 检查 PHP 扩展
php -m | sort

# 4. 检查服务状态
systemctl status nginx php8.2-fpm mariadb redis-server

# 5. 查看最近错误
tail -50 /var/log/nextcloud/nextcloud.log | jq '.message'

# 排查 500 错误
tail -f /var/log/nginx/error.log &
tail -f /var/log/nextcloud/nextcloud.log | jq '.' &
# 触发请求，查看实时日志

# 检查 PHP-FPM 状态
systemctl status php8.2-fpm
journalctl -u php8.2-fpm --since "1 hour ago"

# 检查 socket
ls -la /run/php/nextcloud.sock

# Nginx 超时配置
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
fastcgi_read_timeout 300s;

常见同步错误:

1. "服务器响应了 HTTP 错误 403"
   ├── 原因: 可信域名未配置
   └── 解决: occ config:system:set trusted_domains 1 --value="域名"

2. "服务器响应了 HTTP 错误 507"
   ├── 原因: 存储空间不足（配额用满）
   └── 解决: 扩容或清理文件

3. "CSRF 令牌无效"
   ├── 原因: Session 过期或 Cookie 问题
   └── 解决: 清除客户端缓存，重新登录

4. "文件被锁定"
   ├── 原因: 其他进程正在使用文件
   └── 解决: 等待或手动解锁

5. "连接被重置"
   ├── 原因: 网络中断或防火墙
   └── 解决: 检查网络和防火墙规则

# 查看锁定的文件
sudo -u www-data php /var/www/nextcloud/occ files:lock

# 解除所有文件锁
sudo -u www-data php /var/www/nextcloud/occ files:unlock --all

# 或通过数据库直接解锁
mysql -u ncuser -p nextcloud -e "DELETE FROM oc_file_lock WHERE 1=1;"

# 清除本地同步数据库（客户端）
# 删除客户端同步数据库文件后重新同步
# Windows: %LOCALAPPDATA%\Nextcloud\
# macOS: ~/Library/Preferences/Nextcloud/
# Linux: ~/.config/Nextcloud/

-- MySQL: 查看连接数
SHOW STATUS LIKE 'Threads_connected';
SHOW STATUS LIKE 'Max_used_connections';
SHOW PROCESSLIST;

-- 查看等待锁的查询
SELECT * FROM information_schema.innodb_trx;
SELECT * FROM information_schema.innodb_lock_waits;

-- 查看 InnoDB 状态
SHOW ENGINE INNODB STATUS\G

-- 查看最近的死锁
-- 在输出中搜索 "LATEST DETECTED DEADLOCK"

# 1. 增加锁等待超时
mysql -u root -p -e "SET GLOBAL innodb_lock_wait_timeout = 120;"

# 2. 优化查询（添加索引）
mysql -u root -p nextcloud -e "ANALYZE TABLE oc_filecache;"

-- MySQL: 修复表
REPAIR TABLE oc_filecache;
-- 或
ALTER TABLE oc_filecache ENGINE=InnoDB;

-- PostgreSQL: 重建索引
REINDEX DATABASE nextcloud;
VACUUM FULL ANALYZE;

# 检查数据库大小
mysql -u ncuser -p nextcloud -e "
SELECT 
    table_name AS 'Table',
    ROUND(data_length / 1024 / 1024, 2) AS 'Data (MB)',
    ROUND(index_length / 1024 / 1024, 2) AS 'Index (MB)',
    ROUND((data_length + index_length) / 1024 / 1024, 2) AS 'Total (MB)'
FROM information_schema.tables
WHERE table_schema = 'nextcloud'
ORDER BY data_length + index_length DESC
LIMIT 10;"

# 清理过期数据
sudo -u www-data php /var/www/nextcloud/occ db:convert-filecache-bigint
sudo -u www-data php /var/www/nextcloud/occ trashbin:cleanup
sudo -u www-data php /var/www/nextcloud/occ versions:cleanup

# 1. 检查 PHP-FPM 进程
ps aux | grep php-fpm | wc -l

# 2. 检查系统负载
uptime
top -bn1 | head -20

# 3. 检查磁盘 I/O
iostat -x 1 5
iotop -o

# 4. 检查内存使用
free -h
vmstat 1 5

# 5. 检查网络
iftop -i eth0

# 查看 PHP 进程
ps -eo pid,pcpu,pmem,args --sort=-pcpu | grep php | head -10

# 跟踪 PHP 进程
strace -p <PID> -e trace=network

# 检查预览图队列
sudo -u www-data php /var/www/nextcloud/occ preview:generate-all -vvv

# 使用预览生成器应用优化
sudo -u www-data php /var/www/nextcloud/occ app:install preview_generator

# 查看最近 100 条 Nextcloud 日志
tail -100 /var/log/nextcloud/nextcloud.log | jq '.level, .message'

# 统计错误级别分布
cat /var/log/nextcloud/nextcloud.log | jq -r '.level' | sort | uniq -c | sort -rn

# 查看特定用户的错误
grep '"user":"admin"' /var/log/nextcloud/nextcloud.log | jq '.message'

# 查看特定时间范围
awk -v start="2026-05-10T10:00:00" -v end="2026-05-10T11:00:00" \
  '$0 >= start && $0 <= end' /var/log/nextcloud/nextcloud.log

# 查看数据库相关错误
grep -i "database\|mysql\|pdo" /var/log/nextcloud/nextcloud.log | jq '.message'

# 查看文件锁相关错误
grep -i "lock" /var/log/nextcloud/nextcloud.log | jq '.message' | tail -20

# 使用 jq 过滤日志
cat /var/log/nextcloud/nextcloud.log | jq 'select(.level == "error")' | tail -10

# 查看登录失败
cat /var/log/nextcloud/nextcloud.log | jq 'select(.message | contains("Login failed"))' | tail -20

# 查看分享相关事件
cat /var/log/nextcloud/nextcloud.log | jq 'select(.app == "files_sharing")' | tail -20

// config/config.php (仅调试时使用，不要在生产环境开启)
'debug' => true,
'loglevel' => 0,  // DEBUG level

; /etc/php/8.2/fpm/conf.d/20-xdebug.ini
zend_extension=xdebug.so
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port=9003
xdebug.start_with_request=yes

# 开启 MySQL 通用查询日志（调试用）
mysql -u root -p -e "SET GLOBAL general_log = 'ON';"
mysql -u root -p -e "SET GLOBAL general_log_file = '/var/log/mysql/general.log';"

# 实时监控查询
tail -f /var/log/mysql/general.log

# 使用 curl 测试 WebDAV
curl -v -u admin:password \
  -X PROPFIND \
  "https://cloud.example.com/remote.php/dav/files/admin/" \
  -H "Depth: 0"

# 测试上传
curl -v -u admin:password \
  -X PUT \
  "https://cloud.example.com/remote.php/dav/files/admin/test.txt" \
  -T local-file.txt