# linch-server

**Repository Path**: linch-games/linch-server

## Basic Information

- **Project Name**: linch-server
- **Description**: linch-server多人服务端
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-25
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MCS-26112 游戏服务器

## 项目简介

基于 Due 框架的分布式游戏服务器，采用微服务架构，支持多游戏类型。

## 架构设计

### 服务架构

```
┌─────────┐
│  Gate   │  网关服务（10）
│  (10)   │  职责：WebSocket连接管理、消息转发、心跳管理
└────┬────┘
     │
     ├──────────┬──────────┬──────────┐
     │          │          │          │
┌────▼────┐ ┌──▼───┐ ┌────▼────┐ ┌──▼─────┐
│  Lobby  │ │ Room │ │Game-Uno │ │Game-Uno│
│  (20)   │ │ (25) │ │  (30)   │ │  (30)  │
└─────────┘ └──────┘ └─────────┘ └────────┘
```

### 服务职责

| 服务编号 | 服务名称 | 职责说明 | 状态类型 |
|---------|---------|---------|---------|
| 10 | Gate | 网关入口，WebSocket连接管理、消息转发、心跳管理 | 无状态 |
| 20 | Lobby | 大厅逻辑，用户认证 | 无状态 |
| 25 | Room | 房间管理、房间状态管理、玩家加入/离开 | 有状态 |
| 30 | Game-Uno | UNO 游戏服务，游戏状态管理、规则校验、回合控制 | 有状态 |

## 目录结构

```
MCS-26112-server/
├── apps/                          # 服务目录
│   ├── gate/                      # Gate 网关服务
│   │   ├── etc/                   # 配置文件
│   │   ├── main.go                # 服务入口
│   │   ├── Dockerfile             # Docker 构建文件
│   │   └── docker-compose.yml     # Docker Compose 配置
│   │
│   ├── lobby/                     # Lobby 大厅服务
│   │   ├── internal/              # 内部代码
│   │   │   ├── config/            # 配置和常量
│   │   │   │   └── config.go      # 服务配置
│   │   │   ├── handler/           # 请求处理器
│   │   │   ├── repo/              # 数据访问层
│   │   │   ├── router/            # 路由注册
│   │   │   └── service/           # 业务逻辑层
│   │   ├── etc/                   # 配置文件
│   │   ├── main.go                # 服务入口
│   │   ├── Dockerfile             # Docker 构建文件
│   │   └── docker-compose.yml     # Docker Compose 配置
│   │
│   ├── room/                      # Room 房间服务
│   │   ├── internal/              # 内部代码
│   │   │   ├── actor/             # Actor 模型（房间 Actor）
│   │   │   ├── config/            # 配置和常量
│   │   │   │   └── config.go      # 服务配置
│   │   │   ├── handler/           # 请求处理器
│   │   │   ├── repo/              # 数据访问层
│   │   │   ├── router/            # 路由注册
│   │   │   └── service/           # 业务逻辑层
│   │   ├── etc/                   # 配置文件
│   │   ├── main.go                # 服务入口
│   │   ├── Dockerfile             # Docker 构建文件
│   │   └── docker-compose.yml     # Docker Compose 配置
│   │
│   └── game-uno/                  # Game-Uno 游戏节点服务（专注于 UNO 游戏）
│       ├── internal/              # 内部代码
│       │   ├── config/            # 配置和常量
│       │   │   └── config.go      # 服务配置
│       │   ├── handler/           # 请求处理器
│       │   ├── repo/              # 数据访问层
│       │   ├── router/            # 路由注册
│       │   └── service/           # 业务逻辑层
│       ├── etc/                   # 配置文件
│       ├── main.go                # 服务入口
│       ├── Dockerfile             # Docker 构建文件
│       └── docker-compose.yml     # Docker Compose 配置
│
├── pkg/                           # 公共包
│   ├── global/                    # 全局工具
│   │   ├── errors/                # 错误处理
│   │   └── utils/                 # 工具函数
│   ├── httpc/                     # HTTP 客户端
│   ├── middleware/                # 中间件
│   ├── model/                     # 数据模型
│   ├── platform/                  # 平台服务客户端
│   └── redis/                     # Redis 工具
│
├── docs/                          # 文档目录
│   └── routes.md                  # 路由定义文档
│
├── docker-compose.yml             # 整体服务编排
├── go.mod                         # Go 模块定义
└── README.md                      # 项目说明（本文件）
```

