# MC Report System — 部署文档

## 环境要求

- Node.js ≥ 18 / npm ≥ 9
- MySQL ≥ 5.7（或 MariaDB ≥ 10.2）
- 任意操作系统

## 快速开始

```bash
# 1. 安装依赖
npm install

# 2. 启动
node backend/server.js

# 3. 浏览器打开
#    → 自动跳转安装向导
```

访问 `http://localhost:3100`，将自动进入安装向导。

## 安装向导

两步完成：

**第1步 — 数据库配置**
- MySQL 主机（默认 localhost）
- 端口（默认 3306）
- 用户名 / 密码
- 数据库名（不存在则自动创建）

**第2步 — 创建服主账号**
- 站点名称、站点地址
- 服主用户名、密码、邮箱、游戏名

点击完成后配置写入 `data/config.json`，**重启服务器**即可加载业务路由。

## 生产环境

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `PORT` | 监听端口 | `3100` |
| `CORS_ORIGIN` | 允许的跨域来源 | `http://localhost:3100` |

### 启动（生产）

```bash
# Linux / macOS
PORT=8080 CORS_ORIGIN=https://your-domain.com node backend/server.js

# Windows PowerShell
$env:PORT="8080"
$env:CORS_ORIGIN="https://your-domain.com"
node backend/server.js
```

### 持久化进程（推荐 pm2）

```bash
npm i -g pm2
pm2 start backend/server.js --name mc-report
pm2 save
pm2 startup
```

### Nginx 反代

```nginx
server {
    listen 80;
    server_name report.your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

## 配置文件

安装后生成 `data/config.json`：

```json
{
  "db_host": "localhost",
  "db_port": 3306,
  "db_user": "root",
  "db_pass": "",
  "db_name": "mc_report",
  "jwt_secret": "(随机64位)",
  "api_key": "(随机48位)"
}
```

- `jwt_secret` 安装时随机生成，用于签发登录令牌
- `api_key` 安装时随机生成，前端自动注入请求头，保护 API 接口

## 数据库

MySQL 数据库安装时自动建表。如需备份：

```bash
mysqldump -u root -p mc_report > backup_$(date +%Y%m%d).sql
```

## 上传文件

存储在 `data/uploads/`，通过 `/api/uploads/:filename` 鉴权下载。

| 限制 | 值 |
|------|----|
| 单文件上限 | 50MB |
| 每次最多 | 5 个 |
| 允许格式 | JPG/PNG/GIF/WebP/MP4/WebM |

## 邮件配置

后台"系统设置"页面配置 SMTP。未配置时注册用户自动激活。

## Webhook

后台"通知配置"页面添加 Discord 兼容 Webhook，可选触发事件。

## 目录结构

```
mc-report/
├── backend/
│   ├── server.js
│   ├── db.js              # MySQL 连接池 + 建表
│   ├── mailer.js           # SMTP 邮件
│   ├── captcha.js          # 算术验证码
│   ├── webhook.js          # Webhook 通知
│   ├── middleware/
│   │   ├── auth.js         # JWT 认证
│   │   ├── upload.js       # 文件上传安全
│   │   └── security.js     # 限速 + XSS + API Key
│   └── routes/
│       ├── install.js      # 安装向导 API
│       ├── auth.js         # 注册/登录
│       ├── tickets.js      # 工单核心
│       ├── users.js        # 用户管理
│       ├── settings.js     # 设置 + 邮件模板
│       ├── export.js       # 数据导出
│       ├── captcha.js      # 验证码
│       ├── notifications.js # Webhook 配置
│       └── uploads.js      # 附件下载
├── public/                 # 前端 SPA
├── data/
│   ├── config.json         # 数据库连接 + 密钥
│   └── uploads/            # 上传文件
├── package.json
└── INSTALL.md
```