# Distrubuted Color War

**Repository Path**: raitocc/distrubuted-color-war

## Basic Information

- **Project Name**: Distrubuted Color War
- **Description**: 分布式软件原理与技术期末作业
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ColorWar（像素炮塔：阵地战）

最终提交材料位于 [最终提交文档/](最终提交文档/)，包含整合后的需求规约、概要设计、测试报告和定稿答辩 PDF。

ColorWar 是一个分布式多人在线涂色对战游戏。玩家加入红、蓝、黄、绿四个阵营之一，通过点击发炮、道具强化、Boss 争夺、区块占领分红和据点拍卖来争夺地图控制权。项目重点展示 Spring Boot 微服务、Redis 实时状态、Kafka 事件广播、多 WebSocket Gateway、Nginx 限流负载均衡、TCC 分布式事务和控制中心压测。

## 功能概览

| 模块 | 状态 | 说明 |
| --- | --- | --- |
| 用户系统 | 已完成 | 注册、登录、JWT、游客模式 |
| 游戏 Tick 引擎 | 已完成 | 50ms Tick，子弹移动、碰撞、染色和地图增量同步 |
| 四阵营地图争夺 | 已完成 | 当前演示配置为 100 x 100 地图，参数可配置 |
| 金币经济 | 已完成 | 发炮产金币、余额查询、金币变动推送 |
| 道具背包 | 已完成 | 霰弹、机枪、大球购买、存包和使用 |
| Boss 打野 | 已完成 | 随机刷新、击杀奖励、全服广播 |
| 区块占领与分红 | 已完成 | 10 x 10 区块，占领后按在线玩家分红 |
| 据点拍卖 | 已完成 | auction-svc、Redis CAS、分布式锁、TCC 冻结/确认/取消 |
| 超级炮塔 | 已完成 | 拍卖中标后自动归属阵营并参与射击 |
| WebSocket 实时同步 | 已完成 | TICK_SYNC 二进制帧、STATE_SYNC 权威快照、事件广播 |
| 多网关广播 | 已完成 | 3 个 ws-gateway 实例使用不同 Kafka consumer group 全量消费 |
| 控制中心 | 已完成 | 假人创建、批量启动/停止、服务健康和压测指标 |
| Docker Compose 部署 | 已完成 | Redis、Kafka、MySQL、后端微服务、Nginx、control-svc 一键启动 |

## 技术栈

| 层 | 技术 |
| --- | --- |
| 玩家前端 | Vue 3、TypeScript、Pinia、Vite、Canvas |
| 后端服务 | Spring Boot 3、JDK 21、Maven |
| 控制中心 | Node.js、Express、Vue 3 |
| 实时通信 | WebSocket、Kafka |
| 状态与持久化 | Redis、MySQL 8、Flyway |
| 网关与部署 | Nginx、Docker、Docker Compose |
| 测试与观测 | JUnit、Spring Boot Test、Actuator、Prometheus 指标、control-svc |

## 仓库结构

```text
ColorWar/
├── ColorWarBackend/          # Spring Boot 微服务、Docker Compose、后端测试与压测脚本
├── ColorWarFrontend/         # Vue 3 + TypeScript 玩家前端
├── control-svc/              # Node.js 控制中心，假人管理与监控看板
├── docs/                     # 开发过程文档与阶段交接材料
└── 最终提交文档/              # 课程最终提交整合材料
```

## 系统架构

```text
                         Browser / Control Center
                                  |
                              Nginx :80
                    REST 限流 / WS 负载均衡 / 统一入口
                                  |
        ┌───────────────┬─────────┼───────────────┬────────────────┐
        |               |         |               |                |
  user-svc:8081   game-svc:8080  auction-svc:8083          ws-gateway x3
  用户与 JWT       Tick/地图/经济  竞价引擎/TCC 调用          WebSocket 推送
        |               |         |               |                |
      MySQL           Redis <-----┴---- 资金/拍卖状态         Kafka 消费
                        |
                      Kafka
              游戏事件、Tick、快照、拍卖广播

control-svc:8085 连接 user-svc、game-svc、ws-gateway 和 Redis，
用于创建假人、压测、监控服务健康和延迟指标。
```

