From 73b5f1b18e505b93277abbf3a78f889ce1034fc4 Mon Sep 17 00:00:00 2001 From: krau <71133316+krau@users.noreply.github.com> Date: Mon, 16 Jun 2025 16:30:45 +0800 Subject: [PATCH] docs: add en translate --- docs/content/en/_index.md | 31 ++++ docs/content/en/contribute/_index.md | 14 ++ docs/content/en/deployment/_index.md | 4 + .../en/deployment/configuration/_index.md | 141 +++++++++++++++++ .../en/deployment/configuration/storages.md | 65 ++++++++ docs/content/en/deployment/installation.md | 145 ++++++++++++++++++ docs/content/en/help/_index.md | 18 +++ docs/content/en/usage/_index.md | 65 ++++++++ 8 files changed, 483 insertions(+) create mode 100644 docs/content/en/_index.md create mode 100644 docs/content/en/contribute/_index.md create mode 100644 docs/content/en/deployment/_index.md create mode 100644 docs/content/en/deployment/configuration/_index.md create mode 100644 docs/content/en/deployment/configuration/storages.md create mode 100644 docs/content/en/deployment/installation.md create mode 100644 docs/content/en/help/_index.md create mode 100644 docs/content/en/usage/_index.md diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md new file mode 100644 index 0000000..58fa52e --- /dev/null +++ b/docs/content/en/_index.md @@ -0,0 +1,31 @@ +--- +title: Introduction +--- + +# Save Any Bot + +![](https://img.shields.io/github/go-mod/go-version/krau/SaveAny-Bot?style=flat-square) +![](https://img.shields.io/github/license/krau/SaveAny-Bot?style=flat-square) +![](https://img.shields.io/github/v/release/krau/SaveAny-Bot?color=cyan&style=flat-square) +![](https://img.shields.io/github/downloads/krau/SaveAny-Bot/total?style=flat-square) + +Save Any Bot is a tool that allows you to save files from Telegram to various storage backends. + +## Features + +- Supports documents/videos/images/stickers... and even Telegraph +- Breaks restrictions on saving files +- Batch download +- Streaming +- Multi-user +- Automatic organization based on storage rules +- Supports multiple storage backends: + - Alist + - Minio (S3 compatible) + - WebDAV + - Telegram (re-upload to specified chat) + - Local disk + +## [Contributors](https://github.com/krau/SaveAny-Bot/graphs/contributors) + +![Contributors](https://contrib.rocks/image?repo=krau/SaveAny-Bot&max=750&columns=20) diff --git a/docs/content/en/contribute/_index.md b/docs/content/en/contribute/_index.md new file mode 100644 index 0000000..97679be --- /dev/null +++ b/docs/content/en/contribute/_index.md @@ -0,0 +1,14 @@ +--- +title: "Contributing" +weight: 20 +--- + +# Contributing + +## Contributing New Storage Backend + +1. Fork this repository and clone it to your local machine. +2. Add the new storage backend type in `pkg/enums/storage/storages.go` and run code generation. +3. Define the storage backend configuration in the `config/storage` directory and add it to `config/storage/factory.go`. +4. Create a new package in the `storage` directory, implement the storage backend, and import it in `storage/storage.go`. +5. Update the documentation to include configuration details for the new storage backend. \ No newline at end of file diff --git a/docs/content/en/deployment/_index.md b/docs/content/en/deployment/_index.md new file mode 100644 index 0000000..46f1cf5 --- /dev/null +++ b/docs/content/en/deployment/_index.md @@ -0,0 +1,4 @@ +--- +title: "Deployment Guide" +weight: 5 +--- diff --git a/docs/content/en/deployment/configuration/_index.md b/docs/content/en/deployment/configuration/_index.md new file mode 100644 index 0000000..360546f --- /dev/null +++ b/docs/content/en/deployment/configuration/_index.md @@ -0,0 +1,141 @@ +--- +title: "Configuration Guide" +--- + +# Configuration Guide + +SaveAnyBot uses the toml format for its configuration files. You can learn more about toml syntax on the [TOML official website](https://toml.io/). + +SaveAnyBot needs to read a `config.toml` file in the working directory as its configuration file. If this file is missing, a default file will be created, and the bot will attempt to load configuration from environment variables. + +Here is an example of a minimal configuration file: + +```toml +[telegram] +token = "1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ" + +[[users]] +# telegram user id +id = 777000 +blacklist = true + +[[storages]] +name = "Local Storage" +type = "local" +enable = true +base_path = "./downloads" +``` + +## Detailed Configuration + +### Global Configuration + +- `stream`: Whether to enable Stream mode, default is `false`. When enabled, the Bot will stream files directly to storage endpoints (if supported), without downloading them locally. +{{< hint warning >}} +Stream mode is very useful for deployment environments with limited disk space, but it also has some drawbacks: +
+ +{{< /hint >}} +- `workers`: Number of tasks to process simultaneously, default is 3. +- `threads`: Number of threads used when downloading files, default is 4. Only effective when Stream mode is not enabled. +- `retry`: Number of retries when a task fails, default is 3. + +### Telegram Configuration + +- `token`: Your Telegram Bot Token, which can be obtained by creating a Bot through [BotFather](https://t.me/botfather). +- `app_id`, `app_hash`: Telegram API ID & Hash, obtained by creating an application at [Telegram API](https://my.telegram.org/apps). Default values will be used if not provided. +- `flood_retry`: Number of retries for flood control, default is 5. +- `rpc_retry`: Number of retries for RPC requests, default is 5. +- `proxy`: Proxy configuration, optional. + - `enable`: Whether to enable the proxy. + - `url`: Proxy address, only supports `socks5://` + +```toml +[telegram] +token = "1234567890:ABCDEFGHIJKLMNOPQRSTUVWXYZ" +app_id = 1025907 +app_hash = "452b0359b988148995f22ff0f4229750" +flood_retry = 5 +rpc_retry = 5 +[telegram.proxy] +enable = false +url = "socks5://127.0.0.1:7890" +``` + +### Storage Endpoints List + +The storage endpoints list is used to define the storage locations supported by the Bot. Each storage endpoint needs to specify a name, type, and related configuration, using the double bracket syntax `[[storages]]`. + +Each storage endpoint requires at least the following fields: + +- `name`: Storage endpoint name, used for identification in the Bot, must be unique. +- `enable`: Whether to enable this storage endpoint, default is `true`. +- `type`: Storage endpoint type, currently supports the following types: + - `local`: Local disk + - `alist`: Alist + - `webdav`: WebDAV + - `minio`: MinIO (compatible with S3 API) + - `telegram`: Upload to Telegram + +Example, this is a configuration that includes local storage and webdav storage: + +```toml +[[storages]] +name = "Local Storage" +type = "local" +enable = true +# Custom configuration for local type storage +base_path = "./downloads" + +[[storages]] +name = "WebDAV" +type = "webdav" +enable = true +# Custom configuration for webdav type storage +url = "https://example.com/webdav" +base_path = "/path/to/webdav" +username = "your_username" +password = "your_password" +``` + +For custom configuration items for all storage endpoints, see [Storage Configuration](./storages) + +### User List + +The user list is used to define access control for storage endpoints. Each user needs to specify a Telegram User ID, defined using the double bracket syntax `[[users]]`. + +- `id`: The user's Telegram User ID +- `storages`: Filtered list of storage endpoints, defined by storage endpoint names, default is whitelist mode (i.e., only allows access to storage endpoints in the list) +- `blacklist`: Whether to enable blacklist mode, default is `false`. If blacklist mode is enabled, the user is allowed to access only storage endpoints that are **not** in the list. + +Example, this is a configuration containing three users: user `123123` can only access local storage, user `456456` can only access storage other than WebDAV, and user `789789` has blacklist mode enabled but no storage endpoints specified, so they can access all storage: + +```toml +[[users]] +id = 123123 +storages = ["Local Storage"] + +[[users]] +id = 456456 +storages = ["WebDAV"] +blacklist = true + +[[users]] +id = 789789 +storages = [] +blacklist = true +``` + +### Miscellaneous + +```toml +no_clean_cache = false # Whether not to clear the cache folder when exiting +# Temporary download folder configuration +[temp] +base_path = "./cache" +``` \ No newline at end of file diff --git a/docs/content/en/deployment/configuration/storages.md b/docs/content/en/deployment/configuration/storages.md new file mode 100644 index 0000000..dccd8c3 --- /dev/null +++ b/docs/content/en/deployment/configuration/storages.md @@ -0,0 +1,65 @@ +--- +title: "Storage Configuration" +--- + +# Storage Configuration + +Please first read the [Configuration Guide](../) to understand the basic format of the configuration file. + +## Alist + +`type=alist` + +Stream mode is not supported. + +```toml +url = "https://alist.example.com" # URL of Alist +username = "your_username" # Username for Alist +password = "your_password" # Password for Alist +base_path = "/path/saveanybot" # Base path in Alist, all files will be stored under this path +token_exp = 3600 # Auto-refresh time for Alist access token, in seconds +token = "your_token" +# Access token for Alist, optional, if not set, username and password will be used for authentication. +# When using token authentication, the token cannot be automatically refreshed +``` + +## Local Disk + +`type=local` + +```toml +base_path = "./downloads" # Base path for local storage, all files will be stored under this path +``` + +## WebDAV +`type=webdav` + +```toml +url = "https://webdav.example.com" # URL of WebDAV +username = "your_username" # Username for WebDAV +password = "your_password" # Password for WebDAV +base_path = "/path/to/webdav" # Base path in WebDAV, all files will be stored under this path +``` + +## MinIO (S3) + +`type=minio` + +```toml +endpoint = "minio.example.com" # Endpoint for MinIO or S3 +access_key_id = "your_access_key_id" # Access key ID for MinIO or S3 +secret_access_key = "your_secret_access_key" # Secret access key for MinIO or S3 +bucket_name = "your_bucket_name" # Bucket name for MinIO or S3 +use_ssl = true # Whether to use SSL, default is true +base_path = "/path/to/minio" # Base path in MinIO, all files will be stored under this path +``` + +## Telegram + +`type=telegram` + +Stream mode is not supported. + +```toml +chat_id = "123456789" # Telegram chat ID, the Bot will send files to this chat +``` \ No newline at end of file diff --git a/docs/content/en/deployment/installation.md b/docs/content/en/deployment/installation.md new file mode 100644 index 0000000..2d8150b --- /dev/null +++ b/docs/content/en/deployment/installation.md @@ -0,0 +1,145 @@ +--- +title: "Installation and Updates" +--- + +# Installation and Updates + +## Deploy from Pre-compiled Files + +Download the binary file for your platform from the [Release](https://github.com/krau/SaveAny-Bot/releases) page. + +Create a `config.toml` file in the extracted directory, refer to the [Configuration Guide](../configuration) to edit the configuration file. + +Run: + +```bash +chmod +x saveany-bot +./saveany-bot +``` + +### Process Monitoring + +{{< tabs "daemon" >}} +{{< tab "systemd (Regular Linux)" >}} + +Create a file /etc/systemd/system/saveany-bot.service and write the following content: + +{{< codeblock >}} +[Unit] +Description=SaveAnyBot +After=systemd-user-sessions.service + +[Service] +Type=simple +WorkingDirectory=/yourpath/ +ExecStart=/yourpath/saveany-bot +Restart=on-failure + +[Install] +WantedBy=multi-user.target +{{< /codeblock >}} + +Enable startup on boot and start the service: + +{{< codeblock >}} +systemctl enable --now saveany-bot +{{< /codeblock >}} + +{{< /tab >}} + +{{< tab "procd (OpenWrt)" >}} + +

