NiB 开源聊天应用 Docker 镜像文档

一、镜像概述和主要用途

概述

NiB 开源聊天应用 Docker 镜像是一个轻量级容器化解决方案，旨在将开源聊天功能快速部署为独立服务。该镜像封装了核心聊天逻辑、网络通信模块及基础依赖，提供开箱即用的部署体验，无需复杂环境配置。

主要用途

• 快速搭建小型团队内部即时通讯系统
• 为Web应用或移动应用提供嵌入式聊天功能
• 构建轻量级社区聊天平台（支持多房间/频道）
• 作为开源聊天技术的学***和演示环境

二、核心功能和特性

核心功能

• 实时消息传递：基于WebSocket协议实现低延迟消息收发
• 用户认证：支持***登录、基础账号密码认证（可扩展OAuth2.0）
• 多房间/频道：支持创建多个独立聊天空间，隔离不同主题对话
• 消息持久化：可选本地文件或SQLite数据库存储历史消息（默认内存模式，重启后消息不保留）
• 跨平台兼容：支持Linux/Windows/macOS系统的Docker环境运行

特性

• 轻量级：镜像体积<200MB，运行时内存占用通常<128MB
• 可配置性：通过环境变量自定义端口、认证方式、消息存储策略
• 无状态设计：支持多实例部署（需配合外部Redis等实现会话共享，单实例默认无状态）
• 开源透明：基于MIT协议开源，核心代码可审计、可二次开发

三、使用场景和适用范围

适用场景

• 小型团队协作：50人以内团队的日常沟通（支持文字消息、基础表情）
• Web应用插件：为CMS、论坛或电商平台添加用户间聊天功能（通过API集成）
• 本地测试环境：开发者快速验证聊天功能逻辑（无需搭建完整后端服务）
• 教育/演示：高校或培训机构用于讲解实时通信、WebSocket协议等技术原理

不适用场景

• 大规模用户场景（建议用户量>100时搭配消息队列和分布式存储扩展）
• 对消息安全性要求极高的场景（默认未开启端到端加密，需自行扩展）

四、详细使用方法和配置说明

4.1 环境要求

• Docker Engine 20.10+ 或 Docker Desktop 4.0+
• 宿主机需开放指定端口（默认8080，用于WebSocket和HTTP通信）
• 如需持久化消息：宿主机需挂载数据卷（本地目录或外部存储）

4.2 基础部署（docker run）

最简启动命令（默认配置）

bash
docker run -d --name nib-chat -p 8080:8080 nib-chat:latest

• 访问 http://<宿主机IP>:8080 即可打开聊天界面（默认***登录，支持创建房间）

带消息持久化的启动命令

bash
docker run -d --name nib-chat \
  -p 8080:8080 \
  -v /本地目录/nib-data:/app/data \  # 挂载数据卷存储消息
  -e MESSAGE_STORAGE=file \  # 启用文件存储模式（默认内存模式）
  nib-chat:latest

4.3 docker-compose 部署（推荐生产环境）

创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  nib-chat:
    image: nib-chat:latest
    container_name: nib-chat-service
    restart: always  # 异常退出后自动重启
    ports:
      - "8080:8080"  # 宿主机端口:容器内端口（容器内固定8080）
    environment:
      - AUTH_ENABLED=true  # 启用基础账号密码认证（默认false，***登录）
      - ADMIN_USER=admin  # 管理员账号（AUTH_ENABLED=true时必填）
      - ADMIN_PASSWORD=SecurePass123  # 管理员密码（AUTH_ENABLED=true时必填）
      - MAX_ROOMS=10  # 最大房间数量限制（默认无限制）
      - LOG_LEVEL=info  # 日志级别（debug/info/warn/error，默认info）
    volumes:
      - ./nib-data:/app/data  # 本地目录挂载（存储消息、用户配置等）
    networks:
      - nib-network  # 自定义网络隔离

networks:
  nib-network:
    driver: bridge  # 桥接网络模式（默认）

启动服务：

bash
docker-compose up -d  # 后台运行
docker-compose logs -f  # 查看实时日志

4.4 环境变量配置说明

4.5 数据持久化说明

• 存储路径：容器内数据默认路径为 /app/data（包含消息文件、用户配置等）
• 挂载方式：通过 -v /本地目录:/app/data 挂载宿主机目录，避免容器删除后数据丢失
• 存储模式选择：
  • 开发/测试环境：建议使用默认 memory 模式（性能最优，无需持久化）
  • 生产环境：建议使用 sqlite 模式（需挂载数据卷，支持消息历史查询）

五、常见问题与注意事项

1. 无法访问服务：检查宿主机防火墙是否开放映射端口（如8080），或使用 docker logs <容器名> 查看启动日志排查错误。
2. 消息丢失：若未启用持久化存储（默认memory模式），容器重启后消息会丢失，需配置 MESSAGE_STORAGE 并挂载数据卷。
3. 认证失败：启用 AUTH_ENABLED=true 时，必须同时配置 ADMIN_USER 和 ADMIN_PASSWORD，否则服务启动失败。
4. 性能限制：单实例默认支持≤50并发连接，高并发场景需扩展部署（配合外部Redis实现会话共享）。

六、镜像版本与更新

• 镜像标签：latest（最新稳定版）、v1.0（特定版本，如v1.0、v1.1）
• 更新方法：

  bash
  docker pull nib-chat:latest  # 拉取最新镜像
  docker-compose down && docker-compose up -d  # 重启服务应用更新
  

七、参考链接

• NiB 开源项目GitHub（获取源码及详细开发文档）
• Docker***文档（容器基础操作指南）