wecom_it_smart_desk/docs/10-项目管理/IT智能服务台-标准作业流程SOP.md

企微IT智能服务台 — 标准作业流程SOP

版本: v1.5 | 日期: 2026-07-10

---

目录

1. Gitea部署
2. Gitea备份恢复
3. 推送评审
4. 应急响应
5. 文档管理规范
6. BugFix快捷路径
7. 部署运维工具箱管理
8. 任务路由表

---

1. Gitea部署

适用: 新机器 / NAS 迁移 / Gitea重建 耗时: 30-45 分钟

1.1 前置检查

# 1.1 NAS 可达
ping 100.85.152.112

# 1.2 SSH 通
ssh simon@100.85.152.112

# 1.3 Tailscale 状态
sudo tailscale status

# 1.4 端口 8418 未占
sudo lsof -i :8418

1.2 装 Gitea 套件

1. DSM → 套件中心
2. 搜 Gitea → 安装
3. 装好跳 http://100.85.152.112:8418/

---

2. Gitea备份恢复

适用: 数据丢失应急 / 误操作回滚 / 异地迁移 耗时: 5-15 分钟

2.1 备份策略

项	值	备注
频率	每天 3 点	cron
保留	7 天	默认
路径	/volume1/backups/gitea/	NAS 本地
工具	scripts/backup-gitea.sh	已写

2.2 手动备份(应急)

ssh simon@100.85.152.112
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh

2.3 恢复流程

# 停止 Gitea
sudo docker stop gitea

# 恢复数据
sudo bash /volume1/docker/wecom-it-desk/scripts/restore-gitea.sh <backup_file>

# 启动 Gitea
sudo docker start gitea

---

3. 推送评审

适用: 任何 commit 推 Gitea / PR 评审 / workbuddy 推送 耗时: 5-15 分钟

3.1 推送前自检(4 件套)

cd D:\资料\03-项目开发\wecom_it_smart_desk

# 必跑
bash scripts/pre-commit-check.sh --branch

# 严格模式(任何 warn 失败)
bash scripts/pre-commit-check.sh --branch --strict

通过标准:

• ✅ PASS ≥ 检查项数
• ⚠️ WARN 看是否影响评审
• ❌ FAIL 必修

3.2 Commit 规范

格式: <type>(<scope>): <subject>

type	用途
feat	新功能
fix	Bug修复
docs	文档
style	格式
refactor	重构
test	测试
chore	维护

3.3 PR 评审要求

• 所有 P0 鉴权修复必须走评审
• 端点变更需鉴权依赖
• 数据库 schema 变化必须 alembic 迁移

---

4. 应急响应

适用: P0 漏洞 / 数据丢失 / 服务中断 / 安全事件 响应时间: 5 分钟响应 + 30 分钟止血 + 24 小时根因

4.1 事件分级

等级	场景	响应时间
🔴 P0 紧急	P0 鉴权漏洞 + 数据泄露 + 服务全停	5 min
🟠 P1 高	P1 功能故障 + 单服务降级	30 min
🟡 P2 中	P2 性能 / UI 问题	4 h
🟢 P3 低	体验优化	1 周

4.2 P0 应急流程(5 min 响应)

4.2.1 立即止血

1. 服务降级:

   • 关闭外网访问: sudo iptables -A INPUT -p tcp --dport 8418 -j DROP
   • 或: 套件中心停 Gitea
   • 或: Nginx deny all;

2. 停可疑服务:

   • 停后端: docker compose stop backend
   • 停 WebSocket: docker compose stop nginx

3. 保留现场:

   • 不删任何文件
   • 不改配置
   • 截图/录屏

4.2.2 快速评估

问题	影响范围	可行方案

4.2.3 升级上报

• 5 分钟无法止血 → 升级到技术负责人
• 30 分钟无法解决 → 升级到管理层

4.3 P1 应急流程(30 min)

