Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
460 lines
16 KiB
Markdown
460 lines
16 KiB
Markdown
# 企微IT智能服务台 — 标准作业流程SOP
|
||
|
||
> **版本**: v1.5 | **日期**: 2026-07-10
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [Gitea部署](#1-gitea部署)
|
||
2. [Gitea备份恢复](#2-gitea备份恢复)
|
||
3. [推送评审](#3-推送评审)
|
||
4. [应急响应](#4-应急响应)
|
||
5. [文档管理规范](#5-文档管理规范)
|
||
6. [BugFix快捷路径](#6-bugfix-快捷路径v11-优化版)
|
||
7. [部署运维工具箱管理](#7-部署运维工具箱管理)
|
||
8. [任务路由表](#8-任务路由表)
|
||
|
||
---
|
||
|
||
## 1. Gitea部署
|
||
|
||
> **适用**: 新机器 / NAS 迁移 / Gitea重建
|
||
> **耗时**: 30-45 分钟
|
||
|
||
### 1.1 前置检查
|
||
|
||
```bash
|
||
# 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 手动备份(应急)
|
||
|
||
```bash
|
||
ssh simon@100.85.152.112
|
||
sudo bash /volume1/docker/wecom-it-desk/scripts/backup-gitea.sh
|
||
```
|
||
|
||
### 2.3 恢复流程
|
||
|
||
```bash
|
||
# 停止 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 件套)
|
||
|
||
```bash
|
||
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-产品文档/ # PRD、原型图
|
||
├── 02-技术文档/ # 技术方案、设计
|
||
├── 03-测试文档/ # 测试报告、E2E
|
||
├── 04-运维文档/ # 部署、运维
|
||
├── 05-运营文档/ # 用户手册、运营报告
|
||
├── 06-安全审计/ # 安全相关
|
||
├── 07-项目管理/ # 任务、风险、SOP
|
||
└── 08-历史归档/ # 历史版本
|
||
```
|
||
|
||
### 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-V2 | 容器状态、进程、日志 | 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/04-运维文档/部署运维/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-V2 | 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-V2(传输)
|
||
├─ 应急响应 → SOP §4 流程
|
||
├─ Plan模式 → 评估/方案文档
|
||
└─ 直接执行 → 文档/工具沉淀
|
||
```
|
||
|
||
---
|
||
|
||
## 附录：相关文档
|
||
|
||
| 文档 | 位置 |
|
||
|------|------|
|
||
| 项目管理主文档 | `07-项目管理/任务说明书/` |
|
||
| 风险跟踪表 | `07-项目管理/任务说明书/02-风险跟踪表.md` |
|
||
| 技术架构 | `03-技术架构/` |
|
||
| 部署手册 | `04-运维文档/部署运维/` |
|
||
| 标准故障排查手册 | `04-运维文档/部署运维/00-标准故障排查手册.md` |
|
||
| 部署运维工具箱 | `04-运维文档/部署运维/toolbox/` |
|
||
| task-intake 技能 | `.workbuddy/skills/task-intake/SKILL.md` |
|
||
|
||
---
|
||
|
||
> **本文档为标准作业流程综合文档，最后更新：2026-07-10（§6.5 验证手段分层新增前端诊断 F12 等效命令 + agent-browser SKILL.md 补全 Debug/Network 文档）**
|