diff --git a/docs/.vuepress/config.ts b/docs/.vuepress/config.ts index 4c21e46..e758848 100644 --- a/docs/.vuepress/config.ts +++ b/docs/.vuepress/config.ts @@ -1,12 +1,32 @@ import { defineUserConfig, defaultTheme } from "vuepress"; export default defineUserConfig({ + lang: "zh-CN", title: "Nonebot Bison", description: "Docs for Nonebot Bison", theme: defaultTheme({ navbar: [ { text: "主页", link: "/" }, - { text: "部署与使用", link: "/usage/" }, + { + text: "上车", + children: [ + { + text: "安装", + link: "/usage/install.md", + activeMatch: "^/usage/install", + }, + { + text: "简单使用", + link: "/usage/easy-use.md", + activeMatch: "^/usage/easy-use", + }, + { + text: "详细配置", + link: "/usage", + activeMatch: "^/usage$", + }, + ], + }, { text: "开发", link: "/dev/" }, { text: "Github", link: "https://github.com/felinae98/nonebot-bison" }, ], diff --git a/docs/.vuepress/public/images/add-sub.png b/docs/.vuepress/public/images/add-sub.png new file mode 100644 index 0000000..cb475d1 Binary files /dev/null and b/docs/.vuepress/public/images/add-sub.png differ diff --git a/docs/.vuepress/public/images/choose-category.png b/docs/.vuepress/public/images/choose-category.png new file mode 100644 index 0000000..e77d4db Binary files /dev/null and b/docs/.vuepress/public/images/choose-category.png differ diff --git a/docs/.vuepress/public/images/choose-platform.png b/docs/.vuepress/public/images/choose-platform.png new file mode 100644 index 0000000..129c663 Binary files /dev/null and b/docs/.vuepress/public/images/choose-platform.png differ diff --git a/docs/.vuepress/public/images/choose-tag.png b/docs/.vuepress/public/images/choose-tag.png new file mode 100644 index 0000000..67712af Binary files /dev/null and b/docs/.vuepress/public/images/choose-tag.png differ diff --git a/docs/.vuepress/public/images/del-sub.png b/docs/.vuepress/public/images/del-sub.png new file mode 100644 index 0000000..02d80ac Binary files /dev/null and b/docs/.vuepress/public/images/del-sub.png differ diff --git a/docs/.vuepress/public/images/list-sub.png b/docs/.vuepress/public/images/list-sub.png new file mode 100644 index 0000000..77889d1 Binary files /dev/null and b/docs/.vuepress/public/images/list-sub.png differ diff --git a/docs/.vuepress/public/images/uid-parse.png b/docs/.vuepress/public/images/uid-parse.png new file mode 100644 index 0000000..06b23dd Binary files /dev/null and b/docs/.vuepress/public/images/uid-parse.png differ diff --git a/docs/README.md b/docs/README.md index e1c53d8..17b435a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,10 +1,14 @@ --- home: true heroText: Nonebot Bison -tagline: 本bot励志做全泰拉骑车最快的信使 +tagline: 励志做全泰拉骑车最快的信使 actions: - text: 快速部署 - link: /usage/ + link: /usage/install.md + - text: 快速上手 + link: /usage/easy-use.md + - text: 详细了解 + link: /usage features: - title: 拓展性强 details: 没有自己想要的网站？只要简单的爬虫知识就可以给它适配一个新的网站 diff --git a/docs/usage/README.md b/docs/usage/README.md index 3aaedd2..97715d5 100644 --- a/docs/usage/README.md +++ b/docs/usage/README.md @@ -2,105 +2,10 @@ sidebar: auto --- -# 部署和使用 +# 全方位了解 Bison 的自行车 -本节将教你快速部署和使用一个 nonebot-bison，如果你不知道要选择哪种部署方式，推荐使用[docker-compose](#docker-compose-部署-推荐) - -## 部署 - -本项目可以作为单独的 Bot 使用，可以作为 nonebot2 的插件使用 - -### 作为 Bot 使用 - -额外提供自动同意超级用户的好友申请和同意超级用户的加群邀请的功能 - -#### docker-compose 部署 \[推荐\] - -1. 在一个新的目录中下载[docker-compose.yml](https://raw.githubusercontent.com/felinae98/nonebot-bison/main/docker-compose.yml) - 将其中的``改成自己的 QQ 号 - - ```bash - wget https://raw.githubusercontent.com/felinae98/nonebot-bison/main/docker-compose.yml - ``` - -2. 运行配置 go-cqhttp - - ```bash - docker-compose run go-cqhttp - ``` - - 通信方式选择：`3: 反向 Websocket 通信` - 编辑`bot-data/config.yml`，更改下面字段： - - ```yml - account: # 账号相关 - uin: # QQ账号 - password: "" # 密码为空时使用扫码登录 - - message: - post-format: array - - ............ - - servers: - - ws-reverse: - universal: ws://nonebot:8080/onebot/v11/ws/ # 将这个字段写为这个值 - ``` - -3. 登录 go-cqhttp - 再次 - - ```bash - docker-compose run go-cqhttp - ``` - - 参考[go-cqhttp 文档](https://docs.go-cqhttp.org/faq/slider.html#%E6%96%B9%E6%A1%88a-%E8%87%AA%E8%A1%8C%E6%8A%93%E5%8C%85) - 完成登录 - -4. 确定完成登录后，启动 bot： - - ```bash - docker-compose up -d - ``` - -#### docker 部署 - -本项目的 docker 镜像为`felinae98/nonebot-bison`，可以直接 pull 后 run 进行使用， -相关配置参数可以使用`-e`作为环境变量传入 - -#### 直接运行（不推荐） - -可以参考[nonebot 的运行方法](https://docs.nonebot.dev/guide/getting-started.html) -::: danger -直接克隆源代码需要自行编译前端，否则会出现无法使用管理后台等情况。 -::: -::: danger -本项目中使用了 Python 3.10 的语法，如果出现问题，请检查 Python 版本 -::: - -1. 首先安装 poetry：[安装方法](https://python-poetry.org/docs/#installation) -2. clone 本项目，在项目中`poetry install`安装依赖 -3. 安装 yarn，配置 yarn 源（推荐） -4. 在`admin-fronted`中运行`yarn && yarn build`编译前端 -5. 编辑`.env.prod`配置各种环境变量，见[Nonebot2 配置](https://v2.nonebot.dev/docs/appendices/config) -6. 运行`poetry run python bot.py`启动机器人 - -### 作为插件使用 - -本部分假设大家会部署 nonebot2 -::: tip -参考教程 [nonebot2 部署](https://v2.nonebot.dev/docs/quick-start) -参考视频教程 [保姆级新手教学 - Well404](https://www.bilibili.com/video/BV1984y1b7JY) -::: - -#### 手动安装 - -1. 安装 pip 包`nonebot-bison` -2. 在`bot.py`中导入插件`nonebot_bison` - -#### 使用 nb-cli 安装 - -使用`nb-cli`执行：`nb plugin install nonebot_bison` +本节将详细列出 Bison 的使用方法，包括如何配置 Bison，如何使用 Bison 的后台管理网页，如何使用 Bison 的 API 等等 +如果你想要快速上手 Bison，可以前往[简单使用](/usage/easy-use.md) ## 配置 @@ -110,6 +15,7 @@ sidebar: auto - 请注意，在`.env`/`.env.*`中添加的配置项 **不** 需要声明变量类型 ::: +- `BISON_TO_ME`: 是否需要@Bot 或使用 Bot 的 Nickname 来触发 Bison，默认为`True` - `BISON_CONFIG_PATH`: 插件存放配置文件的位置，如果不设定默认为项目目录下的`data`目录 - `BISON_USE_PIC`: 将文字渲染成图片后进行发送，多用于规避风控 - `BISON_BROWSER`: 本插件使用 Chrome 来渲染图片 @@ -155,7 +61,7 @@ sidebar: auto - `BISON_PROXY`: 使用的代理连接，形如`http://:`（可选） - `BISON_UA`: 使用的 User-Agent，默认为 Chrome -- `BISON_SHOW_NETWORK_WARNING`: 是否在日志中输出网络异常，默认开启 +- `BISON_SHOW_NETWORK_WARNING`: 是否在日志中输出网络异常，默认为`True` ## 使用 diff --git a/docs/usage/easy-use.md b/docs/usage/easy-use.md new file mode 100644 index 0000000..a31751f --- /dev/null +++ b/docs/usage/easy-use.md @@ -0,0 +1,148 @@ +--- +sidebar: auto +--- + +# :package: Bison 的第一个包裹 + +本节将教你如何开始使用 Bison 进行基础的使用， +默认你已经完成了[**安装**](/usage/install.md)并且已经成功启动了 Bison + +如果你想要了解更详细的内容，请前往[详细配置](/usage) + +## :wrench: 骑行前检查 + +首先，我们需要检查一下 Bison 的配置是否正确 +在最基础的使用情况下，我们只需要关注少数几个配置的内容 + +1. `COMMAND_START` + 这个配置是 Bison 的命令前缀，如果你的配置中没有设置，那么默认是`''`，也就是没有前缀 + 在本节中，我们假设`COMMAND_START`设置中包含`'/'`，也就是说，我们的命令前缀是`/` + 例如：`COMMAND_START=['', '/']` +2. `BISON_TO_ME` + 是否需要@Bot 或使用 Bot 的 Nickname 来触发 Bison，默认为`True` + 例如： + - `BISON_TO_ME=True` + `@Bot /help` + - `BISON_TO_ME=False` + `/help` +3. `BISON_USE_PIC` + 将文字渲染成图片后进行发送，多用于规避风控, 默认为`False` +4. `BISON_USE_PIC_MERGE`: 是否启用多图片时合并转发（仅限群） + + - `0`: 不启用(默认) + - `1`: 首条消息单独发送，剩余图片合并转发 + - `2`: 所有消息全部合并转发 + + ::: details BISON_USE_PIC_MERGE 配置项示例 + + - 当`BISON_USE_PIC_MERGE=1`时: + ![simple1](/images/forward-msg-simple1.png) + - 当`BISON_USE_PIC_MERGE=2`时: + ![simple1](/images/forward-msg-simple2.png) + + ::: + ::: warning + 启用此功能时，可能会因为待推送图片过大/过多而导致文字消息与合并转发图片消息推送间隔过大(选择模式`1`时)，请谨慎考虑开启。或者选择模式`2`，使图文消息一同合并转发(可能会使消息推送延迟过长) + ::: + +--- + +::: tip 如何进行合理的配置？ + +- 如果要在在 nonebot 中配置需要的**Bison 配置项**，请参考[NoneBot 配置方式](https://v2.nonebot.dev/docs/appendices/config#dotenv-%E9%85%8D%E7%BD%AE%E6%96%87%E4%BB%B6)，在`.env`/`.env.*`文件中写入希望配置的 Bison 配置项 +- 请注意，在`.env`/`.env.*`中添加的配置项 **不** 需要声明变量类型 + +::: + +## :bike: 上车！ + +首先，我们需要给 Bison 指定一份"订单"，让他知道我们想要订阅什么，去哪里获取包裹 +::: tip 不想在群里添加订阅？ +可以，但下述操作要求你是`SUPERUSERS`中的一员 + +- 个人订阅 + 支持私聊添加仅对自己推送的订阅，流程同下 +- 群组订阅 + 支持私聊给某个群聊添加订阅，请私聊 Bison 发送`群管理`命令，Bison 会给你发送一个群列表，你可以选择你想要添加订阅的群聊以及执行的命令，之后的流程同下 + ::: + ::: warning Bison 不理我？ + 在本段中`COMMAND_START`设置中包含了`'/'`，Bot 的`NICKNAME="bison"` + +- 如果出现 bot 不响应的问题，请先排查这个配置 +- 尝试在命令前添加设置了的命令前缀，如`COMMAND_START=['!']`，则尝试使用`!添加订阅` +- `BISON_TO_ME`默认为`True`, 请在命令前 @Bot 或者添加 Bot 的 Nickname : `@Bot 添加订阅` +- Bison 只会响应群主/群管理/SUPERUSERS 的命令，请检查你的群权限等级 + ::: + +## :memo: 添加订阅 + +选择一个群聊作为 Bison 的客户，发送`添加订阅`命令，Bison 会开始订阅流程 +![add sub](/images/add-sub.png) + +## :card_file_box: 选择订阅的平台 + +Bison 会列出所支持的常用平台，你可以选择你想要订阅的平台，也可以回复`全部`来查看所有 Bison 支持的平台 + +在这里，我们选择`weibo`作为我们的订阅平台 +![choose platform](/images/choose-platform.png) + +## :pushpin: 给出需要订阅的目标 + +Bison 会要求你给出你想要订阅的目标，这个目标可以是一个 uid，也可以是特定格式的包含 uid 的链接 +![uid parse](/images/uid-parse.png) +这里发送了包含有 uid 的链接 +:::tip +在`weibo`中该链接必须符合`https://weibo.com/u/`格式 +具体请以[各个平台的支持情况](/usage/#所支持平台的-uid)为准 +::: +当然，你也可以直接向 Bison 发送 uid:`6279793937` + +## :label: 选择需要订阅的类别 + +在给出需要订阅的目标后，Bison 会告诉你该 uid 所对应的用户名，你可以借此确认订阅是否正确。 +接着，如果该平台支持多个类别，Bison 会要求你选择你想要订阅的类别 +![choose category](/images/choose-category.png) +这里选择订阅明日方舟微博的`视频 图文 文字`类别，当该账号在微博发送了视频、图文、文字时，Bison 会将其派送到你的群聊中 + +## :bookmark: 选择需要特定订阅/屏蔽的话题(tag) + +::: tip 什么是话题(tag)？ +Tag 是社交平台中一种常见的功能，它用井号(#)作为前缀，标记关键词，方便用户搜索相关内容。 +例如：`#明日方舟# #每日打卡#（微博、哔哩哔哩） #baracamp（推特）` + +具体的过滤规则参见[Tag 的推送规则](/usage/#tag-的推送规则) +::: +![choose tag](/images/choose-tag.png) +这里选择不特定订阅也不屏蔽话题，即`全部标签` + +## :tada: 订阅成功，开始派送！ + +订阅流程结束后，Bison 会告诉你订阅成功，并且会在群聊中发送一条订阅成功的消息（如上图） +至此，你已经成功订阅了一个明日方舟微博账号，Bison 会在该账号发布新内容时将其派送到你的群聊中 + +## :mag: 查询订阅 + +你可以在任意时刻查询该群的订阅情况，只需要在群里向 Bison 发送`查询订阅`命令即可 +![query sub](/images/list-sub.png) + +## :wastebasket: 删除订阅 + +你可以在任意时刻删除该群的订阅，只需要在群里向 Bison 发送`删除订阅`命令即可 +![delete sub](/images/del-sub.png) + +## :globe_with_meridians: 使用网页管理订阅 + +Bison 提供了一个网页管理订阅的功能，你可以在网页上查看、添加、删除订阅 +如果需要使用，请 **私聊** Bison 发送`后台管理`命令，Bison 会给你发送一个网页链接，在浏览器打开即可进入网页管理订阅的界面 +::: tip 该命令无效？ +`后台管理`命令仅对`SUPERUSERS`的私聊有效 +::: +::: tip Bison 给出的链接无效？ +Bison 所给的链接中的 ip 和 port 是`BISON_OUTER_URL`配置决定的，也就是说 Bison 本身不能获取服务器的 ip 与自身的 port，所以 Bison 给出的链接可能是无效的。你可以在`BISON_OUTER_URL`中设置你的服务器 ip 与 port，或者直接修改 Bison 给出的链接为正确的`http://:/bison/...`来进入网页管理订阅的界面。 + +参见[详细介绍-配置](usage/#配置)的`BISON_OUTER_URL`部分 +::: +::: tip 认证失败？ +:bug: +在浏览器输入网址进入网页时，第一次进入可能会出现 unauthorized，请再输入网址重新进入一次 +::: diff --git a/docs/usage/install.md b/docs/usage/install.md new file mode 100644 index 0000000..d9af565 --- /dev/null +++ b/docs/usage/install.md @@ -0,0 +1,219 @@ +--- +sidebar: auto +--- + +# 让拜松骑上自行车 + +本节将教你部署 nonebot-bison 项目 +想知道如何开始使用请看[简单使用](/usage/easy-use.md)或者[详细配置](/usage) + +## 如何选择？ + +- 没有其他需要，只想使用 Nonebot-Bison？想在 Bison 的基础上再加入其他插件？ + 试试[**作为 Bot 使用**](#作为-bot-使用)！ +- 已有项目，想要增加 Nonebot-Bison？ + 试试[**作为插件使用**](#作为插件使用)！ + +## 作为插件使用 + +本部分假设大家会部署 nonebot2 +::: tip 看看别的！ +参考教程 [nonebot2 部署](https://v2.nonebot.dev/docs/quick-start) +参考视频教程 [保姆级新手教学 - Well404](https://www.bilibili.com/video/BV1984y1b7JY) +::: +::: warning 防止环境冲突！ +建议所有操作都在虚拟环境下进行，推荐使用[`poetry`](https://python-poetry.org/)或者 python 自带的[`venv`](https://docs.python.org/zh-cn/3/library/venv.html) +::: + +### 使用 nb-cli 安装 + +1. 安装`nb-cli` + + ```bash + pip install nb-cli + ``` + +2. 使用`nb-cli`执行在**项目根目录**执行 + +```bash +nb plugin install nonebot-bison +``` + +### 手动安装 + +1. 安装 pip 包`nonebot-bison` + + ```bash + pip install nonebot-bison + ``` + +2. 在`pyproject.toml`中导入插件`nonebot_bison` + 编辑项目根目录下的`pyproject.toml`文件，添加如下内容： + + ```toml + [tool.nonebot] + plugins = [ + ... # 其他插件 + "nonebot_bison", + ] + ``` + +## 作为 Bot 使用 + +::: tip 额外提供 + +- 自动同意超级用户的好友申请 +- 自动同意超级用户的加群邀请 + ::: + +### docker-compose 部署 + +1. 首先创建一个新的空目录 + + ```bash + mkdir nonebot-bison && cd nonebot-bison + ``` + +2. 在目录中下载[docker-compose.yml](https://raw.githubusercontent.com/felinae98/nonebot-bison/main/docker-compose.yml) + 将其中的``改成自己的 QQ 号 + + :::: code-group + ::: code-group-item linux + + ```bash + wget https://raw.githubusercontent.com/felinae98/nonebot-bison/main/docker-compose.yml + ``` + + ::: + ::: code-group-item windows + + ```powershell + Invoke-WebRequest -Uri https://raw.githubusercontent.com/felinae98/nonebot-bison/main/docker-compose.yml -OutFile docker-compose.yml + ``` + + ::: + :::: + + 部分片断： + + ```yml + ... + HOST: 0.0.0.0 # 0.0.0.0代表监听所有地址 + # SUPERUSERS: '[]' #取消该行注释，并将改为自己的QQ号 + BISON_CONFIG_PATH: /data + # BISON_OUTER_URL: 'http://:8080/bison' + #取消上行注释，并将改为你的服务器ip，bison不会自动获取ip + BISON_FILTER_LOG: 'true' + BISON_USE_PIC: 'false' # 如果需要将文字转为图片发送请改为true + ports: + - 8080:8080 # 容器映射的端口，如果需要修改请同时修改上面的BISON_OUTER_URL + ... + ``` + + ::: tip + 想要指定更多配置请参考[详细配置](/usage#配置) + ::: + +3. 运行配置 go-cqhttp + + ```bash + docker-compose run go-cqhttp + ``` + + 通信方式选择：`3: 反向 Websocket 通信`，选择完成后 go-cqhttp 会停止运行 + 接着打开并编辑`bot-data/config.yml`，找到下面字段并更改： + + ```yml + account: # 账号相关 + uin: <填写Bot的QQ号> # QQ账号 + password: "<填写Bot的QQ密码>" # 密码为空时使用扫码登录 + + message: + post-format: array + + ............ + + servers: + - ws-reverse: + universal: ws://nonebot:8080/onebot/v11/ws/ # 更改为这个值 + ``` + +4. 再次登录 go-cqhttp + + ```bash + docker-compose run go-cqhttp + ``` + + ::: tip + 此时可能会需要进行扫码登陆等操作 + 参考[go-cqhttp 文档](https://docs.go-cqhttp.org/faq/slider.html#%E6%96%B9%E6%A1%88a-%E8%87%AA%E8%A1%8C%E6%8A%93%E5%8C%85) + 进行相应处理 + ::: + +5. 成功启动 go-cqhttp 并登录后，启动 bot： + + ```bash + docker-compose up -d + ``` + +### docker 部署 + +Bison 的 docker 镜像为[`felinae98/nonebot-bison`](https://hub.docker.com/r/felinae98/nonebot-bison) + +在为服务器安装了`docker`后可以直接进行使用 + +```bash +docker pull felinae98/nonebot-bison + +docker run -d --name nonebot-bison \ + -e SUPERUSERS='[]' \ + -e BISON_CONFIG_PATH='/data' \ + -e BISON_OUTER_URL='http://:8080/bison' \ + -e BISON_FILTER_LOG='true' \ + -e BISON_USE_PIC='false' \ + -p 8080:8080 \ + felinae98/nonebot-bison +``` + +相关配置参数可以使用`-e`作为环境变量传入 + +### 直接运行 + +可以参考[nonebot 的运行方法](https://docs.nonebot.dev/guide/getting-started.html) +::: danger +直接克隆源代码需要自行编译前端，否则会出现无法使用管理后台等情况。 +::: +::: danger +本项目中使用了 Python 3.10 的语法，如果出现问题，请检查 Python 版本 +::: + +1. 首先安装 poetry：[安装方法](https://python-poetry.org/docs/#installation) +2. clone 本项目，在项目中`poetry install`安装依赖 + + ```bash + git clone https://github.com/felinae98/nonebot-bison.git + cd nonebot-bison + poetry install + ``` + +3. 安装 yarn，配置 yarn 源 + + - 安装[`Node.js`](https://nodejs.org/en/download) + - 安装`yarn` + + ```bash + npm install -g yarn + ``` + +4. 在`admin-fronted`目录中运行`yarn && yarn build`编译前端 + + ```bash + cd admin-frontend + yarn && yarn build + ``` + +5. 编辑`.env.prod`配置各种环境变量，见[Nonebot2 配置](https://v2.nonebot.dev/docs/appendices/config) + :::tip 找不到 .env.prod ？ + `.env.prod`文件在项目根目录下，请确认当前目录为项目根目录 + ::: +6. 运行`poetry run python bot.py`启动 Bot