mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-09-11 14:36:58 +00:00
🏗️ change doc theme
This commit is contained in:
yanyongyu
42
website/docs/guide/start/README.md
Normal file
42
website/docs/guide/start/README.md
Normal file
@ -0,0 +1,42 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
id: guide
|
||||
slug: /guide
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 10
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 概览
|
||||
|
||||
<!-- :::tip 提示
|
||||
如果在阅读本文档时遇到难以理解的词汇，请随时查阅 [术语表](../glossary.md) 或使用 [Google 搜索](https://www.google.com/)。
|
||||
::: -->
|
||||
|
||||
:::tip 提示
|
||||
初次使用时可能会觉得这里的概览过于枯燥，可以先简单略读之后直接前往 [安装](./installation.md) 查看安装方法，并进行后续的基础使用教程。
|
||||
:::
|
||||
|
||||
NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的事件进行解析和处理，并以插件化的形式，按优先级分发给事件所对应的事件响应器，来完成具体的功能。
|
||||
|
||||
除了起到解析事件的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制。对于命令处理，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。
|
||||
|
||||
得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理事件的吞吐量有了很大的保障，再配合 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，更是有质的飞跃。
|
||||
|
||||
需要注意的是，NoneBot 仅支持 **Python 3.7.3 以上版本**
|
||||
|
||||
## 特色
|
||||
|
||||
NoneBot2 的驱动框架 `Driver` 以及通信协议 `Adapter` 均可**自定义**，并且可以作为插件进行**替换/添加**！
|
||||
|
||||
- 提供使用简易的脚手架
|
||||
- 提供丰富的官方插件
|
||||
- 提供可添加/替换的驱动以及协议选项
|
||||
- 基于异步 I/O
|
||||
- 同时支持 HTTP 和反向 WebSocket 通信方式
|
||||
- 支持多个机器人账号负载均衡
|
||||
- 提供直观的交互式会话接口
|
||||
- 提供可自定义的权限控制机制
|
||||
- 多种方式渲染要发送的消息内容，使对话足够自然
|
||||
4
website/docs/guide/start/_category_.json
Normal file
4
website/docs/guide/start/_category_.json
Normal file
@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "开始",
|
||||
"position": 1
|
||||
}
|
||||
95
website/docs/guide/start/basic-configuration.md
Normal file
95
website/docs/guide/start/basic-configuration.md
Normal file
@ -0,0 +1,95 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 50
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 基本配置
|
||||
|
||||
到目前为止我们还在使用 NoneBot 的默认行为，在开始编写自己的插件之前，我们先尝试在配置文件上动动手脚，让 NoneBot 表现出不同的行为。
|
||||
|
||||
在上一章节中，我们创建了默认的项目结构，其中 `.env` 和 `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式。
|
||||
|
||||
:::danger 警告
|
||||
请勿将敏感信息写入配置文件并提交至开源仓库！
|
||||
:::
|
||||
|
||||
## .env 文件
|
||||
|
||||
NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。
|
||||
这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。
|
||||
|
||||
`.env` 文件是基础环境配置文件，该文件中的配置项在不同环境下都会被加载，但会被 `.env.{ENVIRONMENT}` 文件中的配置所覆盖。
|
||||
|
||||
现在，我们在 `.env` 文件中写入当前环境信息：
|
||||
|
||||
```bash
|
||||
# .env
|
||||
ENVIRONMENT=dev
|
||||
CUSTOM_CONFIG=common config # 这个配置项在任何环境中都会被加载
|
||||
```
|
||||
|
||||
如你所想，之后 NoneBot 就会从 `.env.dev` 文件中加载环境变量。
|
||||
|
||||
## .env.\* 文件
|
||||
|
||||
NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 进行配置管理，会从 `.env.{ENVIRONMENT}` 文件中获悉环境配置。
|
||||
|
||||
可以在 NoneBot 初始化时指定加载某个环境配置文件: `nonebot.init(_env_file=".env.dev")`，这将忽略你在 `.env` 中设置的 `ENVIRONMENT` 。
|
||||
|
||||
:::warning 提示
|
||||
由于 `pydantic` 使用 JSON 解析配置项，请确保配置项值为 JSON 格式的数据。如：
|
||||
|
||||
```bash
|
||||
list=["123456789", "987654321", 1]
|
||||
test={"hello": "world"}
|
||||
```
|
||||
|
||||
如果配置项值解析失败将作为字符串处理。
|
||||
:::
|
||||
|
||||
示例及说明：
|
||||
|
||||
```bash
|
||||
HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名
|
||||
PORT=8080 # 配置 NoneBot 监听的端口
|
||||
DEBUG=true # 开启 debug 模式 **请勿在生产环境开启**
|
||||
SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户
|
||||
NICKNAME=["awesome", "bot"] # 配置机器人的昵称
|
||||
COMMAND_START=["/", ""] # 配置命令起始字符
|
||||
COMMAND_SEP=["."] # 配置命令分割字符
|
||||
|
||||
# Custom Configs
|
||||
CUSTOM_CONFIG1="config in env file"
|
||||
CUSTOM_CONFIG2= # 留空则从系统环境变量读取，如不存在则为空字符串
|
||||
```
|
||||
|
||||
详细的配置项参考 [Config Reference](../api/config.md) 。
|
||||
|
||||
## 系统环境变量
|
||||
|
||||
如果在系统环境变量中定义了配置，则一样会被读取。
|
||||
|
||||
## bot.py 文件
|
||||
|
||||
配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。
|
||||
|
||||
示例：
|
||||
|
||||
```python
|
||||
# bot.py
|
||||
import nonebot
|
||||
|
||||
nonebot.init(custom_config3="config on init")
|
||||
|
||||
config = nonebot.get_driver().config
|
||||
config.custom_config3 = "changed after init"
|
||||
config.custom_config4 = "new config after init"
|
||||
```
|
||||
|
||||
## 优先级
|
||||
|
||||
`bot.py` 文件( `nonebot.init` ) > 系统环境变量 > `.env` `.env.*` 文件
|
||||
67
website/docs/guide/start/creating-a-project.md
Normal file
67
website/docs/guide/start/creating-a-project.md
Normal file
@ -0,0 +1,67 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 40
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 创建一个完整的项目
|
||||
|
||||
上一章中我们已经运行了一个简单的 NoneBot 实例，在这一章，我们将从零开始一个完整的项目。
|
||||
|
||||
## 目录结构
|
||||
|
||||
可以使用 `nb-cli` 或者自行创建完整的项目目录：
|
||||
|
||||
```bash
|
||||
nb create
|
||||
```
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
AweSome-Bot
|
||||
├── `awesome_bot` _(**或是 src**)_
|
||||
│ └── `plugins`
|
||||
├── `.env` _(**可选的**)_
|
||||
├── `.env.dev` _(**可选的**)_
|
||||
├── `.env.prod` _(**可选的**)_
|
||||
├── .gitignore
|
||||
├── `bot.py`
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── `pyproject.toml`
|
||||
└── README.md
|
||||
:::
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件
|
||||
- `.env`, `.env.dev`, `.env.prod`: 各环境配置文件
|
||||
- `bot.py`: bot 入口文件
|
||||
- `pyproject.toml`: 项目依赖管理文件，默认使用 [poetry](https://python-poetry.org/)
|
||||
|
||||
## 启动 Bot
|
||||
|
||||
:::warning 提示
|
||||
如果您使用如 `VSCode` / `PyCharm` 等 IDE 启动 nonebot，请检查 IDE 当前工作空间目录是否与当前侧边栏打开目录一致。
|
||||
|
||||
- 注意：在二者不一致的环境下可能导致 nonebot 读取配置文件和插件等不符合预期
|
||||
|
||||
:::
|
||||
|
||||
通过 `nb-cli`
|
||||
|
||||
```bash
|
||||
nb run [--file=bot.py] [--app=app]
|
||||
```
|
||||
|
||||
或
|
||||
|
||||
```bash
|
||||
python bot.py
|
||||
```
|
||||
|
||||
:::tip 提示
|
||||
如果在 bot 入口文件内定义了 asgi server， `nb-cli` 将会为你启动**冷重载模式**（当文件发生变动时自动重启 NoneBot 实例）
|
||||
:::
|
||||
96
website/docs/guide/start/getting-started.md
Normal file
96
website/docs/guide/start/getting-started.md
Normal file
@ -0,0 +1,96 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 30
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 开始使用
|
||||
|
||||
一切都安装成功后，你就已经做好了进行简单配置以运行一个最小的 NoneBot 实例的准备工作。
|
||||
|
||||
## 最小实例
|
||||
|
||||
如果你已经按照推荐方式安装了 `nb-cli`，使用它创建一个空项目：
|
||||
|
||||
```bash
|
||||
nb create
|
||||
```
|
||||
|
||||
根据引导进行项目配置，完成后会在当前目录下创建一个项目目录，项目目录内包含 `bot.py`。
|
||||
|
||||
如果未安装 `nb-cli`，使用你最熟悉的编辑器或 IDE，创建一个名为 `bot.py` 的文件，内容如下（这里以 CQHTTP 适配器为例）：
|
||||
|
||||
```python{4,6,7,10}
|
||||
import nonebot
|
||||
from nonebot.adapters.cqhttp import Bot as CQHTTPBot
|
||||
|
||||
nonebot.init()
|
||||
driver = nonebot.get_driver()
|
||||
driver.register_adapter("cqhttp", CQHTTPBot)
|
||||
nonebot.load_builtin_plugins()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
## 解读
|
||||
|
||||
在上方 `bot.py` 中，这几行高亮代码将依次：
|
||||
|
||||
1. 使用默认配置初始化 NoneBot
|
||||
2. 加载 NoneBot 内置的 CQHTTP 协议适配组件
|
||||
`register_adapter` 的第一个参数我们传入了一个字符串，该字符串将会在后文 [配置 CQHTTP 协议端](#配置-cqhttp-协议端-以-qq-为例) 时使用。
|
||||
3. 加载 NoneBot 内置的插件
|
||||
4. 在地址 `127.0.0.1:8080` 运行 NoneBot
|
||||
|
||||
在命令行使用如下命令即可运行这个 NoneBot 实例：
|
||||
|
||||
```bash
|
||||
# nb-cli
|
||||
nb run
|
||||
# 其他
|
||||
python bot.py
|
||||
```
|
||||
|
||||
运行后会产生如下日志：
|
||||
|
||||
```plain
|
||||
09-14 21:02:00 [INFO] nonebot | Succeeded to import "nonebot.plugins.base"
|
||||
09-14 21:02:00 [INFO] nonebot | Running NoneBot...
|
||||
09-14 21:02:00 [INFO] uvicorn | Started server process [1234]
|
||||
09-14 21:02:00 [INFO] uvicorn | Waiting for application startup.
|
||||
09-14 21:02:00 [INFO] uvicorn | Application startup complete.
|
||||
09-14 21:02:00 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
|
||||
```
|
||||
|
||||
## 配置协议端上报
|
||||
|
||||
在 `bot.py` 文件中使用 `register_adapter` 注册协议适配之后即可配置协议端来完成与 NoneBot 的通信，详细配置方法参考：
|
||||
|
||||
- [配置 CQHTTP](./cqhttp-guide.md)
|
||||
- [配置钉钉](./ding-guide.md)
|
||||
- [配置 mirai-api-http](./mirai-guide.md)
|
||||
|
||||
NoneBot 接受的上报地址与 `Driver` 有关，默认使用的 `FastAPI Driver` 所接受的上报地址有：
|
||||
|
||||
- `/{adapter name}/`: HTTP POST 上报
|
||||
- `/{adapter name}/http/`: HTTP POST 上报
|
||||
- `/{adapter name}/ws`: WebSocket 上报
|
||||
- `/{adapter name}/ws/`: WebSocket 上报
|
||||
|
||||
:::warning 注意
|
||||
如果到这一步你没有在 NoneBot 看到连接成功日志，比较常见的出错点包括：
|
||||
|
||||
- NoneBot 监听 `0.0.0.0`，然后在协议端上报配置中填了 `ws://0.0.0.0:8080/***/ws`
|
||||
- 在 Docker 容器内运行协议端，并通过 `127.0.0.1` 访问宿主机上的 NoneBot
|
||||
- 想从公网访问，但没有修改云服务商的安全组策略或系统防火墙
|
||||
- NoneBot 所监听的端口存在冲突，已被其它程序占用
|
||||
- 弄混了 NoneBot 的 `host`、`port` 参数与协议端上报配置中的 `host`、`port` 参数
|
||||
- `ws://` 错填为 `http://`
|
||||
- 协议端或 NoneBot 启动时遭到外星武器干扰
|
||||
|
||||
请尝试重启协议端 NoneBot、更换端口、修改防火墙、重启系统、仔细阅读前面的文档及提示、更新协议端 和 NoneBot 到最新版本等方式来解决。
|
||||
:::
|
||||
124
website/docs/guide/start/installation.md
Normal file
124
website/docs/guide/start/installation.md
Normal file
@ -0,0 +1,124 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 20
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 安装
|
||||
|
||||
## 安装 NoneBot
|
||||
|
||||
:::warning 注意
|
||||
请确保你的 Python 版本 >= 3.7。
|
||||
:::
|
||||
|
||||
:::warning 注意
|
||||
请在安装 NoneBot v2 之前卸载 NoneBot v1
|
||||
|
||||
```bash
|
||||
pip uninstall nonebot
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### (推荐安装方式)通过脚手架安装
|
||||
|
||||
1. (推荐)使用你喜欢的 Python 环境管理工具(如 `poetry`)创建新的虚拟环境
|
||||
2. 使用 `pip` 或 其他包管理工具 安装 `nb-cli`，`nonebot2` 会作为其依赖被一起安装
|
||||
|
||||
```bash
|
||||
pip install nb-cli
|
||||
```
|
||||
|
||||
3. 点个 star 吧
|
||||
|
||||
nonebot2: [](https://github.com/nonebot/nonebot2)
|
||||
|
||||
nb-cli: [](https://github.com/nonebot/nb-cli)
|
||||
|
||||
4. 如果有疑问，可以加群交流(点击链接直达)
|
||||
|
||||
[](https://jq.qq.com/?_wv=1027&k=5OFifDh)
|
||||
|
||||
[](https://t.me/cqhttp)
|
||||
|
||||
### (纯净安装)不使用脚手架
|
||||
|
||||
```bash
|
||||
pip install nonebot2
|
||||
# 也可以通过 poetry 安装
|
||||
poetry add nonebot2
|
||||
```
|
||||
|
||||
如果你需要使用最新的（可能**尚未发布**的）特性，可以直接从 GitHub 仓库安装：
|
||||
|
||||
:::warning 注意
|
||||
直接从 Github 仓库中安装意味着你将使用最新提交的代码，它们并没有进行充分的稳定性测试
|
||||
在任何情况下请不要将其应用于生产环境!
|
||||
:::
|
||||
|
||||
```bash
|
||||
# master分支
|
||||
poetry add git+https://github.com/nonebot/nonebot2.git#master
|
||||
# dev分支
|
||||
poetry add git+https://github.com/nonebot/nonebot2.git#dev
|
||||
```
|
||||
|
||||
或者在克隆 Git 仓库后手动安装：
|
||||
|
||||
```bash
|
||||
git clone https://github.com/nonebot/nonebot2.git
|
||||
cd nonebot2
|
||||
poetry install --no-dev # 推荐
|
||||
pip install . # 不推荐
|
||||
```
|
||||
|
||||
## 安装适配器
|
||||
|
||||
适配器可以通过 `nb-cli` 在创建项目时根据你的选择自动安装，也可以自行使用 `pip` 安装
|
||||
|
||||
```bash
|
||||
pip install <adapter-name>
|
||||
```
|
||||
|
||||
```bash
|
||||
# 列出所有的适配器
|
||||
nb adapter list
|
||||
```
|
||||
|
||||
## 安装插件
|
||||
|
||||
插件可以通过 `nb-cli` 进行安装，也可以自行安装并加载插件。
|
||||
|
||||
```bash
|
||||
# 列出所有的插件
|
||||
nb plugin list
|
||||
# 搜索插件
|
||||
nb plugin search <plugin-name>
|
||||
# 安装插件
|
||||
nb plugin install <plugin-name>
|
||||
```
|
||||
|
||||
如果急于上线 Bot 或想要使用现成的插件，以下插件可作为参考：
|
||||
|
||||
### 官方插件
|
||||
|
||||
- [NoneBot-Plugin-Docs](https://github.com/nonebot/nonebot2/tree/master/packages/nonebot-plugin-docs) 离线文档插件
|
||||
- [NoneBot-Plugin-Test](https://github.com/nonebot/plugin-test) 本地机器人测试前端插件
|
||||
- [NoneBot-Plugin-APScheduler](https://github.com/nonebot/plugin-apscheduler) 定时任务插件
|
||||
- [NoneBot-Plugin-LocalStore](https://github.com/nonebot/plugin-localstore) 本地数据文件存储插件
|
||||
- [NoneBot-Plugin-Sentry](https://github.com/cscs181/QQ-GitHub-Bot/tree/master/src/plugins/nonebot_plugin_sentry) Sentry 在线日志分析插件
|
||||
- [NoneBot-Plugin-Status](https://github.com/cscs181/QQ-GitHub-Bot/tree/master/src/plugins/nonebot_plugin_status) 服务器状态查看插件
|
||||
|
||||
### 其他插件
|
||||
|
||||
还有更多的插件在 [这里](/store.html) 等着你发现～
|
||||
|
||||
## 安装开发环境(可选)
|
||||
|
||||
NoneBot v2 全程使用 `VSCode` 搭配 `Pylance` 的开发环境进行开发，在严格的类型检查下，NoneBot v2 具有完善的类型设计与声明。
|
||||
|
||||
在围绕 NoneBot v2 进行开发时，使用 `VSCode` 搭配 `Pylance` 进行类型检查是非常推荐的。这有利于统一代码风格及避免低级错误的发生。
|
||||
Reference in New Issue
Block a user