Docker 部署与容器管理

用 Docker 跑 Bot 的好处是，QQ 需要的那一堆依赖都打包在镜像里，不用在服务器上一个个去装。不过 Desktop 的 Docker 部署只支持远端 Linux。本机 Windows 和远端 Windows 用的都是原生运行，就算你在本机装了 Docker，也不会出现这个部署选项。

如果还没添加服务器，先按 远端 Linux 把主机加好、SSH 测通，再回来看这一篇。

1. 准备 Docker

1. 打开「组件」，切到要部署的那台 Linux 主机。
2. 在运行时依赖里找到 Docker，等它探测完。
3. 还没装的话点「安装」，按提示提供提权信息，在「任务」里看进度。
4. 装完以后重新检测一下，确认 Docker 已经就绪。

侧栏里的「容器」入口要满足两个条件才会出现：至少有一台远端主机上的 Docker 可用，并且「设置 → 功能 → 容器页」是开着的。

光装好 Docker 还不够，SSH 登录的那个用户还得有权限用它。用同一个用户在远端终端里运行：

docker info

能看到服务端的信息就没问题。如果提示连不上 Docker daemon，检查一下 Docker 服务有没有启动；如果提示 permission denied，那是用户权限的问题，重试拉镜像是解决不了的。

可以请服务器管理员把这个用户加进 docker 组，然后退出、重新登录，权限才会生效：

sudo usermod -aG docker "$USER"

要知道，docker 组的权限很大，相当于能控制宿主机上所有的容器。只给你专门用来管理服务器的那个账户就好。

2. 拉取协议镜像

1. 组件页保持选中这台 Linux。
2. 找到 NapCat 或 SnowLuma，点这一行的「拉镜像」。
3. 默认会自动选镜像源；某个源用不了，可以在「选择镜像源」里换一个。
4. 在「任务」里看拉取进度，完成后确认镜像已经就绪。

拉镜像只是把镜像准备好，并不会顺手帮你创建 Bot。容器里需要的依赖镜像都自带了，不用照着原生部署的清单去装宿主机依赖。

「设置 → 网络」里的 GitHub / Node.js 下载线路管不到 Docker 拉镜像。拉得慢的话，要去查这台 Linux 自己的网络，以及这里选的镜像源，见 网络作用范围。

3. 创建 Docker Bot

1. 到「机器人」新建一个 Bot，填 QQ 账号和实例名称。
2. 选刚才拉了镜像的 NapCat 或 SnowLuma。
3. 「运行场景」选远程运行，「目标远程主机」选这台 Linux。
4. 「启动方式」选「Docker」，确认界面上显示 Docker 和镜像都已就绪。
5. 保存，从卡片上启动，打开日志等协议端起来。
6. NapCat 用 WebUI 登录；SnowLuma 用「扫码登录」或者 VNC，见 扫码登录。

容器在运行、QQ 已登录、OneBot 已连上，这是三个独立的状态，要一个个分别确认。容器没退出，不代表账号就在线。

4. 端口：容器内和宿主机

打开侧栏「容器」，选这台主机，在容器卡片上能看到端口映射；点「详情」可以看完整的端口和挂载信息。也可以在远端终端里运行：

docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

举个例子，映射显示宿主机的 6388 转发到容器里的 6099。那么从宿主机访问要用 6388，只有在容器内部才用 6099。这只是个例子，你的端口以实际的映射为准。

想让宿主机或者其他容器能访问到协议端，容器里的服务一般要监听 0.0.0.0，再配合端口发布或者容器网络。如果服务只监听了容器内的 127.0.0.1，那即使做了端口映射，宿主机也访问不到。OneBot 的地址、方向和 token 怎么配，见 连接指南。

NapCat WebUI 提示 token 错误

已经存在的容器，有效的 token 以它当前用的 webui.json 为准，不一定是最初启动时参数里写的那个。Desktop 会去读实际的配置，鉴权失败后也会重新核对一次。

先把 Desktop 更新到最新、重新连接一下 Bot。还是不行的话，检查 SSH 用户能不能执行 Docker 命令、能不能读到容器的配置，再看看 WebUI 是不是提示了限流或者需要两步验证。

容器页

「容器」页按主机列出「容器」「镜像」「网络」「数据卷」，搜索框可以按名称、ID 等过滤。动手之前，先看清楚选中的是哪台服务器。

• 容器：根据状态启动、停止、暂停、恢复或重启；「日志」读的就是 docker logs 的内容。
• 详情：退出码、是不是因为内存不足被终止、重启了几次、健康检查、网络、端口和挂载。容器在运行时，还能看 CPU、内存、网络和磁盘读写。
• 镜像：确认需要的镜像在不在，清理之前看清楚它还被谁引用着。
• 网络与数据卷：看容器用的是哪个网络、数据持久化在哪里。还被容器引用着的，不能直接删。

删除容器只会丢掉它的可写层，挂载的数据卷和宿主机目录都还在；但删除数据卷，就会永久删除卷里的内容。配置 ZIP 不包含容器数据、应用数据库或程序，清理前先确认数据存在哪里，并单独备份。

启动失败时看这三样

1. 容器页里，这个容器是不是已经退出了，退出码是多少。
2. 「日志」里第一条真正的错误，而不是最后一行的汇总。
3. 端口映射和挂载，和你当前的配置对不对得上。

看到 内存不足终止：是，先解决服务器内存不够的问题；看到 permission denied，查执行用户和目录权限；账号没登录，就回登录入口去处理。不是所有问题都是镜像没拉好。

想在 Desktop 退出以后还能继续盯着容器里的账号，可以装 ncd-watch。它会读取容器状态和 WebUI 里的账号状态。光看 docker ps 是判断不出 QQ 有没有掉线的。