feat(docs): 更新文档，添加项目结构和部署指南，优化快速上手部分

2026-01-29 21:35:20 +08:00
parent 351ed0b063
commit f2bf1e4ca5
6 changed files with 437 additions and 186 deletions
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,107 +1,240 @@
-# 部署指南
+# 生产环境部署

-把 Bot 扔到服务器上长期运行，比在自己电脑上跑要多几个步骤。
+将 NEO Bot 部署到服务器长期运行，只需要几个额外的步骤。本指南以 Linux 服务器为例。

 ## 1. 环境准备

 ### a. 安装 Python 3.14

-用3.14。。。
-
-### b. 安装依赖
+在 Linux 服务器上安装 Python 3.14 及开发工具：

 ```bash
-# 切换到项目目录
-cd /path/to/your/bot
+# Ubuntu/Debian
+sudo apt update
+sudo apt install python3.14 python3.14-venv python3.14-dev gcc

-# 创建虚拟环境 (强烈建议)
+# CentOS/RHEL
+sudo yum install python3.14 python3.14-devel gcc
+```
+
+### b. 克隆项目并创建虚拟环境
+
+```bash
+# 切换到项目目录（或新建）
+cd /opt/neobot
+git clone https://github.com/Fairy-Oracle-Sanctuary/NeoBot.git .
+
+# 创建虚拟环境（强烈建议）
 python3.14 -m venv venv
 source venv/bin/activate

 # 安装依赖
 pip install -r requirements.txt
+playwright install chromium
 ```

-### c. 编译核心模块 (可选，但为获得最佳性能强烈建议)
+### c. 编译核心模块（可选但强烈推荐）

-为了最大化性能，你可以将项目中的核心 Python 模块编译成 C 语言扩展。这将大幅提升机器人的响应速度和处理效率。
+为了最大化性能，建议在部署环境上编译 Mypyc 扩展：

 ```bash
-# 确保你在虚拟环境中
-python setup_mypyc.py
+# 确保已激活虚拟环境
+python setup_mypyc.py build_ext --inplace
 ```

-该脚本会自动编译 `core` 和 `models` 目录下的指定模块。编译后的文件（`.pyd` 或 `.so`）会直接生成在源码旁边。
+**注意**：编译产物是平台相关的，必须在目标服务器上执行。详见 [性能优化](../core-concepts/performance.md)。

-> **注意**: 编译产物是平台相关的（例如，在 Windows 上编译的 `.pyd` 文件不能在 Linux 上使用）。因此，**请务必在你最终部署的服务器环境（例如 Linux）上执行此编译步骤**。更多关于 Mypyc 编译的细节，请参考 [性能优化详解](core-concepts/performance.md)。
+## 2. 进程管理

-## 2. 使用进程管理器
+直接运行 `python main.py` 然后关闭 SSH 会导致 Bot 停止。需要用进程管理器来守护 Bot。

-你想直接 `python main.py` 然后关掉 SSH？那机器人也跟着停了。必须用进程管理器来守护它。
+推荐使用 `systemd`（Linux 原生方案）或 `pm2`。

-这里推荐用 `pm2`，虽然是 Node.js 的工具，但管 Python 程序一样好用。
+### 方案 A：systemd（推荐）

-### a. 安装 pm2
+创建 `/etc/systemd/system/neobot.service` 文件：
+
+```ini
+[Unit]
+Description=NEO Bot Service
+After=network.target redis.service
+
+[Service]
+Type=simple
+User=bot
+WorkingDirectory=/opt/neobot
+ExecStart=/opt/neobot/venv/bin/python -X jit main.py
+Restart=always
+RestartSec=10
+StandardOutput=journal
+StandardError=journal
+Environment="PYTHONUNBUFFERED=1"
+
+[Install]
+WantedBy=multi-user.target
+```
+
+然后启动服务：
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable neobot
+sudo systemctl start neobot
+
+# 查看状态
+sudo systemctl status neobot
+
+# 查看日志
+sudo journalctl -u neobot -f
+```
+
+### 方案 B：pm2
+
+如果你习惯用 pm2（Node.js 工具），也可以：

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

-### b. 启动 Bot
-
-在项目根目录，创建一个 `ecosystem.config.js` 文件：
+创建 `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 自动重启
+    interpreter: "/opt/neobot/venv/bin/python",
+    args: "-X jit",
+    max_memory_restart: "512M",
    env: {
-      "PYTHONUNBUFFERED": "1" // 禁用 python 输出缓冲，日志能实时看
-    }
+      "PYTHONUNBUFFERED": "1"
+    },
+    error_file: "./logs/pm2-error.log",
+    out_file: "./logs/pm2-out.log"
  }]
 }
 ```

-然后启动：
+启动：

 ```bash
 pm2 start ecosystem.config.js
