Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .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-*/

2026-08-07 22:31:32 +08:00

16 KiB

Raw Blame History

PRD: OpenClaw 安全合规检查与通知系统

版本: v1.0 日期: 2026-07-20 状态: [草稿] 作者: Simon 需求编号: REQ-集成-001 关联文档:

原型: 01-产品文档/08-集成生态/原型-REQ-集成-001-OpenClaw合规检查-v1.0.html

技术: 02-技术文档/实现配置/技术方案-REQ-集成-001-OpenClaw合规检查-v1.0.md

测试: 03-测试文档/03-功能测试用例/TC-REQ-集成-001-OpenClaw合规检查.md

1. 问题陈述 (Problem Statement)

背景

在重大安全活动期间（如国家网络安全周、重大会议保障期），公司需要对终端进行合规审计。

💡 本期目标：以 OpenClaw 检测为 一期试点，验证安全策略检查与通知框架的可行性。

扩展性设计：本系统设计为 通用安全策略检查平台，未来可低成本扩展其他策略和推送渠道。

问题描述

现状：目前依赖手工导出联软数据或通过火绒终端管理查看，缺乏自动化的定期检查和通知机制
痛点：
- 无法及时发现违规软件安装
- 依赖人工通知，效率低、易遗漏
- 无法形成定期的合规审计报告

影响

安全风险：未经授权的远程软件可能成为攻击入口
合规风险：无法满足重大活动期间的安全审计要求
业务影响：IT 运维人员需要投入大量人工排查

2. 目标 (Goals)

#	目标	成功衡量标准
G1	一期试点：自动检测 OpenClaw 安装	系统可自动发现所有已安装 OpenClaw 的终端，覆盖率 ≥ 95%
G2	及时通知当事人	检测到违规软件后，24 小时内通过企微发送通知给终端用户
G3	支持定时+手动执行	支持每日定时执行 + 管理员手动触发两种方式
G4	合规审计留痕	支持导出 Excel 审计报告，保留检测记录至少 6 个月
G5	活动期间管控	支持设置活动期间，自动开启检查
G6	框架可扩展	新增其他安全策略和推送渠道的成本 ≤ 1人天

3. 非目标 (Non-Goals)

#	非目标	原因
N1	自动封禁/断网	仅做通知提醒，不做自动阻断，避免影响业务连续性
N2	~~支持其他软件检查~~	⚠️ 已调整为扩展性设计，详见下方框架说明
N3	实时监控	采用定时检查（非实时推送），5 分钟级延迟可接受
N4	移动端管理	本期仅支持 PC Web 端管理
N5	火绒+联软自动同步	联软数据本期采用手动导入 Excel，不做自动 API 对接

3.1 扩展性框架设计（重要）

📐 架构理念：将"检测策略"与"推送渠道"解耦，实现可扩展的安全合规平台

3.1.1 策略类型（Strategy）

策略ID	策略名称	检测规则	数据源	状态
openclaw_remote	OpenClaw/向日葵远程软件	软件名包含 OpenClaw/向日葵/sunflower	火绒API	🔵 一期
unknown_usb	未知USB设备	未登记的USB设备接入	联软/火绒	⚪ 二期
illegal_proxy	非法代理软件	软件名包含 proxy/vpn	火绒API	⚪ 二期
unverified_software	未授权软件	不在白名单内的软件	火绒API	⚪ 二期

3.1.2 推送渠道（Channel）

渠道ID	渠道名称	适用场景	状态
wecom_app	企微应用消息	终端用户通知	🔵 一期
wecom_group	企微群通知	部门汇总、管理员	🔵 一期
email	邮件通知	正式留痕、邮件通知	⚪ 二期
sms	短信通知	紧急告警、无企微用户	⚪ 二期
dingtalk	钉钉通知	跨平台通知	⚪ 二期

3.1.3 策略-渠道映射

策略配置:
{
  "strategy_id": "openclaw_remote",
  "name": "OpenClaw远程软件检测",
  "channels": [
    {"id": "wecom_app", "template": "终端用户通知"},
    {"id": "wecom_group", "template": "部门汇总"}
  ],
  "schedule": "0 8 * * *",  # 每天8点
  "enabled": true
}

3.1.4 扩展成本

