# 生产环境部署

将 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
```