技能:open-xiezhi(獬豸)部署与操作

面向 AI 执行者的操作手册。照此文档可独立完成:构建 → 部署 → 验证 → 日常运维。
事实以本文为准;改动代码后先跑 CI 再部署。仓库:C:\CloudMusic\DPS(Gitee master)。

0. 系统事实卡(背下来)

项值
二进制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)

1. 构建


# 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\。

2. 部署(标准 Linux)


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)。

3. 部署(手机 proot / 远程 aarch64 设备)

访问(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 不触发)。

4. 验证清单(部署后逐条跑)


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。

5. 日常操作

操作方式
换 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":"attacknormal"}` → 在线学习
看指标GET /agent/metrics(免鉴权,Prometheus 文本);面板漂移卡同源
封 IP面板紧急操作 / POST /agent/respond {"action":"block_ip","ip":"1.2.3.4"}

6. 故障排查表(全是真实踩过的坑)

症状原因 → 处置
新构建二进制报 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 ownershipgit config --global --add safe.directory C:/CloudMusic/DPS
测试跑不过 control/tempfile同 TEMP 问题(第 1 条)

7. 禁忌

宁ICP备2026004621号