docs: 更新文档内容并优化语言风格

重构所有文档内容，使用更简洁直接的语言风格更新架构、插件开发、部署等核心文档优化代码示例和图表说明统一术语和格式规范
2026-01-13 04:09:13 +08:00
parent a6704a55ff
commit 7880f0f928
7 changed files with 361 additions and 421 deletions
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,102 +1,98 @@
 # 部署指南

-当您的机器人开发完成并准备投入生产环境时，本指南将为您提供部署的最佳实践和建议。
+把 Bot 扔到服务器上长期运行，比在自己电脑上跑要多几个步骤。

-## 1. 生产环境配置
+## 1. 环境准备

-与开发环境不同，生产环境要求更高的稳定性和安全性。
+### a. 安装 Python 3.14

-### 创建生产配置文件
+别用太旧的版本，也别用最新的，就用 3.14。怎么装我就不废话了，自己想办法。

-建议您复制一份 `config.toml` 并重命名为 `config.prod.toml`，专门用于生产环境。
+### b. 安装依赖

-**关键修改项**:
+```bash
+# 切换到项目目录
+cd /path/to/your/bot

-*   **数据库与服务地址**:
-    *   确保 `napcat_ws` 和 `redis` 部分的地址、端口和密码都指向您的生产服务器，而不是本地开发环境。
+# 创建虚拟环境 (强烈建议)
+python3.14 -m venv venv
+source venv/bin/activate

-
-
-## 2. 使用进程守护工具
-
-直接在终端中运行 `python main.py` 适用于开发，但在生产环境中，如果终端关闭或程序意外崩溃，机器人就会下线。
-
-为了确保机器人能够 7x24 小时稳定运行，您应该使用**进程守护工具**。
-
-### 推荐工具
-
-*   **PM2 (Node.js)**: 尽管是 Node.js 工具，但 PM2 提供了强大的 Python 进程管理功能，包括崩溃自启、日志管理和性能监控。
-*   **Supervisor (Python)**: 一个纯 Python 实现的进程控制系统，配置简单，稳定可靠。
-*   **Systemd (Linux)**: Linux 系统自带的服务管理器，可以创建系统服务来管理机器人进程。
-
-### 使用 PM2 (示例)
-
-1.  **安装 PM2**:
-    ```bash
-    npm install -g pm2
-    ```
-
-2.  **创建生态系统文件**:
-    在项目根目录创建一个 `ecosystem.config.js` 文件：
-
-    ```javascript
-    // ecosystem.config.js
-    module.exports = {
-      apps: [
-        {
-          name: 'neo-bot', // 应用名称
-          script: 'main.py', // 启动脚本
-          interpreter: '/path/to/your/venv/bin/python', // 指定虚拟环境的 Python 解释器
-          env: {
-            'APP_ENV': 'production', // 设置环境变量
-          },
-        },
-      ],
-    };
-    ```
-    **注意**: 请务必将 `interpreter` 路径修改为您服务器上虚拟环境的实际路径。
-
-3.  **启动应用**:
-    ```bash
-    pm2 start ecosystem.config.js
-    ```
-
-4.  **常用 PM2 命令**:
-    *   `pm2 list`: 查看所有应用状态
-    *   `pm2 logs neo-bot`: 查看日志
-    *   `pm2 restart neo-bot`: 重启应用
-    *   `pm2 stop neo-bot`: 停止应用
-    *   `pm2 startup`: 设置开机自启
-
-## 3. 禁用热重载
-
-热重载功能在开发时非常有用，但在生产环境中会带来不必要的性能开销和潜在的不稳定性。
-
-在部署前，建议您在 `main.py` 中**注释掉**或移除与 `watchdog` 相关的文件监控代码。
-
-**修改 `main.py`**:
-
-```python
-# main.py
-
-async def main():
-    # ...
-    
-    # 生产环境中禁用文件监控
-    # loop = asyncio.get_running_loop()
-    # event_handler = PluginReloadHandler(loop)
-    # observer = Observer()
-    # if os.path.exists(plugin_path):
-    #     observer.schedule(event_handler, plugin_path, recursive=True)
-    #     observer.start()
-    #     logger.info(f"已启动插件热重载监控: {plugin_path}")
-    
-    try:
-        # ...
-    finally:
-        # if observer.is_alive():
-        #     observer.stop()
-        #     observer.join()
+# 安装依赖
+pip install -r requirements.txt
 ```

-遵循以上步骤，您就可以将 NEO Bot 机器人稳定、高效地部署在生产服务器上。
+### c. 编译核心模块 (可选，但强烈建议)
+
+为了极致性能，把核心模块编译成 C 扩展。
+
+```bash
+python setup_mypyc.py build_ext --inplace
+```
+
+## 2. 使用进程管理器
+
+你想直接 `python main.py` 然后关掉 SSH？那机器人也跟着停了。必须用进程管理器来守护它。
+
+这里推荐用 `pm2`，虽然是 Node.js 的工具，但管 Python 程序一样好用。
+
+### a. 安装 pm2
+
+```bash
+# 你需要先装 Node.js 和 npm
+npm install pm2 -g
+```
+
+### b. 启动 Bot
+
+在项目根目录，创建一个 `ecosystem.config.js` 文件：
+
+```javascript
+module.exports = {
+  apps : [{
+    name   : "neobot",
+    script : "main.py",
+    interpreter: "/path/to/your/bot/venv/bin/python", // 指定虚拟环境里的 python
+    max_memory_restart: "500M", // 内存超过 500M 自动重启
+    env: {
+      "PYTHONUNBUFFERED": "1" // 禁用 python 输出缓冲，日志能实时看
+    }
+  }]
+}
+```
+
+然后启动：
+
+```bash
+pm2 start ecosystem.config.js
+```
+
+### c. 常用 pm2 命令
+
+```bash
+pm2 list          # 查看所有进程状态
+pm2 logs neobot   # 查看 neobot 的实时日志
+pm2 restart neobot# 重启 neobot
+pm2 stop neobot   # 停止 neobot
+pm2 delete neobot # 删除 neobot
+```
+
+## 3. 配置 NapCatQQ
+
+最后一步，修改 NapCatQQ 的配置文件，让它把消息推送到你的服务器上。
+
+找到 NapCatQQ 的 `config/onebot11.json` 文件，修改 `ws_reverse_servers` 部分：
+
+```json
+"ws_reverse_servers": [
+    {
+        "url": "ws://你的服务器IP:8080/onebot/v11/ws",
+        "access_token": "你的访问令牌"
+    }
+]
+```
+
+*   `url`: 改成你服务器的 IP 和 `main.py` 里配置的端口。
+*   `access_token`: 如果你在 `main.py` 里设置了 `ACCESS_TOKEN`，这里要保持一致。
+
+改完后重启 NapCatQQ，Bot 应该就能收到消息了。