heroiclabs/nakama

Nakama 镜像文档

1. 镜像概述和主要用途

Nakama 是一个开源分布式服务器，专为支持现代游戏和应用的后端服务设计。作为生产就绪的解决方案，它提供了完整的工具链，帮助开发者快速构建具备实时交互、社交功能和用户管理能力的应用后端。其核心定位是通过分布式架构实现高效扩展，广泛应用于全球游戏工作室和应用开发者的生产环境中。

2. 核心功能和特性

2.1 核心功能

• 用户账户管理：支持多平台账户集成、身份验证及用户数据持久化
• 实时聊天系统：提供一对一、群组聊天及消息推送能力
• 社交功能套件：包含好友关系管理、排行榜、成就系统等模块
• 智能匹配器：基于规则的玩家/用户匹配（支持技能等级、网络延迟等条件筛选）
• 实时多人交互：低延迟网络通信框架，支持房间创建、状态同步及多人会话管理
• 扩展功能：包括数据存储、分析集成、跨平台支持等（详见官方文档）

2.2 关键特性

• 开源可定制：完整开源代码库，支持按需扩展和二次开发
• 生产级稳定性：经过全球游戏工作室验证的高可用架构
• 分布式扩展：支持水平扩展以应对高并发场景
• 跨平台兼容：适配主流游戏引擎（Unity、Unreal等）及开发框架
• 社区支持：活跃的开发者社区及完善的官方文档

3. 使用场景和适用范围

3.1 典型使用场景

• 实时多人游戏后端（如MOBA、回合制游戏、休闲竞技类游戏）
• 社交应用后端（需用户关系管理、实时聊天的应用）
• 在线协作工具（需实时数据同步和用户交互的平台）
• 互动娱乐产品（含用户管理、内容分发的场景）

3.2 适用范围

• 独立开发者：快速搭建后端服务，降低开发成本
• 中小型游戏工作室：构建可扩展的游戏服务，支持用户规模增长
• 企业级开发者：开发具备实时交互和社交功能的复杂应用

4. 使用方法和配置说明

4.1 环境准备

• 安装Docker Engine（20.10+）及Docker Compose
• 确保目标服务器开放必要端口（默认7350-7352、5432）

4.2 Docker快速启动（单节点）

需提前部署PostgreSQL数据库，执行以下命令启动Nakama：

bash
docker run -d \
  --name nakama \
  -p 7350:7350 \  # 客户端API端口
  -p 7351:7351 \  # 管理API端口
  -p 7352:7352 \  # 实时通信端口
  -e DATABASE_URL="postgresql://user:password@postgres-host:5432/nakama?sslmode=disable" \
  heroiclabs/nakama:latest

4.3 Docker Compose部署（含数据库）

推荐使用Docker Compose管理Nakama与PostgreSQL服务，配置示例如下：

yaml
version: '3'

services:
  # PostgreSQL数据库服务
  postgres:
    image: postgres:14-alpine
    container_name: nakama-postgres
    environment:
      POSTGRES_USER: nakama
      POSTGRES_PASSWORD: nakama
      POSTGRES_DB: nakama
    volumes:
      - postgres-data:/var/lib/postgresql/data  # 数据持久化
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nakama"]
      interval: 5s
      timeout: 5s
      retries: 5

  # Nakama服务
  nakama:
    image: heroiclabs/nakama:latest
    container_name: nakama
    depends_on:
      postgres:
        condition: service_healthy  # 等待数据库就绪
    ports:
      - "7350:7350"  # 客户端API端口
      - "7351:7351"  # 管理API端口
      - "7352:7352"  # 实时通信端口
    environment:
      DATABASE_URL: "postgresql://nakama:nakama@postgres:5432/nakama?sslmode=disable"  # 数据库连接
      LOG_LEVEL: "info"  # 日志级别（debug/info/warn/error）
      PORT: 7350  # 客户端API端口（默认7350）
      ADMIN_PORT: 7351  # 管理API端口（默认7351）
      SOCKET_PORT: 7352  # 实时通信端口（默认7352）
    restart: unless-stopped  # 异常退出后自动重启

volumes:
  postgres-data:  # 数据库数据卷

启动命令：

bash
# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f nakama

4.4 配置参数与环境变量

Nakama核心配置通过环境变量注入，常见参数如下：

完整配置参数见Nakama官方文档

5. 参考资源

• https://github.com/heroiclabs/nakama
• 官方文档
• 开发者社区