diff --git a/docs/content/en/_index.md b/docs/content/en/_index.md index 3aaeda0..f56e024 100644 --- a/docs/content/en/_index.md +++ b/docs/content/en/_index.md @@ -11,20 +11,22 @@ title: Introduction Save Any Bot is a tool that allows you to save files from Telegram to various storage backends. -## Features +## 🎯 Features -- Supports documents/videos/images/stickers... and even Telegraph +- Supports documents/videos/images/stickers... and even [Telegraph](https://telegra.ph/) - Breaks restrictions on saving files - Batch download - Streaming - Multi-user - Automatic organization based on storage rules +- Watch specific chats and automatically save messages, with filters +- Write JS parser plugins to save files from almost any website - Supports multiple storage backends: - Alist - S3 - WebDAV - - Telegram (re-upload to specified chat) - Local disk + - Telegram (re-upload to specified chat) ## [Contributors](https://github.com/krau/SaveAny-Bot/graphs/contributors) diff --git a/docs/content/en/contribute/_index.md b/docs/content/en/contribute/_index.md index 97679be..e7f84d5 100644 --- a/docs/content/en/contribute/_index.md +++ b/docs/content/en/contribute/_index.md @@ -5,10 +5,33 @@ weight: 20 # Contributing +Before you start, please fork this repository, clone it locally, and set up your Go development environment. + +Here are some guidelines and suggestions for contributing code. You don't have to strictly follow them, but they help speed up review and merging: + +- **Open an issue before adding new features**, so we can discuss design and implementation details and avoid work that doesn't fit the project design. +- **Use modern development tools**, format your code before committing, and keep the style consistent. +- **Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)**, and avoid vague or overly simple commit messages. + ## 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 +1. Add the new storage backend type in `pkg/enums/storage/storages.go` and run code generation. +2. Define the storage backend configuration in the `config/storage` directory and add it to `config/storage/factory.go`. +3. Create a new package in the `storage` directory, implement the storage backend, and import it in `storage/storage.go`. +4. Update the documentation to include configuration details for the new storage backend. + +## Contributing New Parsers + +You can either implement native parsers in Go (recommended), or write JavaScript-based parser plugins. + +If you use Go: + +1. Create a new package under the `parsers` directory and implement the parser logic. +2. Register the parser in the `init` function in `parsers/parser.go`. + +If you use JavaScript: + +1. Refer to `plugins/example_parser_basic.js` as an example. +2. Create a new `.js` file in the `plugins` directory and implement your parsing logic there. + +Note: Parsers under the `plugins` directory are not embedded into the binary by default. Users must download them manually and place them in the configured plugin directories to enable them. \ No newline at end of file diff --git a/docs/content/en/deployment/configuration/_index.md b/docs/content/en/deployment/configuration/_index.md index a573d89..0b0bc80 100644 --- a/docs/content/en/deployment/configuration/_index.md +++ b/docs/content/en/deployment/configuration/_index.md @@ -44,6 +44,15 @@ Stream mode is very useful for deployment environments with limited disk space, - `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. +- `proxy`: Global proxy configuration. After setting this, all network connections inside the program will try to use this proxy. Optional. + +```toml +stream = false +workers = 3 +threads = 4 +retry = 3 +proxy = "socks5://127.0.0.1:7890" +``` ### Telegram Configuration @@ -54,6 +63,17 @@ Stream mode is very useful for deployment environments with limited disk space, - `proxy`: Proxy configuration, optional. - `enable`: Whether to enable the proxy. - `url`: Proxy address, only supports `socks5://` +- `userbot`: Userbot configuration, optional. + - `enable`: Enable userbot integration. Requires logging in with a user account; you should use your own API ID & Hash when enabling this. + - `session`: Path to the userbot session file, default is `data/usersession.db`. + +{{< hint warning >}} +After enabling userbot integration, the bot can download files from private channels and groups, but there is an unavoidable risk of the account being banned. +
+On the first start after enabling userbot, you need to input phone number, 2FA and verification code in the terminal. +
+If you deploy with Docker, please run the container with `-it` for an interactive environment, then perform the login. +{{< /hint >}} ```toml [telegram] @@ -65,6 +85,9 @@ rpc_retry = 5 [telegram.proxy] enable = false url = "socks5://127.0.0.1:7890" +[telegram.userbot] +enable = false +session = "data/usersession.db" ``` ### Storage Endpoints List @@ -131,6 +154,39 @@ storages = [] blacklist = true ``` +### Events + +Event hooks allow you to run custom commands based on task status while the bot is processing tasks. Currently only arbitrary command execution is supported, configured via `[hook.exec]`. + +Supported event types: + +- `task_before_start`: Before a task starts +- `task_success`: After a task completes successfully +- `task_fail`: After a task fails +- `task_cancel`: After a task is cancelled + +The configured value must be a full shell command line. The bot will execute this command when the event occurs. Example: + +```toml +[hook.exec] +task_before_start = "echo 'task is about to start'" +task_success = "bash /path/to/success_script.sh" +task_fail = "curl -X POST https://example.com/api/notify -d 'task failed'" +task_cancel = "bash /path/to/cancel_script.sh" +``` + +### Parsers + +Parsers give the bot the ability to handle non-Telegram files, such as downloading files from other websites. Configure them via `[parsers]`. + +```toml +[parsers] +plugin_enable = true # Whether to enable parser plugins +plugin_dirs = ["./plugins"] # Plugin directories, can be multiple +``` + +The above settings only control JavaScript-based parser plugins. The bot also has built-in parsers implemented in Go, which are enabled by default. + ### Miscellaneous ```toml diff --git a/docs/content/en/deployment/configuration/storages.md b/docs/content/en/deployment/configuration/storages.md index 33a64a4..6b6ca8f 100644 --- a/docs/content/en/deployment/configuration/storages.md +++ b/docs/content/en/deployment/configuration/storages.md @@ -46,15 +46,29 @@ base_path = "/path/to/webdav" # Base path in WebDAV, all files will be stored un `type=s3` ```toml -endpoint = "s3.example.com" # Endpoint for S3 +endpoint = "s3.example.com" # Endpoint for S3, defaults to AWS S3 endpoint if not set region = "us-east-1" # Region for S3 access_key_id = "your_access_key_id" # Access key ID for S3 secret_access_key = "your_secret_access_key" # Secret access key for S3 bucket_name = "your_bucket_name" # Bucket name for S3 -use_ssl = true # Whether to use SSL, default is true base_path = "/path/to/s3" # Base path in S3, all files will be stored under this path +virtual_host = false # Use virtual-host style URL, default is false ``` +Example of virtual-host-style URL: + +``` +https://your_bucket_name.s3.example.com/path/to/s3/your_file +``` + +Example of path-style URL (when `virtual_host` is false): + +``` +https://s3.example.com/your_bucket_name/path/to/s3/your_file +``` + +If you are using a third-party S3-compatible service, it usually uses path-style URLs. AWS S3 typically uses virtual-host-style URLs. Please refer to your S3-compatible service documentation for details. + ## Telegram `type=telegram` @@ -62,5 +76,8 @@ base_path = "/path/to/s3" # Base path in S3, all files will be stored under this Stream mode is not supported. ```toml -chat_id = "123456789" # Telegram chat ID, the Bot will send files to this chat +chat_id = "123456789" # Telegram chat ID, the bot will send files to this chat +force_file = false # Force sending as file, default is false +skip_large = false # Skip large files, default is false. If enabled, files exceeding Telegram's limit will not be uploaded. +spilt_size_mb = 2000 # Split size in MB, default is 2000 MB (2 GB). Files larger than this will be split into multiple parts (zip format). Ignored when skip_large is true. ``` \ No newline at end of file diff --git a/docs/content/en/deployment/installation.md b/docs/content/en/deployment/installation.md index c21fd38..6d62a43 100644 --- a/docs/content/en/deployment/installation.md +++ b/docs/content/en/deployment/installation.md @@ -4,7 +4,7 @@ title: "Installation and Updates" # Installation and Updates -## Deploy from Pre-compiled Files +## Deploy from Pre-compiled Files (Recommended) Download the binary file for your platform from the [Release](https://github.com/krau/SaveAny-Bot/releases) page. @@ -129,17 +129,41 @@ docker run -d --name saveany-bot \ ghcr.io/krau/saveany-bot:latest ``` +{{< hint info >}} +About Docker image variants +
+ +You can pull different variants by specifying tags, for example: ghcr.io/krau/saveany-bot:micro +
+For more details about the variants, see the Dockerfile in the project root. +{{< /hint >}} + ## Updates -Use `upgrade` or `up` to upgrade to the latest version +If you deployed from pre-compiled binaries, use the following CLI command to update: ```bash -./saveany-bot upgrade +./saveany-bot up ``` +(`upgrade` is also available as an alias.) + If you deployed with Docker, use the following commands to update: +docker: + ```bash docker pull ghcr.io/krau/saveany-bot:latest docker restart saveany-bot +``` + +docker compose: + +```bash +docker compose pull +docker compose restart ``` \ No newline at end of file diff --git a/docs/content/en/usage/_index.md b/docs/content/en/usage/_index.md index 1863448..c9f5e55 100644 --- a/docs/content/en/usage/_index.md +++ b/docs/content/en/usage/_index.md @@ -5,16 +5,17 @@ weight: 10 # Usage +This page introduces some of Save Any Bot's features and basic usage. If you can't find what you need here, please also see the [Configuration Guide](../deployment/configuration) or ask in GitHub [Discussions](https://github.com/krau/SaveAny-Bot/discussions). + ## File Transfer -The bot accepts two types of messages: files and links. +To use the bot's Telegram file saving feature, you need to send or forward the following types of messages to the bot: -Supported links: +1. File or media messages, such as images, videos, documents, etc. +2. 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.** +3. Telegra.ph article links. The bot will download all images in the article. -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 +## Silent Mode (silent) Use the `/silent` command to toggle silent mode. @@ -27,7 +28,7 @@ Before enabling silent mode, you need to set the default save location using the ## Storage Rules -Allows you to set some redirection rules for the bot when uploading files to storage, for automatic organization of saved files. +Storage rules allow you to define redirection rules when the bot uploads files to storage, so that saved files are automatically organized. See: #28 @@ -35,20 +36,21 @@ Currently supported rule types: 1. FILENAME-REGEX 2. MESSAGE-REGEX +3. IS-ALBUM Basic syntax for adding rules: -"Rule Type Rule Content Storage Name Path" +"RuleType RuleContent StorageName 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: +Pay attention to 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. +In addition, if `CHOSEN` is used as the storage name in the rule, it means files will be stored under the path of the storage you selected by clicking the inline button. -Rule descriptions: +Rule types: ### FILENAME-REGEX @@ -58,8 +60,65 @@ Matches based on filename regex. The rule content must be a valid regular expres 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). +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 +Similar to the above, but matches based on the text content of the message itself. + +### IS-ALBUM + +Matches album messages (media groups). Rule content can only be `true` or `false`. + +If the path in the rule uses `NEW-FOR-ALBUM`, the bot will create a new folder for each media group and store all files of that group there. See: https://github.com/krau/SaveAny-Bot/issues/87 + +For example: + +``` +IS-ALBUM true MyWebdav NEW-FOR-ALBUM +``` + +This will save media-group messages to the storage named `MyWebdav`, creating a new folder (generated from the first file) for each album. + +## Watch Chats + +{{< hint warning >}} +This feature requires enabling UserBot integration. +{{< /hint >}} + +You can watch messages in a specific chat and automatically save them to the default storage, following storage rules. You can also add filters so that only matching messages are saved. + +Watch a chat: + +``` +/watch [filter] +``` + +Stop watching: + +``` +/unwatch +``` + +Filter types: + +### msgre + +Regex-match the message text. For example: + +``` +/watch 12345678 msgre:.*hello.* +``` + +This will watch the chat with ID `12345678`, and only save messages whose text contains `hello`. + +## Save Files Outside Telegram + +Besides files on Telegram, the bot can also save files from other websites via JavaScript plugins or built-in parsers. + +> See the [Contributing Parsers](../contribute) document for details. + +Just send links that match the requirements of a parser to the bot. Currently built-in parsers include: + +- Twitter +- Kemono \ No newline at end of file