从 CHANGELOG 读懂 Memos：版本演进、破坏性变更与升级路径全解析

Memos 是一个开源、可自托管、以 Markdown 为原生载体的快速记录工具。其 CHANGELOG.md 完整记录了从 0.26 到 0.31.0-rc.1 的每次发布内容，而 release-please-config.json 与 internal/version/version.go 则揭示了这套变更历史的生成机制。读完本文，你将理解 Memos 的版本号与发布流水线约定，掌握 0.30 大版本中四处破坏性变更的准确迁移方式，并知道如何安全地把实例从旧版本升级到最新 rc。

一、CHANGELOG 的结构与其背后的发布流水线

Memos 的 CHANGELOG.md 按 SemVer 倒序组织，每个版本块由标题（版本号 + 对比链接 + 发布日期）和若干语义化分区组成。当前仓库中记录的最新条目是 0.31.0-rc.1（2026-08-30），其上依次为 0.30.0（2026-07-26）、两个 0.30 的 RC、0.29.1（2026-06-04）、0.29.0（2026-05-27）、0.28.0（2026-04-27）、0.27.1 与 0.27.0（2026-04-18）。

这份 changelog 并非手写，而是由发布工具链根据 Conventional Commits 自动聚合。release-please-config.json 中的关键字段决定了它的生成规则：

配置项	取值	含义
release-type	go	采用 Go 项目的 SemVer 规则做版本推导
include-v-in-tag	true	版本 tag 带 v 前缀，如 v0.30.0
bump-minor-pre-major	true	在 0.x 阶段，feat 提交提升 minor 而非 patch
versioning / prerelease	prerelease / true	开启预发布流程
prerelease-type	rc.1	候选版本的固定后缀为 -rc.1

changelog-sections 定义了提交类型到分区的映射：feat → Features、fix → Bug Fixes、perf → Performance Improvements、deps → Dependencies、revert → Reverts。这解释了为什么 changelog 中每条记录都带 **scope:** 前缀（如 **store:**、**mcp:**）——它直接来自 commit message 的 scope 段。

值得注意的是，并非每个版本都只有机械分区。0.30.0 这个稳定版额外带有 Summary（版本总结）、⚠ BREAKING CHANGES（破坏性变更）和 Highlights（亮点）三段，RC 版本则带有 Highlights 与 Fixes and polish 段。这说明 Memos 在工具生成的骨架之上，为重要版本手工补充了叙事性内容，把“逐条记录”和“版本导读”结合起来。

版本号在代码中的落地

发布产生的版本号会被注入二进制。internal/version/version.go 中 Version 变量默认是 dev 标记，由 release 构建通过链接期参数写入真实版本；Commit 同理默认 unknown。该包还提供三个被迁移系统使用的工具函数：

• GetMinorVersion：从 0.25.1 提取 0.25；
• IsVersionGreaterOrEqualThan / IsVersionGreaterThan：基于 golang.org/x/mod/semver 的严格 SemVer 比较（内部给版本补 v 前缀）。

这些比较逻辑服务于数据库迁移的前置校验：store/migrator.go 的注释明确写出迁移流程会执行 checkMinimumUpgradeVersion，拒绝 0.22 之前的旧安装直接升级（此类安装必须先升到 0.25.x，完成 migration_history → system_setting 的版本表迁移）。因此阅读 changelog 时，“从哪个版本升到哪个版本”本身就是一条需要核对的约束，而非只关心目标版本的新功能。

二、关键里程碑：0.27 → 0.31 的演进主线

把 CHANGELOG.md 中的条目按主题聚合，可以看到 Memos 在这一段版本区间里推进了四条清晰的主线。

1. 实时性与外部集成（0.27.0 起）

0.27.0 是功能密度最高的一个版本，changelog 中的代表性条目包括：

• 通过 Server-Sent Events（SSE）实现实时刷新，并带可视指示器；0.27.1/0.29.0 继续修复 SSE hub 设计与 token 刷新（sse: stream initial response and refresh tokens）；
• 新增 MCP server（PAT 认证），随后经历 refactor to standard protocol structure、harden tool exposure and side effects 等加固；
• AI 语音转写三件套：实例级 AI provider（ai: add instance AI providers and transcription）、Gemini 转写 provider、BYOK（用户自带密钥）转写；
• 附件能力扩展：Live Photo / Motion Photo 支持、音频附件内联播放器、--allow-private-webhooks 标志用于绕过 webhook 的 SSRF 防护。

