Skip to content
BranchesTags

Repository files navigation

🏔️ Minecraft QQ Territory Platform

网易 IceTown 租赁服 —— 圈地管理系统

基于 Next.js + Node.js + tRPC 的现代化全栈 Minecraft 服务器领地管理平台。为 QQ 群内 Minecraft 基岩版玩家提供领地创建、成员管理、积分捐赠、管理员审批等一站式管理功能。

📁 项目结构

minecraft-qq-territory-platform/
├── apps/
│   ├── server/                # 后端 API 服务 (Express + tRPC)
│   │   ├── src/
│   │   │   ├── app.ts         # Express 应用入口
│   │   │   ├── server.ts      # HTTP 服务器启动
│   │   │   ├── trpc/          # tRPC 路由器 & 中间件
│   │   │   ├── services/      # 业务逻辑层
│   │   │   ├── middlewares/   # Express 中间件 (安全、限流)
│   │   │   ├── jobs/          # 定时任务 (成员清理、群同步)
│   │   │   ├── listeners/     # 事件监听器
│   │   │   ├── database/      # Prisma 数据库连接
│   │   │   └── utils/         # 工具函数
│   │   ├── prisma/            # 数据库 Schema & 迁移
│   │   └── Dockerfile
│   │
│   └── web/                   # 前端 Web 应用 (Next.js + Ant Design)
│       ├── app/               # Next.js App Router 页面
│       │   ├── dashboard/     # 控制台页面
│       │   ├── login/         # 登录页
│       │   └── register/      # 注册页
│       ├── components/        # UI 组件
│       ├── hooks/             # React Hooks (tRPC + React Query)
│       ├── lib/               # 工具库 (tRPC 客户端、认证)
│       └── Dockerfile
│
├── packages/
│   └── shared/                # 共享类型 & Zod 校验
│       └── src/
│           ├── schemas/       # 输入/输出 Schema 定义
│           └── router.ts      # AppRouter 类型导出
│
├── docker-compose.yml         # 统一 Docker 编排
├── turbo.json                 # Turborepo 任务编排
├── pnpm-workspace.yaml       # pnpm Workspace 配置
└── README.md

🚀 技术栈

层级 技术 版本
前端框架 Next.js (App Router) 16.x
UI 组件库 Ant Design 6.x
样式 Tailwind CSS 4.x
状态/缓存 React Query (TanStack) 5.x
API 通信 tRPC 11.x
后端框架 Express 5.x
类型安全 API tRPC Server 11.x
数据校验 Zod 4.x
ORM Prisma 6.x
数据库 MySQL 8.0
实时通信 Socket.IO 4.x
QQ 机器人 node-napcat-ts 0.4.x
认证 JWT + OAuth2 —
构建工具 Turborepo + pnpm —
部署 Docker + PM2 + Nginx —

🔧 快速开始

环境要求

  • Node.js >= 20
  • pnpm >= 10
  • MySQL >= 8.0
  • Napcat QQ 机器人 (可选，用于群同步功能)

1. 克隆项目

git clone <repo-url>
cd minecraft-qq-territory-platform

2. 安装依赖

pnpm install

3. 配置环境变量

复制环境变量模板并填入实际值：

cp .env.example .env

主要配置项：

# 数据库
DATABASE_URL="mysql://user:password@localhost:3306/ice_town"

# JWT 密钥
JWT_SECRET=your-secret-key

# Napcat QQ 机器人
NAPCAT_URL=ws://localhost:6098
NAPCAT_TOKEN=your_napcat_token
NAPCAT_GROUPID=你的QQ群号
ADMIN_QQ=你的QQ号

# 跨域来源
ALLOW_ORIGIN=http://localhost:3101

4. 初始化数据库

# 生成 Prisma Client
pnpm prisma:gen

# 执行数据库迁移
cd apps/server
npx prisma migrate deploy

5. 启动开发环境

# 同时启动前后端（需要 Turborepo）
pnpm dev

# 或分别启动
pnpm dev:server   # 后端 → http://localhost:3000
pnpm dev:web      # 前端 → http://localhost:3101

6. 访问

🐳 Docker 部署

# 构建并启动所有服务
docker compose up -d

# 查看日志
docker compose logs -f

# 停止
docker compose down

服务映射：

服务 端口
前端 (Nginx) 80, 443
后端 API 3000

📡 API 概览 (tRPC)

所有 API 通过 tRPC 暴露，具有完整的端到端类型安全。

认证 (auth.*)

过程 类型 说明
auth.register Mutation 用户注册（发送验证码）
auth.login Mutation 用户登录（设置 Cookie）
auth.authorize Query OAuth2 授权
auth.token Mutation OAuth2 获取 Token
auth.refreshToken Mutation 刷新 Access Token

用户 (user.*)

过程 类型 说明
user.me Query 获取当前用户信息
user.updateNickname Mutation 修改昵称（30天冷却）

领地 (territory.*)

过程 类型 说明
territory.create Mutation 创建领地
territory.myTerritories Query 我的领地列表
territory.updateLocation Mutation 更新领地区域
territory.requestDelete Mutation 申请删除领地
territory.invite Mutation 邀请成员
territory.acceptInvite Mutation 接受邀请
territory.revokeInvite Mutation 撤销邀请
territory.donate Mutation 捐赠积分
territory.removeMember Mutation 移除成员

管理员 (admin.*) 需要管理员权限

过程 类型 说明
admin.tasks Query 管理任务列表
admin.process Mutation 处理管理任务

通知 (notification.*)

过程 类型 说明
notification.unread Query 未读通知列表
notification.markRead Mutation 标记已读

🏗️ 架构设计

graph TB
    subgraph "前端 (apps/web)"
        Next[Next.js App]
        TRPC_C[@trpc/client]
        RQ[React Query]
        SIO_C[Socket.IO Client]
    end

    subgraph "后端 (apps/server)"
        Express[Express Server]
        TRPC_S[tRPC Server]
        SIO_S[Socket.IO Server]
        Jobs[定时任务]
        Listeners[事件监听]
        Services[业务服务层]
        Prisma[Prisma ORM]
    end

    subgraph "共享 (packages/shared)"
        Schemas[Zod Schemas]
        Types[TypeScript Types]
    end

    subgraph "外部"
        MySQL[(MySQL)]
        Napcat[Napcat QQ Bot]
    end

    Next -->|HTTP/tRPC| Express
    TRPC_C -->|类型推导| Schemas
    Express --> TRPC_S
    TRPC_S --> Services
    Services --> Prisma
    Prisma --> MySQL
    Jobs --> Services
    Listeners --> Napcat
    SIO_C <-->|WebSocket| SIO_S
    TRPC_S -->|校验| Schemas
Loading

📦 包说明

包名 路径 说明
@ice-town/server apps/server Express + tRPC 后端服务
@ice-town/web apps/web Next.js 前端应用
@ice-town/shared packages/shared 共享 Zod Schema & 类型定义

🧪 开发指南

添加新的 API

  1. 在 packages/shared/src/schemas/ 定义 Zod Schema
  2. 在 apps/server/src/trpc/routers/ 创建或扩展 Router
  3. 前端自动获得类型推导，无需手动同步

数据库迁移

cd apps/server
npx prisma migrate dev --name description

类型检查

pnpm type-check

📄 许可证

ISC

🏔️ IceTown — 让 Minecraft 领地管理更简单

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages