diff --git a/docs/guide/基本配置.md b/docs/guide/基本配置.md new file mode 100644 index 00000000..f0ee5cd1 --- /dev/null +++ b/docs/guide/基本配置.md @@ -0,0 +1,142 @@ +# 基本配置 + +到目前为止，炸毛框架的配置文件还没有任何变更，是默认的行为。在本章内容中，将列举出炸毛框架的配置文件的规则和使用。 + +!!! error "警告" + + 因为炸毛框架的全局配置中含有数据库名称和密码以及 access_token 等敏感字段，在使用版本控制软件过程中请不要将将敏感信息写入配置文件并提交至开源仓库！ + +## 全局配置文件 global.php + +框架的全局配置文件在 `config/global.php` 文件中。下面是配置文件的各个选项，请根据自己的需要自行配置。 + +| 配置名称 | 说明 | 默认值 | +| :--------------------------- | ------------------------------------------------ | ---------------------------- | +| `host` | 框架监听的地址 | 0.0.0.0 | +| `port` | 框架监听的端口 | 20001 | +| `http_reverse_link` | 框架开到公网或外部的 HTTP 反代链接 | 见配置文件 | +| `zm_data` | 框架的配置文件、日志文件等文件目录 | `./` 下的 `zm_data/` | +| `debug_mode` | 框架是否启动 debug 模式 | false | +| `crash_dir` | 存放崩溃和运行日志的目录 | `zm_data` 下的 `crash/` | +| `swoole` | 对应 Swoole server 中 set 的参数，参考Swoole文档 | 见子表 `swoole` | +| `light_cache` | 轻量内置 key-value 缓存 | 见字表 `light_cache` | +| `sql_config` | MySQL 数据库连接信息 | 见子表 `sql_config` | +| `redis_config` | Redis 连接信息 | 见子表 `redis_config` | +| `access_token` | OneBot 客户端连接约定的token，留空则无 | 空 | +| `http_header` | HTTP 请求自定义返回的header | 见配置文件 | +| `http_default_code_page` | HTTP服务器在指定状态码下回复的默认页面 | 见配置文件 | +| `init_atomics` | 框架启动时初始化的原子计数器列表 | 见配置文件 | +| `info_level` | 终端日志显示等级（0-4） | 2 | +| `context_class` | 上下文所定义的类，待上下文完善后见对应文档 | `\ZM\Context\Context::class` | +| `static_file_server` | 静态文件服务器配置项 | 见子表 `static_file_server` | +| `server_event_handler_class` | 注册 Swoole Server 事件注解的类列表 | 见配置文件 | +| `command_register_class` | 注册自定义命令行选项指令的类 | 见配置文件 | +| `modules` | 服务器启用的外部第三方和内部插件 | `['onebot' => true]` | + +### 子表 **swoole** + +| 配置名称 | 说明 | 默认值 | +| --------------- | ------------------------------------------------------------ | ----------------------------------- | +| `log_file` | Swoole 的日志文件 | `crash_dir` 下的 `swoole_error.log` | +| `worker_num` | Worker 工作进程数 | 运行框架的主机 CPU 核心数 | +| `dispatch_mode` | 数据包分发策略，见 [文档](https://wiki.swoole.com/#/server/setting?id=dispatch_mode) | 2 | +| `max_coroutine` | 最大协程并发数 | 300000 | + +### 子表 **light_cache** + +| 配置名称 | 说明 | 默认值 | +| -------------------------- | ----------------------------------------------- | ---------------------------- | +| `size` | 最多可以缓存的 k-v 条目数（必须是 2 的 n 次方） | 1024 | +| `max_strlen` | 作为 value 字符串的最大长度 | 16384 | +| `hash_conflict_proportion` | Hash冲突率（越大越好，但是需要的内存更多） | 0.6 | +| `persistence_path` | 持久化的键值对的存储路径 | `zm_data` 下的 `_cache.json` | +| `auto_save_interval` | 持久化的键值对自动保存时间间隔（秒） | 900 | + +### 子表 **sql_config** + +| 配置名称 | 说明 | 默认值 | +| ------------------------ | ------------------------------ | ------------------------------------------------------------ | +| `sql_host` | 数据库地址(留空则不使用数据库) | 空 | +| `sql_port` | 数据库端口 | 3306 | +| `sql_username` | 连接数据库的用户名 | | +| `sql_database` | 要连接的数据库名 | | +| `sql_password` | 数据库连接密码 | | +| `sql_options` | PDO 数据库的 options 参数 | `[PDO::ATTR_STRINGIFY_FETCHES => false,PDO::ATTR_EMULATE_PREPARES => false]` | +| `sql_default_fetch_mode` | PDO 的 fetch 模式 | `PDO::FETCH_ASSOC` | + +### 子表 **redis_config** + +| 配置名称 | 说明 | 默认值 | +| ---------- | ------------------------------------------ | ------ | +| `host` | Redis 服务器地址，留空则启动时不创建连接池 | 空 | +| `port` | Redis 服务器端口 | 6379 | +| `timeout` | Redis 超时时间 | 1 | +| `db_index` | Redis 要连接的数据库 index | 0 | +| `auth` | 认证字符串 | 空 | + +### 子表 static_file_server + +| 配置名称 | 说明 | 默认值 | +| ---------------- | ---------------------- | ------------------------------ | +| `status` | 是否开启静态文件服务器 | false | +| `document_root` | 静态文件的根目录 | `{WORKING_DIR}/resources/html` | +| `document_index` | 默认索引的文件名列表 | `["index.html"]` | + +## 多环境下的配置文件 + +炸毛框架的配置文件模块支持不同环境下的配置文件，主要结构为 `global.{环境}.php`。在一般情况下，炸毛框架默认从教程引导方式根据指令 `vendor/bin/start server` 启动的框架是不带环境控制的。这章将讲述如何根据不同的环境（production / development / staging）来编写配置文件。 + +### 使用环境参数 + +在启动框架时，额外增加参数 `--env` 可以指定当前的环境，从而使用不同的配置文件。现在框架支持以下几种环境： `production`，`staging`，`development`。 + +```bash +vendor/bin/start server --env=development +``` + +### 不同环境配置文件 + +由于框架默认只带有 `global.php` 文件，所以假设你现在需要区分开发环境和生产环境的配置，将 `global.php` 文件复制或改名为 `global.development.php` 或 `global.production.php` 即可。 + +### 优先级 + +如果指定了 `--env` 环境参数：`global.{对应环境}.php` > `global.php`，如果两个配置文件都找不到则报错。 + +如果未指定 `--env` 环境参数：`global.php` > `global.development.php` > `global.staging.php` > `global.production.php`。 + +## 其他自定义配置文件 + +炸毛框架的全局配置文件为 `global.php`，为了让不同的开发者更好的二次开发或者集成更多功能，炸毛框架的配置文件模块也支持自己编写的其他 `*.php` 或 `*.json` 格式的配置文件。例如炸毛框架默认附带了 `file_header.json` 这个配置文件（用来返回各类文件扩展名对应的 `Content-Type` 头参数的表）。 + +使用也非常简单，我们先以 `.json` 格式为例，我们创建一个 `example_a.json` 文件在 `config/` 目录（和 `global.php` 一个文件夹下），并编写自己的任意配置内容： + +```json +{ + "key1": "value1" +} +``` + +在框架中，启动后就会默认加载，使用只需要用以下方式即可： + +```php +use ZM\Config\ZMConfig; # 先 use 再使用！ +$r = ZMConfig::get("example_a", "key1"); # $r == "value1" +``` + +如果需要用到变量或其他动态的内容，可以使用 `.php` 格式的配置文件。这里还是以 `example_a.php` 来举例： + +```php + 这篇为炸毛框架以及环境的部署教程。 + +## 主机手动部署环境 + +### Ubuntu / Debian / Kali + +需要的系统内软件包为：`php php-dev php-mbstring gcc make openssl php-mbstring php-json php-curl php-mysql wget composer` + +下面是一个一键安装的命令行（最小安装，需 root 权限）： + +```bash +apt-get update && apt-get install -y software-properties-common && add-apt-repository ppa:ondrej/php && apt-get update && apt-get install php php-dev php-mbstring gcc make openssl php-mbstring php-json php-curl php-mysql -y && apt-get install wget composer -y && wget https://github.com/swoole/swoole-src/archive/v4.5.7.tar.gz && tar -zxvf v4.5.7.tar.gz && cd swoole-src-4.5.7/ && phpize && ./configure --enable-openssl --enable-mysqlnd && make -j2 && make install && (echo "extension=swoole.so" >> $(php -i | grep "Loaded Configuration File" | awk '{print $5}')) +``` + +### macOS (with Homebrew) + +macOS 系统下的部署相对简单很多，只需要使用 Homebrew 安装以下包和执行安装命令即可 + +!!! note "给 macOS 开发者的提示" + + 因为苹果新的 Apple Sillicon 对 Homebrew 的支持目前仅限于 Rosetta2 转译版， + 所以在使用 M1-based Mac 时出现问题暂时无解。 + 使用以下指令可能会遇到报错等问题，如有疑问可直接使用 Docker 或咨询我（炸毛框架开发者）。 + +```bash +brew install php composer +pecl install swoole +``` + +## 手动部署框架 + +```bash +# 方法1: 从 composer 模板项目快速新建（前提是主机有安装 composer） +composer create-project zhamao/framework-starter 你的项目名称 +# 方法2: 从 composer 引入项目（前提是主机有安装 composer） +mkdir 你的项目名称 && cd 你的项目名称 +composer require zhamao/framework +vendor/bin/start init +``` + +## Docker 部署环境和框架 + +对于不想部署到主机环境的情况，推荐直接使用 Docker。 + +!!! Note "提示" + + 本框架内安装的 Docker 容器包括框架本身和开发者开发的模块代码等，此镜像也可用于其他 Swoole 框架的启动，框架本身是需要从 GitHub 拉取或 composer 拉取的。 + +### Docker 容器拉取和构建 + +```bash +# 自行构建 Swoole 环境容器 +git clone https://github.com/zhamao-robot/zhamao-swoole-docker.git +cd zhamao-swoole-docker/ +docker build -t zm . +# 或者使用 dockerhub 构建好的镜像构建 Swoole 环境容器 +docker pull zmbot/swoole +``` + +### 使用 Docker 容器初始化 composer 和框架代码 + +```bash +# 使用 GitHub 克隆快速开始项目仓库 +git clone https://github.com/zhamao-robot/zhamao-framework-starter.git +cd zhamao-framework-starter +docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zm composer update +# 如果使用 dockerhub 拉取的，把 `zm` 换成 `zmbot/swoole` 即可 +``` + +## 启动框架 + +```bash +# 本地环境拉取 zhamao-framework-starter 后启动方式 +cd zhamao-framework-starter +vendor/bin/start server + +# 使用 Docker 启动 +docker run -it --rm -v $(pwd):/app/ -p 20001:20001 zm vendor/bin/start server # 如果使用 dockerhub 拉取的，把 `zm` 换成 `zmbot/swoole` 即可 +``` + +启动后你会看到和下方类似的初始化内容，表明启动成功了 + +```verilog +$ vendor/bin/start server +host: 0.0.0.0 | port: 20001 +log_level: 2 | version: 2.0.0 +config: global.php | worker_num: 4 +working_dir: /Users/jerry/project/git-project/zhamao-framework + ______ +|__ / |__ __ _ _ __ ___ __ _ ___ + / /| '_ \ / _` | '_ ` _ \ / _` |/ _ \ + / /_| | | | (_| | | | | | | (_| | (_) | +/____|_| |_|\__,_|_| |_| |_|\__,_|\___/ + +[14:27:31] [I] [#0] Worker #0 启动中 +[14:27:31] [I] [#2] Worker #2 启动中 +[14:27:31] [I] [#1] Worker #1 启动中 +[14:27:31] [I] [#3] Worker #3 启动中 +[14:27:31] [S] [#3] Worker #3 已启动 +[14:27:31] [S] [#0] Worker #0 已启动 +[14:27:31] [S] [#2] Worker #2 已启动 +[14:27:31] [S] [#1] Worker #1 已启动 +``` + +单纯运行 炸毛框架 后，如果不部署或安装启动任何机器人客户端的话，仅仅相当于启动了一个 监听 20001 端口的WebSoket + HTTP 服务器。你可以通过浏览器访问：http://127.0.0.1:20001 ，或者你部署到了服务器后需要输入服务器地址。 + +## 使用 IDE 等工具开发代码 + +我们使用文本编辑器进行炸毛框架开发，在使用集成开发环境 **IDEA** 或 **PhpStorm** 时，推荐通过插件市场搜索并安装 **PHP Annotations** 插件以提供注解命名空间自动补全、注解属性代码提醒、注解类跳转等，非常有助于提升开发效率的功能。 \ No newline at end of file diff --git a/docs/guide/快速上手-http.md b/docs/guide/快速上手-http.md new file mode 100644 index 00000000..6e9a1d1d --- /dev/null +++ b/docs/guide/快速上手-http.md @@ -0,0 +1,3 @@ +# 快速上手 - HTTP 服务器篇 + +HTTP 服务器篇暂时先放一放，大家应该主要都是奔着机器人开发来的吧～ \ No newline at end of file diff --git a/docs/guide/快速上手-机器人.md b/docs/guide/快速上手-机器人.md new file mode 100644 index 00000000..9a5674c4 --- /dev/null +++ b/docs/guide/快速上手-机器人.md @@ -0,0 +1,226 @@ +# 快速上手 - 机器人篇 + + + +## 简介 + +看到这里，你已经完成了前面的环境部署，到了最关键的第一步了！ + +一切都安装成功后，你就已经做好了进行简单配置以运行一个最小的 **机器人问答模块** 的准备。 + +炸毛框架和机器人客户端是什么关系呢？炸毛框架就好比我们传统的一系列例如 Spring 框架、ThinkPHP 框架等，是服务端，而机器人客户端是一个 HTTP / WebSocket 客户端，时刻准备着连接到炸毛框架的。 + +## 机器人客户端 + +机器人客户端是炸毛框架以外的程序或软件，目前炸毛框架支持的机器人客户端通信标准为 OneBot 标准，只要你的机器人客户端是 OneBot 标准的，就可以和炸毛框架进行无缝对接。 + +OneBot 机器人部分的选择详情见 [OneBot 实例](/guide/OneBot实例/)。 + +这里以炸毛框架开发过程中使用的 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 来举例进行第一个机器人的配置工作。 + +简要步骤描述为： + +1. 下载 go-cqhttp 对应平台的 [release 文件](https://github.com/Mrs4s/go-cqhttp/releases) +2. 双击 exe 文件或者使用 `./go-cqhttp` 启动 +3. 生成默认配置文件并修改默认配置 + +!!! warning "注意" + + 由于 go-cqhttp 项目还处于开发期，而且配置文件格式也发生了多次变化，但大体内容没有变（比如编写此文档时发布的版本中配置文件格式变成了 `hjson` 取代了原来的 `json`。 + +=== "config.json（旧格式）" + + ``` json hl_lines="2 3 30 31" + { + "uin": 你的QQ号, + "password": "你的密码", + "encrypt_password": false, + "password_encrypted": "", + "enable_db": true, + "access_token": "", + "relogin": { + "enabled": true, + "relogin_delay": 3, + "max_relogin_times": 0 + }, + "ignore_invalid_cqcode": false, + "force_fragmented": true, + "heartbeat_interval": 0, + "http_config": { + "enabled": false, + "host": "0.0.0.0", + "port": 5700, + "timeout": 0, + "post_urls": {} + }, + "ws_config": { + "enabled": false, + "host": "0.0.0.0", + "port": 6700 + }, + "ws_reverse_servers": [ + { + "enabled": true, + "reverse_url": "ws://127.0.0.1:20001/", + "reverse_api_url": "", + "reverse_event_url": "", + "reverse_reconnect_interval": 3000 + } + ], + "post_message_format": "string", + "debug": false, + "log_level": "" + } + ``` + +=== "config.hjson（新格式）" + + ``` json hl_lines="3 5 81 84" + { + // QQ号 + uin: 你的机器人QQ + // QQ密码 + password: "你的QQ密码" + // 是否启用密码加密 + encrypt_password: false + // 加密后的密码, 如未启用密码加密将为空, 请勿随意修改. + password_encrypted: "" + // 是否启用内置数据库 + // 启用将会增加10-20MB的内存占用和一定的磁盘空间 + // 关闭将无法使用 撤回 回复 get_msg 等上下文相关功能 + enable_db: true + // 访问密钥, 强烈推荐在公网的服务器设置 + access_token: "" + // 重连设置 + relogin: { + // 是否启用自动重连 + // 如不启用掉线后将不会自动重连 + enabled: true + // 重连延迟, 单位秒 + relogin_delay: 3 + // 最大重连次数, 0为无限制 + max_relogin_times: 0 + } + // API限速设置 + // 该设置为全局生效 + // 原 cqhttp 虽然启用了 rate_limit 后缀, 但是基本没插件适配 + // 目前该限速设置为令牌桶算法, 请参考: + //https://baike.baidu.com/item/%E4%BB%A4%E7%89%8C%E6%A1%B6%E7%AE%97%E6%B3%95/6597000?fr=aladdin + _rate_limit: { + // 是否启用限速 + enabled: false + // 令牌回复频率, 单位秒 + frequency: 1 + // 令牌桶大小 + bucket_size: 1 + } + // 是否忽略无效的CQ码 + // 如果为假将原样发送 + ignore_invalid_cqcode: false + // 是否强制分片发送消息 + // 分片发送将会带来更快的速度 + // 但是兼容性会有些问题 + force_fragmented: false + // 心跳频率, 单位秒 + // -1 为关闭心跳 + heartbeat_interval: 0 + // HTTP设置 + http_config: { + // 是否启用正向HTTP服务器 + enabled: true + // 服务端监听地址 + host: 0.0.0.0 + // 服务端监听端口 + port: 5700 + // 反向HTTP超时时间, 单位秒 + // 最小值为5，小于5将会忽略本项设置 + timeout: 0 + // 反向HTTP POST地址列表 + // 格式: + // { + // 地址: secret + // } + post_urls: {} + } + // 正向WS设置 + ws_config: { + // 是否启用正向WS服务器 + enabled: true + // 正向WS服务器监听地址 + host: 0.0.0.0 + // 正向WS服务器监听端口 + port: 6700 + } + // 反向WS设置 + ws_reverse_servers: [ + // 可以添加多个反向WS推送 + { + // 是否启用该推送 + enabled: true + // 反向WS Universal 地址 + // 注意 设置了此项地址后下面两项将会被忽略 + reverse_url: ws://127.0.0.1:20001/ + // 反向WS API 地址 + reverse_api_url: "" + // 反向WS Event 地址 + reverse_event_url: "" + // 重连间隔 单位毫秒 + reverse_reconnect_interval: 3000 + } + ] + // 上报数据类型 + // 可选: string array + post_message_format: string + // 是否使用服务器下发的新地址进行重连 + // 注意, 此设置可能导致在海外服务器上连接情况更差 + use_sso_address: false + // 是否启用 DEBUG + debug: false + // 日志等级 + // WebUi 设置 + web_ui: { + // 是否启用 WebUi + enabled: true + // 监听地址 + host: 127.0.0.1 + // 监听端口 + web_ui_port: 9999 + // 是否接收来自web的输入 + web_input: false + } + } + ``` + +其中 ws://127.0.0.1:20001/ 中的 127.0.0.1 和 20001 应分别对应炸毛框架配置的 HOST 和 PORT + +## 第一次对话 + +一旦新的配置文件正确生效之后，所在的控制台（如果正在运行的话）应该会输出类似下面的内容： + +```verilog +[15:26:34] [I] [#2] 机器人 你的QQ号 已连接！ +``` + +表明机器人已成功连接到炸毛框架了！ + +这时，如果你是根据安装教程走下来并且未编写任何模块，炸毛自带一个示例模块，里面含有命令：`你好`，`随机数`。如果你对机器人回复：`你好`，它会回复你 `你好啊，我是由炸毛框架构建的机器人！`。这一历史性的对话标志着你已经成功地运行了炸毛框架，开始了编写更强大的 QQ 机器人的创意之旅！ + +## 编写一个命令 + +让我们转到框架的模块源代码部分，目录是 `src/Module/Example`，文件是 `Hello.php`。我们插入一段这样的代码： + +```php +/** + * @CQCommand("echo") + */ +public function repeat() { + $repeat = ctx()->getArgs(ZM_MATCH_ALL, "请输入你要回复的内容"); + ctx()->reply($repeat); + //return $repeat; // 这样的效果等同于 ctx()->reply() +} +``` + +这样，一个简易的复读机就做好了！回到 QQ 机器人聊天，向机器人发送 `echo 你好啊`，它会回复你 `你好啊`。 + +> 如果你只回复 `echo` 的话，它会先和你进入一个会话状态，并问你 `请输入你要回复的内容`，这时你再次说一些内容例如 `哦豁`，会回复你 `哦豁`。效果和直接输入 `echo 哦豁` 是一致的，这是炸毛框架内的一个封装好的命令参数对话询问功能。有关参数询问功能，请看后面的进阶模块。 +