NeoBot/docs/deployment.md

生产环境部署

将 NEO Bot 部署到服务器长期运行，只需要几个额外的步骤。本指南以 Linux 服务器为例。

1. 环境准备

a. 安装 Python 3.14

在 Linux 服务器上安装 Python 3.14 及开发工具：

# 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. 克隆项目并创建虚拟环境

# 切换到项目目录（或新建）
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 扩展：

# 确保已激活虚拟环境
python setup_mypyc.py build_ext --inplace

注意：编译产物是平台相关的，必须在目标服务器上执行。详见 性能优化。

2. 进程管理

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

推荐使用 systemd（Linux 原生方案）或 pm2。

方案 A：systemd（推荐）

创建 /etc/systemd/system/neobot.service 文件：

[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

然后启动服务：

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 工具），也可以：

npm install pm2 -g

创建 ecosystem.config.js：

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"
  }]
}

启动：

pm2 start ecosystem.config.js
pm2 logs neobot
pm2 save
pm2 startup

3. 配置 OneBot 客户端

Bot 使用 正向 WebSocket 连接，即 Bot 主动连接 OneBot 实现（如 NapCatQQ）。

在 config.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 服务器：

{
    "ws": {
        "enable": true,
        "host": "127.0.0.1",
        "port": 3001
    },
    "token": "your_token_here"
}

然后重启 NapCatQQ，Bot 启动后应该能正常连接。

4. 扩展配置

Redis 连接

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

[redis]
host = "127.0.0.1"
port = 6379
db = 0
password = "redis_password"  # 如果有密码

Docker 代码沙箱（可选）

若要使用 code_py 插件，需要配置 Docker：

[docker]
base_url = "unix:///var/run/docker.sock"  # Linux socket
sandbox_image = "python-sandbox:latest"
timeout = 10
concurrency_limit = 5

5. 监控和日志

查看日志

日志文件位于 logs/ 目录，使用 tail 实时查看：

tail -f logs/bot.log

监控系统资源

使用 systemd 时：

# 查看内存和 CPU 使用
systemctl status neobot

重启 Bot

# systemd
sudo systemctl restart neobot

# pm2
pm2 restart neobot

6. 常见问题

Redis 连接失败

检查 Redis 是否运行：

redis-cli ping  # 应返回 PONG

Playwright 缓存问题

如果更新后图片渲染出现问题，清空 Playwright 缓存：

rm -rf ~/.cache/ms-playwright
playwright install chromium

内存持续增长

检查是否有内存泄漏。在 systemd 中添加内存限制：

[Service]
MemoryLimit=512M
MemoryAccounting=yes