+pm2 logs neobot
+pm2 save
+pm2 startup
 ```

-### c. 常用 pm2 命令
+## 3. 配置 OneBot 客户端

-```bash
-pm2 list          # 查看所有进程状态
-pm2 logs neobot   # 查看 neobot 的实时日志
-pm2 restart neobot# 重启 neobot
-pm2 stop neobot   # 停止 neobot
-pm2 delete neobot # 删除 neobot
+Bot 使用 **正向 WebSocket 连接**，即 Bot 主动连接 OneBot 实现（如 NapCatQQ）。
+
+在 `config.toml` 中配置：
+
+```toml
+[napcat_ws]
+# OneBot 客户端的 WebSocket 服务地址
+uri = "ws://127.0.0.1:3001"
+token = "your_token_here"
+reconnect_interval = 5
 ```

-## 3. 配置 NapCatQQ
+### NapCatQQ 配置示例

-最后一步，修改 NapCatQQ 的配置文件，让它把消息推送到你的服务器上。
-
-找到 NapCatQQ 的 `config/onebot11.json` 文件，修改 `ws_reverse_servers` 部分：
+在 NapCatQQ 的 `config/onebot11.json` 中，启用正向 WebSocket 服务器：

 ```json
-"ws_reverse_servers": [
-    {
-        "url": "ws://你的服务器IP:8080/onebot/v11/ws",
-        "access_token": "你的访问令牌"
-    }
-]
+{
+    "ws": {
+        "enable": true,
+        "host": "127.0.0.1",
+        "port": 3001
+    },
+    "token": "your_token_here"
+}
 ```

-*   `url`: 改成你服务器的 IP 和 `main.py` 里配置的端口。
-*   `access_token`: 如果你在 `main.py` 里设置了 `ACCESS_TOKEN`，这里要保持一致。
+然后重启 NapCatQQ，Bot 启动后应该能正常连接。

+## 4. 扩展配置

-或者你也可以用napcat的webui，不多赘述了。。。
+### Redis 连接

+确保 Redis 服务运行在可访问的地址，在 `config.toml` 配置：

-改完后重启 NapCatQQ，Bot 应该就能收到消息了。
+```toml
+[redis]
+host = "127.0.0.1"
+port = 6379
+db = 0
+password = "redis_password"  # 如果有密码
+```
+
+### Docker 代码沙箱（可选）
+
+若要使用 code_py 插件，需要配置 Docker：
+
+```toml
+[docker]
+base_url = "unix:///var/run/docker.sock"  # Linux socket
+sandbox_image = "python-sandbox:latest"
+timeout = 10
+concurrency_limit = 5
+```
+
+## 5. 监控和日志
+
+### 查看日志
+
+日志文件位于 `logs/` 目录，使用 `tail` 实时查看：
+
+```bash
+tail -f logs/bot.log
+```
+
+### 监控系统资源
+
+使用 systemd 时：
+
+```bash
+# 查看内存和 CPU 使用
+systemctl status neobot
+```
+
+### 重启 Bot
+
+```bash
+# systemd
+sudo systemctl restart neobot
+
+# pm2
+pm2 restart neobot
+```
+
+## 6. 常见问题
+
+### Redis 连接失败
+
+检查 Redis 是否运行：
+
+```bash
+redis-cli ping  # 应返回 PONG
+```
+
+### Playwright 缓存问题
+
+如果更新后图片渲染出现问题，清空 Playwright 缓存：
+
+```bash
+rm -rf ~/.cache/ms-playwright
+playwright install chromium
+```
+
+### 内存持续增长
+
+检查是否有内存泄漏。在 systemd 中添加内存限制：
+
+```ini
+[Service]
+MemoryLimit=512M
+MemoryAccounting=yes
+```