# 技术选型总览

> **位置**: `docs/11_技术选型/技术选型总览.md`
> **版本**: v1.0
> **日期**: 2026-07-08
> **关联**: AGENTS.md 技术合规铁律、docs/开发规范/技术栈合规清单.md

---

## 1. 选型原则

> **所有技术必须开源可商用或已获合法授权。**
> 详见 `docs/00_项目概述/开发规范/技术栈合规清单.md`

| 原则 | 说明 |
|------|------|
| 开源优先 | 优先选择 MIT/Apache-2.0/BSD 协议的开源技术 |
| 商用授权 | 闭源技术必须有商用授权协议 |
| 社区活跃 | 选择社区活跃、维护良好的技术，避免技术债务 |
| 团队熟悉 | 优先选择团队有使用经验的技术，降低学习成本 |

---

## 2. 技术栈总览

### 2.1 客户端

| 技术 | 版本 | 用途 | 协议 |
|------|------|------|------|
| **Cocos Creator** | 3.8.8 | 游戏引擎 | 免费版（商用许可） |
| **TypeScript** | 5.x | 客户端脚本语言 | Apache-2.0 |

### 2.2 服务端

| 技术 | 版本 | 用途 | 协议 |
|------|------|------|------|
| **Go** | 1.22+ | 服务端语言 | BSD-3 |
| **Nakama** | 3.x | 游戏服务端框架 | Apache-2.0 |
| **PostgreSQL** | 16+ | 关系型数据库 | PostgreSQL License |
| **Valkey** | 8+ | 缓存/会话存储 | BSD-3 |

### 2.3 基础设施

| 技术 | 版本 | 用途 | 协议 |
|------|------|------|------|
| **Docker** | latest | 容器化 | Apache-2.0 |
| **Nacos** | 2.x | 配置中心/服务发现 | Apache-2.0 |
| **Nginx** | 1.25+ | 反向代理/负载均衡 | BSD-2 |
| **Prometheus** | 2.x | 监控 | Apache-2.0 |
| **Grafana** | 10.x | 可视化监控 | AGPL（前端）/ Apache-2.0（服务端） |
| **Protobuf** | 3.x | 序列化协议 | BSD-3 |

---

## 3. 架构概览

```
┌─────────────────────────────────────────────┐
│              客户端 (Cocos Creator)           │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │
│  │ UI 层   │  │ 系统层  │  │ 网络层      │  │
│  │ scenes  │  │ systems │  │ NetworkMgr  │  │
│  └─────────┘  └─────────┘  └─────────────┘  │
└──────────────────┬──────────────────────────┘
                   │ WebSocket / gRPC
┌──────────────────┴──────────────────────────┐
│              Nakama 游戏服务端                │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │
│  │ RPC     │  │ Match   │  │ Middleware  │  │
│  │ 业务逻辑 │  │ 实时对战 │  │ 认证/限流   │  │
│  └─────────┘  └─────────┘  └─────────────┘  │
└──────────────────┬──────────────────────────┘
                   │ SQL / Redis 协议
        ┌──────────┴──────────┐
        ▼                     ▼
┌───────────────┐    ┌─────────────────┐
│  PostgreSQL   │    │    Valkey       │
│  玩家数据     │    │  缓存/会话/排行  │
└───────────────┘    └─────────────────┘
```

---

## 4. 详细技术文档

> 详细的技术设计文档（TDD）将在进入开发阶段后编写。
> 当前处于设计阶段，技术类内容仅限于选型概览。

| 主题 | 状态 | 说明 |
|------|------|------|
| 服务端整体架构 | 待编写 | 进入开发阶段后补充 TDD |
| 客户端热更新方案 | 待编写 | 进入开发阶段后补充 TDD |
| 数据库表结构设计 | 待编写 | 进入开发阶段后补充 TDD |
| API 接口设计 | 待编写 | 进入开发阶段后补充 TDD |
| 反作弊与安全设计 | 待编写 | 进入开发阶段后补充 TDD |
| 实时位置同步 | 待编写 | 进入开发阶段后补充 TDD |

---

## 5. 版本记录

- **v1.0**（2026-07-08）: 初始版本，汇总技术选型，标记详细 TDD 待开发阶段补充