pushdeer/README.md

492 lines
14 KiB
Markdown
Raw Normal View History

2022-02-02 21:34:59 +08:00
PushDeer是一个可以自行架设的无APP推送服务。
2021-12-23 00:19:55 +08:00
2022-02-04 14:10:35 +08:00
当前状态API、iOS、Android和Mac第一版已完成快应用正在开发🚧
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
[🐙🐱 GitHub仓库](https://github.com/easychen/pushdeer) [🔮 中国大陆镜像仓库@Gitee](https://gitee.com/easychen/pushdeer)
2021-12-24 12:25:16 +08:00
2021-12-23 00:19:55 +08:00
|登入|设备|Key|消息|设置|
|-|-|-|-|-|
|![](doc/design_and_resource/登入.png)|![](doc/design_and_resource/设备.png)|![](doc/design_and_resource/key.png)|![](doc/design_and_resource/消息.png)|![](doc/design_and_resource/设置.png)
2022-02-02 21:34:59 +08:00
# 子项目和核心贡献者
2022-01-20 13:10:11 +08:00
|功能|核心贡献人|预期完成时间|最低版本兼容|本周进度|
2021-12-27 12:53:10 +08:00
|-|-|-|-|-|
2022-02-02 21:34:59 +08:00
|iOS/Clip/Mac|[Hext123](https://github.com/Hext123)|已完成|iOS14|第一版完成代码在iOS目录下|
2022-01-27 18:16:52 +08:00
|Android客户端|[WolfHugo](https://github.com/alone-wolf)|已完成|5.1|第一版开发完成release页面可下载|
2022-02-02 21:34:59 +08:00
|快应用|[7YHong](https://github.com/7YHong)|2022年2月27日|-|对接API中|
|API|[Easy](https://ftqq.com) [古俊杰](https://github.com/ilovintit)|已完成|-|-|
2022-02-08 14:08:56 +08:00
|gorush的mi push版本|[SinTod](https://www.sintod.cn/)|已完成|-|代码在[push/gorush-with-mipush目录下](push/gorush-with-mipush)|
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
# 试用
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
## 使用官方在线版本
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
官方在线版不用自行架设服务器端,只需启动客户端即可
2022-01-29 14:39:51 +08:00
2022-02-02 21:34:59 +08:00
### iOS14+
2022-01-29 14:39:51 +08:00
2022-02-02 21:53:11 +08:00
![](doc/image/clipcode.png)
2022-02-02 21:34:59 +08:00
苹果手机iOS 14+用系统摄像头扫描上边的码即可拉起轻应用。亦可在苹果商店搜索「PushDeer」安装。
2022-01-29 14:39:51 +08:00
2022-02-02 21:34:59 +08:00
> 注意这里不要安装PushDeer自架版
2022-01-29 14:39:51 +08:00
2022-02-02 21:34:59 +08:00
### MacOS 11+
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
PushDeer有Mac客户端亦支持推送。可在Mac应用商店中搜索「PushDeer」安装。
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
### Android
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
快应用尚在开发可下载并安装Android测试版APP([GitHub](https://github.com/easychen/pushdeer/releases/tag/android1.0alpha)|[Gitee](https://gitee.com/easychen/pushdeer/releases/android1.0alpha))。
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
### 发送消息
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
1. 通过apple账号或微信账号·仅Android版支持登录
1. 切换到「设备」标签页,点击右上角的加号,注册当前设备
1. 切换到「Key」标签页点击右上角的加号创建一个Key
2022-02-08 12:19:19 +08:00
1. 通过访问后边的URL即可推送内容https://api2.pushdeer.com/message/push?pushkey=key&text=要发送的内容
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
> 注意注册设备用到了device token应用一旦重装device token会变所以需要重新注册一次。
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
### 发送实例
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
发送文字:
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
```
2022-02-08 12:19:19 +08:00
https://api2.pushdeer.com/message/push?pushkey=key&text=要发送的内容
2022-02-02 21:34:59 +08:00
```
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
发送图片:
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
```
2022-02-08 12:19:19 +08:00
https://api2.pushdeer.com/message/push?pushkey=<key>&text=<图片URL>&type=image
2022-02-02 21:34:59 +08:00
```
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
发送Markdown
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
```
2022-02-08 12:19:19 +08:00
https://api2.pushdeer.com/message/push?pushkey=<key>&text=标题&desp=<markdown>&type=markdown
2022-02-02 21:34:59 +08:00
```
2022-01-20 14:27:12 +08:00
2022-02-02 21:34:59 +08:00
在URL中可以用`%0A`换行当参数中有特殊字符时需要进行urlencode因此更建议通过函数或者SDK发送。
2022-01-20 14:27:12 +08:00
2022-02-02 21:34:59 +08:00
- [Python SDK](https://github.com/gaoliang/pypushdeer) by [Gao Liang](https://github.com/gaoliang)
- [Go SDK](https://github.com/Luoxin/go-pushdeer-sdk) by [Luoxin](https://github.com/Luoxin)
2022-01-18 12:32:00 +08:00
2022-02-02 21:34:59 +08:00
PHP函数
2022-01-18 12:32:00 +08:00
2022-02-02 21:34:59 +08:00
```php
function pushdeer_send($text, $desp = '', $type='text', $key = '[PUSHKEY]')
{
$postdata = http_build_query(array( 'text' => $text, 'desp' => $desp, 'type' => $type , 'pushkey' => $key ));
$opts = array('http' =>
array(
'method' => 'POST',
'header' => 'Content-type: application/x-www-form-urlencoded',
'content' => $postdata));
$context = stream_context_create($opts);
2022-02-08 12:19:19 +08:00
return $result = file_get_contents('https://api2.pushdeer.com/message/push', false, $context);
2022-02-02 21:34:59 +08:00
}
```
2022-01-20 13:10:11 +08:00
2022-02-02 21:34:59 +08:00
### 将 PushDeer 接入 ServerChan
2021-12-23 23:25:41 +08:00
2022-02-02 21:34:59 +08:00
由于 PushDeer 刚开发,很多软件和平台都尚未整合其接口,你可以将 PushDeer 接入Server酱作为通道使用效果是
2021-12-23 23:25:41 +08:00
2022-02-02 21:34:59 +08:00
1. 使用`sendkey`调用Server酱接口
2. 在 PushDeer 客户端收到通知
2021-12-23 23:25:41 +08:00
2022-02-02 21:34:59 +08:00
接入方式如下:
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
1. 登入 sct.ftqq.com 选择「消息通道」页面选择「推荐通道」中的「PushDeer」
1. 将在PushDeer客户端中生成的Key填入即可
2021-12-23 00:19:55 +08:00
2022-02-02 21:45:54 +08:00
![](doc/image/2022-02-02-21-39-16.png)
2022-02-02 21:34:59 +08:00
你也可以通过「其他通道」中的「自定义」来修改转发格式和文案。具体操作是,在「自定义 WebHook 配置用 json」中填入以下内容:
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
```json
{
2022-02-08 12:19:19 +08:00
"url":"https://api2.pushdeer.com/message/push?pushkey={{pushkey}}",
2022-02-02 21:34:59 +08:00
"values":[
{"type":"markdown"},
{"text":"{{title}} "},
{"desp":"{{desp}} [查看详情]({{url}})"}
]
}
```
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
注意将 `{{pushkey}}` 换成你自己的 PushDeer 账号中的 key保存即可。可点右侧的测试按钮测试效果。
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
## 使用自架服务器端和自架版客户端
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
### 自架服务器端
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
除了使用官方架设的服务器端你也可以架设自己的服务器端。本仓库支持通过docker部署服务器端。
2021-12-23 00:19:55 +08:00
2022-02-05 11:25:38 +08:00
如果你没有云服务器,可以看看[腾讯云30~50元首单的特价服务器](https://curl.qcloud.com/VPjlS4gj)
2022-02-02 21:34:59 +08:00
首先请确保服务器(假设其IP或域名为$AAA)上支持docker和docker-compose。
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
然后运行以下代码:
2021-12-23 00:19:55 +08:00
2022-02-03 12:43:12 +08:00
(大陆服务器使用)
2022-02-02 21:34:59 +08:00
```
2022-02-03 12:43:12 +08:00
git clone https://gitee.com/easychen/pushdeer.git
2022-02-02 21:34:59 +08:00
cd pushdeer
docker-compose -f docker-compose.self-hosted.yml up --build -d
```
2021-12-23 00:19:55 +08:00
2022-02-03 12:43:12 +08:00
(海外服务器使用)
```
git clone https://github.com/easychen/pushdeer.git
cd pushdeer
docker-compose -f docker-compose.self-hosted.yml up --build -d
```
> 如提示docker服务未安装/找不到/未启动,可在 docker-compose 前加 sudo 再试
2022-02-02 21:34:59 +08:00
等待初始化完成后,访问 `$AAA(需替换为服务器端IP或域名):8800`,看到以下信息则表示服务器端已启动完毕。
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
```json
{
"PushDeer": "On"
}
```
2021-12-23 00:19:55 +08:00
2022-02-02 21:58:16 +08:00
> ⚠️ 自架服务器端需每年2月拉取一次更新推送证书
2022-02-02 21:34:59 +08:00
### 使用自架版客户端
2021-12-23 00:19:55 +08:00
2022-02-02 21:45:54 +08:00
![](doc/image/2022-02-02-21-45-29.png)
2022-02-02 21:34:59 +08:00
在苹果商店搜索「PushDeer·自架版」安装并启动。
2021-12-23 00:19:55 +08:00
2022-02-02 21:53:11 +08:00
![](doc/image/2022-02-02-21-14-21.png)
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
在启动界面输入 `$AAA(需替换为服务器端IP或域名):8800`点保存。如果通信顺利即可顺利完成「通过Apple登录」。如输入错误可点击「重置API endpoint」重新输入。
2021-12-23 00:19:55 +08:00
2022-02-02 21:53:11 +08:00
![](doc/image/2022-02-02-21-17-45.png)
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
登入成功后,亦可随时在设置页面重置 API endpoint。
2021-12-23 00:19:55 +08:00
2022-02-02 21:53:11 +08:00
![](doc/image/2022-02-02-21-18-49.png)
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
### 生产环境的配置强化/优化
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
参见[𐂂安装文档](doc/安装文档.md)
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
# 关于轻应用
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
> 轻应用找不到了怎么办?
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
在搜索框搜索pushdeer就能找到。
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
> 轻应用怎么清理掉?占空间么?
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
系统设置里边有一个轻应用管理在里边可以清理。30天不用会自动清理掉。注意重新安装后设备id会变动需要再手动注册一遍。
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
# 开发说明
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
视频版设计文档: [📼 项目视频说明](https://www.bilibili.com/video/BV1Ar4y1S7em/) [📼 项目架构和模块说明](https://www.bilibili.com/video/BV1ZS4y1T7Bf/)
2021-12-23 00:19:55 +08:00
2022-02-02 21:34:59 +08:00
## 目录说明
2021-12-23 00:19:55 +08:00
- api: Laravel实现的API接口[点此查看请求和返回demo](doc/api/PushDeerOS.md)
- docker: API实现的docker封装一键启动方便使用
- doc: 文档目录包括界面设计源文件Adobe XD和资源文件logo和avatar
- push: 基于 [gorush](https://github.com/appleboy/gorush) 架设的推送微服务,配置文件开启 async 可以提升发送速度
- ios: 用于放置 iOS 源文件,`ios/Prototype_version` 目录是我边学边写的原型验证版本SwiftUI+Moya+Codable很多地方需要重写仅供参考
- quickapp: 用于放置快应用源代码
2022-02-02 21:34:59 +08:00
- android: 用于放置安卓客户端源代码
2021-12-23 00:19:55 +08:00
## 开发环境搭建
### 下载代码
2021-12-23 12:29:55 +08:00
```git clone https://github.com/easychen/pushdeer.git```
2021-12-23 00:19:55 +08:00
### 启动docker环境
运行 `docker-compose up -d`启动API。默认访问地址为`http://127.0.0.1:8800`。可修改`docker-compose.yml`调整端口。
2021-12-23 00:19:55 +08:00
### API 说明
2022-01-04 18:57:17 +08:00
[在线文档Swagger](https://ilovintit.github.io/pushdeer-api-doc/#/)
2021-12-23 00:19:55 +08:00
API_BASE=http://127.0.0.1:8800
认证方式:通过登入接口获得`token`,通过`post`和`get`方式附带`token`参数即可自动登入。
2022-01-24 12:11:40 +08:00
#### 模拟登入(环境变量APP_DEBUG=true时可用)
2021-12-23 00:19:55 +08:00
`GET /login/fake`
2022-01-24 12:11:40 +08:00
#### 通过苹果 idToken 登入
`POST /login/idtoken`
|参数|说明|备注|
|-|-|-|
|idToken|Sign in with Apple 中得到的 idToken|
#### 通过微信 oauth code 登入
`POST /login/wecode`
|参数|说明|备注|
|-|-|-|
|code|客户端微信授权得到的code|
2022-01-24 13:40:50 +08:00
#### 合并用户并将旧用户删除
`POST /user/merge`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|type|字符串,必须为 apple 或者 wechat|
|tokenorcode|type 为 apple时此字段为 idToken否则为 微信code |
2021-12-23 00:19:55 +08:00
#### 获得当前用户的基本信息
`POST /user/info`
|参数|说明|备注|
|-|-|-|
|token|认证token|
#### 注册设备
`POST /device/reg`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|name|设备名称|
|device_id|device token推送用|
|is_clip|是否轻应用|0为APP|
#### 设备列表
`POST /device/list`
|参数|说明|备注|
|-|-|-|
|token|认证token|
#### 重命名设备
`POST /device/rename`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|设备id|
|name|设备新名称|
#### 移除设备
`POST /device/remove`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|设备id|
#### 生成一个新Key
`POST /key/gen`
|参数|说明|备注|
|-|-|-|
|token|认证token|
#### 重命名Key
`POST /key/rename`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|Key ID|
|name|Key新名称|
#### 重置一个Key
`POST /key/regen`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|Key ID|
#### 获取当前用户的Key列表
`POST /key/list`
|参数|说明|备注|
|-|-|-|
|token|认证token|
#### 删除Key
`POST /key/remove`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|Key ID|
#### 推送消息
`POST /message/push`
|参数|说明|备注|
|-|-|-|
|pushkey|PushKey|
|text|推送消息内容|
|desp|消息内容第二部分,选填|
|type|格式,选填|文本=textmarkdown图片=image默认为markdown|
type 为 image 时text 中为要发送图片的URL。
2021-12-23 00:19:55 +08:00
#### 获得当前用户的消息列表
`POST /message/list`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|limit|消息条数|默认为10最大100
#### 删除消息
`POST /message/remove`
|参数|说明|备注|
|-|-|-|
|token|认证token|
|id|消息ID|
[更详细的请求和返回值可以参考这里](doc/api/PushDeerOS.md)
通用返回格式:
2021-12-23 00:19:55 +08:00
```
{
code:正确为0错误为非0,
content:内容,错误时无此字段,
error:错误信息,无错误时无此字段
2021-12-23 00:19:55 +08:00
}
```
2022-02-02 21:34:59 +08:00
# 产品设计文档
## 产品定义
PushDeer的**核心价值**,包括:「易用」、「可控」和「渐进」。
### 易用
易用性表现在两个方面:
1. 易安装采用无APP方案直接**去掉安装步骤**
1. 易调用只需输入URL**无需阅读文档**,就可以发送消息
### 可控
1. `Self-hosted`:让有能力和精力的用户可以自行架设,避免因为在线服务下线导致的接口更换风险。
1. 非商用免费不用PushDeer挣钱就无需支付费用
1. 不依赖微信消息接口不像Server酱那样受腾讯政策影响
### 渐进
1. 通过URL即可发送基本的文本消息通过更多参数可以对消息的样式等细节进行调整
1. 无APP不能实现的功能不能覆盖的机型后期可以通过APP来补充
## 商业模式
PushDeer是一个商业开源项目采用「开放源码」、「自用免费」、「在线服务收费」的方式进行运作。
### 具体实现
PushDeer是一个以盈利为目的的商业项目品牌和源码所有权都由「方糖君」公司持有但和纯商业项目不同的地方在于
1. 它开放源代码所有人都可以在非商业前提下按GPLv2授权使用
1. 它接受社区贡献代码,作为回报,它会从商业收益中拿出部分来赞助项目贡献人
1. 如果商业收益够大,它会尝试雇佣项目贡献人以兼职或者全职的方式为项目工作
这里边有一些细节:
1. 为了避免某些个人或者公司使用源码搭建在线竞品服务收费,我们限制了源码不能商用
1. 在刚开始的时候项目并没有商业收入而却是开发工作量最大的。所以首先我们会承担产品和界面设计、API设计和开发等工作并通过众筹的方式筹集了一些资金给其他大模块的贡献人
开放源码形式保证了其他代码贡献人在非商业场景下对源码的可控:
1. 如果社区和代码贡献人不满意「方糖君」主导的商业化,可以 Fork 一个版本,继续在非商用的前提下自行运营
1. 如果「方糖君」之后不再开放源代码,普通用户依然可以按之前的协议使用修改协议前的源码
## 用户细分
PushDeer主要面向以下三类用户
1. 高阶电脑用户
1. 开发者
1. 公司或自媒体
### 高阶电脑用户
具有一定电脑操作技能的高阶用户,比如:
1. NAS 用户
1. 站长
1. 电脑技术爱好者
他们使用PushDeer的场景包括但不限于
1. 推送路由器和 NAS 的状态、公网 IP 等信息
1. 推送 Wordpress 最新的评论
1. 推送加密货币达到特定价格的通知
1. 在多台设备上推送文本
1. 自动化工具推送定期汇报
### 开发者
使用PushDeer的场景包括但不限于
1. 推送报错和调试信息
1. 推送服务器异常
1. 推送定时任务输出
1. 在自己的软件发送消息到手机引导用户填入PushDeer的key
### 公司或自媒体
使用PushDeer的场景包括但不限于
1. 面向自己的用户推送通知、内容和营销信息(类似公众号,但不受微信限制)
2022-02-02 22:02:17 +08:00
# 授权
2021-12-23 00:31:15 +08:00
本项目禁止商用(包括但不限于搭建后挂广告或售卖会员、打包后上架商店销售等),对非商业用途采用 GPLV2 授权
2021-12-23 18:04:30 +08:00
2022-02-02 22:02:17 +08:00
# 相关项目
2022-02-02 21:34:59 +08:00
- [API的Go实现](https://github.com/iepngs/pushdeer-backend-go) by [iepngs](https://github.com/iepngs)