# 技能：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. 构建

```powershell
# 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）

```bash
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 否则挂起）：
```powershell
$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）：
```powershell
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. 验证清单（部署后逐条跑）

```powershell
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":"attack|normal"}` → 在线学习 |
| 看指标 | `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 ownership` | `git config --global --add safe.directory C:/CloudMusic/DPS` |
| 测试跑不过 control/tempfile | 同 TEMP 问题（第 1 条） |

## 7. 禁忌

- **不要**在设备上编译（zig 在本机，只传二进制）
- **不要**把数据集文件放进 git（gitignore 守门；许可边界见 `docs/许可合规备忘.md`）
- **不要**改检测语义却跳过闸门：改规则须过 `rule_coverage`（FP ≤1pp），改基线须过 `baseline_eval`
- **不要**把 API Key 当常量：它每次网关重启都会变
- **不要**用改名的方式"禁用"规则文件
- 提交前必跑 `scripts/ci.ps1 -SkipBuild`（fmt/clippy -D/test 三门禁）
