Chart Image

核心功能

chart-image 是一款专为无头服务器环境设计的图表生成工具，基于Vega-Lite语法规范，可直接输出PNG/SVG格式的高质量统计图表。核心采用纯Node.js实现，依赖Sharp图像处理库（预编译二进制），彻底规避了传统方案中canvas原生编译、Puppeteer浏览器依赖等部署痛点。

显著优势

部署友好性突出：无需GCC等构建工具、无需下载Chrome（节省400MB+空间）、冷启动<500ms，完美适配容器化/VPS场景。支持9种图表类型（line/bar/area/pie/donut/candlestick/heatmap/point）及多系列、堆叠、双Y轴等高级组合，覆盖金融K线、监控告警、业务报表等典型场景。

运维监控优化：内置--show-change、--focus-recent、--dark等告警风格参数，可一键生成适合Slack/Discord推送的紧凑图表。Y轴格式化支持percent/dollar/compact/decimal4等快捷指令，省去手动配置d3-format的繁琐。

局限性与注意事项

功能边界：作为静态图表生成器，不支持交互式tooltip、缩放、动态更新等前端特性；Vega-Lite自定义spec需用户自行掌握JSON语法。数据必须通过JSON字符串或管道传入，暂不支持CSV/数据库直连。

视觉定制有限：主题仅提供light/dark两种预设，细粒度样式调整需通过Vega-Lite spec覆盖，学习成本高于Highcharts等商业库。

适用人群

• 需在Fly.io/VPS/Docker部署数据可视化的后端开发者
• 构建监控告警系统的DevOps工程师（自动生成趋势图推送）
• 需要将图表嵌入PDF报告、邮件、IM消息的自动化工作流

常规风险提示

• 输入数据未做严格校验，超大数组可能导致内存占用激增
• 文件输出路径需确保写入权限，推荐使用/data/clawd/tmp/持久化目录
• 时区依赖的--dark自动切换基于以色列时间(UTC+2/3)，非全球通用

核心用法

chart-image 是一个专为无头服务器环境设计的纯 Node.js 图表生成工具，基于 Vega-Lite + Sharp 实现 PNG/SVG 输出。核心优势在于完全抛弃 Puppeteer/Chrome（节省 400MB+ 依赖），仅通过预编译二进制实现 <500ms 冷启动。

典型工作流：
1. 命令行调用 node chart.mjs --type [chartType] --data '[...]' --output chart.png
2. 支持 JSON 管道输入、CSV 文件读取、自定义 Vega-Lite Spec
3. 10+ 图表类型：line/bar/area/pie/donut/candlestick/heatmap，支持多系列、堆叠、双 Y 轴、成交量叠加
4. 专为监控场景优化：--show-change 自动标注涨跌幅，--focus-recent N 聚焦近期数据，--sparkline 生成迷你图

关键特性：

• 零浏览器依赖：纯 Node.js，无 Puppeteer/Chrome 下载
• 预编译二进制：Sharp 带预构建二进制，无需原生编译工具链
• 轻量部署：~15MB 依赖 vs 400MB+ 浏览器方案
• 离线可用：零外部 API 调用（除 Vega schema 文档引用）

显著优点

1. 部署友好度极高：Fly.io/VPS/Docker 一键部署，解决 canvas 包编译失败、Puppeteer 内存占用等痛点
2. 性能优异：冷启动 <500ms，图表生成 <100ms，适合高频监控告警场景
3. 专业级输出：基于 Vega-Lite 语法，支持主题切换（--dark）、D3 格式器（--y-format dollar/percent/compact）、时间轴（--x-type temporal）、事件标注（--annotations）
4. 监控场景深度优化：内置 focus-change（Y 轴智能缩放）、show-values（极值标注）、hline（参考线）等告警图表专属功能

潜在缺点与局限性

1. 输入验证不足：--csv-file 和 --output 路径由用户完全控制，存在越权访问风险（安全报告 RISK-001/002）
2. 数据格式容错弱：--data JSON 无 Schema 校验，字段缺失或类型错误可能抛出未处理异常
3. 高级定制受限：虽支持 --spec 传入自定义 Vega-Lite，但 CLI 参数覆盖复杂图表配置时能力有限
4. 依赖体积权衡：Sharp 预编译二进制虽省编译时间，但跨平台（ARM/x64）镜像体积仍需优化

适合人群

• 运维/SRE：需要服务器端生成监控告警图、Sparkline 仪表盘
• 量化/金融开发者：OHLC 蜡烛图、成交量叠加、时间序列可视化
• Fly.io/VPS 用户：受困于 Puppeteer/canvas 部署失败的容器化场景
• 离线环境：无网络权限的内网报告生成需求

常规风险

| 风险项 | 说明 | 缓释建议 |

|--------|------|----------|

| 路径遍历 | `--csv-file`/`--output` 可指定任意路径 | 沙箱化文件系统权限，限制读写目录 |

| 依赖供应链 | Sharp/Vega 为知名项目，但需持续审计 | 建立定期 `npm audit` 机制 |

| 数据泄露 | 处理敏感数据时，输出文件权限需管控 | 输出目录设置 0600 权限，避免全局可读 |

| 资源耗尽 | 超大 `--data` 数组可能导致内存/CPU 峰值 | 限制输入数据长度，超时熔断 |

安全评级：A 级（82/100），T2 可信组织来源，无危险函数调用，无网络外泄。