[Feature] 内存优化:官方镜像默认 MALLOC_ARENA_MAX=2 + BLAS 单线程,生产实测 RSS -33%(v4.29.4)

Aperta
#11,069 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

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
Stack tecnologico
docker, numpy, pandas, python

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(给维护者的三句话)

  1. 一个功能齐全的 AstrBot 实例在 20 插件下常驻 1.03–1.08 GiB RSS,其中 98.4% 是活跃私有匿名页,不是缓存。 在 4 GiB 主机上这是主要瓶颈。
  2. 仅靠 5 个环境变量 + 一个 mem_limit,就让 RSS 从 1008 MiB 降到 672 MiB(−33%),匿名段从 766 MiB 降到 427 MiB(−44%),容器 swap 归零。 建议上游把这几个默认值写进官方镜像 / compose 模板。
  3. 最值得上游改的,不是删依赖,而是分配器默认值、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/all extra,或由 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 —— 知识库功能实际上没被使用,但相关原生库已常驻。

建议:

  1. 把 embedding_storage.py 顶部的 import numpy as np 也移进函数(与 faiss 一致),或至少移到 FaissVecDB 初始化路径之后;
  2. 让 KBHelper 在 default_kb_collection 为空且无 embedding provider 时完全不初始化 vec_db 相关对象;
  3. 提供 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。

建议:

  1. 在 WebUI 开启 trace 时提示"会增加常驻内存与磁盘 IO",并保持默认关闭(当前默认已是 False,这点上游做得对);
  2. 考虑给 trace_db_max_mb 默认值降到 20–40 MiB,或改为按行数/时间双阈值清理,避免 80 MiB 上限长期顶格;
  3. 评估 PRAGMA mmap_size / cache_size 上限,避免 -shm 映射随并发线性增长。
P1 — plugin_set: ["*"] 与插件依赖的安装时机

实测重建容器后,AstrBot 的 star_manager.py 会自动按 requirements.txt 补装缺失依赖(本次自动装回 bilibili-api-python、curl_cffi、pillowmd、pypinyin 等,约 3 分钟),机制本身很好用。但两个体验问题:

  1. failed to import → 尝试恢复 → 重装 → 重新加载 的过程中,插件实际是延迟 1–2 分钟才可用,且日志里会出现 ERROR-like 的 failed to import 字样,运维容易误判为故障;
  2. plugin_set 默认 ["*"](default.py:322),20 个插件全部 import 并常驻。每个插件的模块级对象、定时器、大 JSON 数据都会叠加到 CPython 堆上。

建议:

  1. 把"依赖缺失→自动安装→加载成功"的日志级别统一为 INFO 并在结束时补一条 plugin X ready after dependency install,避免误报;
  2. 提供 astrbot plugin doctor 之类的启动前依赖预检命令,让容器构建阶段就能装齐依赖,而不是每次重建都在运行时 pip;
  3. 文档里明确"插件数与时延/内存近似线性相关",并给出按需裁剪 plugin_set 的指引。
P2 — 大 JSON 常驻数据(涉及第三方插件,但上游可提供基础设施)

本次 companions.json 为 23 MiB,且插件运行时会周期性改写(还有 8.6 MiB 的 .tmp 原子写残留)。一个 23 MiB 的 JSON 反序列化成 Python 对象通常膨胀 3–5 倍,且会长期停留在 [heap] 里。同目录还有 133 MiB 入站图片、97 MiB 生成封面等。

这属于第三方插件实现,不是 AstrBot 核心缺陷,但上游可以帮忙:

  1. 在插件 SDK 里提供标准的 SQLite / KV 存储封装(astrbot.api.storage 之类),并在插件开发文档中明确"避免把 > 1 MiB 的 JSON 全量常驻内存";
  2. 提供 plugin_data 的按需加载 + LRU 缓存范式;
  3. 对 data/temp 的清理策略给一个官方默认值(当前 temp_dir_max_size=1024 MiB,实测积压 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,是这台小内存主机上的主要内存压力源
检查清单
  • 我已在 Issue 列表中搜索过相关功能,确认该功能想法从未被提出过。
  • 我建议的功能与 AstrBot 本体相关,而非在建议某一插件的功能。
  • 我已阅读并同意本项目的贡献者行为准则。
  • (可选)我愿意提交 PR 以帮助实现该功能。
Lingua principale
Python
Stelle
46.9k
Fork
3.6k
Merge medio
1g 6h
PR unite (30g)
136

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di AstrBotDevs/AstrBot

Tutte le issue di AstrBotDevs/AstrBot

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.