运行资源与文档处理保护

以下设置随包含这些改动的正式稳定版本交付。代码合并、镜像发布和客户更新分别验收，不能把代码合并视为客户环境已经生效。

文档读取

Agent 读取文档时会核对文件地址、响应类型和文件内容。图片、视频和音频应使用对应的素材能力；将图片指定为 Markdown 也不能作为文本文档读取。正常的 UTF-8 TXT、Markdown、DOCX 和 PDF 继续使用原有入口。

下载按实际收到的字节限制，缺少长度信息或压缩传输也会检查；DOCX 解压时检查正文容量。过大内容会明确提示拆分，不将截断内容显示为完整解析成功。

默认保护范围：原始下载最多 100 MiB，解析结果最多 4 MiB，Agent 单次文档工具返回最多 256 KiB，DOCX 正文 XML 展开最多 16 MiB。文本文件还受解析结果预算限制。文档处理同时最多执行两份，等待队列最多十六份；繁忙时稍后重试。模型生成、供应商查询及其他普通接口不使用该文档队列。

内存配置

在安装目录的 .env 中配套配置：

SERVER_MEMORY_LIMIT=3g
NODE_MAX_OLD_SPACE_SIZE=1536
MONGO_MEMORY_LIMIT=2500m
MONGO_WIREDTIGER_CACHE_GB=1.5

容器内存上限包括 JavaScript 堆、Buffer、原生库及其他开销；数据库缓存也不是 MongoDB 的总内存。默认要求堆或缓存与对应容器上限之间至少留出 512 MiB，且不少于容器上限的 25%。安装及更新会在重建服务前检查；请根据提示调整配置，避免使用相互矛盾的数值。

旧环境如果显式设置了 NODE_MAX_OLD_SPACE_SIZE=8192，更新不会擅自覆盖。需要先结合实际主机容量下调堆预算，或同步增加容器上限和主机容量；不一致的配置会被预检拒绝。修改前备份原配置，通过标准更新入口重建对应服务后，再检查实际运行参数和接口。

还应为宿主机以及前端、Redis、消息队列、沙箱等常驻服务保留内存。上限合计不等于实际使用量，但超过整机可分配预算时必须核对并发峰值。保持完整服务组合时，可将 16 GiB 作为容量验证起点；8 GiB 环境需要通过实测减少或拆分常驻服务。增加内存不能替代文档处理缺陷修复。

校验余量与诊断策略也可以在同一份 .env 中配置，保持下列默认值即可沿用当前策略：

# 容器额外余量、宿主机预留：分别取 MiB 与百分比中的较大值
DEPLOY_MEMORY_MIN_HEADROOM_MIB=512
DEPLOY_MEMORY_HEADROOM_PERCENT=25
DEPLOY_HOST_MEMORY_RESERVE_MIB=1024
DEPLOY_HOST_MEMORY_RESERVE_PERCENT=10

# 采集器与 atop 采样间隔（秒）
HOST_DIAGNOSTICS_INTERVAL_SECONDS=30
# 可用内存低于 MiB 与总内存百分比中的较大值时记录异常
HOST_DIAGNOSTICS_MEMORY_AVAILABLE_MIN_MIB=512
HOST_DIAGNOSTICS_MEMORY_AVAILABLE_PERCENT=10
# 内存、磁盘 I/O 的全局等待比例阈值（百分比）
HOST_DIAGNOSTICS_MEMORY_PSI_FULL_PERCENT=10
HOST_DIAGNOSTICS_IO_PSI_FULL_PERCENT=10
# 普通异常诊断包的最短间隔（秒）
HOST_DIAGNOSTICS_CAPTURE_COOLDOWN_SECONDS=180

所有值为整数：预算百分比为 1–99，诊断百分比为 1–100；采样间隔为 1–86400 秒，抓取冷却为 0–86400 秒；预算 MiB 为正数，低内存阈值 MiB 可设为 0。进程环境中的同名设置优先；空值或缺失值使用默认值，非法值会提示具体配置项。

标准更新会补充缺失配置并保留已有自定义值。诊断配置需要经标准更新，或在部署目录重新执行 sudo bash scripts/install-host-diagnostics.sh "$PWD" 后生效；安装器会生成配置并重启采集服务。仅编辑 .env 不会立即改变正在运行的采集器，单独更新诊断无需重建业务容器。

网络与故障诊断

新部署的自动地址池与固定地址分开。旧网络不会在普通更新中自动删除或重建；更新预检发现固定地址被其他容器占用时会拒绝继续。附加容器必须纳入网络规划，不能抢占 MongoDB 等服务的固定地址。旧网络迁移需要独立维护窗口，保留共享网络上的其他服务和数据。

Linux 诊断采集默认在可用内存低于 512 MiB 或物理总内存的 10%，以及内存或 I/O 全局等待比例达到 10% 时记录资源异常及恢复事件，并按配置的冷却时间限制保存诊断包。事件可从 journalctl -u easyai-host-diagnostics 查看。持续监控和通知渠道需要由运维配置；本功能不会自动重启业务、修改云端报警或发送通知。

更新后同时验证完整首页、健康接口、管理员登录、正常文档读取和错误文件拒绝。付费生成、长时间并发及特定业务链路需按实际场景单独验收。