扩展项	工作量预估	说明
新增检测策略	0.5人天	仅需配置检测规则和数据源
新增推送渠道	1人天	需开发渠道适配器
新策略+新渠道	1人天	配置映射关系即可

4. 用户故事 (User Stories)

角色定义

IT 管理员：负责配置检查策略、查看检测结果、触发手动检查
终端用户：收到通知的被检查对象
部门负责人：（可选）收到本部门汇总通知

用户故事列表

#	角色	用户故事	优先级
US1	IT 管理员	我希望系统能自动从火绒 API 获取终端软件列表，以便及时发现 OpenClaw 安装	P0
US2	IT 管理员	我希望能够导入联软导出的用户-终端关联 Excel，以便知道哪台设备属于哪个用户	P0
US3	IT 管理员	我希望系统能自动匹配"终端→用户"，输出"谁在哪台设备安装了 OpenClaw"，以便精准确认责任人	P0
US4	IT 管理员	我希望能够设置定时任务（如每天 8:00 自动检查），以便在活动期间自动执行	P0
US5	IT 管理员	我希望能够手动点击"立即检查"按钮，以便随时执行检查	P0
US6	IT 管理员	我希望能够编辑通知模板（包含变量），以便自定义通知内容	P1
US7	IT 管理员	我希望能够设置"是否通知部门负责人"开关，以便灵活配置通知范围	P1
US8	IT 管理员	我希望能够导出 Excel 报告，以便留存审计记录	P0
US9	终端用户	我希望收到企微应用消息通知，告诉我哪台设备安装了违规软件，以便及时卸载	P0
US10	部门负责人	我希望收到本部门的汇总通知（可选），以便了解本部门合规情况	P1
US11	IT 管理员	我希望能够新增其他安全策略（如未知USB、非法代理），以便扩展检测范围	P0
US12	IT 管理员	我希望能够配置不同策略使用不同推送渠道（如邮件、短信），以便灵活通知	P1

5. 需求规格 (Requirements)

5.1 功能需求

📌 需求说明：一期以 OpenClaw 为试点，但架构设计需支持策略和渠道的扩展。

T0: 策略与渠道管理（框架层）

需求ID	描述	优先级	验收标准
REQ-001-00	策略配置：支持创建/编辑/启停安全策略	P0	可配置策略名称、检测规则、数据源、推送渠道
REQ-001-00a	预置策略：一期预置"OpenClaw远程软件"检测策略	P0	内置关键词规则（OpenClaw/向日葵/sunflower）
REQ-001-00b	渠道配置：支持配置推送渠道参数	P0	企微渠道：应用ID/Secret；邮件渠道：SMTP配置
REQ-001-00c	渠道适配器：企微应用消息发送	P0	复用现有企微消息能力
REQ-001-00d	渠道适配器：（扩展）邮件发送	P2	可延后至二期
REQ-001-00e	渠道适配器：（扩展）短信发送	P2	可延后至二期

T1: 数据采集层

⚠️ 注意：火绒 API 集成功能已存在于系统中（app/integrations/huorong），无需重复开发。

现有 API：GET /api/admin/integrations/huorong/terminals - 获取终端列表

现有 API：GET /api/admin/integrations/huorong/terminals/{client_id} - 获取终端详情（含软件列表）

本期仅需确认现有 API 满足 OpenClaw 检测需求（获取终端软件列表）。

需求ID	描述	优先级	验收标准
REQ-001-01	✅ 已存在：火绒 API 集成（`/api/clnts/_list` 获取终端列表）	-	复用现有功能
REQ-001-02	✅ 已存在：火绒 API 集成（`/api/clnts/_info2` 获取软件列表）	-	复用现有功能，确认支持 OpenClaw 检测
REQ-001-03	联软 Excel 导入：支持上传 .xlsx/.xls 文件	P0	能解析联软导出的 Excel，提取用户-终端关联字段
REQ-001-04	联软字段映射：自动识别 `用户名`、`设备名称`、`MAC地址`、`设备IP`、`部门名称`	P0	上传文件后自动匹配字段，无需手动配置
REQ-001-05	联软数据存储：将导入的关联数据存入数据库	P0	导入后数据持久化，支持后续匹配查询

T2: 数据融合引擎