SSE 相关改动在仓库中对应前端的 hooks 下的 useLiveMemoRefresh 等钩子，与 changelog 中“live refresh via SSE”条目相互印证。

2. 身份与访问体系（0.28.0 → 0.30.0）

• 0.28.0 引入 SSO 用户身份关联（auth: add SSO user identity linkage）并重构了账号与 SSO 管理界面；0.28.0 还强化了授权与用户名校验（auth: harden authorization and username validation）；
• 0.29.0 增加可配置的 --log-level 启动标志、SMTP 邮件通知设置；
• 0.30.0 将 SSO 首登供给做成了跨 SQLite/MySQL/PostgreSQL 的原子操作，保证并发首次登录不会留下孤儿用户——这类修复直接对应 server/auth 与 store/db 中的身份解析实现。

3. 0.30 大版本：编辑器、MCP 与部署配置

0.30.0 的 Summary 段自述其定位：“a major writing and navigation refresh”，核心内容在 changelog 的 Highlights 中逐条列出：

• Markdown 编辑器：重写为单个 CodeMirror 6 装饰源码编辑器，Markdown 原文逐字保留，标题、格式、tag、mention 就地样式化，并附 tag 自动补全、列表缩进、快捷键与可切换的格式工具栏；
• MCP：手写 MCP 实现被替换为由 OpenAPI schema 生成的、复用公开 API 鉴权的工具面，工具集覆盖 memo、comment、relation、reaction、shortcut、identity 与 attachment（含上传）；
• 部署时配置：身份提供方与受支持的实例设置可以通过 /etc/secrets 下经验证的 JSON 文件提供，文件型设置在移除前不能通过 UI/API 修改，只能作为运行时覆盖。这与 docs/configuration-provisioning.md 的说明一致；
• Webhook：引入 Standard Webhooks HMAC-SHA256 签名密钥、webhook 编辑能力与签名状态指示，签名密钥由服务端生成、创建后展示、可在编辑对话框中再次查看，畸形密钥会被校验拒绝；
• 过滤器与 tag 设置：CEL 快捷方式扩展了字符串匹配、正则、集合谓词、时间戳访问器与集合操作；tag 颜色与内容模糊规则改为按用户存储，迁移时复制既有实例级设置；
• 性能：通过指纹资产缓存、按需延迟渲染媒体与富组件、近视口渲染以及跨 creator/reaction/comment/mention/relation 共享用户和 memo 查询来降低首屏工作量。

4. 0.31.0-rc.1：多空间协作与语言规范收口

当前最新的 0.31.0-rc.1 条目把重心放在多空间（Spaces）与领域语言规范上：

• spaces 系列条目构成完整闭环：多空间 memo 协作（spaces: add multi-space memo collaboration）、基于同意的成员邀请（consent-based member invitations）、设置管理、空间感知的 UI 与过滤，以及跨资源页统一集合作用域；
• 规范收口：markdown: unify tag syntax and recognition、user: define username format and mention syntax 与 space: add client-defined UIDs and identity cues 三条特性，分别落地为仓库中的三份 ADR——docs/adr/0001-tag-syntax-and-recognition.md、docs/adr/0002-username-format-and-references.md、docs/adr/0003-space-uid-allocation-and-format.md，多空间的产品边界则记录在 docs/design/multi-spaces.md；
• 存储：storage: add named attachment storage drivers，对应 internal/storage/driver.go 中按 StorageType 分发到 S3 驱动（internal/storage/s3）的 NewDriver 工厂；
• 内容：支持把附件图片插入 memo 正文（support memo-scoped Markdown attachment images 与 insert attachment images into memo content）、按 memo 地理位置过滤（filter: support memo location filters）、持久化并展示客户端媒体元数据。

三、0.30.0 的四处破坏性变更与迁移方式

0.30.0 的 ⚠ BREAKING CHANGES 段是全 changelog 中唯一集中列出破坏性变更的地方，升级前必须逐条核对。以下四条均给出 changelog 原文语义与迁移操作。

