[Feature] 内存优化:官方镜像默认 MALLOC_ARENA_MAX=2 + BLAS 单线程,生产实测 RSS -33%(v4.29.4)
I maintainer di solito rispondono entro 1 giorno
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 25/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Attiva
- Ambito
- backend, infrastructure, performance
Direzione di ricerca
The report proposes changes across the official Docker image and Compose template, dependency declarations in pyproject.toml, and lazy loading in astrbot/core/db/vec_db/faiss_impl/embedding_storage.py and astrbot/core/knowledge_base/kb_helper.py. Start by checking those files and validating the reported memory measurements and import paths; define a scoped change with maintainers. Done would require agreed defaults or code changes plus regression and deployment checks, since the report combines several independent proposals.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
功能描述
给 AstrBot 上游的一份内存优化反馈。全部数据来自一个 v4.29.4、20 插件、OneBot v11 (NapCat)、Docker 部署在 4 GiB 小内存主机上 的真实生产实例的采样观测(/proc + cgroup v2 + smaps 三分法),不是理论推演。
核心结论:官方镜像/compose 默认加入 5 个环境变量 + mem_limit,实测 RSS 1008 → 672 MiB(−33%),其余建议按 P0–P2 列于文末汇总表。
(以下为完整反馈正文,可直接跳到 §3 与 §6 看建议)
给 AstrBot 开发者的内存优化建议
来自一次真实生产部署的观测与优化反馈,非理论推演。
目标:帮助上游降低 AstrBot 在 4 GiB 级小内存主机上的常驻工作集。
| 项目 | 值 |
|---|---|
| 反馈日期 | 2026-11-09 |
| 版本 | AstrBot v4.29.4(mirror.ccs.tencentyun.com/soulter/astrbot:v4.29.4),Python 3.12.16,python:3.12-slim |
| 部署 | Docker Compose,单 python main.py 进程;bind mount /root/astrbot/data:/AstrBot/data |
| 主机 | 4 vCPU / 3.57 GiB RAM / 3.00 GiB Swap |
| 负载 | 20 个插件(含 private_companion、reality_companion、schedule_lite 等),OneBot v11 经 NapCat 回连 |
| 采样方法 | /proc/meminfo、cgroup v2 memory.*、/proc/1/smaps_rollup、/proc/1/smaps、/proc/1/maps、docker stats |
| 完整诊断 | 完整诊断报告(五层证据链与可复现命令)可应要求提供 |
0. TL;DR(给维护者的三句话)
- 一个功能齐全的 AstrBot 实例在 20 插件下常驻 1.03–1.08 GiB RSS,其中 98.4% 是活跃私有匿名页,不是缓存。 在 4 GiB 主机上这是主要瓶颈。
- 仅靠 5 个环境变量 + 一个
mem_limit,就让 RSS 从 1008 MiB 降到 672 MiB(−33%),匿名段从 766 MiB 降到 427 MiB(−44%),容器 swap 归零。 建议上游把这几个默认值写进官方镜像 / compose 模板。 - 最值得上游改的,不是删依赖,而是分配器默认值、
plugin_set/trace_enable的默认值语义、以及大 JSON 常驻数据的生命周期。 详见 §3。
1. 观测事实(优化前基线)
1.1 进程与分段
docker stats: astrbot 1.084 GiB / 3.569 GiB 30.37% PIDs=23
/proc/1/status: VmSize 3.34 GiB | VmRSS 1008 MiB | VmHWM 1.17 GiB | Threads 23
RssAnon 993 MiB | RssFile 12.8 MiB | RssShmem 0
smaps_rollup: Rss 1,032,264 kB | Pss 1,031,837 kB
Private_Dirty 1,007,924 kB | Private_Clean 23,640 kB
Referenced 1,018,140 kB (98.6% of Rss)
Anonymous 1,017,444 kB | AnonHugePages 0 | KSM 0 | LazyFree 0
Pss ≈ Rss、Private_Dirty ≈ Rss、Referenced ≈ Rss 三者同时成立,意味着这块内存既不能共享、不能静默回收,又几乎全部在被频繁访问。因此 drop_caches / 调 swappiness / 清文件缓存对 AstrBot 无效,内核换出后会立刻 refault 换回(实测容器内 pswpin 37305 / pswpout 44988)。
PIDs=23 是线程数,容器内只有 1 个业务进程(python main.py),不存在多 worker 复制。
1.2 smaps 严格三分法归因
| 类型 | RSS | 占比 | 性质 |
|---|---|---|---|
[anon] rw-p |
788.9 MiB | 78.3% | 178 个 64 MiB 对齐匿名段 |
[heap] rw-p |
201.5 MiB | 20.0% | CPython brk 堆 |
| 文件映射 | 15.7 MiB | 1.6% | .so / DB / 字体 |
| 合计 | 1006.1 MiB | 100% |
⚠️ 归因过程中踩过两个坑,已在完整诊断报告 §5.4 记录并作废(可应要求提供):
- "按映射名聚合"会把匿名段错误摊派到邻接的
.so(曾得出pandas 113 MB、NotoSansCJK 220 MB等假数字);- "匿名/文件二分"会把
[heap](含[...])误判为文件映射(曾得出file 219 MiB,虚高 14 倍)。结论:请勿用文件名聚合来判断 AstrBot 的内存归属,必须用三分法并以
RssAnon/RssFile交叉校验。
1.3 一个容易被误判的点:原生库其实不占多少
/proc/1/maps 里有 215 个 pandas、111 个 pillow.libs、59 个 numpy、25 个 faiss_cpu.libs 映射,看起来很吓人。但按严格 RSS 聚合:
| 库 | 实际 RSS |
|---|---|
[anon] + [heap] |
683.3 MiB |
| other-file | 40.1 MiB |
| NotoSansCJK 字体 | 7.3 MiB |
| faiss | 6.8 MiB |
| numpy | 5.9 MiB |
| pandas | 5.8 MiB |
| pillow | 3.1 MiB |
即 faiss/numpy/pandas 的 .so 代码段合计只有约 19 MiB。 它们是给分配器和原生缓冲区"提供能力",不是内存主体。给上游的核心含义是:优化目标是匿名页的分配与归还行为,不是删掉这些包(删包收益最多几十 MiB,却会破坏知识库/文档解析功能)。
2. 已验证有效的优化(建议纳入官方默认值)
在 docker-compose.yml 中仅加入:
environment:
- MALLOC_ARENA_MAX=2
- OMP_NUM_THREADS=1
- OPENBLAS_NUM_THREADS=1
- MKL_NUM_THREADS=1
- NUMEXPR_NUM_THREADS=1
mem_limit: 1500m
memswap_limit: 2g
然后用 docker compose up -d --no-deps --force-recreate astrbot 重建(注意:docker restart 不会重新注入环境变量)。
2.1 实测效果
| 指标 | 优化前 | 优化后 | 变化 |
|---|---|---|---|
VmRSS |
1008 MiB | 672 MiB | −336 MiB (−33%) |
[anon] |
788.9 MiB | 427.1 MiB | −362 MiB (−46%) |
[heap] |
201.5 MiB | 180.7 MiB | −21 MiB |
| 64 MiB 对齐匿名段 | 178 | 125 | −53 |
Threads |
23 | 15 | −8 |
memory.swap.current |
157 MiB | 0 | 归零 |
docker stats |
1.027 GiB | 742 MiB | −285 MiB |
整机 MemAvailable |
785 MiB | 1098 MiB(叠加 zcode 释放后 1510 MiB) | 显著改善 |
oom_kill / oom |
— | 0 / 0 | 未触发 |
memory.max=max → 1.465 GiB 后,memory.events 全 0,说明 1.5 GiB 上限对 20 插件的负载是宽松的,不会误伤。
2.2 原理与建议
A. MALLOC_ARENA_MAX=2(收益最大)
glibc 为每个线程创建独立 malloc arena(x86_64 上 HEAP_MAX_SIZE = 64 MiB),且 free() 后的脏页常不通过 munmap 归还 OS。AstrBot 是 asyncio + 多插件 + 原生库(OpenBLAS/faiss)混用的多线程程序,默认 arena 数 ≈ 8 × CPU 核数,实测形成 178 个 64 MiB 对齐匿名段、约 789 MiB 常驻。限制为 2 后匿名段降到 427 MiB。
建议上游:在官方 Dockerfile 里
ENV MALLOC_ARENA_MAX=2,或在main.py启动早期(必须在任何线程创建之前)设置。对纯 asyncio 单线程场景,2 个 arena 足够;若上游有 CPU 密集并行需求,可用 4 并做压测对比。
B. BLAS/OMP 线程池限制
faiss-cpu、numpy、pandas 拉入的 OpenBLAS 默认按核数起线程池,每线程一份栈与工作缓冲。设 OMP/OPENBLAS/MKL/NUMEXPR=1 后线程数从 23 降到 15。代价是大矩阵运算变慢,对"聊天机器人偶尔做一次向量检索"的场景几乎无感。
建议上游:官方镜像设
ENV OPENBLAS_NUM_THREADS=1(保守值),并在文档里说明需要高吞吐向量检索时如何调大。
C. mem_limit / memswap_limit
优化前 memory.max = max,memory.peak = 1.351 GiB,oom_kill = 0。在 3.57 GiB 整机且同时跑多个服务时,单容器无上限是结构性风险。
建议上游:官方
docker-compose.yml模板给出带注释的mem_limit示例(例如1500m/memswap_limit: 2g),并说明"这只是兜底,不是性能调优"。
D. 备选(未实测,建议上游评估)
LD_PRELOAD挂 jemalloc / mimalloc:直接针对 178 个 glibc arena 的碎片,可能比MALLOC_ARENA_MAX更彻底;- 在长任务结束后调用
ctypes.CDLL("libc.so.6").malloc_trim(0),或调MALLOC_TRIM_THRESHOLD_:对"图片生成后一次性释放大缓冲"这类尖峰有效; - 这两项我们未在生产上验证,建议上游加进 benchmark 矩阵。
3. 建议上游修改的代码/默认值(按优先级)
P0 — pyproject.toml 的 pandas 硬依赖可移除或改为 optional
事实:
$ grep -rln "import pandas|from pandas" /AstrBot --include=*.py # 含插件、含核心
(无任何结果)
$ pip show pandas
Required-by: AstrBot
$ grep -n pandas /AstrBot/pyproject.toml
36: "pandas>=2.2.0",
即 AstrBot 直接声明了 pandas>=2.2.0,但整个代码库(含 20 个插件)从未 import 它。它只作为 markitdown 的可选 extra(读取 .xls/.xlsx)的潜在传递依赖存在。
建议:把
pandas从主依赖移到[project.optional-dependencies]的xls/allextra,或由markitdown[xls]按需引入。好处:镜像体积、冷启动 import 时间、以及动态加载器需要处理的.so数量都会下降(实测常驻 RSS 收益约 6 MiB,不大,但属于零风险清理)。请上游确认是否有我们没覆盖到的动态导入路径(例如
importlib.import_module("pandas"))——如有,建议改为函数内懒加载。
P0 — 重量级原生库建议全面确认"真正懒加载"
已做得很好的部分(值得肯定):
- embedding_storage.py 用
if TYPE_CHECKING: import faiss,实际import faiss全部放在_read_index/_write_index等函数内部; - dashboard/utils.py 的
generate_tsne_visualization()把faiss / matplotlib / sklearn放在函数内导入; - kb_helper.py 的
FaissVecDB在_ensure_vec_db()里才 import。
但实测 /proc/1/maps 里 faiss 的 .so 已被映射(22 个 rw-p、15 个 r--p、8 个 r-xp),numpy 也是启动即 import numpy as np(embedding_storage.py 第 8 行模块级)。而本次实例的 default_kb_collection = ""、没有启用 embedding provider、知识库目录只有 180 KiB —— 知识库功能实际上没被使用,但相关原生库已常驻。
建议:
- 把
embedding_storage.py顶部的import numpy as np也移进函数(与 faiss 一致),或至少移到FaissVecDB初始化路径之后;- 让
KBHelper在default_kb_collection为空且无 embedding provider 时完全不初始化 vec_db 相关对象;- 提供
features.knowledge_base: false之类的启动开关,供不需要知识库的用户彻底跳过整条 import 链。收益主要是冷启动基线与
.so映射数量(几十 MiB 量级),不是 683 MiB 匿名页的主体,但属于低风险、易回归测试的结构改进。
P1 — trace_enable 默认值与 WAL 副作用
事实:
- 上游默认
trace_enable: False(default.py:312),本实例被显式改成true; trace_db_max_mb=80、trace_retention_days=7;实际traces.db长到 71.5 MiB,traces.db-shm被映射两次共 16 MiB RSS;- trace_store.py:347 启用
PRAGMA journal_mode=WAL+journal_size_limit=4 MiB。
建议:
- 在 WebUI 开启 trace 时提示"会增加常驻内存与磁盘 IO",并保持默认关闭(当前默认已是 False,这点上游做得对);
- 考虑给
trace_db_max_mb默认值降到 20–40 MiB,或改为按行数/时间双阈值清理,避免 80 MiB 上限长期顶格;- 评估
PRAGMA mmap_size/cache_size上限,避免-shm映射随并发线性增长。
P1 — plugin_set: ["*"] 与插件依赖的安装时机
实测重建容器后,AstrBot 的 star_manager.py 会自动按 requirements.txt 补装缺失依赖(本次自动装回 bilibili-api-python、curl_cffi、pillowmd、pypinyin 等,约 3 分钟),机制本身很好用。但两个体验问题:
failed to import→ 尝试恢复 → 重装 → 重新加载 的过程中,插件实际是延迟 1–2 分钟才可用,且日志里会出现ERROR-like 的failed to import字样,运维容易误判为故障;plugin_set默认["*"](default.py:322),20 个插件全部import并常驻。每个插件的模块级对象、定时器、大 JSON 数据都会叠加到 CPython 堆上。
建议:
- 把"依赖缺失→自动安装→加载成功"的日志级别统一为
INFO并在结束时补一条plugin X ready after dependency install,避免误报;- 提供
astrbot plugin doctor之类的启动前依赖预检命令,让容器构建阶段就能装齐依赖,而不是每次重建都在运行时 pip;- 文档里明确"插件数与时延/内存近似线性相关",并给出按需裁剪
plugin_set的指引。
P2 — 大 JSON 常驻数据(涉及第三方插件,但上游可提供基础设施)
本次 companions.json 为 23 MiB,且插件运行时会周期性改写(还有 8.6 MiB 的 .tmp 原子写残留)。一个 23 MiB 的 JSON 反序列化成 Python 对象通常膨胀 3–5 倍,且会长期停留在 [heap] 里。同目录还有 133 MiB 入站图片、97 MiB 生成封面等。
这属于第三方插件实现,不是 AstrBot 核心缺陷,但上游可以帮忙:
- 在插件 SDK 里提供标准的 SQLite / KV 存储封装(
astrbot.api.storage之类),并在插件开发文档中明确"避免把 > 1 MiB 的 JSON 全量常驻内存";- 提供
plugin_data的按需加载 + LRU 缓存范式;- 对
data/temp的清理策略给一个官方默认值(当前temp_dir_max_size=1024MiB,实测积压 255 MiB / 811 个文件;我们靠外部 cron 每天清理)。
P2 — 官方镜像可直接带上分配器环境变量
综上 A/B 两条是零代码改动、实测 −33% RSS 的收益。强烈建议上游在官方 Dockerfile 与 docker-compose.yml 模板里默认加入:
ENV MALLOC_ARENA_MAX=2 \
OPENBLAS_NUM_THREADS=1 \
OMP_NUM_THREADS=1 \
MKL_NUM_THREADS=1 \
NUMEXPR_NUM_THREADS=1
并在 release note 里注明"如有大批量向量检索/矩阵计算需求,可显式调大"。这比让每个用户自己踩一遍 178 个 arena 的坑要好得多。
P2 — 建议提供官方内存基线指标
用户很难判断"AstrBot 吃了 1 GiB 是正常还是泄漏"。建议上游提供:
- 启动后暴露
memory.current/VmRSS/tracemalloc快照的/api/metrics(或 Prometheus exporter); - 文档中给出按插件数量分档的基线表(如:核心 ~150 MiB、10 插件 ~400 MiB、20 插件 ~800 MiB);
- 内置一个
astrbot doctor --memory输出smaps_rollup关键项 + 各插件的tracemalloc贡献排序。
这能大幅减少"是不是内存泄漏"类 issue,也方便用户自查第三方插件的内存问题。
4. 建议不要做的事(避免上游走弯路)
| 想法 | 为什么不建议 |
|---|---|
| 删掉 faiss / numpy / pandas 来省内存 | 三者 .so 常驻 RSS 合计仅约 19 MiB;683 MiB 是匿名页。删包破坏功能,收益极小 |
用 gc.collect() 定时强制回收 |
主体是原生匿名页与 malloc arena,CPython GC 管不到;实测 Referenced≈Rss,对象都是活的 |
| 用 Rust / Go 重写核心 | 对"匿名分配器碎片"有效,但 20 个 Python 插件生态无法迁移;且 MALLOC_ARENA_MAX=2 已能零成本逼近大部分收益。若要做,建议只把向量检索/图片处理做成 Rust sidecar(PyO3),保留 Python 主程序与插件生态 |
靠 drop_caches / 调 swappiness |
Private_Clean 仅 23 MiB,可回收页几乎不存在 |
把 Committed_AS = 13.5 GiB 当泄漏 |
虚拟地址预留(mmap),与 RSS 不同维度 |
5. 复现信息与验证结果
5.1 关键命令
docker stats --no-stream
docker exec astrbot sh -c 'grep -E "^(VmRSS|RssAnon|RssFile|Threads)" /proc/1/status'
docker exec astrbot sh -c 'cat /proc/1/smaps_rollup'
docker exec astrbot sh -c '
awk "/^[0-9a-f]+-[0-9a-f]+ /{
if (\$0 ~ /\[heap\]/) k=\"heap\"
else if (\$0 ~ /\[stack\]|\[vvar\]|\[vdso\]/) k=\"special\"
else if (\$0 ~ /\/|^\[/) k=\"file\"
else k=\"anon\"
}
/^Rss:/{a[k]+=\$2}
END{for(k in a) printf \"%-10s %8.1f MiB\n\", k, a[k]/1024}" /proc/1/smaps | sort -k2 -rn'
5.2 优化后业务验证(确认没有功能回归)
- 20 个插件全部加载成功(
bilibili、outputpro的依赖由star_manager自动补装); - WebUI
GET / → 200; - NapCat →
ws://astrbot:6199/ws回连 ESTABLISHED,持续处理真实群消息; - 容器
restarts=0、OOMKilled=false、memory.events全 0、memory.swap.current=0; - 运行 30 分钟后
MemAvailable稳定在 ~1.5 GiB,memory.pressure/io.pressure全 0。
5.3 观察到的非致命项(供参考,非本次优化引入)
astrbot_plugin_webui_speedup(第三方插件)的 gzip 中间件在部分请求触发
h11._util.LocalProtocolError: Too little data for declared Content-Length(改Content-Length未同步),
共 18 次、集中在启动阶段,之后不再复现,不影响进程存活;- 启动时
config.astrbot_config会打印大量Config key removed(清理插件遗留的旧配置键),
实测cmd_config.json未被改写; private_companion插件自行把 289 项扁平配置迁移为分组配置,属插件行为。
6. 优先级汇总
| 优先级 | 建议 | 预期收益 | 改动成本 |
|---|---|---|---|
| P0 | 官方镜像/compose 默认 MALLOC_ARENA_MAX=2 + BLAS 线程=1 |
−33% RSS(实测) | 极低(几行 ENV) |
| P0 | pandas 从主依赖改 optional;numpy 模块级导入改懒加载 |
小但零风险,降冷启动基线 | 低 |
| P1 | mem_limit 写入官方 compose 模板 |
防失控,不省内存 | 极低 |
| P1 | trace 默认/上限/WAL 参数优化;依赖自动安装日志改为 INFO | 20–50 MiB + 可运维性 | 低 |
| P1 | 知识库未启用时跳过整条 vec_db import 链 | 数十 MiB + 启动更快 | 中 |
| P2 | 插件 SDK 提供 SQLite/KV 封装,引导避免大 JSON 常驻 | 潜在 100 MiB+(取决于插件) | 中 |
| P2 | 官方内存基线指标 / astrbot doctor --memory |
降低支持成本 | 中 |
| 备选 | jemalloc/mimalloc、malloc_trim、Rust sidecar |
待 benchmark | 中–高 |
反馈基于 v4.29.4 单实例生产观测,样本为 20 插件 / OneBot v11 / 4 GiB 主机。若上游需要,我可以提供完整的 smaps 原始快照、优化前后 docker stats 时序,以及一份可复现的 benchmark 脚本。
使用场景
- 部署:4 vCPU / 3.57 GiB RAM / 3.00 GiB Swap 的国内 VPS,Docker Compose 单容器(bind mount 持久化)
- 负载:20 个插件(含私聊陪伴、课表、Bilibili 解析等),OneBot v11 经 NapCat 反向 WS 回连,7×24 常驻
- 版本:
mirror.ccs.tencentyun.com/soulter/astrbot:v4.29.4(python:3.12-slim,Python 3.12.16) - 动机:优化前整机
MemAvailable仅 ~785 MiB,容器 swap 157 MiB,是这台小内存主机上的主要内存压力源
检查清单
- Lingua principale
- Python
- Stelle
- 46.9k
- Fork
- 3.6k
- Merge medio
- 1g 6h
- PR unite (30g)
- 136
Preparare l'ambiente
- Include un Dockerfile o un file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di AstrBotDevs/AstrBot
-
[Bug] Sending a Telegram message chain twice duplicates mentionsForse già presa @123XieC l’ha presa 5 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
AstrBotDevs/AstrBot#11125 ·
I maintainer di solito rispondono entro 1 giorno
-
[Bug] Telegram album debounce exceeds the maximum waitForse già presa @123XieC l’ha presa 5 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
AstrBotDevs/AstrBot#11123 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 74/100
AstrBotDevs/AstrBot#11034 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
[Bug] OpenAI-compatible Gemini 工具 schema const 导致 400Forse già presa @arccat-114 l’ha presa 26 giorni fa. Apertabug
Difficoltà 2/5 1-3 ore Idoneità per principianti 77/100
AstrBotDevs/AstrBot#10720 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
[Bug] Discord slash command sync aborts with KeyError when a plugin handler is defined in a submoduleForse già presa @yuexia5 l’ha presa 31 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 77/100
AstrBotDevs/AstrBot#10626 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di AstrBotDevs/AstrBot
Issue simili
-
ready-for-agent
Difficoltà 1/5 1-3 ore Idoneità per principianti 79/100
gregwebs/agent-vm-images#216 ·
I maintainer di solito rispondono entro 1 giorno
-
Layout accepts a step threshold of 0 or less, then in-toto-verify crashes with StopIterationForse già presa @BahaaMattar l’ha presa oggi. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
gcivil-nyu-org/team5-mon-fall26#145 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
gcivil-nyu-org/team3-mon-fall26#156 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
antlr/grammars-v4#5220 ·
I maintainer di solito rispondono entro 1 giorno