## 后端全栈运行

```bash
cd ColorWarBackend
docker compose up -d --build
```

旧版 Docker Compose 命令形式：

```bash
docker-compose up -d --build
```

常用访问地址：

| 地址 | 说明 |
| --- | --- |
| `http://localhost/debug.html` | game-svc 内置调试页面 |
| `http://localhost:8085` | control-svc 控制中心 |
| `http://localhost:8080/swagger-ui.html` | game-svc API 文档 |
| `http://localhost:8081/swagger-ui.html` | user-svc API 文档 |
| `http://localhost:8083/swagger-ui.html` | auction-svc API 文档 |

## 玩家前端运行

前端说明见 [ColorWarFrontend/README.md](ColorWarFrontend/README.md)。

```bash
cd ColorWarFrontend
npm install
npm run dev
```

Vite 开发地址为 `http://localhost:5173`。开发代理在 [ColorWarFrontend/vite.config.ts](ColorWarFrontend/vite.config.ts) 中配置，默认转发到本地后端：

| 前端路径 | 目标服务 |
| --- | --- |
| `/api/game` | `http://localhost:8080` |
| `/api/users` | `http://localhost:8081` |
| `/api/v1/auction` | `http://localhost:8083` |
| `/ws/game` | `ws://localhost:80` |

## 测试

后端测试代码位置：

| 类型 | 位置 |
| --- | --- |
| game-svc 测试 | `ColorWarBackend/colorwar-game-svc/src/test/java/` |
| auction-svc 测试 | `ColorWarBackend/colorwar-auction-svc/src/test/java/` |
| user-svc 测试 | `ColorWarBackend/colorwar-user-svc/src/test/java/` |
| 压测脚本 | `ColorWarBackend/scripts/load-test.js` |

模块测试命令：

```bash
cd ColorWarBackend/colorwar-common
mvn install

cd ../colorwar-game-svc
mvn test

cd ../colorwar-auction-svc
mvn test

cd ../colorwar-user-svc
mvn test
```

压测脚本：

```bash
cd ColorWarBackend/scripts
npm install
node load-test.js 72 60 200
```

## 文档

| 文档 | 说明 |
| --- | --- |
| [最终提交文档/README.md](最终提交文档/README.md) | 最终提交材料清单、源码位置、测试代码位置 |
| [最终提交文档/需求规约.md](最终提交文档/需求规约.md) | 整合版需求规约 |
| [最终提交文档/概要设计.md](最终提交文档/概要设计.md) | 整合版概要设计 |
| [最终提交文档/测试报告.md](最终提交文档/测试报告.md) | 测试环境、测试方法、功能测试、压测结果和结论 |
| [docs/README.md](docs/README.md) | 开发过程文档索引 |

## 关键设计点

### 多 WebSocket Gateway 广播

每个 ws-gateway 实例维护一部分客户端连接。三个 ws-gateway 分别使用 `ws-gateway-1`、`ws-gateway-2`、`ws-gateway-3` 作为 Kafka consumer group id，使每个实例都能消费完整游戏事件，再向本实例连接的客户端广播。

### TCC 拍卖资金链路

拍卖出价先由 game-svc 冻结资金，auction-svc 再更新最高价。拍卖结束后对中标事务 Confirm 扣款，被超越或超时的事务 Cancel 退回。`TccRecoveryTask` 定时扫描超时事务，避免资金长期冻结。

### Tick 增量与权威快照

客户端通过 `tickSeq` 检测 TICK_SYNC 增量帧断档，必要时重拉地图快照。动态实体由周期性 STATE_SYNC 覆盖本地子弹、大球、Boss 和拍卖炮塔状态，降低视觉事件丢失带来的长期偏差。