1. 未配置实例 URL 的实例默认进入私有模式

changelog 原文：实例若未设置 --instance-url（或环境变量 MEMOS_INSTANCE_URL）将以私有模式运行；匿名访问者被重定向到登录页，匿名 API 访问被限制在 setup、认证与共享 memo 路由，RSS 不再可用。

迁移方式：若希望保留 0.30 之前的公开行为，升级后显式设置 --instance-url 或 MEMOS_INSTANCE_URL 为实例的公网访问地址；否则按私有实例管理，为需要匿名访问的入口使用共享 memo 路由。

2. 共享 memo API 的整体替换

GetMemoByShare 与 GET /api/v1/shares/{share_id} 已被 GetSharedMemo 与 GET /api/v1/shares/{share_token}/memo 取代。API 客户端需要同步更新四点：RPC 名、请求类型、字段名和 REST 路径。语义上还有收窄：share-token 响应只包含被共享的 memo 及其附件，不再暴露父级上下文、评论和关系图。该变更在 proto/api/v1/memo_share 相关定义 所描述的 v1 API 体系内，是 0.30 “强化访问边界”主题的一部分。

3. CEL 过滤器：now() 函数变为 now 时间戳变量

旧写法中的 now() 函数已被 now 时间戳变量替代，且时间字段改用 CEL 时间戳类型。保存的快捷方式需要改写为例如：

created_ts >= now - duration("24h")

对 epoch 值则使用 timestamp(<epoch>) 转换，而不是把时间字段与裸 epoch 数字直接比较。这条变更影响面是所有基于 CEL 的筛选表达式，其执行引擎在 internal/filter 中实现（含 internal/filter/parser.go 的词法与 internal/filter/ir.go 的中间表示）。

4. MCP 端点重构为无状态工具面

MCP server 现在是基于 OpenAPI schema 生成的无状态、仅工具端点。以下旧能力全部移除：prompts、resources、工具过滤头与路由别名、无服务前缀的工具名。客户端必须切换到 /mcp 路由并使用新的服务前缀工具名；工具错误也改用 isError + 文本内容，而不再使用非标准的 structuredContent.error 载荷。仓库中 server/router/mcp 目录（含 adapter.go、catalog.go、openapi.go）即为该工具面的实现位置。

四、安全与稳定性条目：changelog 中的“低音量”信号

changelog 的 Bug Fixes 段里散布着对自托管运维者极有价值的条目，值得单独梳理：

• 依赖漏洞修复：upgrade golang.org/x/crypto to 0.52.0 (CVE-2026-39829) 是 changelog 中唯一显式标注 CVE 的依赖升级，说明安全公告会直接体现在变更历史里；
• S3 附件访问收紧：storage: proxy S3 attachments through authenticated routes——S3 后端附件改为经由认证路由代理，避免对象存储 URL 被直接暴露；配合 0.30 Highlights 中提到的 S3 自签名证书选项 insecure_skip_tls_verify；
• 存储层加固：store: begin sqlite memo mutations with BEGIN IMMEDIATE（SQLite 下 memo 写事务以 IMMEDIATE 模式开启，规避写冲突）与 store: harden 0.31 migration upgrades（0.31 迁移升级的加固）；
• 链接元数据抓取防护：httpgetter: prevent DNS rebinding in link metadata fetch（0.29.0），与 0.30 的“standards-based metadata”链接预览特性对应，实现位于 internal/httpgetter；
• 附件所有权：security: enforce attachment ownership on memo updates（0.29.0）；
• 入口脚本：Container: prevented the entrypoint from restarting indefinitely when MEMOS_UID=0——对应 scripts/entrypoint.sh 的容器入口逻辑。

发布流程本身也有测试兜底：scripts/release_smoke_test.sh 会对候选发布镜像跑“全新安装 + 从上一稳定版升级”两类黑盒冒烟测试（支持 --candidate-image、--previous-image、--keep-resources 选项），数据库侧则有一组升级护栏测试，如 store/test/migrator_upgrade_test.go 与 store/test/migrator_stable_upgrade_test.go。这意味着 changelog 中标注 harden ... migration upgrades 的版本，其升级路径是有自动化验证覆盖的。

