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

18 KiB

Raw Blame History

技术方案：安全策略检查平台

版本: v1.0 日期: 2026-07-20 状态: [草稿] 关联PRD: 01-产品文档/08-集成生态/PRD-REQ-集成-001-OpenClaw合规检查-v1.0.md

1. 系统架构

1.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                      安全策略检查平台                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌───────────────────┐   │
│  │   策略配置   │  │   渠道配置    │  │   任务调度        │   │
│  │  (策略管理)  │  │  (渠道管理)   │  │  (定时/手动)      │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬──────────┘   │
│         │                  │                     │              │
│         └──────────────────┼─────────────────────┘              │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    策略执行引擎                          │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
│  │  │ 数据采集层   │→ │ 数据融合层   │→ │ 规则匹配层  │  │   │
│  │  │ 火绒API     │  │ IP/主机名   │  │ 关键词过滤  │  │   │
│  │  │ 联软Excel  │  │ MAC匹配     │  │ 白名单过滤  │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    通知发送层                            │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
│  │  │ 企微应用    │  │ 企微群      │  │ (扩展)邮件  │  │   │
│  │  │             │  │             │  │ (扩展)短信  │  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
│                            ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                    数据存储层                            │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
│  │  │ 策略配置    │  │ 命中记录    │  │ 执行日志    │  │   │
│  │  │ (PostgreSQL)│  │ (PostgreSQL)│  │ (PostgreSQL)│  │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

1.2 模块设计

模块	职责	技术选型
策略配置管理	策略增删改查、启停	FastAPI + SQLAlchemy
渠道配置管理	渠道增删改查、适配器	策略模式
数据采集层	火绒API调用、联软Excel解析	openpyxl + requests
数据融合层	IP/主机名/MAC三级匹配	Python dict/hash
规则匹配层	关键词过滤、白名单	正则表达式
通知发送层	企微消息发送	适配器模式
任务调度层	APScheduler定时任务	APScheduler
数据存储层	PostgreSQL	SQLAlchemy ORM

2. 数据库设计

2.1 表结构

2.1.1 安全策略配置表 (security_strategies)

CREATE TABLE security_strategies (
    id SERIAL PRIMARY KEY,
    strategy_id VARCHAR(50) UNIQUE NOT NULL,  -- 如: openclaw_remote
    name VARCHAR(100) NOT NULL,               -- 策略名称
    description TEXT,                          -- 描述
    detection_type VARCHAR(20) NOT NULL,        -- 检测类型: software/usb/network
    keywords TEXT NOT NULL,                    -- 关键词,逗号分隔
    data_source VARCHAR(50) NOT NULL,          -- 数据源: huorong/lianruan/both
    channels JSONB NOT NULL DEFAULT '[]',      -- 推送渠道配置
    whitelist TEXT,                            -- 白名单,逗号分隔
    is_enabled BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2.1.2 渠道配置表 (notification_channels)

CREATE TABLE notification_channels (
    id SERIAL PRIMARY KEY,
    channel_id VARCHAR(50) UNIQUE NOT NULL,   -- 如: wecom_app
    name VARCHAR(100) NOT NULL,               -- 渠道名称
    channel_type VARCHAR(20) NOT NULL,         -- 渠道类型: wecom/email/sms/dingtalk
    config JSONB NOT NULL DEFAULT '{}',        -- 渠道配置参数
    is_enabled BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2.1.3 命中记录表 (security_hits)

CREATE TABLE security_hits (
    id SERIAL PRIMARY KEY,
    strategy_id VARCHAR(50) NOT NULL,          -- 策略ID
    username VARCHAR(100),                      -- 用户名
    fullname VARCHAR(100),                     -- 用户全名
    dept VARCHAR(100),                         -- 部门
    device_name VARCHAR(100),                  -- 设备名称
    ip_address VARCHAR(50),                     -- IP地址
    mac_address VARCHAR(50),                   -- MAC地址
    hit_content TEXT NOT NULL,                 -- 命中内容(软件名等)
    status VARCHAR(20) DEFAULT 'pending',      -- pending/notified/resolved/false_positive
    first_detected_at TIMESTAMP NOT NULL,      -- 首次检测时间
    last_detected_at TIMESTAMP NOT NULL,      -- 最近检测时间
    notified_at TIMESTAMP,                     -- 通知时间
    resolved_at TIMESTAMP,                     -- 解决时间
    resolved_by VARCHAR(100),                  -- 解决人
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id)
);

2.1.4 状态变更历史表 (security_hit_history)

CREATE TABLE security_hit_history (
    id SERIAL PRIMARY KEY,
    hit_id INTEGER NOT NULL,
    old_status VARCHAR(20),
    new_status VARCHAR(20) NOT NULL,
    changed_by VARCHAR(100),
    change_reason TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (hit_id) REFERENCES security_hits(id)
);

2.1.5 执行日志表 (security_executions)

CREATE TABLE security_executions (
    id SERIAL PRIMARY KEY,
    strategy_id VARCHAR(50) NOT NULL,
    execution_type VARCHAR(20) NOT NULL,      -- scheduled/manual
    total_terminals INTEGER DEFAULT 0,         -- 总终端数
    hit_count INTEGER DEFAULT 0,                -- 命中数
    notified_count INTEGER DEFAULT 0,           -- 通知成功数
    status VARCHAR(20) NOT NULL,               -- running/success/failed
    error_message TEXT,
    started_at TIMESTAMP NOT NULL,
    finished_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id)
);

