企业官网建设流程全解析

• 可观测性
• 数据可视化
• 后端

Graphite 1.1.3 是稳定版 1.1.x 分支的一个 bugfix 维护版本，于 2018 年 4 月 4 日发布，官方明确推荐在生产环境使用。本指南将基于 docs/releases/1_1_3.rst 发布说明，结合本仓库源码（webapp/graphite 下的渲染函数、标签系统与渲染视图实现），逐条拆解该版本的新特性、关键 bug 修复、升级注意事项与不兼容变更，帮助你评估是否升级、如何平滑升级，以及如何在升级后正确使用新增能力。

版本概况与发布组件

Graphite 1.1.3 并非单仓发布，而是由以下四个 Python 组件同步组成，均可在 PyPI 上通过 pip 安装：

从源码包 / PyPI 渠道可以获取上述组件的 1.1.3 版本。需要注意：whisper 无需升级，而carbon、graphite-web、carbonate（如在使用）均应升级，因为其中包含有价值的 bugfix 与改进。

升级注意事项（必读）

一个值得警惕的历史陷阱：pip uninstall 误删数据目录

发布说明特别警告：早期版本的 graphite-web 和 carbon 包在特定情况下会在pip uninstall时删除你的 whisper 数据目录。该问题已在 1.1.3 修复，但升级前必须手工清理旧包安装记录中指向/opt/graphite/storage的条目：

• 检查文件（按安装版本与 Python 版本命名）：

  • /opt/graphite/lib/carbon-X.X.X-pyY.Y.egg-info/installed-files.txt
  • /opt/graphite/lib/graphite-web-X.X.X-pyY.Y.egg-info/installed-files.txt

  其中X.X.X是 Graphite 版本号，Y.Y是 Python 版本号。

• 操作方式：删除这两个文件中所有包含/opt/graphite/storage的条目，再执行升级，以避免 pip 卸载旧版本时连带删除数据。

不兼容变更：标记序列的哈希文件命名（TAG_HASH_FILENAMES）

1.1.3 是 1.1.x 稳定分支上的版本，因此它继承了来自 master 分支的一个重要变更，作为碳（carbon）侧的不兼容变更：

carbon 现在支持仅使用指标名称的哈希来命名带标签（tagged）的序列文件，从而避免在标签数量较多时触及文件名长度上限。

• 新方案（哈希命名）现为默认行为。
• 如需回到旧命名方案，可在 carbon 配置中加入：

TAG_HASH_FILENAMES = False

• graphite-web 侧无需配置：graphite-web 会同时识别两种命名变体（哈希命名与人类可读命名），因此部署时可以逐步切换而不丢数据可见性。

源码中的哈希编码实现佐证

本仓库 webapp/graphite/tags/utils.py 中的encode()静态方法展示了该命名方案的完整实现细节：

• 带标签的序列被存放在顶层_tagged目录下的独立目录层级中；
• 子目录由带标签指标路径 sha256 哈希的前 3 个十六进制字符决定（共 4096 个可能目录），第二级子目录使用后续 3 个十六进制字符（再 4096 个可能目录），总共最多4096²个可能子目录；
• 指标文件名中的.被替换为-（whisper 场景）或_DOT_（编码路径中的占位符），避免指标名、标签名或标签值中包含.时意外产生更多子目录层级；
• hash_only=True时，文件名直接使用完整 sha256 哈希，避免文件名长度限制问题，代价是无法从文件名反解出原始指标名。

文档示例：带标签指标some.metric;tag1=value2;tag2=value.2，若其 sha256 哈希以effaae开头，则分别存储在：

_tagged/eff/aae/some-metric;tag1=value2;tag2=value-2.wsp (whisper) _tagged/eff/aae/some-metric;tag1=value2;tag2=value-2 (ceres)

decode()（webapp/graphite/tags/utils.py）则负责将路径还原为原始指标名。同时，源码注释明确指出：每个 carbon 数据库和 graphite-web finder 都自行负责各自的编码处理，因此不同的后端可以设计各自的命名方案——这正是 graphite-web 无需新增配置项即可同时兼容两种命名的原因。

新特性（Graphite-Web）

本版本共带来 4 项 graphite-web 新特性，全部集中在渲染函数（render functions）层。以下结合 webapp/graphite/render/functions.py 源码逐一说明。

1. aggregateLine 新增可选参数 keepStep（#2234）

aggregateLine接受一个指标或通配符序列，根据应用到每个序列上的函数绘制一条水平线。

新增的keepStep布尔参数（默认False）行为如下（源码 webapp/graphite/render/functions.py）：

• keepStep=True：结果序列与源序列具有相同的时间段与 step，即对每个数据点重复聚合值，产生一条与源序列步长一致的阶梯状水平线；
• keepStep=False（默认）：退回原来的constantLine行为，仅生成一个常值序列。

函数注册信息（同文件 #L4700-L4705）确认参数签名为seriesList（必填）+func（聚合函数，默认average）+keepStep（布尔，默认False）。

示例用法：

&target=aggregateLine(server01.connections.total, 'avg') &target=aggregateLine(server*.connections.total, 'avg') &target=aggregateLine(server01.connections.total, 'avg', true)

官方文档提示（源码 docstring）：由于 graphite 渲染器默认按时间平均合并数据点，若对aggregateLine使用min或max聚合，建议配合consolidateBy()使用相同函数，确保保留正确的数据点，使线条与数据本身对齐，避免出现不自然的空隙。

2. 支持以哈希文件名存储带标签序列（#2221）

