部署 Lagrange.onebot 的 Docker Compose 指南

Lagrange.onebot 是基于 Lagrange.Core 的 OneBot V11 协议实现，用于支持 NTQQ（腾讯 QQ NT 协议）的 Docker 容器镜像。本文将指导您通过 Docker Compose 使用外部网络 common-network 快速部署 Lagrange.onebot，使用官方提供的最新镜像（ghcr.io/lagrangedev/lagrange.onebot:sha-1968eac），并确保配置正确以实现持久化存储和稳定运行。

前置要求

在开始部署之前，请确保满足以下条件：

• Docker 和 Docker Compose 已安装：确保 Docker 版本支持 Compose v2+，运行 docker compose version 确认。
• 外部网络已创建：确保外部网络 common-network 已存在，可通过以下命令创建：

  docker network create common-network
  

• 数据目录准备：创建一个目录（例如 /path/to/lagrange/data）用于存储配置文件（如 appsettings.json、device.json、keystore.json）和数据库文件（lagrange-*.db）。
• 配置文件准备：在数据目录中创建 appsettings.json，至少包含以下内容（根据需求调整）：

  {
    "Implementations": [
      {
        "Type": "ReverseWebSocket",
        "Host": "host.docker.internal",
        "Port": 8081,
        "Suffix": "/ws"
      }
    ],
    "SignServerUrl": "https://sign.lagrangecore.org/api/sign"
  }
  

• 权限设置：获取宿主机的用户 ID 和组 ID（运行 id 查看 $UID 和 $(id -g)），用于容器内权限管理。
• 网络环境：确保宿主机或容器网络可以访问签名服务器（如 https://sign.lagrangecore.org/api/sign）。

如果您需要从旧版本迁移数据库，请参考官方文档，使用 Lagrange.OneBot.DatabaseShift 工具将 lagrange-x.db 转换为新格式。

Docker Compose 配置

以下是推荐的 docker-compose.yml 配置，用于部署 Lagrange.onebot 容器，连接到外部网络 common-network。

version: '3.8'

services:
  lagrange-onebot:
    image: ghcr.io/lagrangedev/lagrange.onebot:sha-1968eac
    container_name: lagrange-onebot
    restart: unless-stopped
    ports:
      - "8081:8081"
    volumes:
      - /path/to/lagrange/data:/app/data
    environment:
      - UID=1000
      - GID=1000
      - TZ=Asia/Shanghai
    networks:
      - common-network

networks:
  common-network:
    external: true

配置说明

• image：使用最新镜像 sha-1968eac，发布于约 17 天前（截至 2025 年 9 月 23 日），确保稳定性。您也可以使用 :edge 标签获取开发版，但可能不稳定。
• container_name：固定容器名称，便于管理。
• restart：设置为 unless-stopped，确保容器在 Docker 重启后自动恢复（除非手动停止）。
• ports：将容器内的 8081 端口映射到宿主机的 8081 端口，支持 OneBot V11 的 WebSocket 或 HTTP 协议访问。
• volumes：将宿主机的 /path/to/lagrange/data 映射到容器内的 /app/data，用于持久化配置文件和数据库。
• environment：
  • UID 和 GID：设置为宿主机用户和组 ID（替换为实际值），避免权限问题。
  • TZ：设置时区为 Asia/Shanghai，可根据需要更改（如 America/New_York）。
• networks：连接到外部网络 common-network，便于与其他服务（如 Bot 框架）通信。

部署步骤

按照以下步骤完成 Lagrange.onebot 的部署：

1. 创建外部网络（如果尚未创建）：

   docker network create common-network
   

2. 创建数据目录和配置文件：

   • 创建目录：mkdir -p /path/to/lagrange/data。
   • 将 appsettings.json 等文件放入该目录，确保配置正确（参考前置要求中的示例）。

3. 创建 Docker Compose 文件：

   • 创建 docker-compose.yml 文件，复制上述配置内容。
   • 将 volumes 中的 /path/to/lagrange/data 替换为实际路径。
   • 将 UID 和 GID 替换为宿主机的用户 ID 和组 ID（运行 id 获取）。

4. 启动容器：

   cd /path/to/your/compose/dir
   docker compose up -d
   

   此命令将拉取镜像并在后台启动容器。

5. 验证部署：

   • 查看容器日志：docker compose logs -f lagrange-onebot，检查是否有错误或二维码登录提示。
   • 测试 OneBot 接口：
     • 使用浏览器访问 http://localhost:8081（健康检查）。
     • 或使用 Bot 框架（如 NoneBot）连接 ws://localhost:8081/ws。
   • 如果使用 QQ 登录，日志会显示二维码或密码登录流程。

6. 管理容器：

   • 停止服务：docker compose down。
   • 更新镜像：修改 image 标签后运行：

     docker compose pull && docker compose up -d
     

注意事项

• 网络配置：确保 common-network 已创建。如果 Bot 框架运行在宿主机，appsettings.json 中的 Host 应为 host.docker.internal；若在其他容器内，需使用容器 IP 或服务名称连接。
• 权限问题：确保数据目录的权限正确，UID 和 GID 匹配宿主机用户，避免 permission denied。
• 数据库迁移：如果从旧版升级，运行 Lagrange.OneBot.DatabaseShift 工具（参考官方文档）。
• 调试：如遇问题，查看 GitHub Issues（46 个活跃问题）或讨论区（28 个讨论），或参考官方文档：
  • Docker 部署指南：https://github.com/LagrangeDev/Lagrange.Core/blob/master/Docker_zh.md
  • OneBot 文档：https://lagrangedev.github.io/Lagrange.Doc/Lagrange.OneBot/

结语

通过以上步骤，您可以使用 Docker Compose 快速部署 Lagrange.onebot，连接到外部网络 common-network，并享受 OneBot V11 协议的便捷性和 NTQQ 的功能支持。如需进一步定制或优化，请参考官方 GitHub 仓库（https://github.com/LagrangeDev/Lagrange.Core）或联系社区支持。