feat: add docs

.github/workflows/docs.yml

@@ -0,0 +1,22 @@
+name: Deploy Docs
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - uses: actions/cache@v4
+        with:
+          key: ${{ github.ref }}
+          path: .cache
+      - run: pip install mkdocs-material
+      - run: cd docs && mkdocs gh-deploy --force

config.example.toml

@@ -2,6 +2,7 @@
 workers = 4 # 同时下载文件数
 retry = 3   # 下载失败重试次数
 threads = 4 # 单个任务下载最大线程数
+stream = false # 使用stream模式, 详情请查看文档
 
 [telegram]
 # Bot Token

docs/docs/depoly.md

@@ -0,0 +1,94 @@
+# 部署指南
+
+## 从二进制文件部署
+
+在 [Release](https://github.com/krau/SaveAny-Bot/releases) 页面下载对应平台的二进制文件.
+
+在解压后目录新建 `config.toml` 文件, 参考 [config.example.toml](./config.example.toml) 编辑配置文件.
+
+运行:
+
+```bash
+chmod +x saveany-bot
+./saveany-bot
+```
+
+### 添加为 systemd 服务
+
+创建文件 `/etc/systemd/system/saveany-bot.service` 并写入以下内容:
+
+```
+[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
+```
+
+设为开机启动并启动服务:
+
+```bash
+systemctl enable --now saveany-bot
+```
+
+### 为OpenWrt及衍生系统添加开机自启动服务
+
+创建文件 ` /etc/init.d/saveanybot` ，参考[saveanybot](./docs/saveanybot)自行修改.
+
+`chmod +x /etc/init.d/saveanybot`
+
+完成后，将文件复制到 `/etc/rc.d`并重命名为`S99saveanybot`.
+
+`chmod +x /etc/rc.d/S99saveanybot`
+
+### 为OpenWrt及衍生系统添加快捷指令
+
+创建文件` /usr/bin/sabot` ，参考[sabot](./docs/sabot)自行配置修改，注意此处文件编码仅支持 ANSI 936 .
+
+`chmod +x /usr/bin/sabot`
+
+之后，终端输入`sabot start|stop|restart|status|enable|disable`即可.
+
+
+## 使用 Docker 部署
+
+### Docker Compose
+
+下载 [docker-compose.yml](./docker-compose.yml) 文件, 在同目录下新建 `config.toml` 文件, 参考 [config.example.toml](./config.example.toml) 编辑配置文件.
+
+启动:
+
+```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
+```
+
+## 更新
+
+使用 `upgrade` 或 `up` 升级到最新版
+
+```bash
+./saveany-bot upgrade
+```
+
+如果是 Docker 部署, 使用以下命令更新:
+
+```bash
+docker pull ghcr.io/krau/saveany-bot:latest
+docker restart saveany-bot
+```

docs/docs/faq.md

@@ -0,0 +1,20 @@
+# 常见问题
+
+## 上传 alist 失败也会显示成功
+
+这是 alist 的上传实现导致的问题, 上传到 alist 的文件实际上会被 alist 暂存在本地, 在客户端上传结束后 alist 就返回成功, 然后 alist 会在后台将文件上传到对应的存储.
+
+目前 bot 是根据 alist 的返回判断是否成功, 无法获知 alist 的后台上传任务是否成功.
+
+在 alist 管理页面适当调整上传分片大小, 为 alist 使用更稳定的网络环境部署, 都可以减少这种情况的发生.
+
+## Bot 提示下载成功但是 alist 未显示
+
+检查 alist 后台 > 任务 > 上传 中对应的上传任务的状态, 如果任务状态为成功但目录中不显示, 是由于 alist 缓存了目录结构, 参考文档可以调整缓存时间
+
+https://alist.nn.ci/zh/guide/drivers/common.html#缓存过期
+
+## docker部署配置了代理后仍无法连接 telegram (初始化客户端超时)
+
+docker 不能直接访问宿主机网络, 如果你不熟悉其用法, 请将容器设为 host 模式:
+

docs/docs/help.md

@@ -0,0 +1,35 @@
+# 使用帮助
+
+## 保存文件
+
+Bot 接受两种消息: 文件和链接.
+
+目前, 链接仅支持公开频道 (具有用户名) 的链接, 例如: `https://t.me/acherkrau/1097`.
+
+**即使频道禁止了转发和保存, Bot 依然可以下载其文件.**
+
+## 静默模式 (silent)
+
+使用 `/silent` 命令可以开关静默模式.
+
+默认情况下不开启静默模式, Bot 会询问你每个文件的保存位置.
+
+开启静默模式后, Bot 会直接保存文件到默认位置, 无需确认.
+
+在开启静默模式之前, 需要使用 `/storage` 命令设置默认保存位置.
+
+## Stream 模式
+
+在配置文件中将 `stream` 设置为 `true` 可以开启 Stream 模式.
+
+未开启时, Bot 处理任务分为两步: 下载和上传. Bot 会将文件暂存到本地, 然后上传到对应存储位置, 最后删除本地文件.
+
+开启后, Bot 将直接将文件流式传输到存储端, 不需要下载到本地.
+
+该功能对于硬盘空间有限的部署环境十分有用, 然而相较于普通模式也具有一些弊端:
+
+- 无法使用多线程从 telegram 下载文件, 速度较慢.
+- 网络不稳定时, 任务失败率高.
+- 无法在中间层对文件进行处理, 例如自动文件类型识别.
+
+虽然目前 Bot 适配的所有存储端 (Alist, 本地磁盘, Webdav) 都支持 Stream 模式, 但今后可能会有不支持的存储端, 此时即使开启 Stream 模式, Bot 也会自动切换到普通模式.

docs/docs/index.md

@@ -0,0 +1,7 @@
+# SaveAnyBot 文档
+
+SaveAnyBot 是一个可以保存 Telegram 上的文件到云存储的机器人, 就像 PikPak Bot 一样.
+
+不同的是, SaveAnyBot 提供更灵活的存储端选择, 并实现一些更强大的功能.
+
+本项目以 AGPL-3.0 协议开源, 请遵守协议使用.

docs/mkdocs.yml

@@ -0,0 +1,33 @@
+site_name: SaveAnyBot 官方文档
+site_author: Krau
+site_description: SaveAnyBot 是一个可以保存 Telegram 上的文件到多种云存储的机器人, 本文档将帮助你了解如何部署和使用它.
+repo_name: krau/saveany-bot
+repo_url: https://github.com/krau/saveany-bot
+copyright: CC BY-NC-SA 4.0
+theme:
+  name: material
+  language: zh
+  highlightjs: true
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: 切换主题
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      toggle:
+        icon: material/brightness-7
+        name: 暗色模式
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: blue grey
+      toggle:
+        icon: material/brightness-4
+        name: 亮色模式
+
+nav:
+  - index.md
+  - deploy.md
+  - help.md
+  - faq.md