五、版本间语言规范的深化：从 changelog 条目到 ADR

0.31.0-rc.1 中三条“规范统一”特性是 changelog 与设计文档关联最紧密的条目，可以顺藤摸瓜深入阅读：

• tag 语法统一：changelog 条目 markdown: unify tag syntax and recognition 对应 docs/adr/0001-tag-syntax-and-recognition.md。该 ADR 定义了基于 Unicode 17.0 / Emoji 17.0 的规范性词法：仅 U+0023 是引入符；/ 是层级分隔符；-、+、& 是段内可见单元；仅接受 Fully_Qualified emoji 序列；等值比较为精确码点相等，不做大小写折叠或 Unicode 归一化。changelog 中 0.30 阶段关于 tag 的修复（链接内 tag 不再被解析、反斜杠转义字面 tag、Unicode 组合符支持）正是这次统一的铺垫；
• 用户名与 mention 语法：条目 user: define username format and mention syntax 对应 docs/adr/0002-username-format-and-references.md：可写用户名为 1–36 位 ASCII 字母/数字/连字符、两端必须为字母或数字、大小写敏感；Markdown mention 候选直接复用该格式（@ + 完整用户名），GFM 邮箱识别优先于 mention。实现可见 internal/base/username.go 与 internal/markdown/parser/mention.go；
• Space UID 分配：条目 space: add client-defined UIDs and identity cues 对应 docs/adr/0003-space-uid-allocation-and-format.md：首方客户端为新建 Space 生成小写 UUID v4 并通过 CreateSpaceRequest.space_id 发送，字段保持可选以兼容旧客户端（为空时服务端生成）；自定义 UID 复用 1–36 字符的公共资源 UID 文法。

这种“changelog 条目 → ADR → 源码实现”的三层结构，是理解 Memos 近期演进的可靠路径。

六、面向使用者的实操清单

基于 changelog 与仓库证据，升级与核对版本可以按以下清单执行：

1. 核对当前版本：0.27.0 起 CLI 提供 version 子命令（changelog 条目 cli: add version subcommand），版本值来自 internal/version/version.go 的构建期注入；
2. 确认升级路径：0.22 之前的旧安装不能直升，需先升到 0.25.x（见 store/migrator.go 的迁移流程注释）；跨大版本建议逐跳升级，每跳对照 CHANGELOG 的 BREAKING CHANGES 段；
3. 升级 0.30 前逐项处理四处破坏性变更：设置 MEMOS_INSTANCE_URL（或改用私有模式）、改造共享 memo API 客户端、改写 CEL 快捷方式中的 now()、更新 MCP 客户端至 /mcp 与新工具名；
4. 核对迁移产物：各驱动的迁移脚本位于 store/migration 下的 mysql、postgres、sqlite 子目录（含各版本增量 SQL 与 LATEST.sql），0.31 迁移还有专门的 harden 0.31 migration upgrades 修复条目；
5. 关注 0.31.0-rc.1 的 rc 状态：按 release-please-config.json 的 prerelease-type: rc.1 约定，-rc.1 是候选发布，生产环境应等待其稳定版（预期为 0.31.0）发布后再升级；
6. 验收手段：仓库自带 scripts/release_smoke_test.sh 覆盖全新安装与上一稳定版升级两类场景，自托管者可以参照其思路对升级后的实例做最小冒烟验证（创建 memo、附件访问、过滤器与 SSE 刷新）。

七、小结

Memos 的 CHANGELOG.md 是一份“机器生成骨架 + 手工版本导读”的混合型变更历史：release-please-config.json 决定版本推导与分区规则，feat/fix/perf/deps/revert 提交类型映射到固定小节，而 0.30 这类大版本额外提供 Summary、BREAKING CHANGES 与 Highlights。0.30.0 的四处破坏性变更（私有模式默认化、共享 memo API 替换、CEL now 变量、MCP 端点重构）构成了从旧版本升级的硬性检查点；0.31.0-rc.1 则以多空间协作为主线，把 tag、username、Space UID 三条语言规范沉淀为 ADR 文档。对自托管用户而言，把 changelog 的破坏性变更段当作升级前置检查单、把 store/migrator.go 的最小版本约束当作升级路径约束，就能在这套快速迭代的版本体系中安全演进。