graphite-web 侧同步支持了碳（carbon）侧的哈希文件名存储能力，即上一节所述hash_only编码。其核心价值是：当标签数量较多时，人类可读的文件名可能触及文件系统命名长度限制，而 sha256 哈希文件名长度恒定，从而规避该问题。graphite-web 会在查找时自动兼容哈希命名与旧命名两种存储布局，无需额外配置。

3. noNullPoints 与 maxDataPoints 可同时指定（#2257）

在此之前，渲染 JSON 输出时noNullPoints与maxDataPoints两个请求选项存在互斥或冲突的问题。本次修复使两者可以同时使用。

从源码 webapp/graphite/render/views.py 可以看到两者的实际处理顺序：

1. 先处理maxDataPoints：将序列按目标点数进行 consolidate（合并），maxDataPoints == 1时直接合并整个序列；否则按valuesPerPoint = ceil(点数 / maxDataPoints)计算每点合并数，并通过 nudge 机制对齐合并区间，消除刷新时出现的“抖动”（jitter）。
2. 再处理noNullPoints：过滤掉所有值为None或NaN的数据点；若过滤后整条序列为空，则跳过该序列（continue），不输出。

此外，请求参数的解析位于同文件 #L394-L397：maxDataPoints以整数形式读入requestOptions，noNullPoints以布尔开关形式置为True。两者现在可以共存于同一次渲染请求中，例如在图表点数受限的同时剔除空点。

4. delay 渲染函数支持负步长（#2262）

delay函数将序列中所有采样点向后平移整数个 step（步数），可用于自定义导数计算等场景。源码实现 webapp/graphite/render/functions.py 的关键逻辑：

if steps < 0: newValues = series[-steps:] + [None] * min(-steps, len(series)) else: newValues = [None] * min(steps, len(series)) + series[:-steps]

• 正步长：将数据后移，在序列开头用None填充（每平移一个 step 填充一个空值）；
• 负步长（本版本新增支持）：将数据前移，在序列结尾用None填充。

该函数与timeShift、timeSlice等其他时间位移函数互补：它不关心被位移的 step 区间本身，只做整数步平移。负步长配合示例场景：

&target=divideSeries(server.FreeSpace,delay(server.FreeSpace,1))

计算的是服务器剩余空间相对上一个采样点的变化百分比；而delay(series, -1)则可用于实现前向位移。

Bug Fixes（Graphite-Web）

本版本共修复 6 项 graphite-web 相关 bug：

1. remote.py 补充 auto_complete 的 local 字段（#2244）：在 webapp/graphite/finders/remote.py 中，auto_complete_tags与auto_complete_values方法用于远程 tag 数据库的标签/取值自动补全；本次修复为这两个方法补上缺失的local字段，使标签自动补全（如 Grafana 中的标签联想输入）在远程 finder 场景下行为正确。

2. 修复 hitcount 桶（bucket）计算（#2252）：hitcount函数用于从“每秒命中数”序列估算更大时间区间（如每小时、每天）的命中总数。源码 webapp/graphite/render/functions.py 展示了其分桶算法：按interval计算桶数bucket_count，将每个采样点按起止时间divmod到所属桶，单桶命中直接累加、跨桶命中按时间比例拆分；本次修复修正了桶边界计算，确保估算值准确。参数还包括可选alignToInterval（默认False），置为True时会基于请求上下文重新拉取数据并对齐到整点/整天边界。

3. glyph.py 中 "unicode" 的 Python 3 兼容修复（#2254）：修复了图表绘制模块 webapp/graphite/render/glyph.py 中对内置unicode的使用，使 webapp 在 Python 3 环境下（配合 tox.ini 中的多版本测试矩阵）正常绘制图形。

4. 为 storage 目录补加 dummy.txt（#2259）：为存储目录补入占位文件，确保目录结构在打包/安装时被完整保留。

5. 文档补充 nginx-uwsgi 的 static 位置说明（#2260）：完善了 nginx + uwsgi 部署场景下静态文件的 location 配置文档，见 docs/admin-webapp.rst。

6. graphite 函数更好地处理空序列上的 max（#2266）：提升了maxSeries（见 webapp/graphite/render/functions.py）等聚合函数对空序列的健壮性——当序列为空或全为None时，max不再抛出异常，而是合理返回空/无效结果。

其它组件修复速览

• Carbon：
  • 存储目录补加 dummy.txt（#753）；
  • （配合 #743）实现带标签序列的哈希文件名存储支持。
• Carbonate：
  • 修复 carbon router hash（#93）；
  • PyPI 包补加 LICENSE 文件（#97）。
• Whisper：本版本无变更。

安全说明

本版本无安全公告（Security Notes: None），即没有已知的安全漏洞修复条目；但这不意味着可以忽略常规安全加固，仍建议遵循 docs/config-local-settings.rst 与 docs/admin-webapp.rst 中的生产部署建议。

升级路径小结

1. 备份/opt/graphite/storage（或你的 whisper 数据目录）；
2. 清理旧安装记录中的 storage 条目（见上文“升级注意事项”）；
3. 依次升级carbon、graphite-web（如使用carbonate也一并升级），whisper无需变动；
4. 若使用旧式带标签序列命名，可在 carbon 配置中显式设置TAG_HASH_FILENAMES = False；graphite-web 无需改动即可兼容两种命名；
5. 验证升级后aggregateLine(..., true)、delay(series, -N)等新参数按预期工作，并可结合noNullPoints与maxDataPoints的组合请求检查渲染输出。

• 可观测性
• 数据可视化
• 后端