添加文档

docs/README.md

@@ -0,0 +1,25 @@
+
+### Bark <!-- {docsify-ignore-all} -->
+- 免费、轻量！简单调用接口即可给自己的iPhone发送推送。
+- 依赖苹果APNs，及时、稳定、可靠
+- 不会消耗设备的电量， 基于系统推送服务与推送扩展，APP本体并不需要运行。
+- 信任成本很昂贵，所以 Bark 默认所有人（但包含作者本人）都有可能窃取你的隐私，以此为基础来设计隐私保护。<br>*点击详细了解Bark如果保障[隐私安全](/privacy)*
+
+### 源码
+- [Bark](https://github.com/Finb/Bark) 是完整开源的 iOS APP，用来接收自定义推送。
+- [bark-server](https://github.com/Finb/bark-server) 是完整开源的 Bark 服务后端，用来接收用户的推送并转发给苹果APNS。
+
+### 反馈
+- [Bark 问题反馈群](https://t.me/joinchat/OsCbLzovUAE0YjY1) （注意点击入群验证）
+- [GitHub Issues](https://github.com/Finb/Bark/issues)
+
+### 免费
+Bark **2018年7月**上线，至少会维持运营到 **2031年7月** 。*（说不出口“永久”这个词，后续还有需求再续吧）*<br> 
+APP在维持期间，不会有任何形式的收费与广告，各位彦祖放心使用。
+
+### 赞助
+目前仅接收 GitHub 赞助，同时非常感谢每一位赞助者 <br>
+赞助者：[https://github.com/sponsors/Finb](https://github.com/sponsors/Finb)
+
+
+

docs/_coverpage.md

@@ -0,0 +1,11 @@
+![logo](_media/icon.png)
+
+# Bark <small></small>
+
+> 一款注重隐私、安全可控的自定义通知推送工具。
+
+- 免费、简单、安全
+- 打开即用
+
+[GitHub](https://github.com/finb/bark)
+[Get Started](#bark)

docs/_navbar.md

@@ -0,0 +1,4 @@
+* Translations
+  - [:cn: 简体中文](/)
+  - [:uk: English](/en-us/)
+  

docs/_sidebar.md

@@ -0,0 +1,10 @@
+- [Bark](/#bark)
+- **App**
+  - [使用教程](/tutorial)
+  - [常见问题](/faq)
+- **服务端**
+  - [部署服务](/deploy)
+  - [直接推送](/apns)
+  - [编译代码](/build)
+  - [推送证书](/cert)
+- [隐私安全](/privacy)

docs/apns.md

@@ -0,0 +1,55 @@
+### 直接调用APNS接口
+如果有设备的 DeviceToken（可在APP中查看），就可以调用苹果APNS接口直接给设备发推送，APP中也无需添加服务器。<br>
+以下是命令行发推送示例：
+
+```shell
+# 设置环境变量
+# 下载 key https://raw.githubusercontent.com/Finb/bark-server/master/deploy/AuthKey_LH4T9V5U4R_5U8LBRXG3A.p8 
+# 将 key 文件路径填到下面
+TOKEN_KEY_FILE_NAME= 
+# 从 app 设置中复制 DeviceToken 到这
+DEVICE_TOKEN=
+
+#下面的不要修改
+TEAM_ID=5U8LBRXG3A
+AUTH_KEY_ID=LH4T9V5U4R
+TOPIC=me.fin.bark
+APNS_HOST_NAME=api.push.apple.com
+
+# 生成TOKEN
+JWT_ISSUE_TIME=$(date +%s)
+JWT_HEADER=$(printf '{ "alg": "ES256", "kid": "%s" }' "${AUTH_KEY_ID}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
+JWT_CLAIMS=$(printf '{ "iss": "%s", "iat": %d }' "${TEAM_ID}" "${JWT_ISSUE_TIME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
+JWT_HEADER_CLAIMS="${JWT_HEADER}.${JWT_CLAIMS}"
+JWT_SIGNED_HEADER_CLAIMS=$(printf "${JWT_HEADER_CLAIMS}" | openssl dgst -binary -sha256 -sign "${TOKEN_KEY_FILE_NAME}" | openssl base64 -e -A | tr -- '+/' '-_' | tr -d =)
+# 如果有条件，最好改进脚本缓存此 Token。Token 30分钟内复用同一个，每过30分钟重新生成
+# 苹果文档指明 TOKEN 生成间隔最短20分钟，TOKEN 有效期最长60分钟
+# 间隔过短重复生成会生成失败，TOKEN 超过1小时不重新生成就不能推送
+# 但经我不负责任的简单测试可以短时间内正常生成
+# 此处仅提醒，或许可能因频繁生成 TOKEN 导致推送失败
+AUTHENTICATION_TOKEN="${JWT_HEADER}.${JWT_CLAIMS}.${JWT_SIGNED_HEADER_CLAIMS}"
+
+#发送推送
+curl -v --header "apns-topic: $TOPIC" --header "apns-push-type: alert" --header "authorization: bearer $AUTHENTICATION_TOKEN" --data '{"aps":{"alert":"test"}}' --http2 https://${APNS_HOST_NAME}/3/device/${DEVICE_TOKEN}
+
+```
+
+### 推送参数格式
+参考 https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/generating_a_remote_notification<br>
+一定要带上 "mutable-content" : 1 ，否则推送扩展不执行，不会保存推送。<br>
+
+示例：
+```js
+{
+    "aps": {
+        "mutable-content": 1,
+        "alert": {
+            "title" : "title",
+            "body": "body"
+        },
+        "category": "myNotificationCategory",
+        "sound": "minuet.caf"
+    },
+    "icon": "https://day.app/assets/images/avatar.jpg"
+}
+```

docs/build.md

@@ -0,0 +1,45 @@
+## 下载源码
+[bark-server](https://github.com/Finb/bark-server)
+```sh
+git clone https://github.com/Finb/bark-server.git
+```
+## 配置依赖
+- Golang 1.18+
+- Go Mod (env GO111MODULE=on)
+- Go Mod Proxy (env GOPROXY=https://goproxy.cn)
+- 安装 [go-task](https://taskfile.dev/installation/) 
+
+## 交叉编译所有平台
+```sh
+task
+```
+
+## 编译指定平台
+```sh
+task linux_amd64
+task linux_amd64_v3
+```
+
+## 支持的平台
+
+- linux_386
+- linux_amd64
+- linux_amd64_v2
+- linux_amd64_v3
+- linux_amd64_v4
+- linux_armv5
+- linux_armv6
+- linux_armv7
+- linux_armv8
+- linux_mips_hardfloat
+- linux_mipsle_softfloat
+- linux_mipsle_hardfloat
+- linux_mips64
+- linux_mips64le
+- windows_386.exe
+- windows_amd64.exe
+- windows_amd64_v2.exe
+- windows_amd64_v3.exe
+- windows_amd64_v4.exe
+- darwin_amd64
+- darwin_arm64

docs/cert.md

@@ -0,0 +1,6 @@
+当你需要集成Bark到自己的系统或重新实现后端代码时可能需要推送证书
+ 
+##### 有效期到: *永久*
+##### Key ID：*LH4T9V5U4R*
+##### TeamID：*5U8LBRXG3A*
+##### 下载地址：[AuthKey_LH4T9V5U4R_5U8LBRXG3A.p8](https://github.com/Finb/bark-server/releases/download/v1.0.2/AuthKey_LH4T9V5U4R_5U8LBRXG3A.p8)

docs/deploy.md

@@ -0,0 +1,59 @@
+
+## Docker 
+```
+docker run -dt --name bark -p 8080:8080 -v `pwd`/bark-data:/data finab/bark-server
+```
+
+## Docker-Compose 
+```
+mkdir bark && cd bark
+curl -sL https://git.io/JvSRl > docker-compose.yaml
+docker-compose up -d
+```
+## 手动部署
+
+1. 根据平台下载可执行文件:<br> <a href='https://github.com/Finb/bark-server/releases'>https://github.com/Finb/bark-server/releases</a><br>
+或自己编译<br>
+<a href="https://github.com/Finb/bark-server">https://github.com/Finb/bark-server</a>
+
+2. 运行
+```
+./bark-server_linux_amd64 -addr 0.0.0.0:8080 -data ./bark-data
+```
+3. 你可能需要
+```
+chmod +x bark-server_linux_amd64
+```
+请注意 bark-server 默认使用 /data 目录保存数据，请确保 bark-server 有权限读写 /data 目录，或者你可以使用 `-data` 选项指定一个目录
+
+## Serverless 
+  
+
+  默认提供 Heroku ~~免费~~ 一键部署 (2022-11-28日后收费)<br>
+  [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/finb/bark-server)<br>
+
+  其他支持WEB路由的 serverless 服务器可以使用 `bark-server -serverless true` 开启。
+
+  开启后， bark-server 会读取系统环境变量 BARK_KEY 和 BARK_DEVICE_TOKEN, 需提前设置好。
+
+  | 变量名 | 填写要求 |
+  | ---- | ---- |
+  | BARK_KEY | 除了不能填 "push" 外，可以随便填写你喜欢的。|
+  | BARK_DEVICE_TOKEN | Bark App 设置中显示的 DeviceToken，此 Token 是 APNS 真实设备 Token ,请不要泄露 |
+
+  请注意 Serverless 模式只允许一台设备使用
+
+## 使用
+```
+curl http://0.0.0.0:8080/ping
+```
+Ping成功后，在APP端填入你的服务器IP或域名
+
+## 其他
+
+1. APP端负责将<a href="https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622958-application">DeviceToken</a>发送到服务端。 <br>服务端收到一个推送请求后，将发送推送给Apple服务器。然后手机收到推送
+
+2. 服务端代码: <a href='https://github.com/Finb/bark-server'>https://github.com/Finb/bark-server</a><br>
+
+3. App代码: <a href="https://github.com/Finb/Bark">https://github.com/Finb/Bark</a>
+

docs/en-us/README.md

@@ -0,0 +1 @@
+...

docs/en-us/_coverpage.md

@@ -0,0 +1,11 @@
+![logo](../_media/icon.png)
+
+# Bark <small></small>
+
+> ...
+
+- ...
+- ...
+
+[GitHub](https://github.com/finb/bark)
+[Get Started](#bark)

docs/en-us/_sidebar.md

@@ -0,0 +1,10 @@
+- [Bark](/en-us/#bark)
+- **App**
+  - [tutorial](/en-us/tutorial)
+  - [FAQ](/en-us/faq)
+- **Server**
+  - [Deploy](/en-us/deploy)
+  - [Push](/en-us/apns)
+  - [Build](/en-us/build)
+  - [Cert](/en-us/cert)
+- [Privacy](/en-us/privacy)

docs/en-us/apns.md

@@ -0,0 +1 @@
+...

docs/en-us/build.md

@@ -0,0 +1 @@
+...

docs/en-us/cert.md

@@ -0,0 +1 @@
+...

docs/en-us/deploy.md

@@ -0,0 +1 @@
+...

docs/en-us/faq.md

@@ -0,0 +1 @@
+...

docs/en-us/privacy.md

@@ -0,0 +1 @@
+...

docs/en-us/tutorial.md

@@ -0,0 +1 @@
+...

docs/faq.md

@@ -0,0 +1,47 @@
+* #### 推送使用次数限制 <!-- {docsify-ignore-all} -->
+正常请求（HTTP状态码为200）无任何限制。<br>
+但如果在5分钟内超过1000次错误请求（HTTP状态码为400 404 500）<b>IP会被 BAN 24小时</b> 
+
+* #### 时效性通知无效 
+可以尝试<b>重启设备</b>来解决。
+
+* #### 无法保存通知历史，或下拉推送没有点击复制按钮无法复制
+可以尝试<b>重启设备</b>来解决。<br />
+因某些原因导致推送服务扩展（[UNNotificationServiceExtension](https://developer.apple.com/documentation/usernotifications/unnotificationserviceextension)）未能正常运行，执行通知保存的代码未能正常执行。
+
+* #### 自动复制推送失效
+iOS 14.5 之后的版本因权限收紧，不能在收到推送时自动复制推送内容到剪切板。<br/>
+可暂时先下拉推送或在锁屏界面左滑推送点查看即可自动复制，或点击弹出的推送复制按钮。
+
+* #### 默认打开通知历史列表
+再次开启APP时，会跳转到上次打开的页面。<br />
+只需退出APP时，停留在历史消息页面，再次打开APP时就是历史消息页面。
+
+* #### 推送 API 是否支持 POST 请求？
+Bark支持 GET POST ,支持使用Json<br>
+无论哪种请求方式，参数名都一样, 参考[使用教程](/tutorial#请求方式)
+
+* #### 推送特殊字符导致推送失败，比如 推送内容包含链接，或推送异常 比如 + 变成空格
+这是因为整个链接不规范导致的问题，常发生在自己手动拼接URL时。<br>
+拼接URL时，注意将参数进行URL编码 
+
+    ```sh
+    # 例如
+    https://api.day.app/key/{推送内容}
+
+    # 如果{推送内容}是
+    "a/b/c/"
+    
+    # 则最后拼接的URL是
+    https://api.day.app/key/a/b/c/
+    # 将找不到对应的路由，后端程序将返回404
+    
+    # 应该将 {推送内容} url编码后再进行拼接
+    https://api.day.app/key/a%2Fb%2Fc%2F
+    ```
+
+    如果是使用成熟的HTTP库时，参数都会被自动处理，无需自己手动编码。<br>
+    但如果是自己去拼接URL时，则需要特别注意参数中的特殊字符，最好不管有没有特殊字符，无脑套一层URL编码。
+
+* #### 如何保障隐私安全
+参考[隐私安全](/privacy)

docs/index.html

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Bark',
+      nameLink: '/#/?id=源码',
+      repo: 'https://github.com/Finb/Bark',
+      logo: '/_media/icon.png height=60px',
+      coverpage: true,
+      loadSidebar: true,
+      subMaxLevel: 4,
+      loadNavbar: true,
+      auto2top: true,
+      coverpage: ['/', '/en-us/'],
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+</body>
+
+</html>

docs/privacy.md

@@ -0,0 +1,30 @@
+#### 隐私如何泄露 <!-- {docsify-ignore-all} -->
+一条推送从发送到接收经过路线是：<br>
+发送端 <font color='red'> →服务端①</font> → 苹果APNS服务器 → 你的设备 → <font color='red'>Bark APP②</font>。
+
+红色的两处地方可能泄露隐私 <br>
+* 发送端未使用HTTPS或使用公共服务器（作者会看到请求日志）
+* Bark App 本身不安全，上传到 App Store 的版本经过修改。
+
+#### 解决服务端隐私问题
+* 你可以使用开源的后端代码，自行[部署后端服务](/deploy.md)，开启HTTPS。
+* 使用自定义秘钥的[加密推送](/tutorial)
+
+#### 保证 APP 完全由开源代码构建
+为确保 Bark App 是安全的，Bark应用设置内可以查看到 GitHub Run Id。 <br>
+点击可在里面找到当前版本构建所使用的配置文件、编译时的源代码、上传到 App Store 的版本 build 号 等等信息。
+
+同一个版本 build 号仅能上传到 App Store 一次，所以这个号是唯一的。<br>
+可用此号对比从商店下载的 Bark App，如果一致则证明从 App Store 下载的 App 是完全由开源代码构建。
+
+举例： Bark 1.2.9 - 3 <br> 
+https://github.com/Finb/Bark/actions/runs/3327969456
+
+1. 找到编译时的 commit id ，可以查看编译时完整的源码
+2. 查看 .github/workflows/testflight.yaml ，验证所有 Action ，确保 Action 打印的日志未被篡改
+3. 查看 Action Logs https://github.com/Finb/Bark/actions/runs/3327969456/jobs/5503414528
+4. 找到 打包的App ID、Team ID、上传到 App Store 的版本与 build 号等信息。
+5. 下载商店对应版本ipa，比对版本build号是否与日志中一致*（这个号码同一个APP是唯一的，成功上传了就不能再以相同的版本build号上传）*
+
+
+*这里不考虑iOS是否泄露隐私*

docs/tutorial.md

@@ -0,0 +1,57 @@
+## 发送推送
+1. 打开APP，复制测试URL 
+
+<img src="https://wx4.sinaimg.cn/mw2000/003rYfqply1grd1meqrvcj60bi08zt9i02.jpg" width=365 />
+
+2. 修改内容，请求这个URL。<br>
+可以发 get 或者 post 请求 ，请求成功会立即收到推送 
+
+## URL格式
+URL由 推送key、参数 title、参数 body 组成。有下面两种组合方式
+
+```
+/:key/:body 
+/:key/:title/:body 
+```
+
+## 请求方式
+GET 请求参数拼接在 URL 后面，例如：
+```sh
+curl https://api.day.app/your_key/推送内容?group=分组&copy=复制
+```
+POST 请求参数放在请求体中，例如：
+```sh
+curl -X POST https://api.day.app/your_key \
+     -d'body=推送内容&group=分组&copy=复制'
+```
+POST 请求支持JSON，例如：
+```sh
+curl -X "POST" "https://api.day.app/your_key" \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "body": "Test Bark Server",
+  "title": "bleem",
+  "badge": 1,
+  "category": "myNotificationCategory",
+  "sound": "minuet.caf",
+  "icon": "https://day.app/assets/images/avatar.jpg",
+  "group": "test",
+  "url": "https://mritd.com"
+}'
+```
+## 请求参数
+支持的参数列表，具体效果可在APP内预览。
+
+| 参数 | 说明 |
+| ----- | ----------- |
+| title | 推送标题 |
+| body | 推送内容 |
+| level | 推送中断级别。 <br>active：默认值，系统会立即亮屏显示通知<br>timeSensitive：时效性通知，可在专注状态下显示通知。<br>passive：仅将通知添加到通知列表，不会亮屏提醒。 |
+| badge | 推送角标，可以是任意数字 |
+| autoCopy | iOS14.5以下自动复制推送内容，iOS14.5以上需手动长按推送或下拉推送 |
+| copy | 复制推送时，指定复制的内容，不传此参数将复制整个推送内容。 |
+| sound | 可以为推送设置不同的铃声 |
+| icon | 为推送设置自定义图标，设置的图标将替换默认Bark图标。<br>图标会自动缓存在本机，相同的图标 URL 仅下载一次。 |
+| group | 对消息进行分组，推送将按group分组显示在通知中心中。<br>也可在历史消息列表中选择查看不同的群组。 |
+| isArchive | 传 1 保存推送，传其他的不保存推送，不传按APP内设置来决定是否保存。 |
+| url | 点击推送时，跳转的URL ，支持URL Scheme 和 Universal Link |