2.1.6 通知模板表 (notification_templates)

CREATE TABLE notification_templates (
    id SERIAL PRIMARY KEY,
    strategy_id VARCHAR(50) NOT NULL,
    channel_id VARCHAR(50) NOT NULL,
    title VARCHAR(200),
    content TEXT NOT NULL,
    is_default BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (strategy_id) REFERENCES security_strategies(strategy_id),
    FOREIGN KEY (channel_id) REFERENCES notification_channels(channel_id)
);

3. 核心流程设计

3.1 定时检查流程

┌─────────────────┐
│  定时任务触发   │
│  (APScheduler)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│ 检查活动期间    │     │ 检查策略是否启用 │
│ (活动开关)      │     │ (is_enabled)    │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
              ┌─────────────┐
              │ 加载策略    │
              │ 获取关键词  │
              │ 获取渠道    │
              └──────┬──────┘
                     ▼
         ┌─────────────────────┐
         │  从火绒API获取      │
         │  终端软件列表       │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  加载联软Excel      │
         │  用户-终端关联      │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  三级匹配           │
         │  IP → 主机名 → MAC │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  关键词过滤         │
         │  白名单过滤         │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  生成命中记录       │
         │  状态=pending       │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  匹配历史记录       │
         │  状态变更判断       │
         │  (自动解决逻辑)    │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  发送企微通知      │
         │  更新状态           │
         └──────────┬──────────┘
                    ▼
         ┌─────────────────────┐
         │  记录执行日志      │
         │  更新统计          │
         └─────────────────────┘

3.2 状态自动变更逻辑

def auto_update_status(new_hits, old_hits_map):
    """
    new_hits: 本次检测到的命中列表
    old_hits_map: 历史命中字典 {user+device: hit_record}
    """
    for hit in new_hits:
        key = f"{hit.username}:{hit.device_name}"
        if key in old_hits_map:
            old_hit = old_hits_map[key]
            # 历史存在，本次仍命中 -> 保持原状态或更新为已通知
            if old_hit.status == 'pending':
                old_hit.status = 'notified'
                old_hit.notified_at = now()
        else:
            # 新命中 -> 创建记录，状态=pending
            create_hit_record(hit)

    # 检查历史命中本次是否未命中 -> 自动标记已解决
    for key, old_hit in old_hits_map.items():
        if key not in new_hits_map:
            if old_hit.status in ['pending', 'notified']:
                old_hit.status = 'resolved'
                old_hit.resolved_at = now()
                old_hit.resolved_by = 'system:auto'

4. API设计

4.1 策略管理

方法	路径	说明
GET	/api/security/strategies	获取策略列表
POST	/api/security/strategies	创建策略
GET	/api/security/strategies/{id}	获取策略详情
PUT	/api/security/strategies/{id}	更新策略
DELETE	/api/security/strategies/{id}	删除策略
POST	/api/security/strategies/{id}/toggle	启用/停用策略

4.2 渠道管理

