WMS_MAIN/app/lib/api_log_sink.js
liufumingren d129103d0b refactor(log): 接口流水改用 Egg 日志落盘,整表下线 wms_system_log
背景:接口流水原本逐条写 wms_system_log 单表(生产 687,030 行、.ibd 28.8 GB、DATA_FREE 仅 5 MB),
删行无法把空间还给操作系统;且每个 needLog 请求都要多一次 INSERT。改为经 Egg 自定义 logger 平铺落盘,
整表 DROP 回收磁盘(生产实测释放 28.8 GB,/www 可用 20G→49G);日志目录同时由 /root/logs/wms
迁到 /www/wwwlogs/wms,不再占用系统盘。

新增 app/lib/api_log_sink.js:
- 一行一条 `HH:mm:ss {JSON}`:前缀是本地时区时分秒,只给人眼定位(tail/grep 的时间锚点),与行内
  created_at(UTC ISO 8601)是同一时刻;机器解析请用 created_at。
- 时间前缀刻意放在代码里而不是 config 的 formatter —— 生产 config 不参与 deploy、由人工维护,
  放代码才能随发布自动生效(此前已因「代码上线、配套配置没上」出现过接口日志静默丢失)。
- 对象/数组一律 JSON.stringify,避免调用方漏 stringify 时落盘成 "[object Object]"。
- customLogger.apiLog 缺失时每个 worker 显式告警一次:egg 的 getLogger(name) 对未声明的 name 返回
  null 而不抛错,不处理就会「既不落盘、也无任何报错」。

新增迁移 database/migrations/20260927090000-offline-wms-system-log.js:
- up 用 information_schema 探测后 DROP TABLE(幂等);该表对 wms_store 是出边外键,无需关外键检查。
- down 用原生 DDL 重建:queryInterface.createTable 在 MySQL 下默认字符集是 utf8mb3,且不会生成原始
  DDL 里的 created_at ON UPDATE CURRENT_TIMESTAMP,只有原生 DDL 才能忠实还原。
- 已在开发库跑通 up → down → up:重建后 14 列、主键、store_id 索引、外键、utf8mb4 均与下线前一致。

下线代码:删除 app/model/system_log.js、app/service/systems/system_log.js(60 天保留期清理服务)、
app/schedule/system_log_cleanup.js(每日 03:00 清理任务);移除 config.systemLog(writeToDb 回滚开关)
与 config.systemLogCleanup;api_log_sink 不再保留任何入库分支。

文档与脚本:AI_METHOD_ROUTING.md 第 6 节清单移除已下线的 systems/system_log.js(文件数 220→219);
script/method-output-regression.cjs 的回放样本来源由 `SELECT ... FROM wms_system_log` 改为读
wms-api.log(含按天轮转文件),并改为先整体 parse、失败再截到第一个 `{` 重试,兼容带/不带时间前缀
两种行(在真实 EggLogger 上验证:FileBufferTransport 每 1000ms flush,需等过 1s 才能读到)。

注:按日切割与 31 天清理由 egg 内置 egg-logrotator 自动完成(walkLoggerFile 覆盖 customLogger),
无需额外配 cron。
2026-09-27 03:05:15 +08:00

