0

.vscode/tasks.json

@@ -15,6 +15,17 @@
                 "clear": true
             },
             "problemMatcher": []
+        },
+        {
+            "label": "检查近期服务端 Bug",
+            "type": "shell",
+            "command": "${workspaceFolder}/local-error-monitor/run.sh",
+            "presentation": {
+                "reveal": "always",
+                "panel": "dedicated",
+                "clear": true
+            },
+            "problemMatcher": []
         }
     ]
-}
+}

README.md

@@ -95,6 +95,12 @@ curl -H "x-internal-token: your-token" "http://localhost:3050/internal/error-log
 curl -H "x-internal-token: your-token" -X POST "http://localhost:3050/internal/error-logs/1/mark-fixed"
 ```
 
+完整错误日志采集和本机检查配置见:
+
+```bash
+doc/server_error_log_monitor.md
+```
+
 ## API端点
 
 

doc/server_error_log_monitor.md

@@ -0,0 +1,332 @@
+# 服务器错误日志检查配置说明
+
+本文档记录 `miaoguo_system_server` 的服务端错误日志采集、入库、查询、本机检查和 Codex 定期检查配置。
+
+## 目标
+
+线上 Node.js 服务出现异常时，把错误写入 MySQL 的 `SystemErrorLogs` 表，并提供内部 API 查询。
+
+当前链路:
+
+```text
+Koa / console.error / unhandledRejection / uncaughtException
+        -> SystemErrorLogs
+PM2 error log
+        -> scripts/collect-pm2-error-logs.js
+        -> SystemErrorLogs
+本机 VS Code / Codex
+        -> SSH 到服务器
+        -> curl http://127.0.0.1:3050/internal/error-logs
+```
+
+## 相关文件
+
+- `src/util/errorLogger.js`: 应用内错误采集入口
+- `src/model/systemErrorLog.js`: `SystemErrorLogs` 表和查询模型
+- `src/api/internal/routes.js`: 内部错误日志 API 路由
+- `src/api/internal/errorLogController.js`: 内部 API controller
+- `scripts/collect-pm2-error-logs.js`: 服务器 PM2 error log 兜底采集
+- `scripts/poll-error-logs.js`: 本机持续轮询脚本
+- `local-error-monitor/`: 本机一键检查工具
+- `.vscode/tasks.json`: VS Code 任务配置
+- `doc/system_error_logs.sql`: 建表 SQL
+
+## 服务器配置
+
+### 1. 创建错误日志表
+
+在服务器项目目录执行:
+
+```bash
+mysql -u cdb_outerroot -p kylx365_db < doc/system_error_logs.sql
+```
+
+服务启动时也会自动尝试创建表，但首次部署建议手动执行一次，便于确认权限正常。
+
+### 2. 设置内部 API token
+
+生成 token:
+
+```bash
+openssl rand -hex 32
+```
+
+生产环境必须设置:
+
+```bash
+INTERNAL_API_TOKEN=你的token
+```
+
+注意: token 不要提交到 git，不要写入公开文档。
+
+### 3. 启动 Node 24 的 web 服务
+
+服务器默认 `node` 可能是旧版本，所以 PM2 要使用 Node 24 的解释器。
+
+先确认 Node 24 路径:
+
+```bash
+nvm which 24.1.0
+```
+
+示例路径:
+
+```bash
+/root/.nvm/versions/node/v24.1.0/bin/node
+```
+
+如果已有 `app-24`，重启时带上 token:
+
+```bash
+INTERNAL_API_TOKEN=你的token pm2 restart app-24 --update-env
+```
+
+如果需要重新启动:
+
+```bash
+INTERNAL_API_TOKEN=你的token pm2 start src/app.js \
+  --name app-24 \
+  --interpreter /root/.nvm/versions/node/v24.1.0/bin/node \
+  --update-env
+```
+
+### 4. 启动 PM2 error log 兜底采集
+
+推荐直接启动脚本，不经过 `npm`，避免落到旧 Node。
+
+```bash
+INTERNAL_API_TOKEN=你的token pm2 start scripts/collect-pm2-error-logs.js \
+  --name error-log-pm2 \
+  --interpreter /root/.nvm/versions/node/v24.1.0/bin/node \
+  --update-env
+```
+
+检查状态:
+
+```bash
+pm2 list
+pm2 logs error-log-pm2 --lines 50
+```
+
+正常日志类似:
+
+```text
+[pm2-error-log-collector] watching /root/.pm2/logs
+```
+
+保存 PM2 配置:
+
+```bash
+pm2 save
+```
+
+## 服务器验证
+
+在服务器上执行:
+
+```bash
+curl -H "x-internal-token: 你的token" \
+  "http://127.0.0.1:3050/internal/error-logs/latest?status=all"
+```
+
+正常返回:
+
+```json
+{"errcode":10000,"result":{"list":[],"next_since_id":0}}
+```
+
+无 token 应返回 401:
+
+```bash
+curl "http://127.0.0.1:3050/internal/error-logs/latest?status=all"
+```
+
+正常返回:
+
+```json
+{"errcode":10401,"errMsg":"Unauthorized"}
+```
+
+手动写一条测试错误:
+
+```bash
+/root/.nvm/versions/node/v24.1.0/bin/node -e "import('./src/util/errorLogger.js').then(async ({recordError}) => { await recordError(new Error('manual test error log')); console.log('ok'); process.exit(0); }).catch((err) => { console.error(err); process.exit(1); })"
+```
+
+## 本机 VS Code 一键检查
+
+本机工具目录:
+
+```bash
+local-error-monitor/
+```
+
+### 1. 配置 `.env`
+
+复制模板:
+
+```bash
+cp local-error-monitor/.env.example local-error-monitor/.env
+```
+
+编辑:
+
+```bash
+ERROR_LOG_SSH_HOST=root@81.68.248.121
+ERROR_LOG_REMOTE_API_URL=http://127.0.0.1:3050/internal/error-logs
+ERROR_LOG_API_TOKEN=你的token
+ERROR_LOG_CHECK_LIMIT=20
+ERROR_LOG_CHECK_STATUS=open,reopened
+```
+
+说明:
+
+- 本机不会直接访问公网 `3050`。
+- 脚本会 SSH 到服务器，然后在服务器上访问 `127.0.0.1:3050`。
+- `.env` 已被 `local-error-monitor/.gitignore` 忽略，不应提交。
+
+### 2. 配置 SSH 免密
+
+建议使用 SSH key，不要把服务器密码写入项目。
+
+本机生成 key:
+
+```bash
+ssh-keygen -t ed25519 -C "miaoguo-error-monitor"
+```
+
+安装到服务器:
+
+```bash
+cat ~/.ssh/id_ed25519.pub | ssh root@81.68.248.121 "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys"
+```
+
+测试:
+
+```bash
+ssh root@81.68.248.121 "echo ok"
+```
+
+不再要求输入密码即可。
+
+也可以配置 `~/.ssh/config`:
+
+```sshconfig
+Host miaoguo-server
+  HostName 81.68.248.121
+  User root
+  IdentityFile ~/.ssh/id_ed25519
+```
+
+然后把 `.env` 改为:
+
+```bash
+ERROR_LOG_SSH_HOST=miaoguo-server
+```
+
+### 3. VS Code 一键检查
+
+在 VS Code 打开项目后:
+
+1. `Cmd + Shift + P`
+2. 选择 `Tasks: Run Task`
+3. 选择 `检查近期服务端 Bug`
+
+它实际执行:
+
+```bash
+local-error-monitor/run.sh
+```
+
+检查结果保存到:
+
+```bash
+local-error-monitor/data/recent-error-check.txt
+```
+
+检查状态保存到:
+
+```bash
+local-error-monitor/data/check-state.json
+```
+
+下次检查只显示上次之后的新错误。
+
+如果要从头重新检查，删除状态文件:
+
+```bash
+rm local-error-monitor/data/check-state.json
+```
+
+## Codex 定期检查
+
+当前已配置 Codex 自动化:
+
+```text
+ID: miaoguo
+名称: 定期检查 miaoguo 服务端错误日志
+频率: 每 1 小时
+状态: ACTIVE
+```
+
+它会定期运行:
+
+```bash
+/Users/chengjie/Documents/git/miaoguo_system_server/local-error-monitor/run.sh
+```
+
+如果没有新错误，会简短报告没有新错误。
+
+如果有新错误，会在当前 Codex 任务里列出错误摘要。之后可以让 Codex 根据日志定位代码并修复。
+
+## 常见问题
+
+### Unauthorized
+
+说明 SSH 和接口路径已经通了，但 token 不正确。
+
+检查:
+
+- 本机 `local-error-monitor/.env` 的 `ERROR_LOG_API_TOKEN`
+- 服务器 PM2 进程的 `INTERNAL_API_TOKEN`
+
+服务器验证:
+
+```bash
+curl -H "x-internal-token: 你的token" \
+  "http://127.0.0.1:3050/internal/error-logs/latest?status=all"
+```
+
+### fetch failed
+
+通常是本机直接访问公网 `3050` 失败，或者 SSH 隧道方式未启动。
+
+现在推荐使用 `local-error-monitor/check-once.js` 的 SSH 远程 curl 模式，不需要本机直接访问公网端口。
+
+### pm2: command not found
+
+非交互 SSH 可能不会加载完整 PATH。排查 PM2 时可以用登录 shell:
+
+```bash
+ssh root@81.68.248.121 'bash -lc "pm2 list"'
+```
+
+### Unexpected token 或 ESM 报错
+
+说明使用了旧 Node。服务器默认 Node 可能是 12，需要显式使用 Node 24:
+
+```bash
+/root/.nvm/versions/node/v24.1.0/bin/node
+```
+
+PM2 启动脚本时使用:
+
+```bash
+--interpreter /root/.nvm/versions/node/v24.1.0/bin/node
+```
+
+## 安全注意
+
+- `INTERNAL_API_TOKEN` 和 `ERROR_LOG_API_TOKEN` 不要提交到 git。
+- token 泄露后应重新生成并重启 `app-24`、`error-log-pm2`。
+- 本机检查建议走 SSH，不建议开放公网 `3050`。

local-error-monitor/.env.example

@@ -0,0 +1,8 @@
+ERROR_LOG_SSH_HOST=root@81.68.248.121
+ERROR_LOG_REMOTE_API_URL=http://127.0.0.1:3050/internal/error-logs
+ERROR_LOG_API_TOKEN=replace-with-your-new-token
+ERROR_LOG_CHECK_LIMIT=20
+ERROR_LOG_CHECK_STATUS=open,reopened
+ERROR_LOG_POLL_INTERVAL_MS=60000
+ERROR_LOG_NOTIFY=true
+ERROR_LOG_START_FROM_BEGINNING=false

local-error-monitor/.gitignore

@@ -0,0 +1,3 @@
+.env
+data/*
+!data/.gitkeep

local-error-monitor/README.md

@@ -0,0 +1,53 @@
+# 本机错误日志检查
+
+这个目录用于在本机检查远程服务器写入 `SystemErrorLogs` 的错误日志。
+
+完整安装、配置、排查说明见:
+
+```bash
+doc/server_error_log_monitor.md
+```
+
+## 第一次配置
+
+复制配置文件:
+
+```bash
+cp local-error-monitor/.env.example local-error-monitor/.env
+```
+
+编辑 `local-error-monitor/.env`:
+
+```bash
+ERROR_LOG_SSH_HOST=root@服务器IP
+ERROR_LOG_REMOTE_API_URL=http://127.0.0.1:3050/internal/error-logs
+ERROR_LOG_API_TOKEN=你的新token
+```
+
+## VS Code 一键检查
+
+在 VS Code 中:
+
+1. `Cmd + Shift + P`
+2. 选择 `Tasks: Run Task`
+3. 选择 `检查近期服务端 Bug`
+
+检查结果会显示在 VS Code Terminal，并写入:
+
+```bash
+local-error-monitor/data/recent-error-check.txt
+```
+
+检查状态会保存在:
+
+```bash
+local-error-monitor/data/check-state.json
+```
+
+下次检查只显示上次之后的新错误。
+
+也可以直接运行:
+
+```bash
+./local-error-monitor/run.sh
+```

local-error-monitor/check-once.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const monitorDir = __dirname;
+const dataDir = path.join(monitorDir, 'data');
+const envFile = path.join(monitorDir, '.env');
+
+function parseEnv(content) {
+  const env = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    const index = trimmed.indexOf('=');
+    if (index === -1) {
+      continue;
+    }
+
+    const key = trimmed.slice(0, index).trim();
+    const value = trimmed.slice(index + 1).trim().replace(/^['"]|['"]$/g, '');
+    env[key] = value;
+  }
+  return env;
+}
+
+async function loadEnv() {
+  const content = await fsp.readFile(envFile, 'utf8');
+  return {
+    ...process.env,
+    ...parseEnv(content),
+  };
+}
+
+async function readJson(filePath, fallback) {
+  try {
+    return JSON.parse(await fsp.readFile(filePath, 'utf8'));
+  } catch (error) {
+    return fallback;
+  }
+}
+
+async function writeJson(filePath, value) {
+  await fsp.mkdir(path.dirname(filePath), { recursive: true });
+  await fsp.writeFile(filePath, JSON.stringify(value, null, 2));
+}
+
+function execFileAsync(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function makeUrl(baseUrl, params) {
+  const url = new URL(baseUrl);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') {
+      url.searchParams.set(key, value);
+    }
+  }
+  return url.toString();
+}
+
+async function fetchViaSsh(env, url) {
+  const sshHost = env.ERROR_LOG_SSH_HOST;
+  if (!sshHost) {
+    throw new Error('ERROR_LOG_SSH_HOST is required for one-click check');
+  }
+
+  const remoteCommand = [
+    'curl',
+    '-sS',
+    '--max-time',
+    String(env.ERROR_LOG_CURL_TIMEOUT || 15),
+    '-H',
+    `x-internal-token: ${env.ERROR_LOG_API_TOKEN || env.INTERNAL_API_TOKEN || ''}`,
+    url,
+  ].map(shellQuote).join(' ');
+
+  const sshArgs = [
+    '-o',
+    `ConnectTimeout=${env.ERROR_LOG_SSH_CONNECT_TIMEOUT || 8}`,
+    sshHost,
+    remoteCommand,
+  ];
+
+  const { stdout } = await execFileAsync('ssh', sshArgs);
+  return JSON.parse(stdout);
+}
+
+function formatLog(item) {
+  const location = item.FilePath ? `${item.FilePath}:${item.LineNumber || 0}:${item.ColumnNumber || 0}` : 'unknown location';
+  const request = item.RequestUrl ? `${item.RequestMethod || 'REQUEST'} ${item.RequestUrl}` : '';
+  const time = item.LastSeenAt || item.CreateTime || '';
+
+  return [
+    `#${item.ID} ${item.Source || 'error'} ${item.Status || ''} x${item.Count || 1} ${time}`,
+    item.Message || '',
+    location,
+    request,
+  ].filter(Boolean).join('\n');
+}
+
+async function main() {
+  const env = await loadEnv();
+  const token = env.ERROR_LOG_API_TOKEN || env.INTERNAL_API_TOKEN || '';
+  if (!token) {
+    throw new Error('ERROR_LOG_API_TOKEN is required in local-error-monitor/.env');
+  }
+
+  const stateFile = env.ERROR_LOG_CHECK_STATE_FILE || path.join(dataDir, 'check-state.json');
+  const outputFile = env.ERROR_LOG_CHECK_OUTPUT_FILE || path.join(dataDir, 'recent-error-check.txt');
+  const state = await readJson(stateFile, { sinceId: Number(env.ERROR_LOG_SINCE_ID || 0) });
+  const limit = Math.min(Math.max(Number(env.ERROR_LOG_CHECK_LIMIT || 20), 1), 100);
+  const apiBaseUrl = env.ERROR_LOG_REMOTE_API_URL || 'http://127.0.0.1:3050/internal/error-logs';
+
+  const url = makeUrl(apiBaseUrl, {
+    since_id: state.sinceId || 0,
+    status: env.ERROR_LOG_CHECK_STATUS || 'open,reopened',
+    limit,
+  });
+
+  const data = await fetchViaSsh(env, url);
+  if (data.errcode !== 10000) {
+    throw new Error(data.errMsg || `Unexpected response: ${JSON.stringify(data)}`);
+  }
+
+  const list = data.result?.list || [];
+  const checkedAt = new Date().toISOString();
+
+  let output;
+  if (list.length === 0) {
+    output = `[${checkedAt}] No new server errors since ID ${state.sinceId || 0}.`;
+  } else {
+    const nextSinceId = list.reduce((maxId, item) => Math.max(maxId, Number(item.ID || 0)), Number(state.sinceId || 0));
+    state.sinceId = nextSinceId;
+    await writeJson(stateFile, state);
+
+    output = [
+      `[${checkedAt}] Found ${list.length} new server error(s). Next since ID: ${nextSinceId}`,
+      '',
+      ...list.map(formatLog),
+    ].join('\n\n');
+  }
+
+  await fsp.mkdir(dataDir, { recursive: true });
+  await fsp.writeFile(outputFile, output + '\n');
+  console.log(output);
+  console.log(`\nSaved to: ${outputFile}`);
+}
+
+main().catch((error) => {
+  console.error('[error-log-check] failed:', error.message || error);
+  if (error.stderr) {
+    console.error(error.stderr);
+  }
+  process.exit(1);
+});

local-error-monitor/check-once.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT_DIR"
+
+node local-error-monitor/check-once.js

local-error-monitor/data/.gitkeep

@@ -0,0 +1 @@
+

local-error-monitor/run.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+exec "$SCRIPT_DIR/check-once.sh"