方法	路径	说明
GET	/api/security/channels	获取渠道列表
POST	/api/security/channels	创建渠道
PUT	/api/security/channels/{id}	更新渠道
DELETE	/api/security/channels/{id}	删除渠道
POST	/api/security/channels/{id}/test	测试渠道连接

4.3 命中记录

方法	路径	说明
GET	/api/security/hits	获取命中记录列表
PUT	/api/security/hits/{id}/status	更新命中状态
GET	/api/security/hits/{id}/history	获取状态变更历史

4.4 执行控制

方法	路径	说明
POST	/api/security/execute	手动触发检查
GET	/api/security/executions	获取执行历史
GET	/api/security/executions/{id}	获取执行详情

4.5 导出

方法	路径	说明
GET	/api/security/export	导出Excel报告

5. 扩展性设计

5.1 策略类型扩展

# 策略检测器基类
class BaseDetector(ABC):
    @abstractmethod
    def detect(self, terminals: List[Terminal]) -> List[Hit]:
        pass

# 软件检测器
class SoftwareDetector(BaseDetector):
    def detect(self, terminals):
        # 关键词匹配
        pass

# USB检测器
class USBDetector(BaseDetector):
    def detect(self, terminals):
        # USB设备检测
        pass

# 注册策略检测器
DETECTOR_REGISTRY = {
    'software': SoftwareDetector,
    'usb': USBDetector,
}

5.2 渠道适配器扩展

# 渠道发送器基类
class BaseSender(ABC):
    @abstractmethod
    def send(self, template: Template, targets: List[Target]) -> SendResult:
        pass

# 企微发送器
class WeComSender(BaseSender):
    def send(self, template, targets):
        # 企微API调用
        pass

# 邮件发送器
class EmailSender(BaseSender):
    def send(self, template, targets):
        # SMTP发送
        pass

# 注册渠道发送器
SENDER_REGISTRY = {
    'wecom': WeComSender,
    'email': EmailSender,
    'sms': SMSSender,
}

6. 安全与合规

6.1 数据安全

白名单、敏感配置数据加密存储
操作日志记录所有管理操作
定期备份数据库

6.2 隐私合规

用户-终端关联数据仅用于通知定位
不存储额外个人信息
符合公司数据安全规范

7. 部署方案

7.1 依赖服务

服务	版本要求
PostgreSQL	14+
Redis	6+ (可选，用于缓存)
APScheduler	3.10+

7.2 环境变量

# 数据库
DATABASE_URL=postgresql://user:pass@localhost:5432/security_db

# 火绒API (复用现有配置)
HUORONG_BASE_URL=
HUORONG_KEY=
HUORONG_SECRET=

# 企微应用 (复用现有配置)
WECOM_AGENT_ID=
WECOM_SECRET=

8. 验收标准

验收项	标准
定时执行	每天8:00自动执行，99%可用率
手动触发	点击后5分钟内完成检查
匹配准确率	IP/主机名/MAC三级匹配成功率≥85%
通知成功率	企微通知送达率≥95%
状态自动更新	历史命中用户再次未命中，自动标记已解决
Excel导出	正确导出所有命中字段

9. 后续扩展

扩展项	工作量	说明
新增检测策略	0.5天	配置关键词和数据源
新增邮件渠道	1天	开发EmailSender
新增短信渠道	1天	开发SMSSender
新增钉钉渠道	1天	开发DingTalkSender

18 KiB Raw Blame History

技术方案：安全策略检查平台

1. 系统架构

1.1 整体架构

1.2 模块设计

2. 数据库设计

2.1 表结构

2.1.1 安全策略配置表 (security_strategies)

2.1.2 渠道配置表 (notification_channels)

2.1.3 命中记录表 (security_hits)

2.1.4 状态变更历史表 (security_hit_history)

2.1.5 执行日志表 (security_executions)

2.1.6 通知模板表 (notification_templates)

3. 核心流程设计

3.1 定时检查流程

3.2 状态自动变更逻辑

4. API设计

4.1 策略管理

4.2 渠道管理

4.3 命中记录

4.4 执行控制

4.5 导出

5. 扩展性设计

5.1 策略类型扩展

5.2 渠道适配器扩展

6. 安全与合规

6.1 数据安全

6.2 隐私合规

7. 部署方案

7.1 依赖服务

7.2 环境变量

8. 验收标准

9. 后续扩展

18 KiB

Raw Blame History