需求ID	描述	优先级	验收标准
REQ-001-06	IP 地址匹配：优先通过 IP 完全匹配关联终端和用户	P0	火绒终端 IP 与联软数据完全一致时，成功匹配
REQ-001-07	主机名匹配：IP 未匹配时，通过主机名包含匹配	P0	火绒主机名包含联软设备名称时，成功匹配
REQ-001-08	MAC 地址匹配：前两者未匹配时，通过 MAC 地址匹配	P0	火绒 MAC 与联软 MAC 一致时，成功匹配
REQ-001-09	未匹配记录标记：无法关联到用户的终端需标记为"未匹配"	P0	输出结果中明确标注哪些终端无法确定责任人
REQ-001-10	OpenClaw 命中过滤：仅输出安装了 OpenClaw 的终端	P0	匹配关键词：`OpenClaw`, `向日葵`, `sunflower`（不区分大小写）

T3: 策略规则与命中管理

需求ID	描述	优先级	验收标准
REQ-001-11	白名单规则：支持配置排除的用户/终端	P1	配置白名单后，命中用户不在通知范围内
REQ-001-12	部门汇总：支持按部门聚合命中结果	P1	统计每个部门的违规终端数量
REQ-001-12a	命中状态管理：支持手动修改命中记录状态	P0	状态：待处理→已通知→已解决/误报
REQ-001-12b	自动状态更新：再次检测时自动判断状态变化	P0	历史命中用户再次检测未命中，自动标记"已解决"
REQ-001-12c	状态变更记录：记录状态变更时间和操作人	P1	可查看每条记录的状态变更历史

T4: 通知模板管理

需求ID	描述	优先级	验收标准
REQ-001-13	模板变量：支持变量替换（{username}, {device}, {dept}, {software}, {detect_time}）	P0	通知内容中变量被正确替换
REQ-001-14	默认模板：内置默认通知模板	P0	未配置模板时使用默认模板发送
REQ-001-15	模板编辑：支持富文本编辑通知模板	P1	可编辑标题和正文内容
REQ-001-16	企微消息发送：通过企微应用消息接口发送通知	P0	成功发送至终端用户企微

T5: 调度与执行

需求ID	描述	优先级	验收标准
REQ-001-17	定时任务：支持配置 cron 表达式执行检查	P0	每天 8:00 自动执行检查任务
REQ-001-18	手动触发：提供"立即检查"按钮	P0	点击后立即执行检查流程
REQ-001-19	活动期间开关：支持设置活动起止时间	P0	活动期间自动开启检查，非活动期间可手动开启
REQ-001-20	执行日志：记录每次执行的起止时间、命中数量、发送结果	P0	可查看历史执行记录
REQ-001-21	Excel 导出：支持导出检测结果为 Excel	P0	导出字段：用户名、用户全名、部门、设备名称、IP、MAC、软件名称、安装日期

5.2 边缘情况处理

场景	处理方式
火绒 API 调用失败	记录错误日志，发送告警给 IT 管理员，继续使用上次导入的联软数据
联软 Excel 未导入	仅使用火绒数据，未匹配用户的终端标记为"用户未知"
用户无企微账户	跳过发送，标记为"发送失败"，记录日志
重复检测	同一用户同一天多次检测，仅发送首次通知（去重）
空结果（无违规）	发送"本次检查无违规"的汇总通知给管理员

6. 成功指标 (Success Metrics)

6.1 领先指标（Leading Indicators）

指标	定义	目标	测量方式
检测覆盖率	成功关联到用户的终端数 / 火绒总终端数	≥ 85%	数据库统计
通知成功率	成功发送通知数 / 需通知总数	≥ 95%	企微 API 返回
执行完成率	定时任务成功执行次数 / 计划执行次数	≥ 99%	调度日志

6.2 滞后指标（Lagging Indicators）

指标	定义	目标	测量方式
闭环率	当事人确认处理（卸载）的比例	≥ 80%	用户反馈或二次检测
投诉率	通知后用户投诉误报的比例	< 5%	反馈记录
合规达标率	活动期间最后一天违规终端清理比例	100%	最终检测报告

7. 开放问题 (Open Questions)

