KVM-privacy/DEVELOP.md

# DEVELOP

## 环境要求

- 开发机：Linux x86_64，Python 3.10+，Go 1.21+
- 目标设备：NanoPC-T6 (RK3588)，192.168.123.181，user: pi
- SSH 访问：`sshpass -p "pi" ssh pi@192.168.123.181`

## 目录结构

```
KVM-privacy/
├── deps/                   # git submodule 依赖
│   ├── KVM/                # KVM 核心（Go + React）
│   ├── embedding/          # mem-bridge 记忆/路由服务
│   └── info-privacy-rs/    # Rust PII 检测脱敏
├── services/
│   └── privacy_gateway/    # mitmproxy 隐私网关（Python）
├── deploy/
│   └── systemd/            # systemd 服务文件（部署到设备）
├── scripts/                # 部署脚本
├── docs/plans/             # 设计文档（归档用，不做日常维护）
└── Makefile
```

## 设备上的实际路径

| 本地开发路径 | 设备部署路径 |
|------------|------------|
| `deps/KVM/` | `/home/pi/Desktop/KVM/` |
| `deps/embedding/` | `/home/pi/Desktop/embed-db/` |
| `deps/info-privacy-rs/` | `/home/pi/Desktop/info-privacy-rs/` |
| `services/privacy_gateway/` | `/data/project/KVM-privacy/services/privacy_gateway/` |

## Privacy Gateway 开发

### 本地测试

```bash
cd services/privacy_gateway
pip install mitmproxy httpx cryptography
python -c "from audit_logger import AuditLogger; l=AuditLogger('/tmp/test.db'); print('OK')"
```

### 服务文件说明

| 文件 | 职责 |
|------|------|
| `addon.py` | mitmproxy 核心：AI 域名匹配 → 拦截解密 → 脱敏 → 放行 |
| `interceptor.py` | 请求内容提取（Content-Type 检查、文件解析） |
| `upload_scanner.py` | 调用 info-privacy-rs API 完成脱敏 |
| `cert_manager.py` | 设备 CA 证书生成，存储于 `/etc/kvm-privacy/ca/` |
| `audit_logger.py` | SQLite append-only 审计，不记录原文 |
| `ai_domains.txt` | 拦截域名白名单 |

## 部署流程

### 初次部署（在本机执行）

```bash
# 克隆项目（含 submodule）
git clone --recurse-submodules http://edge-stack.synology.me:3000/qiurui/KVM-privacy.git
cd KVM-privacy

# 部署 Privacy Gateway（安装 mitmproxy + 上传服务文件 + 生成 CA 证书）
make deploy-gateway

# 部署 mem-bridge 服务（上传 systemd 文件并启动）
make deploy-memory
```

### 更新 Privacy Gateway 服务文件

```bash
sshpass -p pi scp services/privacy_gateway/*.py pi@192.168.123.181:/data/project/KVM-privacy/services/privacy_gateway/
sshpass -p pi ssh pi@192.168.123.181 "sudo systemctl restart privacy-gateway"
```

### systemd 服务管理

```bash
# 查看所有 KVM-Privacy 相关服务状态
make status

# 查看指定服务日志
make logs SVC=info-privacy-rs
make logs SVC=mem-bridge-memory
make logs SVC=privacy-gateway
```

## mem-bridge 开发（deps/embedding）

开发路径：`/data/rockchip/embedding/`，设备路径：`/home/pi/Desktop/embed-db/`

```bash
cd /data/rockchip/embedding
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 运行 memory-service（端口 8003）
python server.py --service memory

# 运行 router-service（端口 8002）
python server.py --service router
```

## info-privacy-rs 开发（deps/info-privacy-rs）

开发路径：`/data/rockchip/info-privacy-rs/`，设备路径：`/home/pi/Desktop/info-privacy-rs/`

```bash
# 交叉编译（在 x86 开发机，目标 aarch64）
cd /data/rockchip/info-privacy-rs
cargo build --release --target aarch64-unknown-linux-gnu

# 上传到设备
scp target/aarch64-unknown-linux-gnu/release/info-privacy-rs pi@192.168.123.181:/home/pi/Desktop/info-privacy-rs/target/release/
```

在设备上验证：
```bash
curl http://192.168.123.181:8001/health
# → {"status":"ok","rknn":true}
```

## KVM 隐私 API

KVM 服务在 8080 端口新增以下隐私相关端点（需 Bearer Token 鉴权）：

```
GET/POST /api/v1/privacy/masking          视频 PII 遮罩开关
GET      /api/v1/privacy/bboxes           当前活跃遮罩区域（调试）
GET      /api/v1/privacy/stats            今日拦截统计
GET      /api/v1/privacy/audit            审计日志（分页）
GET      /api/v1/privacy/cert             下载 CA 证书
GET      /api/v1/memory-admin/stats       记忆使用统计
GET      /api/v1/memory-admin/sessions    活跃会话列表
```