文档中心 - 简修科技

Project A

EasyOps 文档

Knowledge Base

全栈运维知识库

重点：支持离线检索与分类浏览，适配无网机房场景。

网络工程

Huawei/H3C/Cisco 命令速查、OSPF/STP 故障排查。

弱电安防

IPC 调试、门禁接线图、监控黑屏与云台故障定位。

桌面运维

Windows 故障速查、打印机共享问题、DNS/IP 修复。

Linux/服务器

Shell 常用指令、RAID 维护、防火墙配置与加固。

云原生

Docker / K8s 常用命令、Pod 异常诊断与部署速查。

数据库

MySQL / Redis 运维手册、慢查询与备份恢复指南。

Toolbox

工程工具箱

重点：现场高频能力按“计算 + 诊断 + 查询 + 运维”分层组织，便于快速定位工具。

安防存储

NVR 硬盘容量估算

子网掩码

IP 范围与广播计算

PoE 功耗

末端供电预算

光纤衰减

链路 dB 损耗估算

网络诊断

TCP Ping / 端口扫描 / LAN Scan

网络运维中心

HTTP 探测 / WOL / 工具聚合

网络查询中心

DNS / Whois(RDAP) / OUI

SSH 工具

连接管理 / 状态轮询 / 快捷命令

首次初始化说明

重点：首次需联网下载约 15MB 核心数据，初始化完成后可离线使用。

本地优先：知识库、收藏、历史、扫描结果默认存储在设备本地，核心数据不上传。

安全存储：敏感配置项采用系统安全能力（如 Keychain）保存，避免明文暴露。

Project B

Asset Sonar 文档

部署与配置

建议先在测试环境完成一次全流程演练（扫描→校验→同步→导出），再切到生产配置。

重点提醒

建议先在测试环境完整走通一次，再进入生产；生产首批建议 10~20 台灰度同步，稳定后再放量。

01环境要求

Windows 10/11（建议 22H2+，x64）
.NET Desktop Runtime 8.0 (x64)
建议以管理员权限运行（便于读取完整硬件与系统信息）
Snipe-IT API Key（至少具备资产读写、组件/配件关联权限）
客户端到 Snipe-IT 网络可达（HTTP/HTTPS 与反向代理策略允许）

02profiles.json 示例（多环境）

{
  "Profiles": [
    {
      "Name": "Production",
      "ApiUrl": "http://snipeit.company.local/api/v1",
      "ApiKey": "YOUR_PROD_API_KEY",
      "TagPrefix": "AS-",
      "EnableComponents": true,
      "EnableAccessories": true,
      "Location": "HQ",
      "Company": "JianXiu Tech"
    },
    {
      "Name": "Lab",
      "ApiUrl": "http://snipeit-lab.local/api/v1",
      "ApiKey": "YOUR_LAB_API_KEY",
      "TagPrefix": "LAB-",
      "EnableComponents": false,
      "EnableAccessories": false,
      "Location": "LAB",
      "Company": "JianXiu Tech"
    }
  ]
}

建议将 API Key 交由系统安全机制保管，不在共享机器中明文长期保存。

02.1配件 / 组件 / 型号配置参考

用于统一“组件、配件、型号”在 Snipe-IT 中的映射命名，避免同步时出现关联失败或重复创建。

{
  "ActiveProfile": "默认",
  "Profiles": {
    "默认": {
      "InternalUrl": null,
      "ExternalUrl": null,
      "ApiKey": null,
      "Department": null,
      "AssignName": null,
      "AssignUser": null,
      "AssignPassword": null,
      "EmailSuffix": "example.com",
      "ASSET_TAG_PREFIX": "DOZ",
      "CATEGORY_ID_MAP": {
        "笔记本电脑": 4,
        "台式机": 3,
        "显示器": 5
      },
      "COMPONENT_CATEGORY_ID_MAP": {
        "处理器": 7,
        "内存": 9,
        "硬盘": 10
      },
      "ACCESSORY_CATEGORY_ID_MAP": {
        "键盘": 15,
        "鼠标": 16
      },
      "CATEGORY_CODE_MAP": {
        "笔记本电脑": "BJB",
        "台式机": "TSJ"
      }
    }
  }
}

建议先在 Snipe-IT 预建目标 Model、Component、Accessory，再做批量同步。
命名保持唯一且稳定，避免同义词导致重复对象（如 16G / 16GB）。
首次上线建议先抽样 10 台验证映射，再扩大批次。

03推荐操作流程（生产环境）

准备阶段（上线前）
- 确认当前选择的是 Production Profile，避免误写测试环境。
- 验证 ApiUrl、ApiKey、组件/配件开关与本次盘点范围一致。
- 先用 1 台样机做连通性验证（能扫描、能同步、能回写关键字段）。
扫描阶段（先本地、后同步）
- 执行本地扫描，重点检查序列号、型号、资产标签是否完整。
- 对空值字段先补录或标记，避免将脏数据直接同步到资产库。
- 建议按部门/楼层分批建任务（例如每批 30~50 台）。
校验阶段（抽样核对）
- 每批抽样 3~5 台，核对资产标签、序列号、型号、位置字段映射。
- 确认“存在资产更新 / 不存在资产新建”的行为符合预期。
- 若发现字段错位，先修正映射配置，再继续后续批次。
同步阶段（灰度推进）
- 先小批量同步（首批建议 10~20 台），观察错误码与失败率。
- 确认稳定后再扩大批次，避免一次性全量导入带来回滚压力。
- 每批完成后立即导出快照（CSV/PDF）并记录批次编号。
异常处理阶段（先止损）
- 出现大面积失败时先暂停后续批次，不做全量重跑。
- 按错误码分组处理（401/403 权限、404 路径、409 冲突、422 字段）。
- 修复后仅重试失败对象，成功对象不重复写入。
收尾阶段（归档与复盘）
- 归档“扫描快照 + 同步结果 + 异常清单 + 操作日志”。
- 记录本次配置变更与问题处理结论，更新团队 SOP。