1. 定位问题: 30 分钟内确定故障范围
2. 临时方案: 提供绕过/降级方案
3. 根本修复: 24 小时内完成

---

5. 文档管理规范

版本: v1.0 | 日期: 2026-07-04

5.1 文档目录结构

docs/
├── 01-项目总览/          # 项目介绍、部署手册
├── 02-产品需求/          # PRD、需求文档
├── 03-技术架构/          # 技术方案、设计文档
├── 04-原型设计/          # UI原型
├── 05-用户手册/          # 用户指南
├── 06-测试质量/          # 测试报告、E2E
├── 07-代码评审/          # Code Review
├── 08-安全审计/          # 安全相关
├── 09-部署运维/          # 部署、运维
├── 10-项目管理/          # 任务、风险、SOP
└── 11-历史归档/          # 历史版本

5.2 文档命名规范

类型	命名格式	示例
需求文档	需求-<功能名>.md	需求-应急降级页.md
技术方案	技术方案-<模块名>.md	技术方案-消息功能.md
测试报告	测试-<功能>-<日期>.md	测试-E2E-20260708.md
部署手册	部署-<环境>-<日期>.md	部署-生产-20260704.md

5.3 文档维护

文档状态	维护要求
正式发布	仅通过 PR 评审更新
更新中	标注"草稿"或"进行中"
已废弃	移至历史归档

5.4 版本管理

• 重大更新 → 新版本号
• 小修复 → 保留版本号，更新日期
• 版本历史记录在文档末尾

---

6. BugFix 快捷路径（v1.1 优化版）

适用: 非紧急 Bug 修复，不涉及核心架构变更 目标: 快速响应 + 风险可控

6.1 处理流程（6 步）

步骤	操作	产出	备注
1	定位根因	问题定位文档	明确问题文件和行号
2	影响评估	影响分析报告	正面/负面影响 + 风险等级
3	方案确认	修复方案	需用户确认后执行 ⚠️
4	部署执行	部署完成	上传 → cp → 重启
5	功能验证	验证通过	实际触发功能测试
6	状态更新	看板已更新	正在做 → 已完成

6.2 部署三问（部署前必确认）

问题	目的
会影响坐席和员工端使用吗？	评估业务影响
会重启容器或服务吗？	评估可用性影响
验证方式是什么？	明确如何验证修复效果

6.3 复盘要求

场景	是否需要复盘	理由
简单Bug（单文件修改、<15分钟）	❌ 不需要	流程简单，无学习价值
复杂Bug（多文件/多模块、涉及架构）	✅ 建议	有技术沉淀价值
重复出现的问题	✅ 必须	识别系统性风险
有改进点	✅ 必须	沉淀到SOP，避免重复踩坑
紧急止血（P0/P1）	❌ 事后补	先解决问题，24小时内补记录

6.4 验收条件

条件	说明
代码改动已确认	用户或自己确认修复方案
部署后容器健康	docker ps 显示 healthy
功能验证通过	按 §6.5 验证手段分层选择工具，前端类必须 agent-browser 截图
看板状态已更新	正在做 → 已完成
复盘报告（按需）	复杂Bug/重复问题/有改进点时才需要

6.5 验证手段分层

验证不是"看看没报错就行"，必须按以下分层选择验证工具：

验证类型	工具	适用场景	证据形式
API/后端	curl / HTTP 请求	接口返回值、状态码、响应体	curl 输出 + HTTP 状态码
前端渲染/登录/交互	agent-browser 技能	页面渲染、表单填写、按钮点击、键盘输入、登录流程	真实浏览器截图
前端诊断（F12 等效）	agent-browser Debug 命令	白屏、JS 不执行、API 异常、CSP 违规	console 日志 + errors + network 请求 + 截图
服务器状态	jumpserver-ops	容器状态、进程、日志	docker ps / logs 输出

验证硬规则：