Add Boot Autostart Service

+ +Create a file /etc/init.d/saveanybot, refer to wrt_init and modify as needed: + +{{< codeblock >}} +#!/bin/sh /etc/rc.common + +#This is the OpenWRT init.d script for SaveAnyBot + +START=99 +STOP=10 +description="SaveAnyBot" + +WORKING_DIR="/mnt/mmc1-1/SaveAnyBot" +EXEC_PATH="$WORKING_DIR/saveany-bot" +start() { + echo "Starting SaveAnyBot..." + cd $WORKING_DIR + $EXEC_PATH & +} +stop() { + echo "Stopping SaveAnyBot..." + killall saveany-bot +} +reload() { + stop + start +} + +{{< /codeblock >}} + +Set permissions: + +{{< codeblock >}} +chmod +x /etc/init.d/saveanybot +{{< /codeblock >}} + +Then copy the file to /etc/rc.d and rename it to S99saveanybot, also set permissions: + +{{< codeblock >}} +chmod +x /etc/rc.d/S99saveanybot +{{< /codeblock >}} + +

Add Shortcut Commands

+ +Create a file /usr/bin/sabot, refer to wrt_bin and modify as needed. Note that the file encoding here only supports ANSI 936. + +Then set permissions: + +{{< codeblock >}} +chmod +x /usr/bin/sabot +{{< /codeblock >}} + +Usage: sudo sabot start|stop|restart|status|enable|disable + +{{< /tab >}} +{{< /tabs >}} + + +## Deploy Using Docker + +### Docker Compose + +Download the [docker-compose.yml](https://github.com/krau/SaveAny-Bot/blob/main/docker-compose.yml) file, create a new `config.toml` file in the same directory, refer to [config.example.toml](https://github.com/krau/SaveAny-Bot/blob/main/config.example.toml) to edit the configuration file. + +Start: + +```bash +docker compose up -d +``` + +### Docker + +```shell +docker run -d --name saveany-bot \ + -v /path/to/config.toml:/app/config.toml \ + -v /path/to/downloads:/app/downloads \ + ghcr.io/krau/saveany-bot:latest +``` + +## Updates + +Use `upgrade` or `up` to upgrade to the latest version + +```bash +./saveany-bot upgrade +``` + +If you deployed with Docker, use the following commands to update: + +```bash +docker pull ghcr.io/krau/saveany-bot:latest +docker restart saveany-bot +``` \ No newline at end of file diff --git a/docs/content/en/help/_index.md b/docs/content/en/help/_index.md new file mode 100644 index 0000000..f22b539 --- /dev/null +++ b/docs/content/en/help/_index.md @@ -0,0 +1,18 @@ +--- +title: "Frequently Asked Questions" +weight: 15 +--- + +# Frequently Asked Questions + +## Upload to AList shows success but actually fails + +Adjust the upload chunk size in the AList management page, and deploy AList in a more stable network environment to reduce the occurrence of this issue. + +## Bot indicates successful download but files don't show up in AList + +AList caches directory structures. Refer to the documentation to adjust cache expiration time. + +## Docker deployment still can't connect to Telegram despite proxy configuration (client initialization timeout) + +Docker cannot directly access the host network. If you're not familiar with its usage, please set the container to host mode. \ No newline at end of file diff --git a/docs/content/en/usage/_index.md b/docs/content/en/usage/_index.md new file mode 100644 index 0000000..1863448 --- /dev/null +++ b/docs/content/en/usage/_index.md @@ -0,0 +1,65 @@ +--- +title: "Usage" +weight: 10 +--- + +# Usage + +## File Transfer + +The bot accepts two types of messages: files and links. + +Supported links: + +1. Telegram message links, for example: `https://t.me/acherkrau/1097`. **Even if the channel prohibits forwarding and saving, the bot can still download its files.** +2. Telegra.ph article links, the bot will download all images within. + +## Silent Mode + +Use the `/silent` command to toggle silent mode. + +By default, silent mode is off, and the bot will ask you for the save location of each file. + +When silent mode is enabled, the bot will save files directly to the default location without confirmation. + +Before enabling silent mode, you need to set the default save location using the `/storage` command. + + +## Storage Rules + +Allows you to set some redirection rules for the bot when uploading files to storage, for automatic organization of saved files. + +See: #28 + +Currently supported rule types: + +1. FILENAME-REGEX +2. MESSAGE-REGEX + +Basic syntax for adding rules: + +"Rule Type Rule Content Storage Name Path" + +Pay attention to the use of spaces; the bot can only parse correctly formatted syntax. Below is an example of a valid rule command: + +``` +/rule add FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos +``` + +Additionally, if "CHOSEN" is used as the storage name in the rule, it means the file will be stored in the path of the storage selected via button click. + +Rule descriptions: + +### FILENAME-REGEX + +Matches based on filename regex. The rule content must be a valid regular expression, such as: + +``` +FILENAME-REGEX (?i)\.(mp4|mkv|ts|avi|flv)$ MyAlist /videos +``` + +This means files with extensions mp4, mkv, ts, avi, flv will be saved to the /videos directory in the storage named MyAlist (also affected by the `base_path` in the configuration file). + +### MESSAGE-REGEX + +Similar to the above, but matches based on the text content of the message itself. \ No newline at end of file