完善英文文档

Finb · Jan 25, 2025 · cc223e0 · cc223e0
1 parent 1a30eb5
commit cc223e0
Show file tree

Hide file tree

Showing 26 changed files with 267 additions and 461 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -15,10 +15,10 @@
 
 ### 免费
 Bark **2018年7月**上线，至少会维持运营到 **2031年7月** 。*（说不出口“永久”这个词，后续还有需求再续吧）*<br> 
-APP在维持期间，不会有任何形式的收费与广告，各位彦祖放心使用。
+APP在维持期间，不会有任何形式的收费功能与广告，各位彦祖放心使用。
 
 ### 赞助
-目前仅接收 GitHub 赞助，同时非常感谢每一位赞助者<br>
+目前接收 GitHub 赞助、App内内购赞助。非常感谢每一位赞助者！<br>
 赞助者：[https://github.com/sponsors/Finb](https://github.com/sponsors/Finb)
 
 ### 文档

diff --git a/docs/_navbar.md b/docs/_navbar.md
@@ -1,5 +1,3 @@
 * Translations
   - [:cn: 简体中文](/)
-  - [:uk: English](/en-us/)
-  - [:tr: Türkçe](/tr/)
-
+  - [:uk: English](/en-us/)
diff --git a/docs/batch.md b/docs/batch.md
@@ -8,7 +8,7 @@ curl -X "POST" "https://api.day.app/push" \
      -d $'{
   "title": "Title",
   "body": "Body",
-  "sound": "minuet.caf",
+  "sound": "minuet",
   "group": "test",
   "device_keys": ["key1", "key2", ... ]
 }'

