qiurui/KVM-privacy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: add README/DEVELOP/RELEASE and fix systemd service paths

Browse Source 
- Add README.md: 架构概览、端口规划、快速部署
- Add DEVELOP.md: 开发环境、目录结构、部署流程、API 说明
- Add RELEASE.md: v0.1.0 发版记录
- Fix info-privacy.service: Python uvicorn → Rust info-privacy-rs binary
- Fix mem-bridge-*.service: WorkingDirectory /data/rockchip/embedding → /home/pi/Desktop/embed-db

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
qiurui
2026-02-28 19:11:38 +08:00
co-authored by Claude Sonnet 4.6
parent 47fc0dd22e
commit d32b4df709
6 changed files with 247 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEVELOP.md
+138
View File
@@ -0,0 +1,138 @@
# 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 活跃会话列表
```
README.md
+66
View File
@@ -0,0 +1,66 @@
# KVM-Privacy Hub
在 KVM-over-IP 系统基础上叠加三层隐私保护能力，运行于 NanoPC-T6 (RK3588)。
## 架构概览
```
┌─────────────────────────────────────────────────────────┐
│ KVM 控制台 (8080) │
│ Go 单体 + React Web UI + WebRTC 推流 │
└──────────────┬──────────────────────┬───────────────────┘
│ │
┌──────────▼──────────┐ ┌────────▼────────────────┐
│ Phase 1: 视频遮罩 │ │ Phase 3: AI 路由层 │
│ OCR 检测 → YUV黑框 │ │ mem-bridge 8003/8002 │
│ /api/v1/privacy/ │ │ Qwen2-1.5B(Ollama本地) │
└──────────┬──────────┘ └─────────────────────────┘
│
┌──────────▼──────────┐
│ Phase 2: 隐私网关 │
│ mitmproxy (8888) │
│ 拦截 AI 平台上传 │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ info-privacy-rs │
│ RKNN PII 检测/脱敏 │
│ Rust 加速 (8001) │
└─────────────────────┘
```
## 端口规划
| 服务 | 端口 | 说明 |
|------|------|------|
| kvm-server | 8080 | KVM 主服务（systemd 管理） |
| info-privacy-rs | 8001 | Rust/RKNN PII 检测与脱敏 |
| mem-bridge memory | 8003 | 会话记忆服务 |
| mem-bridge router | 8002 | AI 路由服务 |
| privacy-gateway | 8888 | mitmproxy 代理网关 |
## 依赖项目（submodule）
| 路径 | 说明 |
|------|------|
| `deps/KVM` | KVM-over-IP 核心服务（Go + React） |
| `deps/embedding` | mem-bridge 记忆服务与 AI 路由 |
| `deps/info-privacy-rs` | Rust/RKNN 加速的 PII 检测脱敏服务 |
## 快速部署
```bash
git clone --recurse-submodules http://edge-stack.synology.me:3000/qiurui/KVM-privacy.git
cd KVM-privacy
# 部署隐私网关 + systemd 服务
make deploy-gateway
# 部署 mem-bridge 记忆服务
make deploy-memory
# 查看所有服务状态
make status
```
详见 [DEVELOP.md](DEVELOP.md)。
RELEASE.md
+34
View File
@@ -0,0 +1,34 @@
# RELEASE
## v0.1.0 (2026-02-28)
初始版本，KVM-Privacy Hub 三层隐私能力落地。
### 新功能
**Phase 1 — 视频 PII 遮罩**
- OCR 检测屏幕 PII（身份证号、手机号等），在 WebRTC 推流前对帧叠加黑色矩形
- Go API：`/api/v1/privacy/masking`（开关控制）、`/api/v1/privacy/bboxes`（遮罩坐标）
- `frame_redactor.go`：纯 Go 实现 YUV420 矩形黑化，零外部依赖
**Phase 2 — AI 隐私网关**
- mitmproxy 代理（端口 8888），拦截上传至 Claude/GPT 等 AI 平台的附件
- 调用 info-privacy-rs 自动脱敏（PII → `████`），内存处理不落盘
- SQLite append-only 审计日志，记录 PII 类型和文件哈希，不存原文
- CA 证书管理 + KVM API 下载端点
**Phase 3 — AI 路由层**
- mem-bridge 记忆服务（端口 8003）：多维向量记忆 + 事实抽取
- mem-bridge 路由服务（端口 8002）：本地 Qwen2-1.5B / 云端 Claude 自动路由
- KVM API 反向代理：`/api/v1/memory-admin/` 管理端点
### 依赖升级
- 替换 Python 版 info-privacy 为 Rust/RKNN 加速版 info-privacy-rs（端口 8001）
- mem-bridge memory-service 端口 8001 → 8003（避免与 info-privacy-rs 冲突）
### 已知限制
- eth1 网卡未接线，透明代理模式暂不可用，需手动配置系统代理指向 192.168.123.x:8888
- Ollama/Qwen2-1.5B 需手动安装（`scripts/install_ollama.sh`），约占 1GB 存储
- YUV 遮罩基于 OCR 检测坐标，OCR 触发间隔内新出现的 PII 不实时遮罩
deploy/systemd/info-privacy.service
+3 -7
View File
@@ -1,5 +1,5 @@
[Unit]
Description=Info-Privacy PII Detection Service
Description=Info-Privacy-RS PII Detection Service (Rust/RKNN)
After=network.target
Wants=network.target
@@ -7,12 +7,8 @@ Wants=network.target
Type=simple
User=pi
Group=pi
WorkingDirectory=/home/pi/Desktop/info-privacy
ExecStart=/home/pi/Desktop/info-privacy/venv/bin/uvicorn \
info_privacy.api.main:app \
--host 0.0.0.0 \
--port 8000 \
--workers 1
WorkingDirectory=/home/pi/Desktop/info-privacy-rs
ExecStart=/home/pi/Desktop/info-privacy-rs/target/release/info-privacy-rs
Restart=on-failure
RestartSec=5
StandardOutput=journal
deploy/systemd/mem-bridge-memory.service
+3 -3
View File
@@ -7,9 +7,9 @@ Wants=network.target
Type=simple
User=pi
Group=pi
WorkingDirectory=/data/rockchip/embedding
EnvironmentFile=-/data/rockchip/embedding/.env
ExecStart=/data/rockchip/embedding/venv/bin/python server.py --service memory
WorkingDirectory=/home/pi/Desktop/embed-db
EnvironmentFile=-/home/pi/Desktop/embed-db/.env
ExecStart=/home/pi/Desktop/embed-db/venv/bin/python server.py --service memory
Restart=on-failure
RestartSec=5
StandardOutput=journal
deploy/systemd/mem-bridge-router.service
+3 -3
View File
@@ -8,9 +8,9 @@ Requires=mem-bridge-memory.service
Type=simple
User=pi
Group=pi
WorkingDirectory=/data/rockchip/embedding
EnvironmentFile=-/data/rockchip/embedding/.env
ExecStart=/data/rockchip/embedding/venv/bin/python server.py --service router
WorkingDirectory=/home/pi/Desktop/embed-db
EnvironmentFile=-/home/pi/Desktop/embed-db/.env
ExecStart=/home/pi/Desktop/embed-db/venv/bin/python server.py --service router
Restart=on-failure
RestartSec=5
StandardOutput=journal