版本通道、变更日志与升级策略

Feature 成熟度

阶段	生产预期	兼容性	Self-host/BYOC
Alpha	设计伙伴验证，不作生产承诺	可频繁 breaking，可能不 GA	不保证
Beta	端到端可用，可用于受控真实流程	行为/接口仍可能变	通常在 Beta 期间补齐
GA	生产就绪、完整支持	breaking 必须经过 deprecation	全环境支持

文档未标 Alpha/Beta 的功能视为 GA，但仍应核对特定 plan、region 和 chart 最低版本。Beta 用在生产时要有 feature flag、回退和数据兼容策略。

Agent Server release stream

langgraph-api 有三条流：

latest：每天发布，含最新修复和试验功能，使用 .devN；
rc：约每三周发布，供下一 stable 烘焙；
stable：约每三周从 RC 晋级，只在关键修复/安全依赖时 patch，是生产推荐。

新 Revision 默认使用最新 stable，并在每次新 Revision 时更新。若业务需要可重复回滚，在 langgraph.json 固定 api_version，但要建立安全 patch 更新节奏。

2026-08-11 文档显示最新 stable 0.11.0。重点变化包括 DeltaChannel-aware prune、Prometheus scrape、FIPS Wolfi images、Protocol v2/JS streaming、HITL resume、Redis Cluster TLS 和队列兼容修复。涉及 Checkpoint delete/DeltaChannel 的升级必须用历史 Thread 回放测试。

agent-server-changelog-link 与 agent-server-changelog 当前正文完全相同，是有效别名；来源闭环保留两个 URL，但知识上不重复计算两套版本。

Self-hosted release policy

Self-hosted 有 Stable 与 Preview：

Stable major 大约每 6 周一次；每周通常周五发 patch，仅含关键 bug/security，不在 major 间加 migration/服务/breaking。
Preview 跟随 SaaS，包含下一 major 的功能与 migration，用于测试/staging，禁止生产。
仅支持当前 stable major N 与上一 major N-1；N-1 只收 critical backport，更老版本 EOL。

Chart version 与 App version 独立，例如 chart 0.15.17 可对应 app 0.15.24；升级、支持工单和漏洞盘点必须同时记录两者。v15 指 chart major 0.15.Y，不是语义版本 15。

v0.16 基线

Self-hosted changelog 2026-08-05 将 langsmith-0.16.0 标为推荐版本，主要加入 SmithDB beta、Self-hosted Engine、LLM Gateway beta、AWS/GCP Sandboxes，并合并多项 backend images、加入 Cosign/SBOM。

升级前重点关注：

Bulk Export 未显式 compression 时默认改为 zstandard；
agent-bootstrap 删除，旧 Fleet/Agent Builder 部署需迁 standalone；
新 backfillCheck 会阻止未完成检查的升级；
多镜像合并为 smith-backend，私有 Registry/FIPS mirror 清单变化；
SmithDB 新 /v2/* 查询路径与旧 SDK 迁移；
Engine/LLM Gateway/Sandbox 引入新出站、Secret、权限和费用边界。

升级 Runbook

订阅 Agent Server 与 Self-hosted changelog RSS，建立版本库存。
对照当前 chart/app/API/SDK/CLI 与目标版本，列 breaking、migration、image、Secret、CRD 变化。
在生产数据量相近的 staging 恢复备份并升级；运行旧 Thread replay、stream/HITL、Auth、Export 与 Dataset 查询。
一次只跨一个 Self-hosted major；每步完成 migration/backfill 和 smoke test 后再继续。
发布窗口前做协调数据库备份并验证恢复；注意官方不支持 Helm/数据库降级。
生产升级后监控 migration、ingest lag、queue、DB connections、ClickHouse/SmithDB 查询、5xx 与费用。
回退策略以“恢复协调备份 + 旧 chart”设计，而不是 helm rollback 单独回滚应用。

版本信息的时效性

Changelog、最新 stable、定价和支持窗口会持续变化。本笔记记录的是 2026-08-11 官方正文；任何实际升级必须重新读取当前 changelog、release policy 与目标 chart release notes。