---
name: session-20260618-1
description: 2026-06-18 第1次会话 — 网关SocketTimeout日志分析 + Widget接入指南补全（后端文档+前端页面）
metadata:
  type: session
  date: 2026-06-18
  sessionNumber: 1
  startTime: 2026-06-18T01:18:00+08:00
---

# 2026-06-18 第1次会话

## 会话摘要
1. 分析网关日志中频繁出现的 `SocketTimeoutException` / `Broken pipe` 错误，确认是下游 `devops.server.zgitm.com` 响应太慢导致客户端超时断开，不是网关 Bug
2. 将 Widget 接入详细指南补充到 deployServer 文档体系（新建 `06-gateway-widget.md`）
3. 将 Widget 接入详细内容更新到网关前端公网文档页面 `IntegrationDoc.vue`（`https://web.gw.zgitm.com/docs/:token`）

## 关键操作

### 一、网关 SocketTimeout/Broken pipe 日志分析
- **做了什么**: 分析了 `mokee-gateway-gateway` 服务日志中大量 `AsyncRequestNotUsableException` → `ClientAbortException` → `SocketTimeoutException` / `Broken pipe` 异常栈
- **根因**: 下游 `devops.server.zgitm.com` 的 `/api/apps/{8,9,10}/builds` 接口响应时间 >3秒，浏览器/前端超时主动断开连接，网关尝试写响应时发现 socket 已关闭
- **结论**: 
  - 🔴 主要问题：下游 devops 服务响应太慢
  - ⚠️ 网关问题：GlobalExceptionHandler 把客户端断开当成 ERROR 记录，应降级为 WARN 或静默忽略
  - 🟡 前端问题：超时设置过短（~3秒），并发请求多导致日志刷屏

### 二、deployServer 文档体系补充 Widget 接入指南
- **做了什么**: 将 `mokee-gateway-widget-integration.md` 内容格式化后新建为编号文档 `docs/06-gateway-widget.md`
- **原因**: 文档目录中原只有 01-05 号文档，Widget 接入指南是独立的未编号文件，需要纳入体系
- **涉及文件**:
  - 新建：`deployServer/docs/06-gateway-widget.md`
  - 更新：`deployServer/README.md`（文档导航新增链接）
  - 更新：`deployServer/docs/05-implementation-plan.md`（文件清单树形图）

### 三、IntegrationDoc.vue 第 3.6 节 Widget 接入大幅扩展
- **做了什么**: 将原来 3 行简略 HTML 代码替换为完整接入指南
- **新增内容**:
  - 🚫 常见错误说明：`process is not defined` 的原因（Vue 3.x 打包引用 process.env，浏览器无此全局变量）
  - 步骤 1：index.html 引入 CSS（不引入 JS、不放占位 div）
  - 步骤 2：TopBar.vue 中放置占位 div（必须在 Vue 模板中，不在 index.html）
  - 步骤 3：main.js 中 mount 后动态加载脚本 + `window.process = { env: {} }` polyfill
  - 原理说明：ASCII 流程图展示加载时序
  - 排查清单：5 项常见问题对照表（Widget 不显示 / process 报错 / 登录不识别 / 样式错乱 / 跨域报错）
  - CDN 资源地址
- **涉及文件**: `mokee-gateway-web/src/views/docs/IntegrationDoc.vue`
  - 注释头更新：8 个章节 → 10 个章节
  - 模板：第 3.6 节完全重写
  - Script：新增 `widgetTroubleshooting` 数据

## 待处理
- [ ] `IntegrationDoc.vue` 修改需要重新构建部署 `mokee-gateway-web` 前端才能在 `https://web.gw.zgitm.com/docs/:token` 看到更新
- [ ] 网关 `GlobalExceptionHandler` 需要优化：`ClientAbortException` / `AsyncRequestNotUsableException` 降级为 WARN 或静默处理
- [ ] 排查 `devops.server.zgitm.com` 的 `/api/apps/{8,9,10}/builds` 接口性能，优化响应时间
- [ ] 前端可考虑增加超时时间或减少并发请求数