NcatBot 文档

外观

部署指南

约 859 字大约 3 分钟

2026-03-21

Windows 本地开发 + Linux Docker 生产部署 — 从开发到上线的典型工作流。

前提条件

1. 本地开发环境（Windows）

开发模式

ncatbot dev

开发模式特性：

  • DEBUG 日志：输出详细调试信息
  • 热重载：修改插件代码后自动重载，无需重启
  • 适合场景：日常开发、调试插件

生产模式（本地测试）

ncatbot run

与 dev 的区别：日志级别为 INFO，但仍启用热重载。正式部署前建议先本地跑一遍 ncatbot run 确认没有问题。

日志查看

日志文件保存在项目根目录的 logs/ 目录，按日期轮转：

logs/
├── bot.log.2026_03_20
├── bot.log.2026_03_21
└── ...

2. 生产环境（Linux Docker）

为什么用 Docker？

  • 环境隔离：不影响服务器上的其他服务
  • 一键部署：打包好的镜像可以在任何 Linux 服务器运行
  • 易于运维：重启、更新、回滚都很方便

NcatBot-Docker

NcatBot 提供了官方 Docker 部署方案：

📦 仓库地址：https://github.com/ncatbot/NcatBot-Docker

该仓库包含预配置的 Docker Compose 模板，可同时运行 NapCat（QQ 协议端）和 NcatBot（Bot 框架），开箱即用。

连接模式

在 Docker 环境中，NapCat 通常作为独立容器运行。NcatBot 需要使用连接模式（跳过本地安装 NapCat）：

# config.yaml
adapters:
  - type: napcat
    platform: qq
    enabled: true
    config:
      ws_uri: ws://napcat:3001   # Docker 网络中的 NapCat 地址
      ws_token: your_token
      skip_setup: true           # 跳过自动安装 NapCat

详见 NapCat 适配器 — 连接模式。

服务器运行（无 Docker）

如果不使用 Docker，也可以直接在 Linux 服务器上运行：

# 安装
pip install ncatbot5

# 后台运行（推荐用 systemd 管理）
ncatbot run --no-hot-reload

--no-hot-reload 禁用热重载，减少文件监控开销，适合生产环境。

3. Win→Linux 部署工作流

典型的开发部署流程：

┌─────────────────────┐     git push     ┌─────────────────────┐
│   Windows 开发机     │ ──────────────▶ │   Linux 服务器      │
│                     │                  │                     │
│  1. 编写插件代码     │                  │  3. git pull        │
│  2. ncatbot dev 调试 │                  │  4. docker compose │
│     本地验证通过     │                  │     up -d           │
└─────────────────────┘                  └─────────────────────┘

步骤详解

1. 本地开发与测试

# Windows 开发机
ncatbot dev           # 开发调试
ncatbot run           # 上线前验证

2. 推送代码

git add .
git commit -m "feat: 新增 XX 功能"
git push origin main

3. 服务器拉取并部署

# Linux 服务器
cd /opt/my-bot
git pull origin main

# 使用 Docker Compose（推荐）
docker compose up -d --build

# 或直接运行
pip install ncatbot5 --upgrade
ncatbot run --no-hot-reload

4. 运维要点

进程守护

确保 Bot 崩溃后能自动重启：

Docker：docker compose 默认支持 restart: unless-stopped。

systemd（无 Docker）：

# /etc/systemd/system/ncatbot.service
[Unit]
Description=NcatBot Service
After=network.target

[Service]
Type=simple
User=bot
WorkingDirectory=/opt/my-bot
ExecStart=/opt/my-bot/.venv/bin/ncatbot run --no-hot-reload
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl enable ncatbot
sudo systemctl start ncatbot

日志持久化

Docker 环境中，将日志目录挂载到宿主机：

volumes:
  - ./logs:/app/logs

配置安全

  • 不要将 config.yaml 中的 Token 提交到 Git
  • 使用 .gitignore 忽略 config.yaml，提供 config.yaml.example 作为模板
  • 敏感信息优先使用环境变量

延伸阅读

版权归属：huan-yp

许可证：署名 4.0 国际 (CC-BY-4.0)

© 2025-2026 NcatBot