请先选择你的 Linux 发行版，下方会自动显示对应的安装命令。建议在全新系统上执行，安装完成后可用 docker --version 验证。

# 更新软件源
sudo apt-get update

# 安装依赖
sudo apt-get install -y ca-certificates curl gnupg

# 添加 Docker 官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# 添加 Docker 软件源（Debian 用户请将 ubuntu 改为 debian）
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装 Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
docker --version

# 安装 yum-utils
sudo yum install -y yum-utils

# 添加 Docker 软件源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装 Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
docker --version

# 安装 dnf-plugins-core
sudo dnf -y install dnf-plugins-core

# 添加 Docker 软件源
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

# 安装 Docker Engine
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
docker --version

# 更新系统并安装 Docker
sudo pacman -Syu --noconfirm docker docker-compose

# 启动并设置开机自启
sudo systemctl enable --now docker

# 验证安装
docker --version

上述安装步骤已包含 docker-compose-plugin（命令为 docker compose，注意中间有空格）。请执行以下命令确认：

docker compose version

若显示版本信息（如 Docker Compose version v2.x.x）即可继续。旧版独立命令 docker-compose 同样可用，但本教程统一使用 docker compose。

镜像包文件名为 xl-napcat.tar.gz，请从官方 QQ 群内下载，并放到服务器的 /root 目录后再导入。

3.1 从群内下载镜像包

1. 加入官方 QQ 群，在群文件或群公告中找到 xl-napcat.tar.gz
2. 将文件下载到服务器，并确保最终路径为 /root/xl-napcat.tar.gz

若先下载到了其他位置（如 /tmp 或当前用户家目录），可执行：

# 示例：将下载的文件移动到 /root（源路径按实际修改）
mv /tmp/xl-napcat.tar.gz /root/xl-napcat.tar.gz

# 确认文件已在 /root 且大小正常
ls -lh /root/xl-napcat.tar.gz

3.2 导入镜像

在服务器上执行以下命令，从 /root 目录读取压缩包并导入 Docker 镜像：

# 从 /root 目录读取 xl-napcat.tar.gz 并导入镜像
gunzip -c /root/xl-napcat.tar.gz | docker load

# 确认镜像已存在
docker images | grep napcat

导入成功后应能看到 xl-napcat 镜像，标签为 latest。/root/xl-napcat.tar.gz 可保留作备份，不影响后续部署。

4.1 创建部署目录

mkdir -p /root/data/docker/{config,cache,ntqq}
mkdir -p /root/napcat-deploy
cd /root/napcat-deploy

4.2 创建 docker-compose.yml

在 /root/napcat-deploy/ 下创建 docker-compose.yml，内容如下。请将 xlwd2026 替换为你的登录密钥：

services:
  napcat:
    image: xl-napcat:latest
    container_name: qqbot-hub-napcat
    restart: unless-stopped
    network_mode: host
    environment:
      NAPCAT_UID: 0
      NAPCAT_GID: 0
      WEBUI_TOKEN: 请替换为你的登录密钥
    volumes:
      - /root/data/docker/config:/app/napcat/config
      - /root/data/docker/cache:/app/napcat/cache
      - /root/data/docker/ntqq:/app/.config/QQ

4.3 配置项说明

确认已修改登录密钥后，在 docker-compose.yml 所在目录执行：

cd /root/napcat-deploy
docker compose up -d

# 查看运行状态
docker compose ps

# 查看日志（可选）
docker compose logs -f --tail=50

状态为 running 即表示启动成功。首次启动可能需要数十秒初始化。

1. 浏览器访问：http://你的服务器IP:6099
2. 输入你在 WEBUI_TOKEN 中设置的登录密钥
3. 按页面引导扫码或快捷登录 QQ 账号
4. 登录成功后可在仪表盘查看机器人在线状态

若需让外部插件调用机器人 API 并接收事件推送，需在 WebUI 的网络配置中添加 HTTP 服务（无需重复部署机器人）。按以下步骤操作：

若有多个插件对接同一机器人，请为每个插件重复执行本步骤，新建一条独立的 HTTP 服务器，分别配置不同端口与 Token。

1. 进入 WebUI → 网络配置
2. 点击 新建 → HTTP 服务器
3. 按下方清单勾选并填写
4. 点击 保存，并记录生成的 Token（插件配置需要）

推荐配置清单

• 启用 — 勾选
• 启用 CORS — 勾选（允许跨域请求）
• 启用 WebSocket — 勾选（事件下行推送）
• Host — 填写 0.0.0.0
• 端口 — 自定义一个可用端口（如 3000、3001）。多个服务端口不可重复，例如 A 区插件用 3000，B 区须用其他端口
• Token — 保存后复制，供插件使用
• 其他选项 — 无需勾选，保持默认即可

此为可选但强烈建议的配置。若不设置过滤，机器人会向下行通道推送全部群消息，大量消息可能导致插件带宽不足、延迟升高。

推荐做法

• 在同一 HTTP 服务配置中找到 下行推送过滤
• 配置 群白名单，填入插件实际使用的群号
• 效果：该通道仅下发白名单群内的消息，其他群消息不会混入

回到你的插件机器人配置页面，填写以下信息并保存：

填写完成后点击保存链接配置，插件即可通过该地址与机器人通信。