htknow/DEBUG_MEMORY.md

Debug 镜像内存分析指南

构建 Debug 镜像

Debug 镜像包含 jemalloc 内存分析工具:

• libjemalloc-dev - jemalloc 开发库
• perl - jeprof 脚本依赖
• graphviz - 生成可视化图表
• binutils - 符号解析工具

构建命令

# 构建 debug 镜像
./build-docker.sh debug

# 构建 release 镜像 (不包含分析工具)
./build-docker.sh

导出 Heap Dump

方法 1: 直接获取 PDF 报告 (最简单 🚀)

# 一键生成并下载 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 文件

# 导出当前内存快照
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: 进入容器手动导出

# 进入容器
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

手动分析

# 安装 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:

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 缓存

- HTKNOW_TANTIVY_MEMORY_MB=25  # 默认 50

2. 减少数据库连接

- HTKNOW_DB_MAX_CONNECTIONS=5  # 默认 10

3. 调整搜索结果数量

- HTKNOW_SEARCH_LIMIT=5  # 默认 10

容器内分析工具

进入容器后可用的工具:

# 查看进程内存
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 镜像:

./build-docker.sh

参考链接

• jemalloc Documentation
• jeprof Manual
• Rust jemalloc