• 前端/登录类修复 → 必须用 agent-browser 截图取证，不能只用 curl
• API/后端类修复 → curl 真实返回 + 必要时代码层拦截响应体
• 禁止只因 docker logs 无报错就断言修复

前端诊断命令组合（白屏/JS不执行/API异常/CSP违规场景必须采集）：

采集项	agent-browser 命令	F12 等效面板	必须采集
JS 错误	errors	Console > Errors	✅
控制台日志	console	Console	✅
网络请求	network requests	Network	✅
页面截图	screenshot	—	✅
HAR 录制	network har start → 操作 → network har stop	Network (完整请求/响应)	API 异常时
DOM 检查	eval "document.documentElement.outerHTML.substring(0, 500)"	Elements	疑似渲染异常时
Cookie/Storage	cookies / storage local	Application	登录态问题时

标准前端诊断流程：

agent-browser open <url>
agent-browser wait --load load
agent-browser console --clear           # 清除旧日志
agent-browser errors                     # 采集 JS 错误
agent-browser console                    # 采集控制台日志
agent-browser network requests           # 采集网络请求
agent-browser screenshot                 # 截图取证
agent-browser close

注意：以上命令在同一个浏览器 session 中执行，cookie 和状态自动保持。只需在最后执行一次 close。

---

7. 部署运维工具箱管理

适用: 故障排查 / 部署运维过程中产生的可复用脚本、配置模板、调试工具 工具箱位置: docs/09-部署运维/toolbox/

7.1 工具沉淀流程

每次故障排查或部署完成后，按以下流程处理排查过程中产生的脚本和工具：

步骤	操作	说明
1	评估复用价值	该脚本/配置是否可能在后续排查中再次使用？
2	归档	有复用价值 → 复制到 toolbox/（活跃工具）或 toolbox/archive/（历史脚本）
3	登记	在 toolbox/README.md 的工具索引表中添加条目（工具名、用途、使用方式）
4	清理根目录	删除项目根目录的临时文件（渲染输出、中间产物等），保持根目录整洁

7.2 归档分类标准

分类	存放位置	判定标准	示例
活跃工具	toolbox/	当前可复用、有通用价值的脚本或配置模板	fast_upload.py、nginx-access-control.conf
历史脚本	toolbox/archive/	一次性修复脚本，仅供历史参考	fix_admin_role.py、patch-redis-url.py
临时文件	直接删除	渲染输出、中间产物、调试快照	rendered_scan.html、tmp_*.html

7.3 README 维护要求

• 新增工具时必须同步更新 toolbox/README.md 的工具索引表
• 每个条目包含：工具名、用途、使用方式
• archive/ 中的脚本按"修复场景 + 日期"分组登记
• README 版本号随工具增减递增

7.4 故障排查手册更新触发条件

以下场景必须同步更新 00-标准故障排查手册.md：

触发条件	更新内容
新案例（排查耗时 > 30 分钟）	§4 案例库新增 CASE-YYYYMMDD-序号 条目
发现新的排查盲点	§1 快速诊断决策树补充检查步骤
新的错误现象	§2 错误码速查表新增行
nginx 新陷阱	§4 附：nginx 配错急救流程新增步骤
响应头相关故障	§1 Step 0 HTTP 响应头检查更新

7.5 工具箱与 SOP 的关系

故障排查 → 产出脚本 → 评估复用价值 → 归档到 toolbox
                                    ↓
                              更新 README.md
                                    ↓
                        更新故障排查手册（按需）
                                    ↓
                        更新 SOP（仅涉及流程变更时）

原则：工具箱是"弹药库"，故障排查手册是"作战手册"，SOP 是"军规"。三者各司其职，不混为一谈。

---

8. 任务路由表

适用: 收到任何新请求时的统一入口 执行者: 交付总监（齐活林）使用 task-intake 技能执行 原则: 先路由再执行，先想清楚再动手

8.1 路由表

