Files

K2cr2O1 7868fb2b41 docs: 更新性能优化文档并修复命令管理器帮助输出

更新性能优化相关文档，详细说明 Python 3.14 JIT 编译器的使用方法和原理，补充与 Mypyc 的互补策略。同时修复命令管理器中帮助信息的输出方式，移除图片发送仅保留文本输出。

调整部署文档结构，明确两种性能优化方案（AOT 和 JIT）的配置方法和适用场景。完善架构文档中关于 JIT 的原理和启用方式说明。

2026-01-13 10:18:48 +08:00

3.5 KiB

Raw Blame History

部署指南

把 Bot 扔到服务器上长期运行，比在自己电脑上跑要多几个步骤。

1. 环境准备

a. 安装 Python 3.14

用3.14。。。

b. 安装依赖

# 切换到项目目录
cd /path/to/your/bot

# 创建虚拟环境 (强烈建议)
python3.14 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

c. 编译核心模块 (可选，但为获得最佳性能强烈建议)

为了最大化性能，我们提供了两层级性能优化方案：

1. Mypyc 编译 (AOT - Ahead-of-Time)

将核心 Python 模块编译成 C 语言扩展。这将大幅提升机器人的响应速度和处理效率。

# 确保你在虚拟环境中
python setup_mypyc.py

该脚本会自动编译 core 和 models 目录下的指定模块。编译后的文件（.pyd 或 .so）会直接生成在源码旁边。

注意: 编译产物是平台相关的（例如，在 Windows 上编译的 .pyd 文件不能在 Linux 上使用）。因此，请务必在你最终部署的服务器环境（例如 Linux）上执行此编译步骤。更多关于 Mypyc 编译的细节，请参考性能优化详解。

2. Python 3.14 JIT (Just-In-Time)

即使不编译核心模块，你也可以通过启用 Python 3.14 自带的 JIT 编译器来获得性能提升。JIT 会在运行时将热点代码编译为机器码。

如何启用: 在启动命令中添加 -X jit 参数，或者在下面的 pm2 配置中添加 JIT 参数。

性能策略:

AOT (Mypyc): 负责静态、类型明确的核心模块（WebSocket、管理器、工具函数）
JIT: 负责动态、灵活的插件代码（B站解析、代码沙箱等业务逻辑）
两者结合: 可获得最佳性能，全面覆盖所有代码路径

2. 使用进程管理器

你想直接 python main.py 然后关掉 SSH？那机器人也跟着停了。必须用进程管理器来守护它。

这里推荐用 pm2，虽然是 Node.js 的工具，但管 Python 程序一样好用。

a. 安装 pm2

# 你需要先装 Node.js 和 npm
npm install pm2 -g

b. 启动 Bot

在项目根目录，创建一个 ecosystem.config.js 文件：

module.exports = {
  apps : [{
    name   : "neobot",
    script : "main.py",
    interpreter: "/path/to/your/bot/venv/bin/python", // 指定虚拟环境里的 python
    args: "-X jit", // 启用 Python 3.14 JIT 编译器
    max_memory_restart: "500M", // 内存超过 500M 自动重启
    env: {
      "PYTHONUNBUFFERED": "1" // 禁用 python 输出缓冲，日志能实时看
    }
  }]
}

然后启动：

pm2 start ecosystem.config.js

c. 常用 pm2 命令

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 部分：

"ws_reverse_servers": [
    {
        "url": "ws://你的服务器IP:8080/onebot/v11/ws",
        "access_token": "你的访问令牌"
    }
]

url: 改成你服务器的 IP 和 main.py 里配置的端口。
access_token: 如果你在 main.py 里设置了 ACCESS_TOKEN，这里要保持一致。

或者你也可以用napcat的webui，不多赘述了。。。

改完后重启 NapCatQQ，Bot 应该就能收到消息了。

3.5 KiB Raw Blame History Unescape Escape