diff --git a/docs/en-us/README.md b/docs/en-us/README.md
@@ -28,6 +28,7 @@ Sponsors：[https://github.com/sponsors/Finb](https://github.com/sponsors/Finb)
   - [FAQs](/en-us/faq)
 - **Server**
   - [Deploy](/en-us/deploy)
+  - [Batch Push](/en-us/batch)
   - [Build](/en-us/build)
   - [Certificate](/en-us/cert)
 - [Privacy](/en-us/privacy)
diff --git a/docs/en-us/_coverpage.md b/docs/en-us/_coverpage.md
@@ -5,7 +5,7 @@
 > A privacy-focused, secure and controllable custom notification push tool.
 
 - Free, simple and safe
-- Ready to use
+- Open and go
 
 [GitHub](https://github.com/finb/bark)
 [Get Started](#bark)
diff --git a/docs/en-us/_sidebar.md b/docs/en-us/_sidebar.md
@@ -5,7 +5,7 @@
   - [FAQs](/en-us/faq)
 - **Server**
   - [Deploy](/en-us/deploy)
-  - [Direct Push](/en-us/apns)
+  - [Batch Push](/en-us/batch)
   - [Build](/en-us/build)
   - [Certificate](/en-us/cert)
 - [Privacy](/en-us/privacy)
diff --git a/docs/en-us/apns.md b/docs/en-us/apns.md
diff --git a/docs/en-us/batch.md b/docs/en-us/batch.md
@@ -0,0 +1,35 @@
+
+### Individual Users
+Batch push is only supported with Json requests, and bark-server needs to be updated to v2.1.9. ([https://api.day.app](https://api.day.app) will not be updated to v2.1.9 for now, and currently does not support batch push.)<br />
+Usage:
+```sh
+curl -X "POST" "https://api.day.app/push" \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "title": "Title",
+  "body": "Body",
+  "sound": "minuet",
+  "group": "test",
+  "device_keys": ["key1", "key2", ... ]
+}'
+```
+
+### Middleware Services
+If your service requires sending large volumes of push notifications to users in a timely manner, it is recommended to set up your own server. You can provide a Url Scheme to allow users to change the server with one click.
+
+Url Scheme Example:
+```
+bark://addServer?address=https%3A%2F%2Fapi.day.app
+```
+bark-server has very low configuration requirements. Below are the QPS test results for various configurations on a US West VPS:
+
+| Cores | Ram | Speed |
+| ----- | ----------- |----------- |
+| 1 | 3.75 gb |4,023 p/sec |
+| 4 | 16 gb |21,413 p/sec |
+| 16 | 64 gb |64,516 p/sec |
+| 64 | 256 gb |105,263 p/sec |
+
+If QPS does not exceed 200, you can continue to use the public service（[https://api.day.app](https://api.day.app)）。<br />
+If QPS exceeds 200, it is recommended to set up your own server. In the future, when the public server is under high load, traffic restrictions may be introduced (currently, there are no restrictions).<br />
+If QPS exceeds 3000, it is strongly recommended to set up your own server and add the --max-apns-client-count parameter during deployment. For details, refer to the[Deployment Documentation.](/en-us/deploy)
diff --git a/docs/en-us/build.md b/docs/en-us/build.md
@@ -1 +1,47 @@
-...
+## Download Source Code
+Download the source code from GitHub [bark-server](https://github.com/Finb/bark-server)
+
+or
+```sh
+git clone https://github.com/Finb/bark-server.git
+```
+## Configure Dependencies
+- Golang 1.18+
+- Go Mod (env GO111MODULE=on)
+- Go Mod Proxy (env GOPROXY=https://goproxy.cn)
+- Install [go-task](https://taskfile.dev/installation/) 
+
+## Cross-Compile for All Platforms
+```sh
+task
+```
+
+## Compile for Specific Platforms
+```sh
+task linux_amd64
+task linux_amd64_v3
+```
+
+## Supported Platforms
+
+- 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
diff --git a/docs/en-us/cert.md b/docs/en-us/cert.md
@@ -1 +1,6 @@
-...
+When you need to integrate Bark into your own system or re-implement the backend code, you may need to push certificates.
+
+##### 有效期到: *Permanent*
+##### Key ID：*LH4T9V5U4R*
+##### TeamID：*5U8LBRXG3A*
+##### 下载地址：[AuthKey_LH4T9V5U4R_5U8LBRXG3A.p8](https://github.com/Finb/bark-server/releases/download/v1.0.2/AuthKey_LH4T9V5U4R_5U8LBRXG3A.p8)
diff --git a/docs/en-us/deploy.md b/docs/en-us/deploy.md
@@ -12,23 +12,65 @@ docker-compose up -d
 ```
 ## Manual Deployment
 
-1. Download executable files based on operating system platform. <br> <a href='https://github.com/Finb/bark-server/releases'>https://github.com/Finb/bark-server/releases</a><br>
-Or compile it yourself. <br>
+1. Download the executable file based on your platform:<br> <a href='https://github.com/Finb/bark-server/releases'>https://github.com/Finb/bark-server/releases</a><br>
+Or compile it yourself:<br>
 <a href="https://github.com/Finb/bark-server">https://github.com/Finb/bark-server</a>
 
-2. Run
+2. Run the server:
 ```
 ./bark-server_linux_amd64 -addr 0.0.0.0:8080 -data ./bark-data
 ```
-3. You may need to do
+3. You may need to make the file executable:
 ```
 chmod +x bark-server_linux_amd64
 ```
-Please note that bark-server defaults to using the /data directory to save data. Please make sure that bark-server has permission to read and write the /data directory, or you can use the -data option to specify a directory.
+Note: The bark-server uses the /data directory by default to store data. Ensure it has read/write permissions or specify a custom directory with the -data option.
 
-## Test
+
+## Cloudflare Worker
+[https://github.com/cwxiaos/bark-worker](https://github.com/cwxiaos/bark-worker)
+
+## 测试
 ```
 curl http://0.0.0.0:8080/ping
 ```
-If it returns pong, it means the deployment was successful
+If it returns pong, the deployment is successful.
+
+## High-Volume Push Notifications (For regular users, ignore this. Use only if QPS exceeds 3000)
+If you need to send a large volume of push notifications in a short period, you can configure the bark-server to use multiple APNS Clients for delivery.
+Each Client represents a new connection (which may connect to different APNs servers). Please set this parameter according to the number of CPU cores. The number of Clients cannot exceed the number of CPU cores (if exceeded, it will automatically be set to the current number of CPU cores).
+
+#### Docker
+```
+docker run -dt --name bark -p 8080:8080 -v `pwd`/bark-data:/data finab/bark-server bark-server --max-apns-client-count 4
+```
+
+#### Docker-Compose 
+```yaml
+version: '3.8'
+services:
+  bark-server:
+    image: finab/bark-server
+    container_name: bark-server
+    restart: always
+    volumes:
+      - ./data:/data
+    ports:
+      - "8080:8080"
+    command: bark-server --max-apns-client-count 4
+```
+
+#### Manual Deployment
+```
+./bark-server --addr 0.0.0.0:8080 --data ./bark-data --max-apns-client-count 4
+```
+
+
+## 其他
+
+1. The app sends the <a href="https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1622958-application">DeviceToken</a>to the server.<br>The server sends push requests to Apple’s servers.
+
+2. Server code: <a href='https://github.com/Finb/bark-server'>https://github.com/Finb/bark-server</a><br>
+
+3. App code: <a href="https://github.com/Finb/Bark">https://github.com/Finb/Bark</a>
 
diff --git a/docs/en-us/privacy.md b/docs/en-us/privacy.md
@@ -1 +1,31 @@
-...
+#### How Privacy Can Be Leaked <!-- {docsify-ignore-all} -->
+The route a push notification takes from sending to receiving is as follows:<br>
+Sender <font color='red'> → Server①</font> → Apple APNS Server → Your Device → <font color='red'>Bark APP②</font>.
+
+The two red-marked areas are potential points of privacy leakage <br>
+* The sender does not use HTTPS or uses a public server*（the author can see the request logs）*
+* The Bark App itself is insecure, and the version uploaded to the App Store has been modified.
+
+#### Solving Server-Side Privacy Issues
+* You can use the open-source backend code to [ deploy your own backend service ](/en-us/deploy.md) and enable HTTPS.
+* Use [encrypted push](/en-us/encryption) with a custom key to encrypt the push content.
+
+#### Ensuring the App is Completely Built from Open-Source Code
+To ensure that the App is secure and has not been modified by anyone (including the author), Bark is built by GitHub Actions and then uploaded to the App Store.<br>
+Within the Bark app settings, you can view the GitHub Run Id. Clicking on it will allow you to find the configuration files used for the current version's build, the source code at compile time, the build number of the version uploaded to the App Store, and more.<br>
+
+
+The same build number can only be uploaded to the App Store once, making this number unique.<br>
+You can use this number to compare with the Bark App downloaded from the store. If they match, it proves that the App downloaded from the App Store is completely built from open-source code.
+
+Example: Bark 1.2.9 - 3 <br> 
+https://github.com/Finb/Bark/actions/runs/3327969456
+
+1. Find the commit id at compile time to view the complete source code at compile time.
+2. Check .github/workflows/testflight.yaml to verify all Actions and ensure that the logs printed by the Actions have not been tampered with.
+3. View Action Logs https://github.com/Finb/Bark/actions/runs/3327969456/jobs/5503414528
+4. Find the packaged App ID, Team ID, version, and build number uploaded to the App Store, among other information.
+5. Download the corresponding version ipa from the store and compare whether the build number matches the one in the logs*（this number is unique for the same APP, and once successfully uploaded, it cannot be uploaded again with the same version build number）*
+
+
+*Here, we do not consider whether iOS leaks privacy.*
diff --git a/docs/en-us/tutorial.md b/docs/en-us/tutorial.md
@@ -1 +1,80 @@
-...
+## Sending Push Notifications
+1. Open the APP and copy the test URL. 
+
+<img src="../_media/example.jpg" width=365 />
+
+2. Modify the content and request this URL.<br>
+You can send a GET or POST request. If the request is successful, you will receive the push notification immediately.
+
+## URL Format
+The URL consists of the push key, parameter title, parameter subtitle, and parameter body. There are three combinations:
+
+```
+/:key/:body 
+/:key/:title/:body 
+/:key/:title/:subtitle/:body 
+```
+
+## Request Methods
+##### GET request parameters are appended to the URL, for example:
+```sh
+curl https://api.day.app/your_key/body?group=groupName&copy=copyText
+```
+*When manually appending parameters to the URL, please pay attention to URL encoding issues. 
+
+##### POST request parameters are placed in the request body, for example:
+```sh
+curl -X POST https://api.day.app/your_key \
+     -d'body=body&group=groupName&copy=copyText'
+```
+##### POST requests support JSON, for example:
+```sh
+curl -X "POST" "https://api.day.app/your_key" \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "body": "Test Bark Server",
+  "title": "Test Title",
+  "badge": 1,
+  "sound": "minuet",
+  "icon": "https://day.app/assets/images/avatar.jpg",
+  "group": "test",
+  "url": "https://mritd.com"
+}'
+```
+
+##### JSON request key can be placed in the request body, the URL path must be /push, for example:
+```sh
+curl -X "POST" "https://api.day.app/push" \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "body": "Test Bark Server",
+  "title": "Test Title",
+  "device_key": "your_key"
+}'
+```
+
+## Request Parameters
+List of supported parameters, specific effects can be previewed in the APP.
+
+| Parameter | Description |
+| ----- | ----------- |
+| title | Push title |
+| subtitle | Push subtitle |
+| body | Push content |
+| device_key | Device key |
+| device_keys | Key array, used for batch push |
+| level | Push interruption level.<br>critical: Important alert, will ring even in silent mode <br>active：Default value, the system will immediately light up the screen to display the notification<br>timeSensitive：Time-sensitive notification, can display the notification in focus mode.<br>passive：Only adds the notification to the notification list, will not light up the screen. |
+| volume | Important alert notification volume, value range: 0-10, default is 5 if not passed |
+| badge | Push badge, can be any number |
+| call | Pass "1" to repeat the notification ringtone |
+| autoCopy | Pass "1" to automatically copy the push content on iOS14.5 and below, on iOS14.5 and above, you need to long press or pull down the push to copy |
+| copy | When copying the push, specify the content to copy, if this parameter is not passed, the entire push content will be copied. |
+| sound | Can set different ringtones for the push |
+| icon | Set a custom icon for the push, the set icon will replace the default Bark icon.
+The icon will be automatically cached on the device, the same icon URL will only be downloaded once. |
+| group | Group messages, pushes will be displayed in the notification center by group.<br />
+You can also choose to view different groups in the history message list. |
+| ciphertext | Ciphertext for encrypted push |
+| isArchive | Pass 1 to save the push, pass other values to not save the push, if not passed, it will be decided by the APP settings whether to save. |
+| url | URL to jump to when the push is clicked, supports URL Scheme and Universal Link |
+| action | Pass "none" to prevent a popup when the push is clicked |
diff --git a/docs/index.html b/docs/index.html
@@ -15,15 +15,15 @@
   <script>
     window.$docsify = {
       name: 'Bark',
-      nameLink: '/#/?id=源码',
+      nameLink: '/#/en-us/?id=source-code',
       // 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/', '/tr/'],
+      coverpage: ['/', '/en-us/'],
     }
   </script>
   <!-- Docsify v4 -->