Skip to content

Commit e32c159

Browse files
claude-code-bestclaude-code-best
committed
feat: 关闭自动更新
1 parent 1195185 commit e32c159

2 files changed

Lines changed: 316 additions & 0 deletions

File tree

‎docs/auto-updater.md‎

Lines changed: 312 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,312 @@
1+
# 自动更新机制
2+
3+
## 概述
4+
5+
Claude Code 拥有一套复杂的多策略自动更新系统，支持三种安装方式、后台静默更新、手动 CLI 命令、服务端版本门控以及更新日志展示。系统设计目标是在最小用户干预下保持 CLI 最新，同时提供回滚和手动控制的兜底手段。
6+
7+
---
8+
9+
## 安装类型与更新策略
10+
11+
更新策略由安装方式决定，通过 `src/utils/doctorDiagnostic.ts` 检测：
12+
13+
| 安装类型 | 更新策略 | 自动安装？ |
14+
|---|---|---|
15+
| `native` | 从 GCS/Artifactory 下载二进制文件，通过符号链接激活 | 是（静默） |
16+
| `npm-global` | `npm install -g` / `bun install -g` | 是（静默） |
17+
| `npm-local` | `npm install` 到 `~/.claude/local/` | 是（静默） |
18+
| `package-manager` | 显示通知，附带对应操作系统的升级命令 | 否（仅通知） |
19+
| `development` | 不适用 — 执行 `claude update` 时报错 | 不适用 |
20+
21+
### 策略路由
22+
23+
`src/components/AutoUpdaterWrapper.tsx` — 挂载在 React/Ink UI 树中 — 检测安装类型并渲染对应的更新组件：
24+
25+
- `native` → `NativeAutoUpdater`（二进制下载 + 符号链接）
26+
- `package-manager` → `PackageManagerAutoUpdater`（仅通知）
27+
- 其他 → `AutoUpdater`（基于 JS/npm）
28+
29+
---
30+
31+
## 后台自动更新循环
32+
33+
三个更新组件共享相同的轮询模式：
34+
35+
```typescript
36+
useInterval(checkForUpdates, 30 * 60 * 1000); // 每 30 分钟
37+
```
38+
39+
组件挂载时（即启动时）也会执行一次检查。
40+
41+
### 前置检查门控
42+
43+
任何更新尝试之前，系统会依次检查：
44+
45+
1. **自动更新是否被禁用？** — `getAutoUpdaterDisabledReason()`（`src/utils/config.ts:1735`）
46+
- `NODE_ENV === 'development'`
47+
- 设置了 `DISABLE_AUTOUPDATER` 环境变量
48+
- 仅限必要流量模式
49+
- `config.autoUpdates === false`（native 安装的保护模式除外）
50+
2. **最大版本上限？** — `getMaxVersion()`（`src/utils/autoUpdater.ts:108`）— 服务端熔断开关，防止更新到已知有问题的版本
51+
3. **是否跳过该版本？** — `shouldSkipVersion()`（`src/utils/autoUpdater.ts:145`）— 尊重用户的 `minimumVersion` 设置，防止切换到 stable 频道时发生意外的版本降级
52+
53+
### Native 自动更新器（`src/components/NativeAutoUpdater.tsx`）
54+
55+
1. 调用 `src/utils/nativeInstaller/installer.ts` 中的 `installLatest()`
56+
2. 通过 `src/utils/nativeInstaller/download.ts` 下载二进制文件（GCS 或 Artifactory）
57+
3. 验证 SHA256 校验和（3 次重试，60 秒卡顿检测）
58+
4. 将版本化二进制文件存储到 XDG 目录
59+
5. 更新符号链接（`~/.local/bin/claude` → 新版本二进制文件）
60+
6. 保留最近 2 个版本，清理旧版本
61+
7. 将错误分类上报分析（超时、校验和、权限、磁盘空间不足、npm、网络）
62+
63+
### JS/npm 自动更新器（`src/components/AutoUpdater.tsx`）
64+
65+
1. 调用 `getLatestVersion()` 获取当前 npm dist-tag
66+
2. 通过 semver `gte()` 比较版本
67+
3. 根据安装类型路由到本地或全局安装
68+
4. 使用文件锁（`acquireLock()` / `releaseLock()`）防止并发更新
69+
70+
### 包管理器通知器（`src/components/PackageManagerAutoUpdater.tsx`）
71+
72+
每 30 分钟通过 GCS 存储桶（非 npm）检查更新。**不会自动安装** — 仅显示对应操作系统的升级命令：
73+
74+
- macOS: `brew upgrade claude-code`
75+
- Windows: `winget upgrade Anthropic.ClaudeCode`
76+
- Alpine: `apk upgrade claude-code`
77+
78+
---
79+
80+
## 启动版本门控
81+
82+
`src/utils/autoUpdater.ts:70` — `assertMinVersion()`
83+
84+
从 `src/main.tsx:1775` 在启动时调用：
85+
86+
```typescript
87+
void assertMinVersion();
88+
```
89+
90+
1. 从 GrowthBook 动态配置获取 `tengu_version_config`
91+
2. 如果 `MACRO.VERSION < minVersion`，打印错误信息并调用 `gracefulShutdownSync(1)` — 强制用户更新
92+
3. 这是一个**硬性门控** — 低于最低版本的 CLI 将无法启动
93+
94+
---
95+
96+
## 手动 CLI 命令
97+
98+
### `claude update` / `claude upgrade`
99+
100+
**文件**: `src/cli/update.ts`
101+
102+
完整流程：
103+
1. 运行 `getDoctorDiagnostic()` 检查系统健康状态
104+
2. 检查是否存在多个安装及配置不一致
105+
3. 根据安装类型路由：
106+
- `development` → 报错（"开发版本不支持自动更新"）
107+
- `package-manager` → 打印对应操作系统的更新命令
108+
- `native` → 使用原生安装器的 `updateLatest()`
109+
- `npm-local` → 在 `~/.claude/local/` 执行 `npm install`
110+
- `npm-global` → 执行 `npm install -g`（含权限检查）
111+
4. 报告当前版本、最新版本、成功/失败状态
112+
113+
### `claude rollback [target]`（仅限内部）
114+
115+
回滚到之前的版本。支持 `--list`、`--dry-run`、`--safe` 标志。
116+
117+
### `claude install [target]`
118+
119+
安装或重新安装原生构建版本。接受可选的版本目标参数。
120+
121+
### `claude doctor`
122+
123+
检查自动更新器的健康状态，报告状态、权限和配置信息。
124+
125+
---
126+
127+
## 原生安装器架构
128+
129+
**文件**: `src/utils/nativeInstaller/installer.ts`
130+
131+
### 二进制文件存储布局
132+
133+
```
134+
~/.local/share/claude-code/
135+
├── versions/ # 版本化二进制文件 (claude-1.0.3, claude-1.0.4, ...)
136+
├── staging/ # 临时下载暂存区
137+
└── locks/ # 基于 PID 和 mtime 的锁文件
138+
139+
~/.local/bin/claude # 指向当前版本二进制文件的符号链接
140+
```
141+
142+
Windows 系统使用文件复制而非符号链接。
143+
144+
### 核心操作
145+
146+
| 函数 | 说明 |
147+
|---|---|
148+
| `updateLatest()` | 核心更新流程：最大版本上限 → 跳过检查 → 加锁 → 下载 → 安装 → 更新符号链接 |
149+
| `installLatest()` | Singleflight 包装版本，防止重复的进行中安装 |
150+
| `cleanupOldVersions()` | 保留最近 2 个版本，清理过期的暂存区和临时文件 |
151+
| `lockCurrentVersion()` | 进程生命周期锁，防止正在运行的版本被删除 |
152+
| `cleanupNpmInstallations()` | 迁移到原生安装时清理旧的 npm 安装 |
153+
154+
### 下载与校验
155+
156+
**文件**: `src/utils/nativeInstaller/download.ts`
157+
158+
1. 路由到 Artifactory（内部用户）或 GCS 存储桶（外部用户）
159+
2. 下载二进制文件并跟踪进度
160+
3. SHA256 校验和验证
161+
4. 60 秒卡顿检测（中止停滞的下载）
162+
5. 失败时自动重试 3 次
163+
164+
---
165+
166+
## 文件锁机制
167+
168+
**文件**: `src/utils/autoUpdater.ts:176-268`
169+
170+
防止并发更新进程破坏安装：
171+
172+
- 锁文件：`~/.claude/update.lock`（或等效路径）
173+
- 5 分钟超时 — 超过 5 分钟的锁被视为过期，强制获取
174+
- 进程将其 PID 写入锁文件
175+
- `acquireLock()` 和 `releaseLock()` 同时被 JS/npm 和原生安装器使用
176+
177+
---
178+
179+
## 配置
180+
181+
### 设置项
182+
183+
**文件**: `src/utils/settings/types.ts`
184+
185+
| 设置项 | 类型 | 说明 |
186+
|---|---|---|
187+
| `autoUpdatesChannel` | `'latest' \| 'stable'` | 自动更新的发布频道 |
188+
| `minimumVersion` | string | 最低版本要求，防止意外的版本降级 |
189+
190+
### 全局配置
191+
192+
**文件**: `src/utils/config.ts:191-193`
193+
194+
| 字段 | 类型 | 说明 |
195+
|---|---|---|
196+
| `autoUpdates` | boolean | 启用/禁用自动更新（旧版） |
197+
| `autoUpdatesProtectedForNative` | boolean | 原生安装始终自动更新 |
198+
199+
### 配置迁移
200+
201+
**文件**: `src/migrations/migrateAutoUpdatesToSettings.ts`
202+
203+
一次性将旧版 `globalConfig.autoUpdates = false` 迁移为 settings 中的 `DISABLE_AUTOUPDATER=1` 环境变量。从 `src/main.tsx:325` 在启动时调用。
204+
205+
---
206+
207+
## 更新通知去重
208+
209+
**文件**: `src/hooks/useUpdateNotification.ts`
210+
211+
React hook `useUpdateNotification(updatedVersion)` — 确保每次 semver 变更（major.minor.patch）只显示一次"重启以更新"消息，避免同一版本的重复通知。
212+
213+
---
214+
215+
## 更新日志
216+
217+
**文件**: `src/utils/releaseNotes.ts`
218+
219+
1. 从 `src/setup.ts:387` 在每次启动时调用
220+
2. 从 GitHub 获取 changelog
221+
3. 缓存到 `~/.claude/cache/changelog.md`
222+
4. 展示比 `lastReleaseNotesSeen` 更新的版本的更新日志
223+
5. 使用 semver 比较确定需要展示哪些日志
224+
225+
---
226+
227+
## 版本比较
228+
229+
**文件**: `src/utils/semver.ts`
230+
231+
- 提供 `gt()`、`gte()`、`lt()`、`lte()`、`satisfies()`、`order()`
232+
- 在 Bun 环境下使用 `Bun.semver.order()`（快 20 倍）
233+
- 在 Node.js 环境下回退到 npm `semver` 包
234+
235+
---
236+
237+
## 分析事件
238+
239+
所有更新相关的遥测数据使用 `tengu_` 前缀的事件：
240+
241+
| 类别 | 事件 |
242+
|---|---|
243+
| 版本检查 | `tengu_version_check_success`、`tengu_version_check_failure` |
244+
| JS 自动更新器 | `tengu_auto_updater_start/success/fail/up_to_date/lock_contention` |
245+
| 原生自动更新器 | `tengu_native_auto_updater_start/success/fail` |
246+
| 原生更新 | `tengu_native_update_complete/skipped_max_version/skipped_minimum_version` |
247+
| 锁机制 | `tengu_version_lock_acquired/failed`、`tengu_native_update_lock_failed` |
248+
| 二进制下载 | `tengu_binary_download_attempt/success/failure`、`tengu_binary_manifest_fetch_failure` |
249+
| 清理 | `tengu_native_version_cleanup`、`tengu_native_staging_cleanup`、`tengu_native_stale_locks_cleanup` |
250+
| 安装 | `tengu_native_install_package_success/failure`、`tengu_native_install_binary_success/failure` |
251+
| 手动更新 | `tengu_update_check` |
252+
| 迁移 | `tengu_migrate_autoupdates_to_settings`、`tengu_migrate_autoupdates_error` |
253+
254+
---
255+
256+
## 关键文件索引
257+
258+
| 文件 | 职责 |
259+
|---|---|
260+
| `src/utils/autoUpdater.ts` | 核心逻辑：版本检查、npm 安装、文件锁、最低/最高版本门控 |
261+
| `src/cli/update.ts` | `claude update` 命令处理 |
262+
| `src/utils/nativeInstaller/installer.ts` | 原生二进制安装器：下载、版本管理、符号链接、清理 |
263+
| `src/utils/nativeInstaller/download.ts` | 从 GCS/Artifactory 下载二进制文件并校验 |
264+
| `src/utils/localInstaller.ts` | 本地安装器（`~/.claude/local/`）基于 npm |
265+
| `src/components/AutoUpdaterWrapper.tsx` | 基于安装类型的策略路由 |
266+
| `src/components/AutoUpdater.tsx` | JS/npm 后台自动更新器（30 分钟间隔） |
267+
| `src/components/NativeAutoUpdater.tsx` | 原生二进制后台自动更新器（30 分钟间隔） |
268+
| `src/components/PackageManagerAutoUpdater.tsx` | 包管理器通知（30 分钟，仅展示） |
269+
| `src/hooks/useUpdateNotification.ts` | 按 semver 去重更新通知 |
270+
| `src/utils/releaseNotes.ts` | Changelog 获取、缓存与展示 |
271+
| `src/utils/semver.ts` | Semver 版本比较（Bun 原生 + npm 回退） |
272+
| `src/utils/doctorDiagnostic.ts` | 安装类型检测与健康诊断 |
273+
| `src/utils/config.ts:1735` | `getAutoUpdaterDisabledReason()` — 禁用检查逻辑 |
274+
| `src/migrations/migrateAutoUpdatesToSettings.ts` | 旧版配置迁移 |
275+
| `src/screens/Doctor.tsx` | Doctor 命令 UI，展示自动更新状态 |
276+
277+
---
278+
279+
## 流程图
280+
281+
```
282+
启动阶段
283+
├── assertMinVersion() → 版本过低时硬性拦截，拒绝启动
284+
├── migrateAutoUpdatesToSettings() → 一次性配置迁移
285+
└── checkForReleaseNotes() → 展示新版本的更新日志
286+
287+
REPL 运行中（每 30 分钟）
288+
├── AutoUpdaterWrapper 检测安装类型
289+
│
290+
├── native → NativeAutoUpdater
291+
│ ├── 从 GCS/Artifactory 获取版本
292+
│ ├── 检查最大版本上限（服务端控制）
293+
│ ├── 检查 minimumVersion 设置（跳过）
294+
│ ├── acquireLock()
295+
│ ├── downloadAndVerifyBinary()（SHA256 校验，3 次重试）
296+
│ ├── 安装到 versions/ 目录
297+
│ ├── 更新符号链接
298+
│ └── cleanupOldVersions()（保留 2 个版本）
299+
│
300+
├── npm-global/local → AutoUpdater
301+
│ ├── 从 npm registry 获取最新版本
302+
│ ├── semver 版本比较
303+
│ ├── acquireLock()
304+
│ └── npm install -g / 本地安装
305+
│
306+
└── package-manager → PackageManagerAutoUpdater
307+
├── 从 GCS 获取版本
308+
└── 显示 "Run: brew upgrade ..."（不自动安装）
309+
310+
手动操作
311+
└── claude update → 完整诊断 + 安装编排
312+
```

‎src/utils/config.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1736,6 +1736,10 @@ export function getAutoUpdaterDisabledReason(): AutoUpdaterDisabledReason | null
17361736
if (process.env.NODE_ENV === 'development') {
17371737
return { type: 'development' }
17381738
}
1739+
// 本项目默认关闭自动更新；通过 ENABLE_AUTOUPDATER=1 显式开启
1740+
if (!isEnvTruthy(process.env.ENABLE_AUTOUPDATER)) {
1741+
return { type: 'config' }
1742+
}
17391743
if (isEnvTruthy(process.env.DISABLE_AUTOUPDATER)) {
17401744
return { type: 'env', envVar: 'DISABLE_AUTOUPDATER' }
17411745
}

0 commit comments

Comments
 (0)