第二十七节 升级与版本号
[!ref] 详解见用户手册「升级、备份与同步」节。
27.0 配置目录品牌迁移（zcode → avlcode）
自 v0.6.30-alpha 起，面向用户的品牌标识——全局配置目录、工作区 .zcode/ → .avlcode/、ZCODE_* → AVLCODE_* 环境变量等——统一迁移为 avlcode，启动 / 打开工作区时自动完成、有 toast 提示、保留旧名双读回退；内部进程名（zAgent / zMCP / zWorkspace）与 ZAGENT_* / ZMCP_* 等内部环境变量不在迁移范围：
| 旧 | 新 |
|---|---|
全局配置目录 ~/.config/zcode/ |
~/.config/avlcode/ |
工作区内 .zcode/（含 rag/、sbom.* 等） |
.avlcode/ |
环境变量 ZCODE_…（如 ZCODE_DISABLE_VENV_AUTODETECT） |
AVLCODE_… |
配置 YAML 与 frontmatter 字段（x-zcode-… 等） |
对应 avlcode / x-avlcode-… |
UA 尾部令牌 zCode/<ver> |
avlcode/<ver> |
SSH 远端 ~/.zcode、远程工作区 .zcode |
~/.avlcode、.avlcode |
界面与对外输出里残留的「zCode」统一为「AVL Code」。脚本里写死过旧路径 / 旧变量的，建议改用新名。
27.1 版本号格式
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]
| 段 | 含义 |
|---|---|
| MAJOR | 不兼容更改（数据迁移 / 配置不兼容） |
| MINOR | 新功能（向后兼容） |
| PATCH | 修复 / 优化（向后兼容） |
| PRERELEASE | alpha.<n> / beta.<n> / rc.<n> |
| BUILD | 构建元数据，不参与版本比较 |
27.2 升级路径
| 路径 | 频率 | 说明 |
|---|---|---|
| 应用内升级 | 默认每天检查 | 推荐 |
| 手动下载（免安装） | 按需 | 官网下载页 www.avlcode.cn/#download，下载直接替换运行，配置目录不动 |
| 内部市场 | 视团队配置 | 组织管理员控制版本 |
Alpha 版本有效期 45 天：自版本号中编码的发布时间（UTC+8）起算，启动时与此后每小时检查；超期挂全屏锁定遮罩 —— 已登录且有用量：自动检查更新 → 下载 → 倒计时重启（可「立即重启」）；未登录：「去登录」「重新检查」「访问官网」；已登录无用量：「购买点券」「升级 · 订阅套餐」「重新检查」「访问官网」；底部恒有「退出应用」。
官网下载页按平台提供构建（Windows x64 / macOS 通用版·Apple 芯片版 / Linux x64·AppImage·Snap·WebKit4.1 / 银河麒麟 V10 SP1 / 统信 UOS V20 / 银河麒麟 ARM64），走 alpha 渠道、恒为最新构建。
27.2.1 国产化 ARM64 渠道
国产化 ARM64（aarch64）有独立的发布与升级源，与国产化 x86 互不影响：
| 项 | 取值 |
|---|---|
| 构建物 | 压缩包（linux-arm64-domestic.zip）与麒麟 V10 ARM64 DEB（avlcode_v10_<版本>_arm64.deb） |
| WebKit | DEB 包内自带可重定位的 WebKit 4.1 运行时，目标机无合适 webkit2gtk-4.1 也可运行 |
| 逻辑渠道 | 仍是 dev / alpha / beta / rc / stable；架构隔离由独立的源命名空间表达，不新造渠道名 |
| 签名 | 与既有发布同一套国密 SM2 签名与可信公钥 |
| 客户端 | 在 ARM64 国产化环境上自动选用该源检查更新 |
本渠道当前不含 ARM64 的 AppImage / Snap 与多架构合并清单。
27.3 升级签名
| 步骤 | 说明 |
|---|---|
| 下载 | 从内部升级源拉到本地缓存 |
| 验签 | 国密签名 + 嵌入公钥校验 |
| 替换 | 验签通过后原子替换主二进制 |
| 回滚 | 验签失败 / 启动失败时自动回滚到上一版本 |