## 服务详细说明

### Gate 服务 (10)

**职责：**
- WebSocket 连接管理
- 消息路由转发
- 心跳管理
- 用户会话绑定

**特点：**
- 无状态服务，可水平扩展
- 不处理业务逻辑，只负责消息转发

### Lobby 服务 (20)

**职责：**
- 用户认证（登录）

**内部结构：**
- `config/` - 配置和常量
- `handler/` - HTTP 请求处理器
- `repo/` - 数据访问层（Redis）
- `router/` - 路由注册
- `service/` - 业务逻辑层

**特点：**
- 无状态服务，可水平扩展
- 专注于用户认证功能

### Room 服务 (25)

**职责：**
- 房间管理（创建、加入、离开）
- 房间状态管理（通过 Actor 模式）
- 房间信息查询

**内部结构：**
- `actor/` - Room Actor，管理房间状态
- `config/` - 配置和常量
- `handler/` - HTTP 请求处理器
- `repo/` - 数据访问层（Redis）
- `router/` - 路由注册
- `service/` - 业务逻辑层

**特点：**
- 有状态服务（房间状态）
- 使用 Actor 模式保证并发安全
- 专注于房间生命周期管理

### Game-Uno 服务 (30)

**职责：**
- UNO 游戏状态管理（权威状态源）
- UNO 游戏规则校验
- 回合控制
- 游戏结果广播
- 防作弊

**内部结构：**
- `config/` - 配置和常量
- `handler/` - 请求处理器（游戏动作处理）
- `repo/` - 数据访问层（Redis）
- `router/` - 路由注册
- `service/` - 业务逻辑层（UNO 游戏服务）

**特点：**
- 专注于 UNO 游戏逻辑实现
- 维护游戏状态作为唯一真相源
- 客户端发送意图（Intent），服务端校验和执行
- 与 Room 服务解耦，通过消息和 Redis 协作

## 路由设计

路由ID格式：`SS * 100 + FF`
- SS: 服务编号 (10~99)
- FF: 功能编号 (10~99)

详细路由定义请参考：[docs/routes.md](./docs/routes.md)

## 技术栈

- **框架**: Due v2（分布式游戏服务器框架）
- **语言**: Go
- **通信**: WebSocket
- **注册中心**: Consul
- **定位服务**: Redis
- **数据存储**: Redis
- **容器化**: Docker + Docker Compose

## 部署说明

### 开发环境

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f [service-name]
```

### 生产环境

各服务提供独立的 Docker Compose 配置，可独立部署和扩展。

## 分支管理

### 分支说明

| 分支名称 | 说明 | 提交/合并规则 |
|---------|------|-------------|
| main | 主分支，仅用于生产环境代码 | 只接受 release 分支合并，不能直接提交或 MR |
| dev | 开发分支，用于日常开发和功能集成 | 可以向 release 分支发起 MR，但不直接合并到 main |
| release/x.y.z | 版本发布分支，每个版本单独创建 | 从 dev 分支 MR 创建；完成测试后合并到 main 并打标签 |

### 分支管理流程

1. **开发阶段**
   - 所有新功能或修复在 dev 分支上完成
   - 提交要求：
     - 保持提交信息清晰，例如 `feat: 添加登录功能`、`fix: 修复注册页面报错`
     - 避免直接提交到 main

2. **准备发布**
   - 当 dev 分支功能稳定时，创建新的 release 分支
   - 在 release/x.y.z 分支上进行必要的测试和 Bug 修复

### 版本号规则（x.y.z）

| 字段 | 含义 | 变更条件 |
|-----|------|---------|
| x | 主版本号（Major） | 发生重大功能变更或向后不兼容的修改，例如架构升级、大幅改动接口 |
| y | 次版本号（Minor） | 新增功能或模块，但向后兼容现有功能。例如添加新页面、功能模块或 API 扩展 |
| z | 修订号/补丁（Patch） | Bug 修复、性能优化或小调整，不影响现有功能或接口 |

## 架构演进

### 当前架构
- Gate = 网关服务（无状态）
- Lobby = 大厅服务（无状态，认证）
- Room = 房间服务（有状态，房间管理）
- Game-Uno = UNO 游戏服务（有状态，游戏逻辑）

### 未来扩展
- Game-Dice = Dice 游戏服务
- Game-XXX = 其他游戏服务

## 相关文档

- [路由定义文档](./docs/routes.md)