241 lines
4.3 KiB
Markdown
241 lines
4.3 KiB
Markdown
# 生产环境部署
|
||
|
||
将 NEO Bot 部署到服务器长期运行，只需要几个额外的步骤。本指南以 Linux 服务器为例。
|
||
|
||
## 1. 环境准备
|
||
|
||
### a. 安装 Python 3.14
|
||
|
||
在 Linux 服务器上安装 Python 3.14 及开发工具：
|
||
|
||
```bash
|
||
# 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. 编译核心模块（可选但强烈推荐）
|
||
|
||
为了最大化性能，建议在部署环境上编译 Mypyc 扩展：
|
||
|
||
```bash
|
||
# 确保已激活虚拟环境
|
||
python setup_mypyc.py build_ext --inplace
|
||
```
|
||
|
||
**注意**：编译产物是平台相关的，必须在目标服务器上执行。详见 [性能优化](../core-concepts/performance.md)。
|
||
|
||
## 2. 进程管理
|
||
|
||
直接运行 `python main.py` 然后关闭 SSH 会导致 Bot 停止。需要用进程管理器来守护 Bot。
|
||
|
||
推荐使用 `systemd`（Linux 原生方案）或 `pm2`。
|
||
|
||
### 方案 A：systemd（推荐）
|
||
|
||
创建 `/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
|
||
npm install pm2 -g
|
||
```
|
||
|
||
创建 `ecosystem.config.js`：
|
||
|
||
```javascript
|
||
module.exports = {
|
||
apps : [{
|
||
name : "neobot",
|
||
script : "main.py",
|
||
interpreter: "/opt/neobot/venv/bin/python",
|
||
args: "-X jit",
|
||
max_memory_restart: "512M",
|
||
env: {
|
||
"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
|
||
```
|
||
|
||
## 3. 配置 OneBot 客户端
|
||
|
||
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
|
||
```
|
||
|
||
### NapCatQQ 配置示例
|
||
|
||
在 NapCatQQ 的 `config/onebot11.json` 中，启用正向 WebSocket 服务器：
|
||
|
||
```json
|
||
{
|
||
"ws": {
|
||
"enable": true,
|
||
"host": "127.0.0.1",
|
||
"port": 3001
|
||
},
|
||
"token": "your_token_here"
|
||
}
|
||
```
|
||
|
||
然后重启 NapCatQQ，Bot 启动后应该能正常连接。
|
||
|
||
## 4. 扩展配置
|
||
|
||
### Redis 连接
|
||
|
||
确保 Redis 服务运行在可访问的地址，在 `config.toml` 配置：
|
||
|
||
```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
|
||
```
|