#	问题	负责人	状态
Q1	联软 Excel 导入频率？建议每日导入一次还是每次检查前导入？	产品	待确认
Q2	部门负责人通知是否需要汇总（多条合并为1条）？	产品	待确认
Q3	活动期间结束后，是否需要自动关闭定时任务？	产品	待确认

7.1 任务拆分说明（重要）

⚠️ 系统现有火绒 API 集成，无需重复开发

任务	说明	状态
T0: 策略与渠道管理	需开发：策略配置、渠道适配器框架	🔲 待开发
T1a: 火绒API集成	现有功能已支持（`/api/admin/integrations/huorong/terminals`）	✅ 已存在
T1b: 联软Excel导入	需开发：从联软导出Excel导入用户-终端关联	🔲 待开发
T2: 数据融合引擎	需开发：IP/主机名/MAC三级匹配	🔲 待开发
T3: 策略规则引擎	需开发：白名单、命中过滤	🔲 待开发
T4: 通知模板管理	需开发：模板编辑、企微消息发送	🔲 待开发
T5: 调度与执行	需开发：定时任务、手动触发、活动开关	🔲 待开发

实际开发任务：T0 + T1b + T2 + T3 + T4 + T5（共6个任务）

8. 时间计划 (Timeline)

阶段划分

⚠️ 注：T1a（火绒API）已存在，无需开发。

阶段	内容	预估工期
Phase 0	T0（策略与渠道框架）+ T1b（联软导入）	2 天
Phase 1	T2（融合引擎）+ T3（策略规则）	2 天
Phase 2	T4（通知模板）+ T5（调度执行+导出）	2 天
Phase 3	联调测试 + 验收	2 天
合计	实际开发	8 天

里程碑

日期	里程碑
2026-07-25	Phase 1-2 完成，进入联调
2026-07-28	Phase 3-4 完成，进入测试
2026-07-30	UAT 通过，具备上线条件

9. 风险与依赖 (Risks & Dependencies)

风险/依赖	影响	缓解措施
火绒 API 性能	终端数量多时可能超时	分页获取，增加重试机制
联软数据更新	用户-终端关联可能变更	建议每次检查前重新导入最新 Excel
企微消息频率限制	大批量发送可能触发限制	增加发送间隔，批量改单发

10. 附录

数据字段映射

火绒终端字段（API 返回）

client_id: 终端唯一标识
hostname: 主机名
ip: IP 地址
mac: MAC 地址
software: 已安装软件列表

联软 Excel 字段

用户名: 企微/AD 用户名
用户全名: 真实姓名
部门名称: 组织架构
设备名称: 终端名称
设备IP: IP 地址
MAC地址: MAC 地址
软件名称: 已安装软件
安装日期: 软件安装时间

匹配优先级

IP 地址完全匹配
主机名包含匹配（联软设备名称 in 火绒主机名）
MAC 地址匹配

变更记录

日期	版本	变更内容	变更人	变更原因
2026-07-20	v1.0	初始版本	Simon	新建需求

审批记录

角色	姓名	日期	签字
产品负责人
技术负责人
业务负责人

16 KiB Raw Blame History Unescape Escape

PRD: OpenClaw 安全合规检查与通知系统

1. 问题陈述 (Problem Statement)

背景

问题描述

影响

2. 目标 (Goals)

3. 非目标 (Non-Goals)

3.1 扩展性框架设计（重要）

3.1.1 策略类型（Strategy）

3.1.2 推送渠道（Channel）

3.1.3 策略-渠道映射

3.1.4 扩展成本

4. 用户故事 (User Stories)

角色定义

用户故事列表

5. 需求规格 (Requirements)

5.1 功能需求

T0: 策略与渠道管理（框架层）

T1: 数据采集层

T2: 数据融合引擎

T3: 策略规则与命中管理

T4: 通知模板管理

T5: 调度与执行

5.2 边缘情况处理

6. 成功指标 (Success Metrics)

6.1 领先指标（Leading Indicators）

6.2 滞后指标（Lagging Indicators）

7. 开放问题 (Open Questions)

7.1 任务拆分说明（重要）

8. 时间计划 (Timeline)

阶段划分

里程碑

9. 风险与依赖 (Risks & Dependencies)

10. 附录

数据字段映射

火绒终端字段（API 返回）

联软 Excel 字段

匹配优先级

变更记录

16 KiB

Raw Blame History