notify_push

概述与主要用途

notify_push是为Nextcloud客户端提供更新通知的应用，旨在解决客户端需定期检查服务器文件变更导致的服务器负载过高问题。通过服务器主动推送更新通知，可大幅减少客户端检查频率，同时客户端仍需定期检查（频率可降低），通知基于“尽力而为”原则，可能存在遗漏或误发情况。

核心功能与特性

• 减少服务器负载：通过服务器主动推送通知，降低客户端因频繁检查文件变更带来的服务器压力
• 提升同步效率：客户端无需高频轮询，通过推送通知更快响应文件更新
• 灵活配置：支持通过Nextcloud的config.php或环境变量配置，确保配置同步
• 兼容性：需配合Redis服务器使用，适用于各类Nextcloud客户端（Web、桌面及移动客户端）

要求

• 已部署Redis服务器
• Nextcloud已配置使用Redis服务器

使用场景

适用于Nextcloud服务器管理员，尤其在客户端数量较多、频繁的更新检查导致服务器负载过高的场景，可优化服务器性能，提升文件同步体验。

详细配置与使用方法

部署步骤

部署需完成三个核心步骤：设置推送服务器、配置反向代理、配置Nextcloud应用。

1. 设置推送服务器

设置服务

推送服务器需作为后台守护进程运行，推荐通过systemd服务管理。创建服务文件/etc/systemd/system/notify_push.service，内容如下：

[Unit]
Description = Push daemon for Nextcloud clients

[Service]
Environment = PORT=3030 # 若该端口已占用，可修改为其他端口
ExecStart = /path/to/push/binary/notify_push /path/to/nextcloud/config/config.php

[Install]
WantedBy = multi-user.target

说明：需根据实际环境调整二进制文件路径（/path/to/push/binary/notify_push）和Nextcloud配置文件路径（/path/to/nextcloud/config/config.php）。

配置参数

推送服务器支持两种配置方式，推荐优先使用Nextcloud的config.php以保持配置同步：

• 通过config.php配置：自动加载Nextcloud数据库、Redis及实例URL等配置
• 通过环境变量配置：当无法使用config.php时，设置以下变量（环境变量优先级高于config.php）：
  • DATABASE_URL：Nextcloud数据库连接URL，如postgres://user:password@db_host/db_name
  • REDIS_URL：Redis连接URL，如redis://redis_host
  • NEXTCLOUD_URL：Nextcloud实例URL，如[***]

端口配置：仅通过环境变量PORT设置，默认80。

启动服务

配置完成后，启动服务并设置开机自启：

# 启动服务
sudo systemctl start notify_push

# 设置开机自启
sudo systemctl enable notify_push

2. 配置反向代理

强烈建议将推送服务部署在反向代理后，以处理TLS加密并避免开放新端口。可复用Nextcloud现有Web服务器（Nginx或Apache）。

Nginx配置

在Nextcloud的server块中添加以下location配置：

location /push/ {
    proxy_pass http://localhost:3030/; # 若推送服务使用其他端口，需对应修改
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

说明：路径末尾斜杠必须保留。修改后重载Nginx：

sudo nginx -s reload

Apache配置

先启用代理模块：

sudo a2enmod proxy
sudo a2enmod proxy_http

在Nextcloud的<VirtualHost>块中添加：

ProxyPass /push/ http://localhost:3030/
ProxyPassReverse /push/ http://localhost:3030/

重启Apache生效：

sudo systemctl restart apache2

3. 配置Nextcloud应用

推送服务器和反向代理配置完成后，启用应用并设置推送服务器URL：

# 启用notify_push应用
occ app:enable notify_push

# 设置推送服务器URL（替换为实际反向代理后的URL）
occ notify_push:setup [***]

说明：应用会自动测试配置是否正确，确保推送服务可正常访问。

开发相关

Nextcloud Web界面开发

开发Nextcloud Web应用时，可使用@nextcloud/notify_push JavaScript库（npm地址）处理认证、连接推送服务器及监听事件。

客户端开发指南

桌面及非Web客户端接收通知的实现步骤：

1. 获取推送服务器URL：通过认证请求访问[***]，从响应的ocs.data.capabilities.notify_push.endpoints.websocket获取WebSocket端点。
2. 建立连接：使用WebSocket连接到该端点。
3. 认证：发送用户名和密码完成认证。
4. 接收通知：认证成功后，客户端将收到以下通知：
   • notify_file：用户文件变更
   • notify_activity：新活动项（文件相关活动可能不触发）
   • notify_notification：通知创建、处理或已忽略

客户端示例代码（JavaScript）

function discover_endpoint(nextcloud_url, user, password) {
    let headers = new Headers();
    headers.set('Accept', 'application/json');
    headers.set('OCS-APIREQUEST', 'true');
    headers.set('Authorization', 'Basic ' + btoa(user + ":" + password));

    return fetch(`${nextcloud_url}/ocs/v2.php/cloud/capabilities`, {
        method: 'GET',
        headers: headers,
    })
        .then(response => response.json())
        .then(json => json.ocs.data.capabilities.notify_push.endpoints.websocket);
}

function listen(url, user, password) {
    let ws = new WebSocket(url);
    ws.onmessage = (msg) => {
        console.log("收到通知:", msg);
    }
    ws.onopen = () => {
        ws.send(user); // 发送用户名
        ws.send(password); // 发送密码
    }
}

// 使用示例
let username = "your_username";
let password = "your_password";
let nextcloud_url = "[***]";
discover_endpoint(nextcloud_url, username, password).then((endpoint) => {
    console.log(`推送服务器地址: ${endpoint}`);
    listen(endpoint, username, password);
});

测试客户端

开发阶段可使用测试客户端（从GitHub Actions下载），命令格式：

test_client [***] 用户名 密码

说明：测试客户端用于验证推送服务是否正常工作，输出接收到的通知信息。