# xmmanageservice

**Repository Path**: xingbboy/xmmanageservice

## Basic Information

- **Project Name**: xmmanageservice
- **Description**: 魔兽争霸3 xm后台服务
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 魔兽后台

面向 Warcraft III 地图和游戏服务的管理后台，提供地图管理、地图访问控制、Lua 触发器编辑与校验、排行榜、玩家数据、游戏统计、归档、用户管理和安全防护等功能。

本项目由两个应用组成：

- **Java 后端**：基于 Spring Boot，提供业务 API、权限校验、数据库访问、Redis 缓存和外部服务通信。
- **Vue 前端**：基于 Vue 3，提供后台管理界面、数据展示、表单交互和 Lua 触发器编辑器。

## 功能概览

- 后台用户登录、Token 会话、角色权限和密码管理
- 魔兽地图信息、版本、CDKey 和访问权限管理
- Lua 触发器编辑、保存、校验和发布内容维护
- 排行榜配置、玩家排行数据、周期快照和扩展存储
- 游戏数据、玩家数据和每日统计查询
- 地图或排行榜数据归档
- 在线游戏用户和地图关联查询
- 安全守卫记录和异常用户管理
- Lua 执行日志与错误日志查询

## 技术栈

### 后端

- Java 8
- Spring Boot 2.7.18
- Spring Security
- MyBatis-Plus 3.5.5
- PostgreSQL 16
- Redis 8
- Maven
- BouncyCastle、Fastjson2、Gson

### 前端

- Vue 3
- Vite
- Vue Router
- Pinia
- Ant Design Vue
- Axios
- Less
- LuaParse

## 项目结构

```text
.
├── frontend/                         # Vue 3 前端
│   ├── src/api/                      # HTTP 请求封装
│   ├── src/components/               # 公共组件和 Lua 触发器编辑器
│   ├── src/layout/                   # 后台布局
│   ├── src/router/                   # 路由和登录拦截
│   └── src/views/                    # 业务页面
├── src/main/java/                    # Spring Boot 后端源码
│   └── com/pms/
│       ├── common/                   # 公共配置、权限、缓存和工具
│       └── modules/                  # system、map、trigger、ranking 等业务模块
├── src/main/resources/
│   ├── application.yml               # 后端配置
│   ├── schema.sql                    # 数据库结构
│   ├── data.sql                      # 初始化 SQL
│   └── mapper/                       # MyBatis XML Mapper
├── pom.xml                           # Maven 配置
├── docker-compose.yml                # 完整服务编排
├── Dockerfile                        # 后端镜像构建文件
└── .env.example                      # 环境变量示例
```

## 环境要求

本地开发需要：

- JDK 8
- Maven 3.8 或更高版本
- Node.js 18 或更高版本
- npm
- PostgreSQL 16 或兼容版本
- Redis 6 或更高版本

也可以使用 Docker Compose 运行 PostgreSQL 和 Redis。

## 配置

复制环境变量示例并修改密码：

```bash
copy .env.example .env
```

Linux/macOS 可以使用：

```bash
cp .env.example .env
```

启动前必须设置 `PMS_ADMIN_PASSWORD`。如果未设置，后端会生成随机管理员密码并写入应用日志，不适合作为生产环境初始化方式。

主要变量如下：

| 变量 | 说明 |
| --- | --- |
| `POSTGRES_PASSWORD` | Docker Compose 使用的 PostgreSQL 密码 |
| `REDIS_PASSWORD` | Docker Compose 使用的 Redis 密码 |
| `PMS_ADMIN_PASSWORD` | 首次创建管理员账号时使用的密码 |
| `DB_URL` | 后端 PostgreSQL JDBC 地址 |
| `DB_USERNAME` | PostgreSQL 用户名 |
| `DB_PASSWORD` | 后端 PostgreSQL 密码 |
| `REDIS_HOST` | Redis 地址 |
| `REDIS_PORT` | Redis 端口 |
| `REDIS_PASSWORD` | 后端 Redis 密码 |
| `CERT_SERVICE_URL` | 可选的外部证书服务地址 |

后端默认配置位于 `src/main/resources/application.yml`，默认端口为 `8080`，接口上下文路径为 `/api`。数据库启动时会执行 `schema.sql`，管理员账号由应用启动初始化逻辑创建。

**注意**：`DB_PASSWORD` 和 `REDIS_PASSWORD` 没有默认值，本地启动后端前必须设置，否则应用无法连接数据库和 Redis。

生产环境必须替换所有示例密码，并妥善保管 `.env` 和其他包含凭据的配置文件。

### 本地启动后端时的环境变量设置

在 IDE（IDEA / VS Code）中运行时，直接在 Run Configuration 的 Environment variables 里填写：

