From 257cd140512525cf94d587a497711317e0165b92 Mon Sep 17 00:00:00 2001 From: canglan Date: Wed, 19 Aug 2026 19:12:34 +0800 Subject: [PATCH] feat: external API for QQ bot - client id+secret auth, ticket tracking, bans, per-server data MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - db: api_clients table + server_groups.alias + tickets/bans server_name (auto-migrate) - external.js: client_id+secret auth (multi-client, bcrypt, show-once secret), legacy x-external-key compat, JWT pass-through - POST /tickets (optional server), GET /tickets/track?token= (full lifecycle) - GET/POST /bans, reported-players/stats/all-tickets with server filter - GET /servers (alias list), client CRUD (owner/admin, audit logged) - resolveServer: alias | 分组/子服 | server_name - polls.js: server_groups CRUD with alias (add/edit, dup check) - servers page: alias display + edit; new 外部API page: client mgmt + quick docs - API.md: full external API section (auth matrix, server param syntax) - verified: 37 checks incl. resolveServer sandbox (alias/group/fallback) --- backend/db.js | 17 +++ backend/routes/external.js | 234 ++++++++++++++++++++++++++------ backend/routes/polls.js | 19 ++- docs/API.md | 52 +++++-- public/index.html | 1 + public/js/app.js | 3 + public/js/pages/external-api.js | 81 +++++++++++ public/js/pages/servers.js | 40 +++++- 8 files changed, 393 insertions(+), 54 deletions(-) create mode 100644 public/js/pages/external-api.js diff --git a/backend/db.js b/backend/db.js index 97a0b17..e512e10 100644 --- a/backend/db.js +++ b/backend/db.js @@ -103,6 +103,7 @@ async function initSchema(connection) { id INT AUTO_INCREMENT PRIMARY KEY, user_id INT, type ENUM('report','suggestion','appeal','result_appeal') NOT NULL, + server_name VARCHAR(100) NOT NULL DEFAULT '', title VARCHAR(100) NOT NULL, status ENUM('pending','processing','awaiting_info','appealing','resolved','rejected','closed') NOT NULL DEFAULT 'pending', priority ENUM('low','medium','high','urgent') NOT NULL DEFAULT 'medium', @@ -250,9 +251,20 @@ async function initSchema(connection) { id INT AUTO_INCREMENT PRIMARY KEY, group_name VARCHAR(100) NOT NULL, server_name VARCHAR(100) NOT NULL, + alias VARCHAR(100) NOT NULL DEFAULT '', UNIQUE KEY uk_group_server (group_name, server_name) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); + await createIfNotExists('api_clients', `CREATE TABLE api_clients ( + id INT AUTO_INCREMENT PRIMARY KEY, + name VARCHAR(100) NOT NULL, + client_id VARCHAR(64) NOT NULL UNIQUE, + secret_hash VARCHAR(255) NOT NULL, + active TINYINT(1) NOT NULL DEFAULT 1, + created_at DATETIME DEFAULT CURRENT_TIMESTAMP, + INDEX idx_active (active) + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); + await createIfNotExists('user_servers', `CREATE TABLE user_servers ( user_id INT NOT NULL, group_name VARCHAR(100) NOT NULL, @@ -265,6 +277,7 @@ async function initSchema(connection) { id INT AUTO_INCREMENT PRIMARY KEY, player_name VARCHAR(50) NOT NULL, player_uid VARCHAR(50), + server_name VARCHAR(100) NOT NULL DEFAULT '', source VARCHAR(10) DEFAULT '', reason TEXT, type ENUM('ban','mute','warn','other') NOT NULL DEFAULT 'ban', @@ -374,6 +387,10 @@ async function migrateAdditions(db) { try { await db.execute(`CREATE TABLE IF NOT EXISTS feature_votes (id INT AUTO_INCREMENT PRIMARY KEY, item_id INT NOT NULL, user_id INT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, UNIQUE KEY uk_item_user (item_id, user_id), INDEX idx_item (item_id)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); } catch {} try { await db.execute(`CREATE TABLE IF NOT EXISTS feature_comments (id INT AUTO_INCREMENT PRIMARY KEY, item_id INT NOT NULL, user_id INT NOT NULL, content TEXT NOT NULL, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_item (item_id)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); } catch {} try { await db.execute(`CREATE TABLE IF NOT EXISTS server_groups (id INT AUTO_INCREMENT PRIMARY KEY, group_name VARCHAR(100) NOT NULL, server_name VARCHAR(100) NOT NULL, UNIQUE KEY uk_group_server (group_name, server_name)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); } catch {} + try { await db.execute("ALTER TABLE server_groups ADD COLUMN alias VARCHAR(100) NOT NULL DEFAULT ''"); } catch {} + try { await db.execute(`CREATE TABLE IF NOT EXISTS api_clients (id INT AUTO_INCREMENT PRIMARY KEY, name VARCHAR(100) NOT NULL, client_id VARCHAR(64) NOT NULL UNIQUE, secret_hash VARCHAR(255) NOT NULL, active TINYINT(1) NOT NULL DEFAULT 1, created_at DATETIME DEFAULT CURRENT_TIMESTAMP, INDEX idx_active (active)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4`); } catch {} + try { await db.execute("ALTER TABLE tickets ADD COLUMN server_name VARCHAR(100) NOT NULL DEFAULT ''"); } catch {} + try { await db.execute("ALTER TABLE bans ADD COLUMN server_name VARCHAR(100) NOT NULL DEFAULT ''"); } catch {} } async function seedTemplates(db) { diff --git a/backend/routes/external.js b/backend/routes/external.js index e9008a9..01f8c49 100644 --- a/backend/routes/external.js +++ b/backend/routes/external.js @@ -1,24 +1,103 @@ const express = require('express'); const bcrypt = require('bcryptjs'); +const crypto = require('crypto'); const { v4: uuid } = require('uuid'); -const { query, getRow, getConfig, getPool } = require('../db'); +const { query, getRow, getConfig } = require('../db'); const { generateToken, authenticate } = require('../middleware/auth'); const { sendEmail } = require('../mailer'); +const { logSystem } = require('../logger'); const router = express.Router(); +// ============ 鉴权 ============ +// 支持三种方式(免用户登录): +// 1. x-external-key: 旧版单 key(config.external_api_key) +// 2. x-api-client-id + x-api-secret: api_clients 表多客户端(推荐) +// 3. Authorization: Bearer : 用户登录态(插件用) + function getExternalKey() { try { return getConfig()?.external_api_key || process.env.EXTERNAL_API_KEY || ''; } catch { return process.env.EXTERNAL_API_KEY || ''; } } -function externalAuth(req, res, next) { - const required = getExternalKey(); - if (!required) return next(); - if (req.headers['x-external-key'] === required) return next(); - return res.status(401).json({ error: '未授权' }); +async function clientAuth(req, res, next) { + // 方式1: 旧版单 key + const legacy = getExternalKey(); + if (legacy && req.headers['x-external-key'] === legacy) return next(); + + // 方式2: client_id + secret + const cid = req.headers['x-api-client-id']; + const secret = req.headers['x-api-secret']; + if (cid && secret) { + try { + const client = await getRow('SELECT * FROM api_clients WHERE client_id = ?', [cid]); + if (client && client.active && bcrypt.compareSync(secret, client.secret_hash)) return next(); + } catch {} + return res.status(401).json({ error: '客户端鉴权失败' }); + } + + // 方式3: 用户 JWT(交给 authenticate 处理, 这里放行) + if (req.headers['authorization']?.startsWith('Bearer ')) return next(); + + // 方式1 配置了 key 但没带 → 拒绝(避免裸奔) + if (legacy) return res.status(401).json({ error: '未授权' }); + // 什么都没配置: 允许(兼容旧部署) + return next(); } -// ---- Auth (no external key needed) ---- +// 服务器 alias 解析: '分组/服务器' 或 alias 或 server_name +async function resolveServer(q) { + if (!q) return { group_name: '', server_name: '', alias: '' }; + if (q.includes('/')) { + const [g, s] = q.split('/'); + return { group_name: g.trim(), server_name: s.trim(), alias: '' }; + } + const row = await getRow('SELECT group_name, server_name, alias FROM server_groups WHERE alias = ? OR server_name = ? LIMIT 1', [q, q]); + if (row) return { group_name: row.group_name, server_name: row.server_name, alias: row.alias }; + return { group_name: '', server_name: q, alias: '' }; +} + +// ============ 客户端管理(owner) ============ +router.post('/clients', authenticate, async (req, res) => { + try { + if (!['owner','admin'].includes(req.user.role)) return res.status(403).json({ error: '无权限' }); + const { name } = req.body; + if (!name) return res.status(400).json({ error: '名称必填' }); + const clientId = 'c_' + crypto.randomBytes(12).toString('hex'); + const secret = 's_' + crypto.randomBytes(24).toString('hex'); + await query('INSERT INTO api_clients(name, client_id, secret_hash) VALUES (?,?,?)', [name, clientId, bcrypt.hashSync(secret, 10)]); + await logSystem('info', 'api', `创建外部API客户端: ${name}`, { client_id: clientId }); + res.json({ client_id: clientId, secret, message: '请立即保存 secret(仅显示一次)' }); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +router.get('/clients', authenticate, async (req, res) => { + try { + if (!['owner','admin'].includes(req.user.role)) return res.status(403).json({ error: '无权限' }); + const rows = await query('SELECT id, name, client_id, active, created_at FROM api_clients ORDER BY id DESC'); + res.json(rows); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +router.put('/clients/:id', authenticate, async (req, res) => { + try { + if (!['owner','admin'].includes(req.user.role)) return res.status(403).json({ error: '无权限' }); + const { active } = req.body; + await query('UPDATE api_clients SET active = ? WHERE id = ?', [active ? 1 : 0, req.params.id]); + await logSystem('info', 'api', `更新外部API客户端 #${req.params.id}`, { active: !!active }); + res.json({ message: '已更新' }); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +router.delete('/clients/:id', authenticate, async (req, res) => { + try { + if (!['owner','admin'].includes(req.user.role)) return res.status(403).json({ error: '无权限' }); + await query('DELETE FROM api_clients WHERE id = ?', [req.params.id]); + await logSystem('info', 'api', `删除外部API客户端 #${req.params.id}`); + res.json({ message: '已删除' }); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +// ============ Auth (no external key needed) ============ router.post('/auth/register', async (req, res) => { try { const { username, password, email, game_name, game_uid, source } = req.body; @@ -58,48 +137,72 @@ router.post('/auth/login', async (req, res) => { } catch (e) { res.status(500).json({ error: '服务器错误' }); } }); -// ---- Plugin API (JWT auth) ---- -router.use(externalAuth); +// ---- 以下接口: 免用户登录(client_id+secret / x-external-key / JWT) ---- +router.use(clientAuth); +// ============ 工单: 提交 ============ +// server: '分组/服务器名' 或 alias 或 server_name(可选) +router.post('/tickets', async (req, res) => { + try { + const { type, title, reporter_game_name, reporter_game_uid, target_game_name, target_game_uid, reason, description, is_admin_complaint, server } = req.body; + if (!type || !['report','suggestion','appeal'].includes(type)) return res.status(400).json({ error: '类型不正确' }); + if (!title || !reporter_game_name || !reporter_game_uid) return res.status(400).json({ error: '必填字段不完整' }); + if (type === 'report' && !reason) return res.status(400).json({ error: '请填写举报原因' }); + if (type === 'suggestion' && !description) return res.status(400).json({ error: '建议内容不能为空' }); + if (type === 'appeal' && (!reason || !description)) return res.status(400).json({ error: '请填写完整申诉信息' }); + + const countRow = await getRow("SELECT COUNT(*) as c FROM tickets WHERE (reporter_game_name = ? OR reporter_game_uid = ?) AND status IN ('pending','processing','awaiting_info','appealing')", [reporter_game_name, reporter_game_uid]); + if (countRow.c >= 5) return res.status(400).json({ error: '待处理工单已达上限' }); + + const sv = await resolveServer(server); + const trackingToken = uuid(); + const r = await query(`INSERT INTO tickets(type,title,reporter_game_name,reporter_game_uid,target_game_name,target_game_uid,reason,description,tracking_token,is_admin_complaint,server_name) VALUES (?,?,?,?,?,?,?,?,?,?,?)`, + [type, title, reporter_game_name, reporter_game_uid, target_game_name||'', target_game_uid||'', reason||'', description||'', trackingToken, is_admin_complaint?1:0, sv.server_name]); + await query("INSERT INTO responses(ticket_id,content,is_staff) VALUES (?,?,0)", [r.insertId, `游戏内提交\n类型: ${type}\n提交人: ${reporter_game_name} (UID: ${reporter_game_uid})${sv.server_name?'\n服务器: '+sv.server_name:''}`]); + res.status(201).json({ id: r.insertId, tracking_token: trackingToken, server: sv.server_name }); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +// ============ 工单: 追踪(token 即凭据, 提交人可查) ============ +router.get('/tickets/track', async (req, res) => { + try { + const { token } = req.query; + if (!token) return res.status(400).json({ error: '缺少 tracking_token' }); + const t = await getRow(`SELECT id, type, title, status, priority, reporter_game_name, reporter_game_uid, + target_game_name, target_game_uid, reason, description, assigned_to, claim_note, server_name, created_at, updated_at + FROM tickets WHERE tracking_token = ?`, [token]); + if (!t) return res.status(404).json({ error: '工单不存在' }); + t.responses = await query('SELECT content, is_staff, created_at FROM responses WHERE ticket_id = ? ORDER BY created_at ASC', [t.id]); + res.json(t); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +// 我的工单(JWT 用户) router.get('/my-tickets', authenticate, async (req, res) => { const { limit } = req.query; - const rows = await query(`SELECT id, type, title, status, priority, created_at, updated_at FROM tickets WHERE user_id = ? ORDER BY updated_at DESC LIMIT ?`, [req.user.id, Math.min(parseInt(limit)||10, 50)]); + const rows = await query(`SELECT id, type, title, status, priority, server_name, created_at, updated_at FROM tickets WHERE user_id = ? ORDER BY updated_at DESC LIMIT ?`, [req.user.id, Math.min(parseInt(limit)||10, 50)]); res.json({ list: rows }); }); router.get('/my-tickets/:id', authenticate, async (req, res) => { const t = await getRow(`SELECT id, type, title, status, priority, reporter_game_name, reporter_game_uid, - target_game_name, target_game_uid, reason, description, assigned_to, claim_note, created_at, updated_at + target_game_name, target_game_uid, reason, description, assigned_to, claim_note, server_name, created_at, updated_at FROM tickets WHERE id = ? AND user_id = ?`, [req.params.id, req.user.id]); if (!t) return res.status(404).json({ error: '工单不存在' }); res.json(t); }); -router.post('/tickets', async (req, res) => { - const { type, title, reporter_game_name, reporter_game_uid, target_game_name, target_game_uid, reason, description, is_admin_complaint } = req.body; - if (!type || !['report','suggestion','appeal'].includes(type)) return res.status(400).json({ error: '类型不正确' }); - if (!title || !reporter_game_name || !reporter_game_uid) return res.status(400).json({ error: '必填字段不完整' }); - if (type === 'report' && !reason) return res.status(400).json({ error: '请填写举报原因' }); - if (type === 'suggestion' && !description) return res.status(400).json({ error: '建议内容不能为空' }); - if (type === 'appeal' && (!reason || !description)) return res.status(400).json({ error: '请填写完整申诉信息' }); - - const countRow = await getRow("SELECT COUNT(*) as c FROM tickets WHERE (reporter_game_name = ? OR reporter_game_uid = ?) AND status IN ('pending','processing','awaiting_info','appealing')", [reporter_game_name, reporter_game_uid]); - if (countRow.c >= 5) return res.status(400).json({ error: '待处理工单已达上限' }); - - const trackingToken = uuid(); - const [r] = await query(`INSERT INTO tickets(type,title,reporter_game_name,reporter_game_uid,target_game_name,target_game_uid,reason,description,tracking_token,is_admin_complaint) VALUES (?,?,?,?,?,?,?,?,?,?)`, - [type, title, reporter_game_name, reporter_game_uid, target_game_name||'', target_game_uid||'', reason||'', description||'', trackingToken, is_admin_complaint?1:0]); - await query("INSERT INTO responses(ticket_id,content,is_staff) VALUES (?,?,0)", [r.insertId, `游戏内提交\n类型: ${type}\n提交人: ${reporter_game_name} (UID: ${reporter_game_uid})`]); - res.status(201).json({ id: r.insertId, tracking_token: trackingToken }); -}); - -// ---- Java Server API (x-external-key only) ---- +// ============ 工单列表(带 server 过滤) ============ router.get('/all-tickets', async (req, res) => { - const { type, status, page, limit } = req.query; - let q = `SELECT id, type, title, status, priority, reporter_game_name, reporter_game_uid, target_game_name, target_game_uid, reason, description, assigned_to, claim_note, created_at, updated_at FROM tickets WHERE 1=1`; + const { type, status, server, page, limit } = req.query; + let q = `SELECT id, type, title, status, priority, reporter_game_name, reporter_game_uid, target_game_name, target_game_uid, reason, description, assigned_to, claim_note, server_name, created_at, updated_at FROM tickets WHERE 1=1`; const p = []; if (type) { q += ' AND type = ?'; p.push(type); } if (status) { q += ' AND status = ?'; p.push(status); } + if (server) { + const sv = await resolveServer(server); + q += ' AND server_name = ?'; p.push(sv.server_name); + } const pg = parseInt(page) || 1; const lm = Math.min(parseInt(limit) || 50, 200); q += ` ORDER BY updated_at DESC LIMIT ${(pg-1)*lm}, ${lm}`; @@ -114,23 +217,72 @@ router.get('/all-tickets/:id', async (req, res) => { res.json(t); }); +// ============ 封禁 ============ +// 拉取封禁: ?server=alias|server_name|分组/服务器&status=active|expired|appealed|lifted&player=&limit= +router.get('/bans', async (req, res) => { + const { server, status, player, page, limit } = req.query; + let q = 'SELECT id, player_name, player_uid, source, reason, type, duration, server_name, status, created_at, expires_at FROM bans WHERE 1=1'; + const p = []; + if (server) { + const sv = await resolveServer(server); + q += ' AND server_name = ?'; p.push(sv.server_name); + } + if (status) { q += ' AND status = ?'; p.push(status); } + if (player) { q += ' AND (player_name = ? OR player_uid = ?)'; p.push(player, player); } + const pg = parseInt(page) || 1; + const lm = Math.min(parseInt(limit) || 100, 500); + q += ` ORDER BY created_at DESC LIMIT ${(pg-1)*lm}, ${lm}`; + res.json(await query(q, p)); +}); + +// 新增封禁(可带 server) +router.post('/bans', async (req, res) => { + try { + const { player_name, player_uid, source, reason, type, duration, expires_at, server, status } = req.body; + if (!player_name) return res.status(400).json({ error: 'player_name 必填' }); + const sv = await resolveServer(server); + const r = await query(`INSERT INTO bans(player_name, player_uid, source, reason, type, duration, server_name, status, expires_at) VALUES (?,?,?,?,?,?,?,?,?)`, + [player_name, player_uid||'', source||'', reason||'', ['ban','mute','warn','other'].includes(type)?type:'ban', duration||'', sv.server_name, ['active','expired','appealed','lifted'].includes(status)?status:'active', expires_at||null]); + await logSystem('info', 'api', `外部创建封禁: ${player_name}`, { server: sv.server_name, type: type||'ban' }); + res.status(201).json({ id: r.insertId }); + } catch (e) { res.status(500).json({ error: e.message }); } +}); + +// ============ 被举报人统计(带 server 过滤) ============ router.get('/reported-players', async (req, res) => { - const rows = await query(`SELECT target_game_name, target_game_uid, COUNT(*) as total, + const { server } = req.query; + let q = `SELECT target_game_name, target_game_uid, COUNT(*) as total, SUM(CASE WHEN status IN ('pending','processing','awaiting_info','appealing') THEN 1 ELSE 0 END) as active, SUM(CASE WHEN status='resolved' THEN 1 ELSE 0 END) as resolved, MAX(created_at) as last_report - FROM tickets WHERE type='report' AND target_game_name IS NOT NULL AND target_game_name != '' - GROUP BY target_game_name, target_game_uid ORDER BY total DESC LIMIT 500`); + FROM tickets WHERE type='report' AND target_game_name IS NOT NULL AND target_game_name != ''`; + const p = []; + if (server) { + const sv = await resolveServer(server); + q += ' AND server_name = ?'; p.push(sv.server_name); + } + q += ' GROUP BY target_game_name, target_game_uid ORDER BY total DESC LIMIT 500'; + res.json(await query(q, p)); +}); + +// ============ 服务器列表(含 alias) ============ +router.get('/servers', async (req, res) => { + const rows = await query('SELECT group_name, server_name, alias FROM server_groups ORDER BY group_name, server_name'); res.json(rows); }); router.get('/stats', async (req, res) => { - const [[{c:total}], byType, byStatus] = await Promise.all([ - query('SELECT COUNT(*) as c FROM tickets'), - query('SELECT type, COUNT(*) as c FROM tickets GROUP BY type'), - query('SELECT status, COUNT(*) as c FROM tickets GROUP BY status'), - ]); - res.json({ total, byType, byStatus }); + const { server } = req.query; + let q = 'SELECT COUNT(*) as c FROM tickets'; + const p = []; + if (server) { + const sv = await resolveServer(server); + q += ' WHERE server_name = ?'; p.push(sv.server_name); + } + const total = await getRow(q, p); + const byType = await query('SELECT type, COUNT(*) as c FROM tickets ' + (server ? 'WHERE server_name = ? ' : '') + 'GROUP BY type', p); + const byStatus = await query('SELECT status, COUNT(*) as c FROM tickets ' + (server ? 'WHERE server_name = ? ' : '') + 'GROUP BY status', p); + res.json({ total: total.c, byType, byStatus }); }); module.exports = router; diff --git a/backend/routes/polls.js b/backend/routes/polls.js index 5a8ce4d..7df85ef 100644 --- a/backend/routes/polls.js +++ b/backend/routes/polls.js @@ -9,12 +9,27 @@ router.get('/groups', authenticate, async (req, res) => { }); router.post('/groups', authenticate, requireRole('owner'), async (req, res) => { - const { group_name, server_name } = req.body; + const { group_name, server_name, alias } = req.body; if (!group_name || !server_name) return res.status(400).json({ error: '分组名和子服名为必填' }); - await query('INSERT IGNORE INTO server_groups(group_name, server_name) VALUES (?,?)', [group_name, server_name]); + if (alias) { + const dup = await getRow('SELECT id FROM server_groups WHERE alias = ?', [alias]); + if (dup) return res.status(400).json({ error: '该外部别名已被使用' }); + } + await query('INSERT IGNORE INTO server_groups(group_name, server_name, alias) VALUES (?,?,?)', [group_name, server_name, alias || '']); res.status(201).json({ message: '已添加' }); }); +router.put('/groups/:id', authenticate, requireRole('owner'), async (req, res) => { + const { group_name, server_name, alias } = req.body; + if (!group_name || !server_name) return res.status(400).json({ error: '分组名和子服名为必填' }); + if (alias) { + const dup = await getRow('SELECT id FROM server_groups WHERE alias = ? AND id != ?', [alias, req.params.id]); + if (dup) return res.status(400).json({ error: '该外部别名已被使用' }); + } + await query('UPDATE server_groups SET group_name = ?, server_name = ?, alias = ? WHERE id = ?', [group_name, server_name, alias || '', req.params.id]); + res.json({ message: '已更新' }); +}); + router.delete('/groups/:id', authenticate, requireRole('owner'), async (req, res) => { await query('DELETE FROM server_groups WHERE id = ?', [req.params.id]); res.json({ message: '已删除' }); diff --git a/docs/API.md b/docs/API.md index 2b6ca19..69b45cf 100644 --- a/docs/API.md +++ b/docs/API.md @@ -329,15 +329,41 @@ Base URL: `http://:3100/api` | 端点 | 认证 | 说明 | |------|------|------| -| POST /external/auth/register | external-key | 插件注册(邮箱验证链接) | -| POST /external/auth/login | external-key | 插件登录,返回 JWT | -| GET /external/my-tickets | external-key + Bearer | 我的工单列表(limit ≤50) | -| GET /external/my-tickets/:id | external-key + Bearer | 我的工单详情 | -| POST /external/tickets | external-key | 游戏内提交工单(自动写主身份) | -| GET /external/all-tickets | external-key | 全部工单(分页 page/limit ≤200) | -| GET /external/all-tickets/:id | external-key | 工单详情(含回复/附件) | -| GET /external/reported-players | external-key | 被举报统计 | -| GET /external/stats | external-key | 工单统计 | +| POST /external/auth/register | — | 插件注册(邮箱验证链接) | +| POST /external/auth/login | — | 插件登录,返回 JWT | +| GET /external/my-tickets | Bearer | 我的工单列表(limit ≤50) | +| GET /external/my-tickets/:id | Bearer | 我的工单详情 | +| POST /external/tickets | client | 提交工单(带 `server` 可选;返回 id + tracking_token) | +| GET /external/tickets/track?token= | client | 按追踪码查工单状态+回复(提交→处理→结束全流程) | +| GET /external/all-tickets | client | 全部工单(分页 page/limit ≤200,可按 `server`/`status`/`type` 过滤) | +| GET /external/all-tickets/:id | client | 工单详情(含回复/附件) | +| GET /external/bans?server=&status=&player= | client | 拉取封禁列表(可按子服/状态/玩家过滤) | +| POST /external/bans | client | 新增封禁(可带 `server`) | +| GET /external/reported-players?server= | client | 被举报统计(可按子服过滤) | +| GET /external/servers | client | 服务器列表(含外部别名) | +| GET /external/stats?server= | client | 工单统计(可按子服过滤) | +| POST /external/clients | Bearer(owner/admin) | 创建 API 客户端,返回 client_id + secret(仅显示一次) | +| GET /external/clients | Bearer(owner/admin) | 客户端列表 | +| PUT /external/clients/:id | Bearer(owner/admin) | 启用/停用客户端 | +| DELETE /external/clients/:id | Bearer(owner/admin) | 删除客户端 | + +### 外部鉴权(三选一) + +| 方式 | 请求头 | 适用 | +|------|--------|------| +| 多客户端(推荐) | `x-api-client-id` + `x-api-secret` | QQ机器人等外部系统,后台可创建/停用多个客户端 | +| 旧版单 key | `x-external-key` | 兼容旧部署(`config.external_api_key`) | +| 用户 JWT | `Authorization: Bearer ` | 插件/已登录用户 | + +### 子服务器定位(`server` 参数) + +每个子服可在「服务器管理」配置**外部别名(alias)**,外部 API 的 `server` 参数支持三种写法: + +- **别名**: `survival`(推荐,改名不影响) +- **分组/子服**: `网易服务器/生存服` +- **子服名**: `生存服`(同名时取第一个) + +工单/封禁按提交时的 `server` 归属存储,查询时用同一参数即可精确拉取对应子服数据。 --- @@ -365,3 +391,11 @@ Base URL: `http://:3100/api` 5. 工单提交:登录用户可选择任一已绑定身份(后端校验归属);匿名仍走表单字段 > 老数据无需手工处理,服务启动时自动迁移;`users` 表原有字段(主身份)保持不变,完全向后兼容。 + +外部 API 功能新增迁移(幂等,服务启动自动执行): + +1. 创建 `api_clients` 表(多客户端鉴权) +2. `server_groups` 加 `alias` 列(子服外部别名) +3. `tickets` / `bans` 加 `server_name` 列(按子服归属存储) + +> 老工单/封禁 `server_name` 为空串,不影响原有查询;新提交的数据自动带子服归属。 diff --git a/public/index.html b/public/index.html index 365a54e..9c087f8 100644 --- a/public/index.html +++ b/public/index.html @@ -69,6 +69,7 @@ + diff --git a/public/js/app.js b/public/js/app.js index 57db167..01401e7 100644 --- a/public/js/app.js +++ b/public/js/app.js @@ -9,6 +9,7 @@ const App = { { id: 'polls', label: '投票', icon: 'fa-poll', roles: ['owner'] }, { id: 'features', label: '更新内容', icon: 'fa-lightbulb', roles: ['owner'] }, { id: 'notifications', label: '通知配置', icon: 'fa-bell', roles: ['owner'] }, + { id: 'external-api', label: '外部API', icon: 'fa-key', roles: ['owner'] }, { id: 'templates', label: '邮件模板', icon: 'fa-envelope', roles: ['owner'] }, { id: 'settings', label: '系统设置', icon: 'fa-cog', roles: ['owner'] }, { id: 'logs', label: '系统日志', icon: 'fa-clipboard-list', roles: ['owner','admin'] }, @@ -92,6 +93,7 @@ const App = { case 'tracking': this.renderMain('追踪工单', TrackingPage, param); break; case 'users': this.renderMain('用户管理', UsersPage, param); break; case 'notifications': this.renderMain('通知配置', NotificationsPage, param); break; + case 'external-api': this.renderMain('外部API', ExternalApiPage, param); break; case 'templates': this.renderMain('邮件模板', TemplatesPage, param); break; case 'settings': this.renderMain('系统设置', SettingsPage, param); break; case 'export': this.renderMain('数据导出', ExportPage, param); break; @@ -173,6 +175,7 @@ window.UnclaimedPage = UnclaimedPage; window.UsersPage = UsersPage; window.TemplatesPage = TemplatesPage; window.NotificationsPage = NotificationsPage; +window.ExternalApiPage = ExternalApiPage; window.SettingsPage = SettingsPage; window.ExportPage = ExportPage; window.PollsPage = PollsPage; diff --git a/public/js/pages/external-api.js b/public/js/pages/external-api.js new file mode 100644 index 0000000..bdc9234 --- /dev/null +++ b/public/js/pages/external-api.js @@ -0,0 +1,81 @@ +const ExternalApiPage = { + async render() { return '
'; }, + + async mount() { + document.getElementById('page-title').textContent = '外部API'; + document.getElementById('page-actions').innerHTML = ''; + await this.load(); + }, + + async load() { + const ct = document.getElementById('page-content'); + try { + const clients = await API.get('/external/clients'); + ct.innerHTML = ` +
API 客户端
+ ${clients.length === 0 ? '

暂无客户端

' : `
${clients.map(c => ` + + + + + + + + `).join('')}
#名称Client ID状态创建时间操作
${c.id}${U.esc(c.name)}${U.esc(c.client_id)}${c.active ? '启用' : '停用'}${U.date(c.created_at)} + + +
`} +
鉴权方式: 请求头 x-api-client-id + x-api-secret(推荐);旧版单 key 仍可用 x-external-key。secret 仅创建时显示一次,请立即保存。
+
+ +
接口速览(免用户登录, 需上述鉴权头)
+ + + + + + + + + + +
方法路径说明
POST/api/external/tickets提交工单(举报/建议/申诉),返回 id + tracking_token;可带 server(别名或「分组/子服」)
GET/api/external/tickets/track?token=xxx按追踪码查工单状态 + 回复,从提交到结束全程可查
GET/api/external/all-tickets?server=&status=&type=&page=&limit=工单列表(可按子服过滤)
GET/api/external/all-tickets/:id工单详情(含回复/附件)
GET/api/external/bans?server=&status=&player=拉取封禁列表
POST/api/external/bans新增封禁(可带 server)
GET/api/external/reported-players?server=被举报人统计
GET/api/external/servers服务器列表(含别名)
GET/api/external/stats?server=工单统计
POST/api/external/clients创建客户端(需登录态, 本页操作)
+

完整请求/响应示例见 docs/API.md 外部API章节。

+ `; + } catch (e) { ct.innerHTML = `
${e.message}
`; } + }, + + async showCreate() { + U.modal('创建 API 客户端', ` +
+
+
+
+ `); + document.getElementById('apikey-form').onsubmit = async e => { + e.preventDefault(); + try { + const r = await API.post('/external/clients', { name: document.getElementById('ak-name').value }); + App.closeModal(); + U.modal('客户端已创建', ` +

请立即保存以下凭据(secret 只显示一次):

+
+
Client ID: ${U.esc(r.client_id)}
+
Secret: ${U.esc(r.secret)}
+
+
+ `); + this.load(); + } catch(ex){alert(ex.message);} + }; + }, + + async toggle(id, active) { + try { await API.put(`/external/clients/${id}`, { active: !!active }); this.load(); } catch(ex){alert(ex.message);} + }, + + async del(id) { + if (!await U.confirm('确认删除该客户端？')) return; + try { await API.delete(`/external/clients/${id}`); this.load(); } catch(ex){alert(ex.message);} + } +}; diff --git a/public/js/pages/servers.js b/public/js/pages/servers.js index 171e237..2a771a9 100644 --- a/public/js/pages/servers.js +++ b/public/js/pages/servers.js @@ -29,7 +29,8 @@ const ServersPage = { ${servers.map(s => `
${U.esc(s.server_name)} - ${Auth.isOwner() ? `` : ''} + ${s.alias ? `${U.esc(s.alias)}` : ''} + ${Auth.isOwner() ? `` : ''}
`).join('')} @@ -43,14 +44,49 @@ const ServersPage = {
+
外部 API 可用别名或「分组/子服名」定位此服务器
`); document.getElementById('add-srv-form').onsubmit = async e => { e.preventDefault(); - try { await API.post('/polls/groups', { group_name: document.getElementById('as-group').value, server_name: document.getElementById('as-server').value }); App.closeModal(); this.load(); } catch(ex){alert(ex.message);} + try { + await API.post('/polls/groups', { + group_name: document.getElementById('as-group').value, + server_name: document.getElementById('as-server').value, + alias: document.getElementById('as-alias').value.trim(), + }); + App.closeModal(); this.load(); + } catch(ex){alert(ex.message);} }; }, + async showEdit(id) { + try { + const groups = await API.get('/polls/groups'); + const s = groups.find(x => x.id === id); + if (!s) return alert('未找到'); + U.modal('编辑服务器', ` +
+
+
+
外部 API 可用别名或「分组/子服名」定位此服务器
+
+
+ `); + document.getElementById('edit-srv-form').onsubmit = async e => { + e.preventDefault(); + try { + await API.put(`/polls/groups/${id}`, { + group_name: document.getElementById('es-group').value, + server_name: document.getElementById('es-server').value, + alias: document.getElementById('es-alias').value.trim(), + }); + App.closeModal(); this.load(); + } catch(ex){alert(ex.message);} + }; + } catch (ex) { alert(ex.message); } + }, + async del(id) { if (!await U.confirm('确认删除？')) return; try { await API.req('DELETE', '/polls/groups/'+id); this.load(); } catch(ex){alert(ex.message);} } };