# run.md — QYLAW 法律法规知识库 运行手册

> 项目:QYLAW 法律法规知识库
> 部署:192.168.110.114 (Docker, --network host)
> 更新:2026-08-06

---

## 一、技术栈

| 项目 | 版本/说明 |
|------|------|
| 后端 | Python 3.11 + FastAPI + Uvicorn |
| 向量库 | FAISS (faiss-cpu, HNSW 索引) |
| metadata | SQLite (Python 内置 sqlite3) |
| 向量化 | Qwen3-Embedding-0.6B (114:8003, 复用) |
| RAG 生成 | Qwen3.5-35B (114:7000, 复用) |
| 前端 | HTML + Vanilla JS + Tailwind CDN |
| 部署 | Docker (--network host) |
| 端口 | 8090 |

---

## 二、首次准备

### 2.1 数据准备

```bash
ssh nvidia@192.168.110.114
# 密码: qy123.

# 确认 law-pack 已传输到 114
ls /data/law-pack-2026-07-01-markdown/
# 预期: 法律/ 行政法规/ 监察法规/ 司法解释/ 地方性法规/ 地方性法规区域映射.json

# 若不存在,从本机 rsync 传输(310MB)
# 在本机执行:
rsync -avz --progress /Users/freedak/Documents/AIDashboard/qy123/law-pack-2026-07-01-markdown/ \
  nvidia@192.168.110.114:/data/law-pack-2026-07-01-markdown/

# 创建索引数据目录
mkdir -p /data/law-kb-data/faiss /data/law-kb-data/logs
```

### 2.2 确认依赖服务

```bash
# embedding 服务(8003)
curl -s http://localhost:8003/v1/models | python3 -m json.tool

# qwen35 服务(7000)
curl -s http://localhost:7000/v1/models | python3 -m json.tool
```

---

## 三、索引构建

### 3.1 全量构建

```bash
# [Docker] 在容器内执行(构建脚本需要访问 embedding 服务)
docker run --rm --network host \
  -v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
  -v /data/law-kb-data:/data/law-kb-data \
  law-kb:latest \
  python scripts/build_index.py --mode full

# [Native] 本地直接执行(需已安装依赖)
cd law-kb
python scripts/build_index.py --mode full
```

**输出示例**:
```
============================================
  QYLAW 索引构建 — 全量模式
  时间: 2026-08-06 14:00:00
============================================
  扫描目录: /data/law-pack-2026-07-01-markdown
  [法律] 349 文件, 切片 12500 条
  [行政法规] 606 文件, 切片 28000 条
  ...
  跳过文件(null 映射): 23 篇
  总切片: 520000 条
  向量维度: 1024
  FAISS 索引大小: 1.2 GB
  耗时: 2.5 小时
  索引文件: /data/law-kb-data/faiss/index.faiss
  SQLite: /data/law-kb-data/metadata.db
============================================
```

### 3.2 增量构建

```bash
# [Docker]
docker run --rm --network host \
  -v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
  -v /data/law-kb-data:/data/law-kb-data \
  law-kb:latest \
  python scripts/build_index.py --mode incremental
```

### 3.3 索引验证

```bash
# [Docker]
docker run --rm --network host \
  -v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
  -v /data/law-kb-data:/data/law-kb-data \
  law-kb:latest \
  python scripts/verify_index.py
```

---

## 四、应用启停

### 4.1 启动服务

```bash
# [Docker] 启动 law-kb 容器
docker run -d --name law-kb --network host \
  --restart unless-stopped \
  -v /data/law-pack-2026-07-01-markdown:/data/law-pack-2026-07-01-markdown:ro \
  -v /data/law-kb-data:/data/law-kb-data \
  law-kb:latest

# 验证
curl -s http://localhost:8090/health
curl -s http://localhost:8090/api/stats | python3 -m json.tool
```

### 4.2 停止服务

```bash
docker stop law-kb
```

### 4.3 重启服务

```bash
docker restart law-kb
```

### 4.4 查看日志

```bash
docker logs law-kb --tail 50
docker logs -f law-kb
```

---

## 五、构建与部署

### 5.1 构建镜像

```bash
# 在 114 上构建
cd /data/project/law-kb  # 或项目实际路径
docker build -t law-kb:latest .
```

### 5.2 一键部署

```bash
# 使用部署脚本(本机执行,自动 rsync + 构建 + 启动)
bash scripts/deploy.sh
```

---

## 六、备份与恢复

### 6.1 备份索引

```bash
# 索引文件可独立备份(FAISS + SQLite)
ssh nvidia@192.168.110.114
tar -czf /data/backup/law-kb-index-$(date +%Y%m%d).tar.gz \
  -C /data/law-kb-data faiss/ metadata.db
```

### 6.2 恢复索引

```bash
ssh nvidia@192.168.110.114
docker stop law-kb
tar -xzf /data/backup/law-kb-index-YYYYMMDD.tar.gz -C /data/law-kb-data/
docker start law-kb
```

---

## 七、排错

| 问题 | 原因 | 解决方案 |
|------|------|------|
| 启动后 stats 返回 ready=false | 索引未构建 | 执行全量构建(三、3.1) |
| 检索返回 503 | embedding 服务未启动 | `docker ps` 确认 embedding 容器运行 |
| RAG 返回 503 | qwen35 服务未启动 | `docker ps` 确认 qwen35 容器运行 |
| RAG 返回 no_result | 相似度低于阈值(0.3) | 检查索引质量或调整问题表述 |
| 构建脚本 OOM | 切片数过多内存不足 | 减小 EMBEDDING_BATCH_SIZE |
| 容器无法访问 8003/7000 | 未用 --network host | 确认启动命令含 `--network host` |

---

## 八、端口表

| 端口 | 服务 | 类型 | 说明 |
|------|------|------|------|
| 8090 | law-kb | HTTP | QYLAW 知识库 Web + API |
| 8003 | embedding | HTTP | 向量化服务(复用) |
| 7000 | qwen35 | HTTP | RAG 生成服务(复用) |

---

## 九、环境变量

| 变量 | 默认值 | 说明 |
|------|------|------|
| `LAW_PACK_DIR` | /data/law-pack-2026-07-01-markdown | 法规原文目录 |
| `LAW_KB_DATA_DIR` | /data/law-kb-data | 索引数据目录 |
| `EMBEDDING_URL` | http://localhost:8003/v1 | embedding 服务地址 |
| `LLM_URL` | http://localhost:7000/v1 | LLM 服务地址 |
| `EMBEDDING_MODEL` | qwen3-embedding-0.6b | embedding 模型名 |
| `LLM_MODEL` | qwen3.5-35b | LLM 模型名 |
| `EMBEDDING_BATCH_SIZE` | 32 | embedding 批量大小 |
| `APP_PORT` | 8090 | 应用端口 |

---

## 十、FAQ

**Q: 为什么用 --network host?**
A: 容器需要访问 114 本地的 8003(embedding)和 7000(qwen35)端口。host 网络模式下容器直接用宿主网络,无需 --add-host 或端口映射,最简配置。内网环境无安全顾虑。

**Q: 索引构建中断了怎么办?**
A: 构建脚本先写临时文件,成功后原子替换。中断不会损坏已有索引。直接重跑即可。

**Q: 地方性法规 null 映射文件如何补?**
A: 编辑 `地方性法规区域映射.json` 补充映射,然后执行增量构建。

**Q: 如何更新法规数据?**
A: 替换 `/data/law-pack-2026-07-01-markdown/` 下的文件,执行增量构建(三、3.2)。