更新文档

kooritea · Apr 7, 2020 · e287ef7 · e287ef7
1 parent a3f185a
commit e287ef7
Show file tree

Hide file tree

Showing 4 changed files with 152 additions and 93 deletions.
diff --git a/WSCLIENT_DEV.md → CLIENT_DEV.md b/WSCLIENT_DEV.md → CLIENT_DEV.md
diff --git a/README.md b/README.md
@@ -1,155 +1,177 @@
-# Mpush 2.0
+# Mpush 2.1
 
 ## 功能
-mpush是一套致力于用最简单,最快速的方式把消息从任何地方推送到指定的人的终端的系统,就像[server酱](http://sc.ftqq.com/3.version)一样  
-只不过接收消息的不是微信而是任何可以建立websocket的客户端,就像下一点提到的安卓客户端,又或者是http服务器(webhook方式)  
+
+mpush 是一套致力于用最简单,最快速的方式把消息从任何地方推送到指定的人的终端的系统,就像[server 酱](http://sc.ftqq.com/3.version)一样  
+只不过接收消息的不是微信而是任何可以建立 websocket 的客户端,就像下一点提到的安卓客户端,又或者是 http 服务器(webhook 方式),亦或者 FCM
 
 ## 安卓客户端仓库
+
 [mpush-android-client(2.x)](https://github.com/kooritea/mpush-android-client/tree/2.x)
 
-- 已经可以使用,功能正在完善中 
-- 2.x版本mpush需要配合使用2.x版本的mpush-android-client
+- 已经可以使用,功能正在完善中
+- 2.x 版本 mpush 需要配合使用 2.x 版本的 mpush-android-client
 
 ## 新特性
-- 使用typescript重新编写
+
+- 使用 typescript 重新编写
 - 新增一对多按组推送
-- 新增webhook的接入方式
-- 新增websocket客户端双向传递消息
+- 新增 webhook 的接入方式
+- 新增 websocket 客户端双向传递消息
+- 新增 FCM 接入方式(2.1)
 
 ## 一、安装
-- ### 稳定版  
+
+- ### 稳定版
 
 在[发布页](https://github.com/kooritea/mpush/releases)下载并解压
-仅需要ndoe环境(建议使用LTS 10.16.2或以上版本)
+仅需要 ndoe 环境(建议使用 LTS 10.16.2 或以上版本)
+
+```bash
+npm install --production
+
+# 按需修改完配置文件后运行
+npm run start
+```
 
 ---
 
 - ### 开发版
 
 ```bash
 git clone https://github.com/kooritea/mpush.git
+cd mpush
+npm install
+
+# 按需修改完配置文件后运行
+npm run dev
 ```
-需要安装typescript，package的脚本是linux上的，windows需要自行修改
 
 ## 二、配置
 
-直接编辑根目录的config.json
-* 开发版只需编辑根目录的config.json
-* 直接运行dist目录下编译后的应用则需要运行npm run build覆盖配置或手动编辑  
+直接编辑根目录的 config.json
+2.1 和 2.0 已有有较大幅度变化
 
 ```javascript
 {
-    "HTTP_PORT":8090, // http服务器监听的地址
-    "WEBSOCKET_PORT":8091, // websocket服务器监听的地址
-    "TOKEN": "test", // 客户端接入需要与这个token匹配,webhook会带上这个token用于接收方校验
-    "WEBHOOK_CLIENTS": [ // webhook配置,不使用可以留空(不要删除中括号[])
-        {
-            "NAME": "wh1", // 唯一名称,不应该与其他任何客户端同名,否则只有先接入的客户端能接收到消息
-            "GROUP": "group2", // 组名,按组推送使用,
-            "URL": "http://127.0.0.1:8092/mpush", // 请求地址
-            "METHOD": "GET" // 请求方法
-        },
-        {
-            "NAME": "TEST_WEBHOOK_POST",
-            "URL": "http://127.0.0.1:8092/mpush",
-            "METHOD": "POST"
-        }
+  "token": "test",
+  "http": {
+    "verifyToken": false, // 验证token,token位置为http头的authorization字段
+    "port": 9093,
+    "waitTimeout": 5000 //等待客户端答复的最长时间,超时后会返回目标客户端的接受状态
+  },
+  "websocket": {
+    "verifyToken": true, // websocket连接起始阶段的AUTH指令是否验证token
+    "port": 9094,
+    "authTimeout": 30000, // 时间内未验证成功将会断开socket
+    "retryTimeout": 3000, // 时间内未收到socket客户端的消息确认会重新发送
+    "waitTimeout": 5000  // 使用socket客户端向其他客户端发送消息时,等待其他客户端答复的最长时间,超时后会返回目标客户端的接受状态
+  },
+  "webhook": {
+    "retryTimeout": 3000,//时间内未收到2xx状态码会重新发送
+    "clients": [
+      {
+        "name": "wh1",
+        "group": "group2",
+        "url": "http://127.0.0.1:8089/",
+        "method": "GET", // 请求体下面补充
+        // "proxy": { // 代理设置,可以在clients内对单个客户端设置,也可以在webhook.proxy统一设置
+        //   "host": "127.0.0.1",
+        //   "port": 12333,
+        //   "auth": {
+        //     "username": "string",
+        //     "password": "string"
+        //   },
+        //   "protocol": "http"
+        // }
+      }
     ],
-    "PUSH_TIMEOUT": 10000, // 等待回复确认的时间,超时未确认将会重发消息
-    "PUSH_INTERVAL": 5000, // 重试间隔 推送失败或异常等待多少时间再重发
-    "DEBUG": false, // 打印更多信息
+    // "proxy": {
+    //   "host": "127.0.0.1",
+    //   "port": 12333,
+    //   "auth": {
+    //     "username": "string",
+    //     "password": "string"
+    //   },
+    //   "protocol": "http"
+    // }
+  },
+  "fcm": {
+    "serverKey": "", // FCMserverKey,获取方式下面补充
+    "proxy": "http://127.0.0.1:12333",// http代理
+    "retryTimeout": 10000 // 向FCM服务器发送请求等待时间,超时未成功会重试
+  }
 }
 ```
 
-## 三、运行
-
-### 1、安装依赖
-
-```bash
-npm i
-```
-### 2、运行
-
-- ### [发布页](https://github.com/kooritea/mpush/releases)下载的稳定版
-```bash
-node src/app.js
-```
-
----
-
-- ### 直接克隆或下载仓库的开发版
-```bash
-npm run dev
-```
-
-## 四、使用方式
+## 三、使用方式
 
 ### 1、客户端接入方式
 
 #### (1) websocket
 
-具体接入方式的实现由客户端实现，仅需要在客户端中填写name、group、token即可
+具体接入方式的实现由客户端实现，仅需要在客户端中填写 name、group、token 即可
+
 #### (2) webhook
 
-收到消息会以http请求的方式发送到指定的服务器，配置参考第二点中WEBHOOK字段
+收到消息会以 http 请求的方式发送到指定的服务器，配置参考第二点中 webhook 字段
 
-`额外信息(extra)是指指定的字段外的字段`
+`额外信息(extra)是指text,desp的字段外的字段`
 `额外信息可以配合客户端实现例如: 优先级,scheme等功能`
 
+token 存放在 http 头的 authorization 字段
+
 ```javascript
 // get
 // 所有额外信息都会平铺到url上,但额外信息如果是多层对象则不会继续平铺,例如下面的a字段和b字段,b是一个编码的JSON字符串{hello:'world'}
 
-'/mpush?token=test&sendType=personal&target=wh1&fromMethod=websock&fromName=anonymous&mid=111111111111&text=text10&desp=desp10&a=233&b=%7B%22hello%22:%22world%22%7D'
+'/mpush?sendType=personal&target=wh1&fromMethod=websock&fromName=anonymous&mid=111111111111&text=text10&desp=desp10&a=233&b=%7B%22hello%22:%22world%22%7D'
 
 
 // post
 // 这里的额外信息会全部放到message.extra字段,没有额外信息字段的时候extra为空对象
 {
-    token: config.TOKEN,
+  cmd: 'MESSAGE',
+  data: {
     sendType: "personal" | "group",
     target: name | group name,
     from: {
-        method: 'websocket' | 'curl',
-        name: name | 'anonymous'
+      method: 'websocket' | 'http',
+      name: name | ''
     },
     mid: timestamp,
     message: {
-        text: string,
-        desp: string,
-        extra: {
-            a: 233,
-            b: {
-                hello: 'world'
-            }
+      text: string,
+      desp: string,
+      extra: {
+        a: 233,
+        b: {
+          hello: 'world'
         }
+      }
     }
+  }
 }
-```
-
-接收到webhook请求后 需要返回mid,不需要json格式,直接响应mid字符串
-
-```javascript
-GET 
--> mid
 
 ```
 
+`接收到 webhook 请求后 需要返回 2xx的响应码,否则超过设置的时间后会重新发送该消息`
+
 ### 2、发送消息
 
-#### (1) 使用http请求发送消息，可以使用GET和POST方法,接收text和desp两个字段，text一般用作title，参考server酱,除了text和desp参数,其他参数都会被放到extra字段中返回给客户端
+#### (1) 使用 http GET 请求发送消息,GET 方法接收 text 和 desp 两个字段，text 一般用作 title，参考 server 酱,除了 text 和 desp 参数,其他参数都会被放到 extra 字段中返回给接收方
 
 格式
 
 ```bash
 curl http://${HOST}:${HTTP_PORT}/${name}.${type:'send' | 'group'}?text=${text}&desp=${desp}&a=233&b=%7B%22hello%22:%22world%22%7D
 ```
 
-其中`type`为`send`的时候name为客户端的name  
+其中`type`为`send`的时候 name 为客户端的 name  
 为`group`的时候`name`为`group name`,即一对多推送
 
 例如  
-向name为`kooritea`的客户端推送消息text为`hello`,desp为`world`的消息
+向 name 为`kooritea`的客户端推送消息 text 为`hello`,desp 为`world`的消息
 
 ```bash
 curl http://HOST:HTTP_PORT/kooritea.send?text=hello&desp=world
@@ -160,6 +182,25 @@ curl http://HOST:HTTP_PORT/kooritea.send?text=hello&desp=world
 ```bash
 curl http://HOST:HTTP_PORT/kgroup.group?text=hello&desp=world
 ```
+
+#### (1) 使用 http POST 请求发送消息,POST 方法接收一个完整的消息包,格式如下
+
+```javascript
+{
+    cmd: "MESSAGE",
+    data : {
+      sendType: 'personal' | 'group',
+      target: string,
+      message: {
+        text: string,
+        desp: string,
+        extra: object
+      }
+    }
+}
+
+```
+
 ---
 
 ```javascript
@@ -171,24 +212,25 @@ curl http://HOST:HTTP_PORT/kgroup.group?text=hello&desp=world
         "client2 name": "ok",
         "client3 name": "no",
         "client4 name": "wait",
-        "client5 name": "timeout",
+        "client5 name": "fcm-wait",
+        "client5 name": "fcm-ok",
     }
 }
 ```
-|status | 意义|
-|------|---|
-|ready | 消息队列中还有未发送的消息,正在等待前面的消息推送完成|
-|ok | 推送成功|
-|no | 推送失败,没有找到该客户端(只会出现在一对一推送)|
-|wait | 正在等待回复确认|
-|timeout | 首次推送超过时间未回复确认,该消息会等待重发|
 
-注意: 假如该消息目标未进行第一次连接或未在config定义wenhook,则会默默失效
+| status   | 意义                                            |
+| -------- | ----------------------------------------------- |
+| ready    | 正在送信队列排队                                |
+| ok       | 送达,对端已确认                                 |
+| no       | 推送失败,没有找到该客户端(只会出现在一对一推送) |
+| wait     | 已发送,等待对端确认                             |
+| fcm-wait | 已通过 FCM 发送,等待对端确认                    |
+| fcm-ok   | 对端已确认 fcm 消息送达(不代表消息送达)         |
 
-#### (2) 通过websocket客户端发送推送消息请求
+#### (2) 通过 websocket 客户端发送推送消息请求
 
 这部分会由客户端实现(具体实现方式可以看下面的开发文档),用户只需要选择目标和内容
 
-## 五、websocket客户端开发
+## 五、客户端开发
 
-[通信方式](./WSCLIENT_DEV.md)
+[通信方式](./CLIENT_DEV.md)
diff --git a/package.json b/package.json
@@ -5,8 +5,8 @@
   "main": "src/main.js",
   "scripts": {
     "dev": "tsnd -P ./tsconfig.json --respawn ./src/main.ts",
-    "build": "tsc",
-    "start": "node mpush/src/main.js",
+    "build": "rm -rf ./dist && tsc --build ./tsconfig.prod.json && cp ./package.json ./dist/package.json",
+    "start": "node src/main.js",
     "test": "node test.js"
   },
   "repository": {
@@ -34,4 +34,4 @@
     "web-push": "^3.4.3",
     "ws": "^7.1.1"
   }
-}
+}
diff --git a/tsconfig.prod.json b/tsconfig.prod.json
@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "declaration": false,
+    "removeComments": true,
+    "emitDecoratorMetadata": false,
+    "experimentalDecorators": false,
+    "target": "es2017",
+    "sourceMap": false,
+    "outDir": "./dist",
+    "baseUrl": "./",
+    "incremental": false,
+    "resolveJsonModule": true,
+    "strictNullChecks": true
+  },
+  "exclude": ["node_modules", "dist"]
+}