lawless/README.md

洪荒大陆 · 服务端本地开发环境

当前阶段：游戏设计阶段 — 暂停技术实现

用户已明确要求，在宣布进入下一阶段前不做技术实现。本仓库中的代码骨架（server/、client/、api/、database/、configs/、docker-compose.yml 等）仅作为设计阶段产物保留，不继续开发、不新增业务逻辑、不提交生产代码。设计文档位于 docs/。

本项目为《洪荒大陆》挂机手游的后端骨架，基于 Nakama 3.x + Go 插件 + PostgreSQL 16 + Valkey + Nacos 2.x。

设计文档总览

游戏设计文档（GDD）- 33个

分类	文档	说明
核心机制	GDD-00~02	决策总索引、种族系统、底层核心机制
战斗系统	GDD-03	ATB即时制战斗、逃跑系统、一键完成、百工战斗
技能功法	GDD-04/10/17/26	功法系统、隐藏天赋、技能总库、功法心法详细
职业生活	GDD-05/24	职业与生活技能、种族传承大师
经济系统	GDD-06/14/15	经济系统、稀有宝物拍卖、个性化成长
社交组织	GDD-07/13/16/29	帮派门派社交、佣兵悬赏、社交扩展、聊天系统
地图世界	GDD-08/09/18/22/25	大陆地图、出生地、地图副本遗迹引擎、随机事件、世界观
转生渡劫	GDD-11/12	种族转生转化、渡劫破镜
怪物装备	GDD-19/20	怪物图鉴、武器装备打造
数值平衡	GDD-21	数值平衡与联调参数总表
能量体系	GDD-23	能量体系与功法相性设计
修仙元素	GDD-27/28	修仙小说经典元素、神话体系与旧日邪神
成就图鉴	GDD-30	成就里程碑与图鉴系统
洞府系统	GDD-31	洞府与个人空间系统
NPC势力	GDD-32	NPC与势力关系系统
世界Boss	GDD-33	世界Boss与大型PVE协作机制

技术设计文档（TDD）- 10个

文档	说明
TDD-01	服务端整体架构设计（服务拓扑、水平扩展、消息队列、缓存、容灾、部署、监控）
TDD-02	客户端热更新技术方案
TDD-03	客户端架构设计（场景管理、状态管理、网络层、战报渲染）
TDD-04	数据库表结构设计
TDD-05	API接口设计
TDD-06	离线挂机结算系统设计
TDD-07	反作弊与安全设计
TDD-08	GM与运营后台设计
TDD-09	推送与通知系统设计
TDD-10	数据埋点与分析设计

需求文档（PRD）- 3个

文档	说明
PRD-01	核心玩法与系统需求文档
PRD-02	境界隔离系统需求文档
PRD-03	热更新与活动系统需求文档

快速开始

1. 准备环境变量

cp .env.example .env

.env 中已包含本地开发默认值，通常无需修改。

2. 一键启动全部服务

docker compose up -d

首次启动会自动完成：

• 拉取/构建 PostgreSQL 16、Nakama 3.24.2、Valkey 8、Nacos 2.x 镜像
• 自动创建 nakama（Nakama 元数据）和 honghuang（游戏业务）两个数据库
• 在 honghuang 库执行 database/migrations/001_init_schema.up.sql（含种族、境界、世界层、货币等 seed 数据）
• 自动创建 Nacos namespace honghuang 并导入 configs/nacos/*.yaml
• 编译并加载 server/honghuang-server.so 插件

3. 查看服务状态

docker compose ps
docker compose logs -f nakama

4. 常用端口

服务	端口	说明
Nakama	7349	gRPC API
Nakama	7350	Realtime / HTTP API
Nakama	7351	Console（admin / password）
PostgreSQL	5432	业务库 honghuang + Nakama 库
Valkey	6379	Redis 兼容缓存
Nacos	8848	配置中心 http://localhost:8848/nacos

5. 停止/重置

# 停止服务
docker compose down

# 停止并清空所有本地数据卷（彻底重置）
docker compose down -v

# 只重启 Nakama
docker compose restart nakama

目录说明

• server/ — Go 服务端源码与 Nakama 插件（骨架阶段）
• database/migrations/ — 数据库迁移脚本
• configs/nacos/ — Nacos 动态配置（GDD-21 数值参数）
• docker/ — 各服务 Dockerfile 与初始化脚本
• api/ — Protobuf / OpenAPI 定义
• client/ — Cocos Creator 3.x 客户端资源（骨架阶段）
• docs/ — GDD / TDD / PRD 等设计文档（核心产出）
  • docs/设计文档/ — GDD-00~33 游戏设计文档
  • docs/技术文档/ — TDD-01~10 技术设计文档
  • docs/需求文档/ — PRD-01~03 需求文档
  • docs/ai-collab/ — AI协作记录

本地开发 tip

• 修改 server/ 源码后，重新构建 Nakama 镜像：

  docker compose up -d --build nakama
  

• 修改 configs/nacos/*.yaml 后，重新执行配置导入：

  docker compose run --rm nacos-init
  

• 数据库迁移脚本可通过 scripts/migrate.sh、scripts/seed.sh、scripts/reset.sh 在本地 psql 环境执行（需安装 PostgreSQL 客户端）。