```text
DB_URL=jdbc:postgresql://localhost:5432/pms_db
DB_USERNAME=postgres
DB_PASSWORD=你的数据库密码
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=你的Redis密码
PMS_ADMIN_PASSWORD=你的管理员初始密码
```

命令行启动时，先在当前终端设置环境变量再执行 `mvn spring-boot:run`。

Windows PowerShell：

```powershell
$env:DB_URL = "jdbc:postgresql://localhost:5432/pms_db"
$env:DB_USERNAME = "postgres"
$env:DB_PASSWORD = "你的数据库密码"
$env:REDIS_HOST = "localhost"
$env:REDIS_PORT = "6379"
$env:REDIS_PASSWORD = "你的Redis密码"
$env:PMS_ADMIN_PASSWORD = "你的管理员初始密码"
mvn spring-boot:run
```

Linux/macOS：

```bash
export DB_URL="jdbc:postgresql://localhost:5432/pms_db"
export DB_USERNAME="postgres"
export DB_PASSWORD="你的数据库密码"
export REDIS_HOST="localhost"
export REDIS_PORT="6379"
export REDIS_PASSWORD="你的Redis密码"
export PMS_ADMIN_PASSWORD="你的管理员初始密码"
mvn spring-boot:run
```

如果使用 Docker Compose 部署，以上变量由 `docker-compose.yml` 自动注入，只需在 `.env` 中填好 `POSTGRES_PASSWORD`、`REDIS_PASSWORD`、`PMS_ADMIN_PASSWORD` 即可。

## 本地开发

### 启动数据库和 Redis

```bash
docker compose up -d postgres redis
```

### 启动后端

在项目根目录执行：

```bash
mvn spring-boot:run
```

或构建并运行：

```bash
mvn clean package
java -jar target/pms-1.0.0-SNAPSHOT.jar
```

后端地址：`http://localhost:8080/api`

### 启动前端

```bash
cd frontend
npm ci
npm run dev
```

前端开发地址通常为：`http://localhost:3000`

Vite 会将 `/api` 请求代理到 `http://localhost:8080`。具体代理配置以 `frontend/vite.config.js` 为准。

### 前端构建

```bash
cd frontend
npm run build
```

构建产物位于 `frontend/dist/`，可由 Nginx 或前端 Docker 镜像提供服务。

## Docker 部署

`docker-compose.yml` 定义了以下服务：

- `postgres`：PostgreSQL 数据库，宿主机本地端口 `5432`
- `redis`：Redis，宿主机本地端口 `6379`
- `game`：游戏服务，端口 `7777`
- `log`：日志服务，端口 `7778`
- `backend`：Java 后端，端口 `8080`
- `frontend`：Nginx 前端，端口 `80`

Compose 文件引用已经构建好的 `w3service:latest`、`backend:latest` 和 `frontend:latest` 镜像。构建镜像后再启动完整服务：

```bash
mvn clean package
docker build -t backend:latest -f Dockerfile target

cd frontend
npm ci
npm run build
docker build -t frontend:latest .

cd ..
docker compose up -d
```

> 后端 Dockerfile 的构建上下文需要是 `target/`，因为 Dockerfile 使用 `COPY pms-1.0.0-SNAPSHOT.jar pms.jar`。如果使用其他构建方式，请确保该 JAR 位于 Docker 构建上下文根目录。

如果游戏服务镜像还未构建，请先在相邻的 `魔兽服务器-公开版` 项目中构建 `w3service:latest`。完整部署需要该项目、数据库和 Redis 配置保持一致。

查看服务状态：

```bash
docker compose ps
docker compose logs -f backend
```

## 相关接口和访问地址

- 前端：`http://localhost/`
- 后端 API：`http://localhost:8080/api`
- 前端 Nginx 会将 `/api` 转发到后端服务

后端接口按业务模块组织，主要模块包括：用户、地图、触发器、排行榜、统计、归档、游戏用户和安全守卫。

## 安全注意事项

- 不要在仓库中提交 `.env`、真实数据库密码、Redis 密码或私钥。
- 生产环境不要使用示例密码或默认管理员密码。
- Redis 和 PostgreSQL 默认只映射到宿主机本地地址，公开部署时应结合网络策略重新评估。
- 管理接口应通过网关、内网或其他鉴权措施保护。
- 修改证书服务地址或通信公钥前，应确认服务端协议和密钥配置同步更新。
- 对外提供服务时建议启用 HTTPS，并限制数据库、Redis 和管理端口的公网访问。

## 许可证

当前仓库未提供独立许可证文件。使用、修改和再发布前，请根据项目实际授权约定确认许可范围。