191 lines
7.0 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// app/lib/api_log_sink.js
'use strict';
/**
* 接口日志落盘器:接口流水经 Egg 日志写出(`wms_system_log` 表已下线删除)。
*
* 设计要点:
* 1. 只使用 Egg 自带 logger(`app.getLogger('apiLog')`),不自行操作 fs ——
* egg-logger 的 FileTransport 以 O_APPEND 追加写、多 worker 共写同一文件、
* 自动创建目录并按天轮转,避免自建写流带来的「轮转后句柄失效 / ENOSPC 崩进程 /
* 每请求建流导致 fd 泄漏 / 退出前未 flush」等问题。
* 2. 一行一条记录,形如 `HH:mm:ss {JSON}`:
* 前缀是**本地时区的时分秒**,只给人眼定位用(tail/grep 时有个时间锚点),
* 机器解析请用行内的 `created_at`(ISO 8601 UTC,无时区歧义,与前缀为同一时刻);
* 前缀之后是沿用旧 `wms_system_log` 表结构的平铺 JSON(不嵌套,首字符是 `{`),
* 可直接用 grep 搜索;用 jq 时先剥前缀:`jq -R 'sub("^[0-9:]+ "; "") | fromjson'`。
* 3. 写入失败绝不影响接口返回:异常由调用方兜底,只记 app logger。
*/
/** body / result 截断长度:沿用旧 wms_system_log 入库时的长文本上限(65535) */
const TEXT_LIMIT = 65535;
/** customLogger.apiLog 缺失的告警只打一次,避免每请求刷屏 */
let warnedApiLogMissing = false;
/**
* 归一化为字符串,必要时截断。
* @param {*} value 原始值。
* @param {number} [limit] 截断长度(正数才生效),默认不截断。
* @return {string} 字符串结果。
*/
function toText(value, limit) {
if (value === undefined || value === null) {
return '';
}
// 对象/数组一律 JSON 序列化:调用方若漏了 JSON.stringify(例如 controller 直接把
// 响应对象塞进 logData.result),String() 会得到 "[object Object]" 而丢掉内容。
let text;
if (typeof value === 'string') {
text = value;
} else if (typeof value === 'object') {
try {
text = JSON.stringify(value);
} catch (e) {
text = String(value);
}
} else {
text = String(value);
}
if (Number(limit) > 0 && text.length > Number(limit)) {
return text.substring(0, Number(limit));
}
return text;
}
/**
* 构造一行平铺记录。
*
* 字段与顺序沿用旧 `wms_system_log` 入库时的入参:
* method / v / url / headers / auth / created_at / body / result / use_time / store_id / device。
* `created_at` 统一写 ISO 8601(UTC,带 Z):与原入库是同一时刻,但没有时区歧义。
*
* @param {object} logData 原始日志数据。
* @param {object} [options] 选项。
* @param {number} [options.startTime] 请求开始时间戳(ms),用于计算 use_time。
* @param {number} [options.useTime] 直接指定耗时(ms),优先于 startTime。
* @param {string} [options.device] 设备标识。
* @param {Date} [options.createdAt] 记录时间,默认当前时间。
* @return {object} 平铺记录对象。
*/
function buildRecord(logData, options = {}) {
const source = logData && typeof logData === 'object' ? logData : {};
const createdAt = options.createdAt instanceof Date ? options.createdAt : new Date();
let useTime = 0;
if (options.useTime !== undefined) {
useTime = Number(options.useTime);
} else if (Number(options.startTime) > 0) {
useTime = Date.now() - Number(options.startTime);
}
if (!Number.isFinite(useTime) || useTime < 0) {
useTime = 0;
}
return {
method: toText(source.method),
v: toText(source.v),
url: toText(source.url),
headers: toText(source.headers),
auth: toText(source.auth),
created_at: createdAt.toISOString(),
body: toText(source.body, TEXT_LIMIT),
result: toText(source.result, TEXT_LIMIT),
use_time: useTime,
store_id: source.store_id || null,
device: toText(options.device),
};
}
/**
* customLogger.apiLog 缺失时的显式告警(每个 worker 只打一次)。
*
* egg 的 `app.getLogger(name)` 对未声明的 name 返回 null 而不抛错,
* 若不处理就会「日志静默消失、且无任何报错」。
* 生产 config 不参与 deploy,「代码已上线、配套配置没上」极易发生,故必须显式报出来。
*
* @param {Egg.Application} app Egg 应用实例。
* @return {void}
*/
function warnApiLogMissing(app) {
if (warnedApiLogMissing) {
return;
}
warnedApiLogMissing = true;
const logger = app && typeof app.getLogger === 'function' ? app.getLogger('logger') : null;
if (logger && typeof logger.error === 'function') {
logger.error(
'[api_log_sink] config.customLogger.apiLog 未配置,接口日志不会落盘!' +
'请在 config.default.js 补上 customLogger.apiLog' +
'(生产 config 不参与 deploy,需手工同步到线上)。'
);
}
}
/**
* 两位补零。
* @param {number} value 待补零的数字。
* @return {string} 补零后的字符串。
*/
function pad2(value) {
return String(value).padStart(2, '0');
}
/**
* 生成日志行的时间前缀(本地时区 `HH:mm:ss`)。
*
* 整行内容本身是完整 JSON(首字符是 `{`),直接 tail/grep 时没有时间锚点,
* 故在行首加一个本地时间的时分秒前缀。前缀只给人看:
* 它与行内 `created_at` 取同一时刻,仅表达方式不同(本地 `HH:mm:ss` vs UTC ISO 8601)。
* 日期无需前缀 —— 日志按天轮转为 `wms-api.log.YYYY-MM-DD`,日期由文件名提供。
*
* @param {Date|string} [value] 记录时间;缺省或非法时回退当前时间。
* @return {string} `HH:mm:ss` 形式的前缀。
*/
function formatTimePrefix(value) {
const parsed = value instanceof Date ? value : new Date(value || Date.now());
const date = Number.isNaN(parsed.getTime()) ? new Date() : parsed;
return `${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}`;
}
/**
* 写出接口日志。
*
* 只落 Egg 日志文件(`config.customLogger.apiLog`);wms_system_log 表已下线,
* 不再存在任何入库分支。
*
* @param {Egg.Application} app Egg 应用实例。
* @param {object} payload 负载。
* @param {object} payload.logData 原始日志数据。
* @param {number} [payload.startTime] 请求开始时间戳(ms)。
* @param {number} [payload.useTime] 直接指定耗时(ms)。
* @param {string} [payload.device] 设备标识。
* @param {Date} [payload.createdAt] 记录时间。
* @return {Promise<object>} 实际写出的平铺记录。
*/
async function write(app, payload = {}) {
const record = buildRecord(payload.logData, {
startTime: payload.startTime,
useTime: payload.useTime,
device: payload.device,
createdAt: payload.createdAt,
});
const logger = app && typeof app.getLogger === 'function' ? app.getLogger('apiLog') : null;
if (logger) {
// 一行一条:`HH:mm:ss {完整 JSON}`,前缀与行内 created_at 是同一时刻
logger.info(`${formatTimePrefix(record.created_at)} ${JSON.stringify(record)}`);
} else {
warnApiLogMissing(app);
}
return record;
}
module.exports = {
TEXT_LIMIT,
buildRecord,
formatTimePrefix,
write,
};