面向 AI 执行者的操作手册。照此文档可独立完成:构建 → 部署 → 验证 → 日常运维。
事实以本文为准;改动代码后先跑 CI 再部署。仓库:C:\CloudMusic\DPS(Gitee master)。
| 项 | 值 | |
|---|---|---|
| 二进制 | dps-engine(gRPC 检测引擎)、dps-gateway(网关+面板)、dps-train(训练) | |
| 引擎 gRPC | :50051(DPS_LISTEN_ADDR) | |
| 网关端口 | 反代 :8080、正代/CONNECT :8081、智能体 API :9070、面板 :9080、控制口 :9090 | |
| 面板 | http://主机:9080,五页 SPA;Key 在右下卡片填入 | |
| API Key | 内存态,网关每次重启换新;从 gateway.log 提取:`grep -o 'dps_[0-9a-f]\{32\}' gateway.log \ | tail -1` |
| 规则 | rules/crs/.yaml(OWASP CRS 精选)+ rules/custom/.yaml(含 composite/mail);改内容即热加载,改名/移动不触发 | |
| 模型/基线 | data/ml_model.json(缺省降级纯规则)、data/param_baseline.json(缺省不加载基线通道) | |
| 测试 | scripts/ci.ps1(Windows)/ scripts/ci.sh(POSIX)= fmt → clippy -D → test → build;当前 213 测试全绿 | |
| 检测分层 | L0 黑名单 → 网关 fast 快筛(14) → L1 规则(122) → L2 语义(SQL AST) → L3 ML(贝叶斯+异常+参数基线四信号) → 处置建议(Block/Challenge/Monitor/Allow) | |
| 三种模式 | inline=快筛拦+深检同步拦;mixed(默认)=快筛拦+深检异步记;bypass=只记录。运行时切换真实生效(面板/POST /api/mode/控制口);配置 inspect.mode=sync 是启动默认(=inline) |
# Windows(DSH 沙箱必须先重定向 TEMP,否则新二进制写 %TEMP% 报 os error 5)
$env:TEMP=$env:TMP='C:\CloudMusic\DPS\data\tmp'
cd C:\CloudMusic\DPS\dps-engine
cargo build --release # 本机 x86_64
cargo zigbuild --release --target aarch64-unknown-linux-gnu --bin dps-engine --bin dps-gateway # ARM 交叉
交叉编译产物无 .exe 后缀,在 target\aarch64-unknown-linux-gnu\release\。
mkdir -p /opt/xiezhi && cp dps-engine dps-gateway /opt/xiezhi/ && cp -r rules /opt/xiezhi/
cd /opt/xiezhi
# 可选:data/ml_model.json + data/param_baseline.json(没有则自动降级)
DPS_LISTEN_ADDR=0.0.0.0:50051 DPS_ML_MODEL=data/ml_model.json ./dps-engine &
DPS_AGENT_ADDR=0.0.0.0:9070 DPS_WEB_ADDR=0.0.0.0:9080 DPS_CONTROL_API=0.0.0.0:9090 ./dps-gateway &
# 常驻:写 systemd unit,Restart=always,gateway After=engine
关键环境变量另有:DPS_ML_SAVE_INTERVAL(学习落盘,默认 60s)、DPS_BASELINE_SAVE_INTERVAL(基线落盘,默认 300s)。
访问(dropbear SSH 端口 2022,必须带 hostkey 否则挂起):
$plink='C:\CloudMusic\DPS\data\tools\plink.exe'
$fp='SHA256:Yqk6ZeeXkMPehGwcNmxL7IPsAqkzHihTVU7ksubDa1A'
$pw='<设备root密码>'
& $plink -batch -ssh -P 2022 -hostkey $fp -pw $pw root@192.168.1.10 '<远程命令>'
传文件唯一可靠方式 = cat 管道(pscp/scp 在该 proot 上报 unexpected EOF):
cmd /c "`"$plink`" -batch -ssh -P 2022 -hostkey $fp -pw $pw root@192.168.1.10 `"cat > /root/open-xiezhi/bin/dps-gateway`" < `"C:\...\dps-gateway`""
# 配置等文本文件用 base64 通道(防 BOM/转义):
$b64=[Convert]::ToBase64String([IO.File]::ReadAllBytes($p)); # 远端: echo $b64 | base64 -d > file
重启(设备布局 /root/open-xiezhi/{bin,rules,data}):
cd /root/open-xiezhi; chmod +x bin/*; pkill dps-engine; pkill dps-gateway; sleep 2
(nohup env DPS_LISTEN_ADDR=0.0.0.0:50051 DPS_ML_MODEL=/root/open-xiezhi/data/ml_model.json DPS_PARAM_BASELINE=/root/open-xiezhi/data/param_baseline.json ./bin/dps-engine > engine.log 2>&1 &)
(nohup env DPS_AGENT_ADDR=0.0.0.0:9070 DPS_WEB_ADDR=0.0.0.0:9080 DPS_CONTROL_API=0.0.0.0:9090 ./bin/dps-gateway > gateway.log 2>&1 &)
改了 rules/ 后必须重启引擎(watcher 只认内容变更,rename 不触发)。
curl http://主机:9070/agent/health # → {"status":"healthy",...}
curl http://主机:9080/ -o NUL -w '%{http_code}' # → 200,字节数应 ~46K(最新面板)
# Key 提取后:
curl http://主机:9080/api/rules -H "x-api-key: $K" # → gateway ~14 + engine ~94
curl http://主机:9070/agent/metrics # → dps_detect_total / dps_drift_* 等 gauge
# 攻击弹(应 verdict=attack)与干净弹(应 clean):
curl -X POST http://主机:9070/agent/analyze -H "x-api-key: $K" -H 'content-type: application/json' -d '{"payload":"GET /login?user=admin'"'"' OR 1=1-- HTTP/1.1","source_type":"http"}'
# 模式执法(需有 inspect:true 路由):mixed 下 -H "X-Test: ' or 1=1" 打8080 应 403;切 bypass 应放行
source_type 支持 http / sql / mail。
| 操作 | 方式 | |
|---|---|---|
| 换 Key | 重启网关 → 从 gateway.log 提取 → 面板"系统运维"保存(Key 每次重启必换) | |
| 切模式 | 面板 seg 按钮 / POST http://主机:9080/api/mode {"mode":"inline"}(同源带 Key) | |
| 加临时规则 | 面板"规则管理"添加(进 fast 层立即生效);或 POST /agent/rules 批量 | |
| 正式加规则 | 改 rules/*.yaml(内容,不改名)→ 热加载;不放心就重启引擎 | |
| 看处置 | 面板"检测事件"(GET /api/events);统计看 /api/stats | |
| 误漏报回灌 | `POST /agent/feedback {"payload":"...","label":"attack | normal"}` → 在线学习 |
| 看指标 | GET /agent/metrics(免鉴权,Prometheus 文本);面板漂移卡同源 | |
| 封 IP | 面板紧急操作 / POST /agent/respond {"action":"block_ip","ip":"1.2.3.4"} |
| 症状 | 原因 → 处置 |
|---|---|
新构建二进制报 os error 5 写 %TEMP% | DSH 沙箱 → 先 set TEMP=C:\CloudMusic\DPS\data\tmp |
| plink 卡死在 hostkey 提示 | 必须 -batch -hostkey SHA256:Yqk6... |
pscp/scp unexpected EOF | 该 proot 只认 cat 管道/base64 通道 |
| 规则改了不生效 | watcher 不吃 rename → 改文件内容,或重启引擎 |
| 规则数对不上(如 118 vs 122) | 设备 rules/ 落后仓库 → 同步文件后重启 |
| 面板卡片"一直加载中" | 跨源 CORS → 网关须为含 OPTIONS 预检的版本(已有);或 Key 未填 |
| 设备 ping 不通/SSH 超时 | 手机息屏断网/WiFi 租期 → 唤醒重连;别在息屏时归因代码 |
| 设备整体卡死、SSH 数分钟无响应 | proot 单实例串行化 syscall,CPU 密集任务饿死同 proot 进程 → 等空载复测再归因 |
| 面板统计只有 14 条规则 | 老版本口径 bug(只数 fast 层)→ 升级网关,新口径显示 108+ |
| PowerShell 内联 JSON/正则引号被吞 | 用文件 -d "@file" / 变量拼模式;Set-Content -Encoding UTF8 会加 BOM → 用 [IO.File]::WriteAllText |
git dubious ownership | git config --global --add safe.directory C:/CloudMusic/DPS |
| 测试跑不过 control/tempfile | 同 TEMP 问题(第 1 条) |
docs/许可合规备忘.md)rule_coverage(FP ≤1pp),改基线须过 baseline_evalscripts/ci.ps1 -SkipBuild(fmt/clippy -D/test 三门禁)