185 lines
4.0 KiB
Markdown
185 lines
4.0 KiB
Markdown
# Debug 镜像内存分析指南
|
|
|
|
## 构建 Debug 镜像
|
|
|
|
Debug 镜像包含 jemalloc 内存分析工具:
|
|
- `libjemalloc-dev` - jemalloc 开发库
|
|
- `perl` - jeprof 脚本依赖
|
|
- `graphviz` - 生成可视化图表
|
|
- `binutils` - 符号解析工具
|
|
|
|
### 构建命令
|
|
|
|
```bash
|
|
# 构建 debug 镜像
|
|
./build-docker.sh debug
|
|
|
|
# 构建 release 镜像 (不包含分析工具)
|
|
./build-docker.sh
|
|
```
|
|
|
|
## 导出 Heap Dump
|
|
|
|
### 方法 1: 直接获取 PDF 报告 (最简单 🚀)
|
|
|
|
```bash
|
|
# 一键生成并下载 PDF 报告
|
|
curl -H "x-user-id: 1" \
|
|
-H "x-user-name: admin" \
|
|
-H "x-role: admin" \
|
|
-o heap_analysis.pdf \
|
|
http://localhost:8080/api/v1/knowledge/system/heap/pdf
|
|
|
|
# 然后直接打开查看
|
|
open heap_analysis.pdf # macOS
|
|
xdg-open heap_analysis.pdf # Linux
|
|
```
|
|
|
|
### 方法 2: 通过 API 导出原始 heap 文件
|
|
|
|
```bash
|
|
# 导出当前内存快照
|
|
curl -H "x-user-id: 1" \
|
|
-H "x-user-name: admin" \
|
|
-H "x-role: admin" \
|
|
-o htknow.heap.$(date +%s).heap \
|
|
http://localhost:8080/api/v1/knowledge/system/heap
|
|
|
|
# 查看堆分析状态
|
|
curl -H "x-user-id: 1" \
|
|
-H "x-user-name: admin" \
|
|
-H "x-role: admin" \
|
|
http://localhost:8080/api/v1/knowledge/system/heap/status | jq
|
|
|
|
# 查看内存占用
|
|
curl -H "x-user-id: 1" \
|
|
-H "x-user-name: admin" \
|
|
-H "x-role: admin" \
|
|
http://localhost:8080/api/v1/knowledge/system/memory | jq
|
|
```
|
|
|
|
### 方法 3: 进入容器手动导出
|
|
|
|
```bash
|
|
# 进入容器
|
|
docker exec -it htknow bash
|
|
|
|
# 安装 jeprof (如果需要在容器内分析)
|
|
apt update && apt install -y google-perftools
|
|
|
|
# 使用 jeprof 生成报告
|
|
jeprof --show_bytes --text /app/htknow /path/to/heap.file
|
|
```
|
|
|
|
## 分析 Heap Dump
|
|
|
|
### 手动分析
|
|
|
|
```bash
|
|
# 安装 gperftools (macOS)
|
|
brew install gperftools
|
|
|
|
# 安装 gperftools (Linux)
|
|
apt-get install google-perftools
|
|
|
|
# 生成 PDF 报告
|
|
jeprof --show_bytes --pdf target/debug/htknow htknow.heap.*.heap > report.pdf
|
|
|
|
# 生成文本报告
|
|
jeprof --show_bytes --text target/debug/htknow htknow.heap.*.heap > report.txt
|
|
|
|
# 查看前 10 个内存分配点
|
|
jeprof --show_bytes --text target/debug/htknow htknow.heap.*.heap | head -20
|
|
```
|
|
|
|
## 采样率配置
|
|
|
|
当前配置在 `src/main.rs:6`:
|
|
|
|
```rust
|
|
pub static MALLOC_CONF: &[u8] = b"prof:true,prof_active:true,lg_prof_sample:10\0";
|
|
```
|
|
|
|
| lg_prof_sample | 采样间隔 | 适用场景 | 性能开销 |
|
|
|----------------|----------|----------|----------|
|
|
| 0 | 每次分配 | 详细分析 | 非常高 |
|
|
| **10** | 1 KB | **推荐** | 中等 |
|
|
| 15 | 32 KB | 轻量监控 | 较低 |
|
|
| 19 | 512 KB | 只看大块 | 很低 |
|
|
|
|
## 内存优化
|
|
|
|
如果发现内存占用过高,可以调整以下配置 (在 `docker-compose.yml`):
|
|
|
|
### 1. 降低 Tantivy 缓存
|
|
|
|
```yaml
|
|
- HTKNOW_TANTIVY_MEMORY_MB=25 # 默认 50
|
|
```
|
|
|
|
### 2. 减少数据库连接
|
|
|
|
```yaml
|
|
- HTKNOW_DB_MAX_CONNECTIONS=5 # 默认 10
|
|
```
|
|
|
|
### 3. 调整搜索结果数量
|
|
|
|
```yaml
|
|
- HTKNOW_SEARCH_LIMIT=5 # 默认 10
|
|
```
|
|
|
|
## 容器内分析工具
|
|
|
|
进入容器后可用的工具:
|
|
|
|
```bash
|
|
# 查看进程内存
|
|
htop
|
|
|
|
# 查看系统内存
|
|
free -h
|
|
|
|
# 查看磁盘占用
|
|
df -h
|
|
|
|
# 查看目录大小
|
|
du -sh /app/data/*
|
|
|
|
# 实时监控容器
|
|
docker stats htknow
|
|
```
|
|
|
|
## 常见问题
|
|
|
|
### Q: 为什么 heap dump 文件很小?
|
|
|
|
A: 采样率太高 (lg_prof_sample:19),降低到 10 可获得更详细的数据。
|
|
|
|
### Q: 容器内存 251MB 但 heap 只有 1.7MB?
|
|
|
|
A: 可能原因:
|
|
1. 采样率过高,未记录小内存分配
|
|
2. 向量数据库 (LanceDB) 占用大量内存
|
|
3. 全文索引 (Tantivy) 缓存
|
|
4. Tokio 运行时和其他系统内存
|
|
|
|
### Q: Debug 镜像可以用于生产吗?
|
|
|
|
A: 不推荐。Debug 镜像:
|
|
- 包含额外的分析工具 (~100MB)
|
|
- 使用 debug 二进制 (更大,更慢)
|
|
- 启用了详细日志 (RUST_LOG=debug)
|
|
- 启用了内存分析 (性能开销)
|
|
|
|
生产环境请使用 release 镜像:
|
|
```bash
|
|
./build-docker.sh
|
|
```
|
|
|
|
## 参考链接
|
|
|
|
- [jemalloc Documentation](http://jemalloc.net/)
|
|
- [jeprof Manual](https://github.com/jemalloc/jemalloc/wiki/Use-Case%3A-Heap-Profiling)
|
|
- [Rust jemalloc](https://github.com/tikv/jemallocator)
|