GithubBackup/SaveAny-Bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Enhance documentation with new features, guidelines, and configuration details

Browse Source
This commit is contained in:
krau
2025-12-19 21:03:58 +08:00
parent 5b8249060d
commit 95f7d5abb5
6 changed files with 208 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/content/en/_index.md
View File

@@ -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)

33
docs/content/en/contribute/_index.md
View File

@@ -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.
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.

56
docs/content/en/deployment/configuration/_index.md
View File

@@ -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.
<br />
On the first start after enabling userbot, you need to input phone number, 2FA and verification code in the terminal.
<br />
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

23
docs/content/en/deployment/configuration/storages.md
View File

@@ -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.
```

30
docs/content/en/deployment/installation.md
View File

@@ -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
<br />
<ul>
<li>Default: Includes all features and dependencies, larger in size. Use this if you don't have special requirements.</li>
<li>micro: Slimmed-down image with some optional dependencies removed, smaller in size.</li>
<li>pico: Minimal image containing only core features, smallest in size.</li>
</ul>
You can pull different variants by specifying tags, for example: <code>ghcr.io/krau/saveany-bot:micro</code>
<br />
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
```

85
docs/content/en/usage/_index.md
View File

@@ -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: <a href="https://github.com/krau/SaveAny-Bot/issues/28" target="_blank">#28</a>
@@ -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.
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 <chat_id/username> [filter]
```
Stop watching:
```
/unwatch <chat_id/username>
```
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