04过滤与去噪建议

"IGNORE_KEYWORDS": [
  "VMware", "Virtual", "Hyper-V", "Loopback", "Bluetooth",
  "WAN Miniport", "Teredo", "Docker", "vEthernet"
]

用于过滤虚拟网卡、隧道适配器和临时接口，减少无效资产噪声。

05导出与归档建议

盘点阶段建议同时导出 CSV + PDF，便于系统对账与人工签字留档。
命名建议：site-dept-date-batch，例如 hq-it-2026-04-08-b01。
将“扫描快照 + 同步结果 + 异常清单”放入同一归档目录，便于审计复盘。

常见问题与排障

建议先看“现象 → 原因 → 处理步骤”，按顺序排查可快速定位问题。

1) 扫描不到序列号或型号为空？

常见原因：权限不足、WMI 服务异常、设备 BIOS 信息缺失。

以管理员身份运行 Asset Sonar。
检查 WMI 服务（Winmgmt）是否正常。
在 BIOS/UEFI 中确认序列号字段未被清空。

2) 无法连接 Snipe-IT（401/403/404）？

先确认 API 地址包含 /api/v1，再检查 Key 与权限。

401：API Key 错误或过期。
403：Key 权限不足（无写入/关联权限）。
404：路径错误、反向代理未转发 API 路由。

3) 同步后出现重复资产？

重复通常来自“序列号不一致”或“历史脏数据”。

优先将“序列号 + 资产标签”作为主键策略。
对历史空序列号资产先人工补齐或标记归档。
先在测试环境跑一批，确认去重策略再上生产。

4) 组件/配件关联失败？

多见于目标对象不存在或 ID 映射失败。

确认目标组件、配件在 Snipe-IT 中已存在且可分配。
检查 profiles 中是否启用 EnableComponents / EnableAccessories。
查看失败日志里的对象名称与 ID，修正映射后重试。

5) 扫描速度慢或 UI 卡顿？

建议降低并发、缩小扫描范围，并过滤虚拟设备。

先做硬件主字段采集，再做扩展字段补扫。
排除虚拟网卡与无效接口，减少噪声。
将大批量盘点分批执行（按部门/楼层）。

6) 导出文件乱码或字段错位？

一般是编码或区域设置差异导致。

CSV 建议使用 UTF-8（含 BOM）导入表格工具。
统一日期格式与小数点规则，避免本地化差异。
跨团队传递时优先使用 PDF 归档版防止变形。

7) 为什么会出现“部分成功、部分失败”？

这是批处理场景中的正常保护策略：成功项先落库，失败项进入重试队列。

先导出失败清单，按错误码分组处理。
修复权限/映射/网络后，仅重试失败批次即可。
避免全量重跑，减少重复写入和脏数据风险。

8) 如何安全地在生产环境上线？

错误码速查（HTTP / 常见报错）

用于快速判断“配置问题、权限问题、网络问题”分别应该从哪里下手。

错误码 / 现象	典型原因	优先处理步骤
`401 Unauthorized`	API Key 错误、过期或被撤销	重新生成 Key，确认请求头格式与 Profile 生效
`403 Forbidden`	Key 权限不足（无写入/关联）	为 Key 增加资产、组件、配件相关权限
`404 Not Found`	URL 路径错误，缺少 `/api/v1`	修正 ApiUrl，检查反向代理转发规则
`409 Conflict`	资产标签或序列号冲突	先按主键去重，再执行增量同步
`422 Unprocessable Entity`	字段格式不符合 API 要求	核对必填字段、长度、枚举值与日期格式
`429 Too Many Requests`	请求频率过高触发限流	降低并发，增加退避重试与批次间隔
`500 / 503`	服务端异常或维护窗口	保留失败批次，间隔重试并联系服务端管理员
连接超时 / TLS 失败	网络不可达、证书链异常	先测试连通性，再校验证书与时间同步

排障 Runbook（现场执行版）

当同步异常时，建议按以下顺序执行，减少误判与重复操作。

阶段 A：基础连通性

检查 ApiUrl 是否可访问（含 /api/v1）。
验证 DNS 解析、端口策略和代理规则。
确认设备系统时间准确，避免 TLS 校验失败。

阶段 B：权限与配置

校验 API Key 有效性与角色权限。
确认 Profile 选中的是正确环境（Lab/Prod）。
检查组件/配件开关与映射是否一致。

阶段 C：数据质量与去重

抽样核对序列号、资产标签、型号字段。
清理历史空序列号和重复资产。
为失败批次建立“错误码→处理人”跟踪表。

阶段 D：恢复与复盘

仅重试失败批次，避免全量重跑。
导出“成功/失败清单”并归档。
记录根因与修复方案，更新团队 SOP。

5 分钟快速排查卡（值班应急）

适用于“现场催得急、先恢复再深挖”的场景。先把问题分流，再进入完整 Runbook。

第 1 分钟

看错误码

先区分 4xx / 5xx / 超时，决定走权限还是网络线路。

第 2 分钟

验 URL 与 Key

确认 /api/v1、Profile、API Key 与权限是否正确。

第 3-4 分钟

小批重试

只重试失败对象，不做全量重跑，避免放大影响。

第 5 分钟

留证据

导出失败清单 + 日志片段，按工单模板上报并交接。

文档中心.