canglan
188e083719
Previous async validateAuth() approach caused: recursion loop, wrong /me path (404 -> session cleared), init() fetching auth-required settings without token (cleared session every load). New synchronous approach: - Auth.expired(): decodes JWT payload locally, checks exp timestamp - Auth.logged(): token+user exist AND not expired; auto-clears stale session on expiry (no network, no async, no loops) - route(): simple sync guard - if !Auth.logged() reset + redirect to #/login; home page stays public (clears stale cookie only) - API.req: 401 response -> Auth.reset() + redirect to login unless on public page (fallback for server-side revocation/invalid signature) - Removed validateAuth/_validating/_doRoute entirely
MC Report System
游戏玩家投诉/建议/申诉系统。Web 端 + Paper 插件双端提交，MySQL 存储，JWT 鉴权，三级角色。
功能模块
| 模块 | 说明 |
|---|---|
| 举报 | 指定目标玩家或事项举报，可上传截图/视频（≤50MB），支持投诉管理员（仅服主可见） |
| 建议 | 提交改进建议，仅服主处理 |
| 申诉 | 封禁申诉 + 结果申诉（对处理结果不满可提交一次，关联原工单） |
| 审批流 | 待处理→接单→处理中→待补充→已解决/已驳回→关闭（7天自动关闭） |
| 接单制 | 管理员一人一单，可转单（带原因），处理备注（玩家不可见） |
| 投票 | 分组/子服管理，定时/不定时投票，盲投制，管理员 1.5 票权 |
| 更新内容 | Issues 风格，分状态（待定/计划中/已完成），讨论区，按时间/热度排序，分组筛选 |
| 通知 | SMTP 邮件 + Webhook（Discord/企微/QQ/飞书，SSRF 防护），邮件模板自定义 |
| 日志 | 邮件日志 + 系统日志（Webhook 失败/服务器错误），后台可视化排查 |
| 导出 | CSV（UTF-8 BOM），导出工单/被举报人统计/操作日志（仅服主） |
| 外部 API | ID+Secret → SESSION 鉴权；工单提交/追踪、封禁拉取/新增、按子服过滤（机器人/插件对接） |
| 找回密码 | 邮箱验证，1小时有效重置链接 |
| 多来源身份 | 来源动态管理（后台增删），一个账号可绑定多个来源身份，无默认来源 |
| 安装向导 | Web 页面配置 MySQL 连接 + 创建服主账号（完成后无需重启） |
API 文档
- 完整接口文档:docs/API.md(认证/工单/封禁/用户/设置/通知/投票/更新/导出/外部 API)
- 第三方外部 API(机器人/插件):docs/EXTERNAL-API.md(ID+Secret 换取 SESSION、提交工单、进度追踪、封禁拉取、按子服拉数据)
- MC 插件对接示例:docs/PLUGIN-GUIDE.md(Java 实现:换取 SESSION、提交举报、同步封禁)
快速开始
npm install
node backend/server.js
# → 打开 http://localhost:3100/#/install
两步安装：填 MySQL 连接信息 → 建服主账号 → 重启生效。
默认端口
3100，可通过 PORT=8080 环境变量修改。
技术栈
| 层 | 技术 |
|---|---|
| 后端 | Node.js + Express + mysql2 |
| 前端 | Vanilla JS SPA（Hash路由）+ Inter 字体 |
| 数据库 | MySQL ≥ 5.7 / MariaDB ≥ 10.2 |
| 认证 | Web: JWT（256 位随机密钥，72h 有效期）；外部 API: ID+Secret → SESSION（24h，单会话） |
| 安全 | Helmet 7 + Rate Limit（分路由限速）+ XSS 过滤 + CSP + SSRF 防护 |
| 验证码 | SVG 混淆图片（svg-captcha，4 位字符 + 噪点 + 颜色变形） |
| 文件上传 | Multer + MIME + 魔数字节校验，UUID 命名，web 外存储 |
| 许可证 | AGPLv3 |
角色权限矩阵
| 操作 | 玩家 | 管理员 | 服主 |
|---|---|---|---|
| 提交工单 | ✅ | ✅ | ✅ |
| 查看工单 | 仅自己 | 待处理 + 自己接的 | 全部 |
| 查看详情 | 仅自己 | 待处理 + 自己接的 | 全部 |
| 接单认领 | — | 举报/申诉 | 全部 |
| 更新处理备注 | — | 自己接的 | 全部 |
| 变更状态 | — | 自己接的 | 全部 |
| 转单 | — | 自己接的 | 全部 |
| 回复工单 | 自己的 | ✅ | ✅ |
| 用户管理 | — | ✅ | ✅ |
| 邮件模板 | — | ✅ | ✅ |
| 通知配置 | — | ✅ | ✅ |
| 系统设置 | — | ✅ | ✅ |
| 导出数据 | — | — | ✅ |
| 投票/更新管理 | — | — | ✅ |
| 工单追加(未接单) | 自己的 | — | — |
审批流状态
待处理(pending) ──接单──→ 处理中(processing) ──→ 已解决(resolved)
│ │ ├── 已驳回(rejected)
│ 待补充(awaiting_info) └── 7天自动关闭(closed)
│ │
└── 结果申诉 ──→ 申诉中(appealing) ──服主处理──→ 原工单关闭
closed为终态，仅服主可操作- 结果申诉仅一次，关联原工单，仅服主可见
注册来源与多身份
来源在后台「来源管理」页动态维护(可增删/停用/排序,不设默认)。初始预置:
| 来源 | 标识 | 说明 |
|---|---|---|
| 网易端 | netease |
网易端身份 |
| 皮肤站 | skin |
皮肤站身份 |
多身份绑定:一个账号可绑定多个来源身份(控制台「我的身份」或 POST /api/auth/identities 管理)。提交工单时可选择使用哪个身份;user_identities 表由启动时自动迁移回填,users 表主身份字段保持不变(完全兼容旧数据)。
工单提交流程
- 填写标题 + 游戏名(登录后自动填充)
- 举报:选目标玩家 + 原因(内置选项或自定义)+ 可投诉管理员
- 建议:填写建议内容
- 申诉:填写封禁申诉理由
- 上传附件(可选,图片/视频 ≤50MB,最多5个)
- 提交 → 生成 tracking_token(Cookie 留存)
外部 API
| 端点 | 用途 | 认证 |
|---|---|---|
POST /api/external/auth/session |
ID+Secret 换取 SESSION | x-api-client-id + x-api-secret |
POST /api/external/auth/register |
插件注册 | Bearer SESSION |
POST /api/external/tickets |
提交工单(带 server 可选) | Bearer SESSION |
GET /api/external/tickets/track |
按追踪码查进度 | Bearer SESSION |
GET /api/external/all-tickets |
工单列表(可按子服过滤) | Bearer SESSION |
GET/POST /api/external/bans |
拉取/新增封禁 | Bearer SESSION |
GET /api/external/reported-players |
被举报统计 | Bearer SESSION |
GET /api/external/servers |
服务器列表(含别名) | Bearer SESSION |
GET /api/external/stats |
统计 | Bearer SESSION |
完整说明见 docs/EXTERNAL-API.md;MC 插件对接示例见 docs/PLUGIN-GUIDE.md。
部署
# 环境变量
PORT=3100 CORS_ORIGIN=https://your-domain.com node backend/server.js
# PM2 持久化
pm2 start backend/server.js --name mc-report
# Nginx 反代（还需 include nginx.inc）
proxy_pass http://127.0.0.1:3100;
完整部署步骤见 INSTALL.md。
MC 插件对接
仓库不内置插件代码,按 docs/PLUGIN-GUIDE.md 用 Java 自行实现即可:
POST /api/external/auth/session:ID+Secret 换取 SESSION(自动续期)POST /api/external/tickets:游戏内提交举报/建议/申诉(带子服)GET /api/external/tickets/track:玩家查询处理进度(tracking_token)GET/POST /api/external/bans:同步本服封禁
目录结构
├── backend/
│ ├── server.js # Express 入口(动态加载业务路由)
│ ├── db.js # MySQL 连接池 + 建表 + 幂等迁移
│ ├── logger.js # 邮件/系统日志(写库, 失败不影响主流程)
│ ├── mailer.js # SMTP 邮件(自动记录日志)
│ ├── webhook.js # Webhook 推送(SSRF 防护 + 10s 超时)
│ ├── middleware/
│ │ ├── auth.js # JWT(Web 鉴权)
│ │ ├── security.js # 限速 + XSS + API Key 校验
│ │ └── upload.js # 文件上传(魔数校验)
│ └── routes/
│ ├── auth.js # 注册/登录/验证/找回密码/多身份
│ ├── tickets.js # 工单核心(状态流转)
│ ├── install.js # 安装向导
│ ├── external.js # 外部 API(SESSION 鉴权)
│ ├── sources.js # 动态来源管理
│ ├── users.js # 用户管理
│ ├── logs.js # 日志查询
│ ├── settings.js # 站点设置 + UUID 查询
│ ├── export.js # CSV 导出
│ ├── polls.js # 投票 + 服务器分组
│ ├── features.js # 更新内容
│ ├── notifications.js # 通知配置
│ ├── captcha.js # SVG 验证码
│ └── uploads.js # 附件下载
├── public/ # 前端 SPA
├── docs/ # 文档(API / 外部API / 插件指南)
├── nginx.inc # Nginx 额外配置
├── data/ # config.json + uploads/ (git 忽略)
├── README.md
├── INSTALL.md
├── LICENSE # AGPLv3
└── 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 自动放行 |