输入特征	路由到	产出物	执行方	参考
🏗️ 新功能（中大型，>10文件）	软件团队标准 SOP	PRD+架构+代码+测试	PM→Architect→Engineer→QA	软件团队 SOP
⚡ 新功能（小型，≤10文件）	软件团队快速模式	代码+测试	Engineer→QA	软件团队 SOP
🔧 Bug 修复	SOP §6 BugFix	修复+验证	Engineer→QA	SOP §6
🚀 部署运维	直接执行	部署完成+验证	AI+jumpserver-ops	SOP §7
🩺 故障排查	deploy-troubleshoot	定位+修复+案例	三步隔离法	故障排查手册
🔴 应急事件（P0/P1）	SOP §4 应急响应	止血+根因	应急流程	SOP §4
🔍 代码调试	diagnose 技能	根因+回归	六阶段调试	diagnose SKILL.md
📊 技术评估/决策	Plan 模式	评估报告	AI+人	—
📋 方案调研	Plan 模式	方案文档	AI+人	—
📝 文档更新	直接执行	文档	AI	SOP §5
🛠️ 工具沉淀	SOP §7 流程	工具归档+README	AI	SOP §7

8.2 路由优先级

当请求可能匹配多个分类时，按以下优先级路由：

1. 🔴 应急事件 > 一切（先止血再说）
2. 🩺 故障排查 > 🔧 Bug 修复（先隔离定位再修 Bug）
3. 🏗️/⚡ 新功能 > 📊 技术评估（明确要做的不需要评估）
4. 📝 文档更新 / 🛠️ 工具沉淀 通常作为其他任务的收尾步骤

8.3 task-intake 技能

任务路由通过 task-intake 技能执行（项目级 skill，位置：.workbuddy/skills/task-intake/）。

执行流程：

1. 分类 — 判断请求属于哪类任务
2. 结构化 — 输出四要素（是什么/要什么/怎么做/谁来做）
3. 路由 — 对照 §8.1 路由表确定执行路径
4. 移交 — 输出路由卡，交给对应执行方

路由卡格式：

是什么：[任务分类] + [一句话描述]
要什么：[期望产出物] + [验收标准]
怎么做：[执行路径] + [技能/工具]
谁来做：[执行角色] + [协作方]
路由到：[工作流名称]

8.4 上下文隔离原则

路由卡只传递结论，不传递思考过程。下一阶段拿到的是干净的输入，不被前一阶段的假设和试错带偏。

正确	错误
"故障定位在 Nginx 层，证据是 curl 返回 403"	"我一开始以为是后端，试了 A/B/C 都不对..."
"根因是 CSP 缺少 unsafe-inline"	"我检查了 JS 加载、签名 URL、轮询逻辑..."

8.5 与齐活林（交付总监）的集成

请求到达 → 齐活林调用 task-intake → 输出路由卡
  ↓
├─ 标准SOP → TeamCreate → PM → Architect → Engineer → QA
├─ 快速模式 → TeamCreate → Engineer → QA
├─ BugFix → TeamCreate → Engineer → QA
├─ 故障排查 → deploy-troubleshoot → jumpserver-ops(传输)
├─ 应急响应 → SOP §4 流程
├─ Plan模式 → 评估/方案文档
└─ 直接执行 → 文档/工具沉淀

---

附录：相关文档

文档	位置
项目管理主文档	10-项目管理/任务说明书/
风险跟踪表	10-项目管理/任务说明书/02-风险跟踪表.md
技术架构	03-技术架构/
部署手册	09-部署运维/
标准故障排查手册	09-部署运维/00-标准故障排查手册.md
部署运维工具箱	09-部署运维/toolbox/
task-intake 技能	.workbuddy/skills/task-intake/SKILL.md

---

本文档为标准作业流程综合文档，最后更新：2026-07-10（§6.5 验证手段分层新增前端诊断 F12 等效命令 + agent-browser SKILL.md 补全 Debug/Network 文档）