docs: full README+INSTALL sync, plugin source field

2026-07-15 04:47:31 +08:00
parent 4fe1b30278
commit de22a9d9cb
3 changed files with 196 additions and 154 deletions
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,90 +1,34 @@
-# MC Report System — 部署文档
+# MC Report — 部署文档

 ## 环境要求

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

 ## 快速开始

 ```bash
-# 1. 安装依赖
 npm install
-
-# 2. 启动
 node backend/server.js
-
-# 3. 浏览器打开
+# → 浏览器打开 http://localhost:3100
 # → 自动跳转安装向导
 ```

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

-## 安装向导
-
-两步完成：
-
-**第1步 — 数据库配置**
+**第1步：数据库配置**
 - MySQL 主机（默认 localhost）
 - 端口（默认 3306）
 - 用户名 / 密码
 - 数据库名（不存在则自动创建）

-**第2步 — 创建服主账号**
+**第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`：
+## 配置文件 `data/config.json`

 ```json
 {
@@ -93,68 +37,74 @@ server {
  "db_user": "root",
  "db_pass": "",
  "db_name": "mc_report",
-  "jwt_secret": "(随机64位)",
-  "api_key": "(随机48位)"
+  "jwt_secret": "(安装时随机64位)",
+  "api_key": "(安装时随机48位)",
+  "external_api_key": "(安装时随机48位)"
 }
 ```

- `jwt_secret` 安装时随机生成，用于签发登录令牌
- `api_key` 安装时随机生成，前端自动注入请求头，保护 API 接口
-
-## 数据库
-
-MySQL 数据库安装时自动建表。如需备份：
+## 生产部署

 ```bash
-mysqldump -u root -p mc_report > backup_$(date +%Y%m%d).sql
+PORT=3100 CORS_ORIGIN=https://your-domain.com node backend/server.js
 ```

-## 上传文件
+### PM2

-存储在 `data/uploads/`，通过 `/api/uploads/:filename` 鉴权下载。
+```bash
+npm i -g pm2
+pm2 start backend/server.js --name mc-report
+pm2 save && pm2 startup
+```

-| 限制 | 值 |
-|------|----|
-| 单文件上限 | 50MB |
-| 每次最多 | 5 个 |
-| 允许格式 | JPG/PNG/GIF/WebP/MP4/WebM |
+### Nginx
+
+```nginx
+server {
+    listen 80;
+    server_name mc.example.com;
+    client_max_body_size 55m;
+
+    location / {
+        proxy_pass http://127.0.0.1:3100;
+        include nginx.inc;
+    }
+}
+```

 ## 邮件配置

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

 ## Webhook

-后台"通知配置"页面添加 Discord 兼容 Webhook，可选触发事件。
+后台 → 通知配置 → 添加 Discord Webhook URL → 选择触发事件（工单创建/认领/转交/更新）。

-## 目录结构
+## 数据库
+
+MySQL，安装时自动建表。备份：
+
+```bash
+mysqldump -u root -p mc_report > backup.sql
+```
+
+## 目录

 ```
 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/            # 上传文件
+│   ├── db.js
+│   ├── mailer.js
+│   ├── webhook.js
+│   ├── middleware/{auth,security,upload}.js
+│   └── routes/{auth,tickets,install,external,users,settings,export,polls,features,notifications,captcha,uploads}.js
+├── public/           # 前端 SPA（16 页面）
+├── mc-report-plugin/ # Paper 1.20+ 插件
+├── nginx.inc
+├── data/config.json
+├── data/uploads/
 ├── package.json
+├── README.md
 └── INSTALL.md
 ```
--- a/README.md
+++ b/README.md
@@ -1,93 +1,184 @@
 # MC Report System

-游戏玩家投诉建议申诉系统。支持 Web 端 + Paper 插件双端提交，MySQL 存储，JWT 鉴权，三级角色（服主/管理员/玩家）。
+游戏玩家投诉/建议/申诉系统。Web 端 + Paper 插件双端提交，MySQL 存储，JWT 鉴权，三级角色。

-## 功能
+## 功能模块

 | 模块 | 说明 |
 |------|------|
-| 举报 | 玩家举报违规行为，可指定目标玩家，上传截图/视频 |
-| 建议 | 玩家提交改进建议 |
-| 申诉 | 封禁申诉（Web端）+ 结果申诉（对处理不服） |
-| 接单制 | 管理员认领工单，一人一单，可转单 |
-| 审批流 | 待处理→处理中→待补充→已解决/已驳回→关闭 |
-| 投票 | 分组子服定时/不定时投票，盲投制，管理员1.5票权 |
-| 更新内容 | PCL风格功能投票，按时间/热度排序，分组筛选 |
-| 通知 | SMTP邮件 + Discord Webhook 双通道 |
-| 导出 | CSV格式导出工单/被举报人/日志（服主专享） |
-| 插件 | Paper 1.20+ 插件，游戏内注册/登录/举报/追踪 |
+| **举报** | 指定目标玩家或事项举报，可上传截图/视频（≤50MB），支持投诉管理员（仅服主可见） |
+| **建议** | 提交改进建议，仅服主处理 |
+| **申诉** | 封禁申诉 + 结果申诉（对处理结果不满可提交一次，关联原工单） |
+| **审批流** | 待处理→接单→处理中→待补充→已解决/已驳回→关闭（7天自动关闭） |
+| **接单制** | 管理员一人一单，可转单（带原因），处理备注（玩家不可见） |
+| **投票** | 分组/子服管理，定时/不定时投票，盲投制，管理员 1.5 票权 |
+| **更新内容** | Issues 风格，分状态（待定/计划中/已完成），讨论区，按时间/热度排序，分组筛选 |
+| **通知** | SMTP 邮件 + Discord Webhook（SSRF 防护），邮件模板自定义（编辑变量） |
+| **导出** | CSV（UTF-8 BOM），导出工单/被举报人统计/操作日志（仅服主） |
+| **插件** | Paper 1.20+，统一 `/report` 命令，游戏内注册/登录/举报/追踪 |
+| **找回密码** | 邮箱验证，1小时有效重置链接 |
+| **安装向导** | Web 页面配置 MySQL 连接 + 创建服主账号 |

 ## 快速开始

 ```bash
-# 安装依赖
 npm install
-
-# 启动
 node backend/server.js
-# → 访问 http://localhost:3100/#/install
+# → 打开 http://localhost:3100/#/install
 ```

-安装向导两步完成：MySQL 连接配置 → 创建服主账号。重启后自动加载业务路由。
+两步安装：填 MySQL 连接信息 → 建服主账号 → 重启生效。
+
+## 默认端口
+
+`3100`，可通过 `PORT=8080` 环境变量修改。

 ## 技术栈

 | 层 | 技术 |
 |----|------|
 | 后端 | Node.js + Express + mysql2 |
-| 前端 | Vanilla JS SPA + Hash路由 |
-| 数据库 | MySQL 5.7+ |
-| 认证 | JWT（256位随机密钥） |
-| 安全 | Helmet + Rate Limit + XSS + CSP |
+| 前端 | Vanilla JS SPA（Hash路由）+ Inter 字体 |
+| 数据库 | MySQL ≥ 5.7 |
+| 认证 | JWT（256 位随机密钥，72h 有效期） |
+| 安全 | Helmet 7 + Rate Limit（分路由限速）+ XSS 过滤 + CSP + API Key 常量时间比对 + SSRF 防护 |
+| 验证码 | SVG 混淆图片（svg-captcha，4 位字符 + 噪点 + 颜色变形） |
+| 文件上传 | Multer + MIME + 魔数字节校验，UUID 命名，web 外存储 |
 | 插件 | Paper API 1.20.4 + java.net.HttpURLConnection |

-## 角色权限
+## 角色权限矩阵

 | 操作 | 玩家 | 管理员 | 服主 |
 |------|:--:|:--:|:--:|
 | 提交工单 | ✅ | ✅ | ✅ |
-| 查看工单 | 自己 | 待处理+自己接的 | 全部 |
-| 接单 | — | 举报/申诉 | 全部 |
-| 处理工单 | — | 自己接的 | 全部 |
+| 查看工单 | 仅自己 | 待处理 + 自己接的 | 全部 |
+| 查看详情 | 仅自己 | 待处理 + 自己接的 | 全部 |
+| 接单认领 | — | 举报/申诉 | 全部 |
+| 更新处理备注 | — | 自己接的 | 全部 |
+| 变更状态 | — | 自己接的 | 全部 |
+| 转单 | — | 自己接的 | 全部 |
+| 回复工单 | 自己的 | ✅ | ✅ |
 | 用户管理 | — | ✅ | ✅ |
+| 邮件模板 | — | ✅ | ✅ |
+| 通知配置 | — | ✅ | ✅ |
 | 系统设置 | — | ✅ | ✅ |
 | 导出数据 | — | — | ✅ |
-| 投票管理 | — | — | ✅ |
+| 投票/更新管理 | — | — | ✅ |
+| 工单追加(未接单) | 自己的 | — | — |
+
+## 审批流状态
+
+```
+待处理(pending) ──接单──→ 处理中(processing) ──→ 已解决(resolved)
+    │                          │                    ├── 已驳回(rejected)
+    │                    待补充(awaiting_info)       └── 7天自动关闭(closed)
+    │                          │
+    └── 结果申诉 ──→ 申诉中(appealing) ──服主处理──→ 原工单关闭
+```
+
+- `closed` 为终态，仅服主可操作
+- 结果申诉仅一次，关联原工单，仅服主可见
+
+## 注册来源
+
+| 来源 | 标识 | UID 含义 |
+|------|------|---------|
+| 网易端 | `netease` | 网易 UID |
+| 皮肤站 | `skin` | 皮肤站 UID / Minecraft UUID |
+
+插件注册默认 `skin`。
+
+## 工单提交流程
+
+1. 填写标题 + 游戏名 + UID（登录后自动填充）
+2. 举报：选目标玩家 + 原因（内置选项或自定义）+ 可投诉管理员
+3. 建议：填写建议内容
+4. 申诉：填写封禁申诉理由
+5. 上传附件（可选，图片/视频 ≤50MB，最多5个）
+6. 提交 → 生成 tracking_token（Cookie 留存）
+
+## 外部 API
+
+| 端点 | 用途 | 认证 |
+|------|------|------|
+| `POST /api/external/auth/register` | 插件注册 | x-external-key |
+| `POST /api/external/auth/login` | 插件登录 | x-external-key |
+| `GET /api/external/my-tickets` | 我的工单(JWT) | x-external-key + Bearer |
+| `GET /api/external/my-tickets/:id` | 工单详情(JWT) | x-external-key + Bearer |
+| `POST /api/external/tickets` | 提交工单 | x-external-key |
+| `GET /api/external/all-tickets` | 全部工单 | x-external-key |
+| `GET /api/external/reported-players` | 被举报统计 | x-external-key |
+| `GET /api/external/stats` | 统计 | x-external-key |

 ## 部署

 ```bash
-# 生产环境变量
+# 环境变量
 PORT=3100 CORS_ORIGIN=https://your-domain.com node backend/server.js

-# PM2
+# PM2 持久化
 pm2 start backend/server.js --name mc-report

-# Nginx 反代
-# include nginx.inc;
+# Nginx 反代（还需 include nginx.inc）
+proxy_pass http://127.0.0.1:3100;
 ```

-## 目录
+## 插件命令
+
+```
+/report reg <密码> <邮箱> [用户名]    注册（默认用户=游戏名）
+/report login <密码> [用户名]        登录
+/report report [玩家] <原因>         举报
+/report suggest <内容>              建议
+/report track [id]                  追踪工单
+```
+
+配置 `plugins/MCReport/config.yml` 填写 `api_url` 和 `external_key`。
+
+## 目录结构

 ```
 ├── backend/
 │   ├── server.js              # Express 入口
-│   ├── db.js              # MySQL连接池 + 建表
-│   ├── mailer.js          # SMTP邮件
-│   ├── captcha.js         # SVG验证码
-│   ├── webhook.js         # Discord Webhook
+│   ├── db.js                  # MySQL 连接池 + 建表 + 迁移
+│   ├── mailer.js              # SMTP 邮件（缓存 transporter）
+│   ├── webhook.js             # Discord Webhook（SSRF 防护 + 10s 超时）
 │   ├── middleware/
-│   │   ├── auth.js        # JWT认证
-│   │   ├── security.js    # 限速+XSS+APIKey
-│   │   └── upload.js      # 文件上传安全
+│   │   ├── auth.js            # JWT（惰性缓存 secret）
+│   │   ├── security.js        # 限速 + XSS 递归 + API Key 常量时间比对
+│   │   └── upload.js          # 文件上传（仅读 256B 头验证魔数）
 │   └── routes/
-│       ├── auth.js        # 注册/登录
-│       ├── tickets.js     # 工单核心
-│       ├── install.js     # 安装向导
-│       ├── external.js    # 外部API(插件用)
-│       └── ...            # 其他路由
-├── public/                # 前端SPA
-├── mc-report-plugin/      # Paper 1.20+ 插件
+│       ├── auth.js            # 注册/登录/验证/找回密码
+│       ├── tickets.js         # 工单核心（自动关闭 + 状态流转）
+│       ├── install.js         # 安装向导（含 api_key 生成）
+│       ├── external.js        # 外部 API（插件 + Java 服务器）
+│       ├── users.js           # 用户管理（含 source 字段）
+│       ├── settings.js        # 站点设置 + 邮件模板编辑
+│       ├── export.js          # CSV 导出（服主专享）
+│       ├── polls.js           # 投票（分组/子服/定时）
+│       ├── features.js        # 更新内容（Issues 风格 + 讨论）
+│       ├── notifications.js   # Webhook 配置
+│       ├── captcha.js         # SVG 验证码
+│       └── uploads.js         # 附件下载（鉴权）
+├── public/                    # 前端 SPA (16 页面)
+├── mc-report-plugin/          # Paper 1.20+ 插件 (Maven)
 ├── nginx.inc                  # Nginx 额外配置
-└── data/                  # 运行时数据
+├── data/                      # config.json + uploads/
+├── README.md
+└── package.json
 ```
+
+## 安全
+
+| 措施 | 实现 |
+|------|------|
+| JWT 秘钥 | 256 位随机，惰性缓存，无硬编码 fallback |
+| API Key | 48 位随机，常量时间比对防时序攻击 |
+| 限速 | 登录 8/min、注册 3/min、工单 10/min、全局 300/min |
+| XSS | `sanitizeBody` 递归过滤 + `U.esc` 前端转义 |
+| CSP | Helmet + `script-src-attr 'unsafe-inline'` |
+| SQL 注入 | 全参数化查询 |
+| 文件上传 | 扩展名 + MIME + 魔数（仅读 256B）+ UUID 命名 |
+| Webhook SSRF | DNS 解析后过滤内网 IP |
+| 用户名枚举 | 注册/登录统一错误信息 |
+| CORS | 环境变量控制 + localhost 自动放行 |
--- a/mc-report-plugin/src/main/java/com/mcreport/plugin/ApiClient.java
+++ b/mc-report-plugin/src/main/java/com/mcreport/plugin/ApiClient.java
@@ -71,6 +71,7 @@ public class ApiClient {
        body.addProperty("email", email);
        body.addProperty("game_name", gameName);
        body.addProperty("game_uid", gameUid);
+        body.addProperty("source", "skin");
        return request("POST", "/auth/register", body, null);
    }