T3 Code 更新指南：服务端、桌面端与移动端的完整升级流程

T3 Code 更新指南服务端、桌面端与移动端的完整升级流程【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code导读T3 Code 采用客户端与服务端分离的架构你日常使用的应用桌面端、Web 端、移动端与真正运行 Agent 的服务器可能位于完全不同的机器上。因此更新不是简单地升级一个安装包而是要在正确识别哪个组件落后于哪个版本的前提下用与运行方式匹配的手段完成升级。本文基于 docs/user/updating.md 整理完整更新流程并结合 apps/server/src/serviceLauncher.ts、apps/server/src/cli/service.ts、apps/mobile/src/features/updates/app-updates.ts 等源码深入讲解后台服务更新的事务性提交机制、失败回滚与移动端后台下载更新的实现原理。读完本文你将掌握如何判断更新提示指向哪台机器、三种服务器运行形态各自对应的更新动作、npx t3client-version service update的正确用法、更新失败的排查步骤以及桌面端与移动端的更新行为差异。一、更新模型先搞清楚谁落后于谁你使用的应用和运行 Agent 的服务器可能在不同的机器上。当服务器位于你的 Web 应用或桌面应用之后时版本不匹配会产生更新提示提示出现在两处对话conversation中Settings → Connections设置页更新提示会明确指出版本落后的机器名称。升级时务必更新提示中指定的那台机器而不是你当前正在操作的设备——这是最常见的误操作来源用户在客户端所在机器上反复点击更新却始终无法消除提示因为真正需要更新的是另一台机器上的服务器。从源码结构看服务器侧的版本协调逻辑集中在 apps/server/src/cloud/serviceProtocol.ts 中它定义了服务状态文件SERVICE_STATE_FILE、launcher 与子进程间的 IPC 消息update-accepted、update-rejected、committed等以及精确版本比较函数。所谓精确版本exact version指形如0.0.41-preview.20260912.1595的完整版本号远程更新只接受比当前版本更新的精确版本serviceLauncher.ts 中的#handleUpdateRequest会拒绝非精确版本、非绝对路径以及不高于当前版本的目标。二、更新前的准备理解更新会带来什么影响服务器更新会重启连接并可能中断正在运行的 Agent 与终端命令。但以下数据会完整保留已保存的会话saved threads设置settings项目文件project files2.1 Continue threads after restarts 设置Settings → General → Continue threads after restarts默认关闭。开启后可在更新、崩溃或机器重启后恢复支持的活跃会话supported active threads。需要注意的细节该设置会保存到支持此设置的已连接环境中先更新旧服务器再启用该设置效果最佳。如果某个受支持的环境当时离线或保存的值不同可等它连接后在 Settings 中使用Apply to all统一应用。该设置不会自动启动 T3 Code——你必须在该机器上手动重新启动它。终端命令仍可能被中断没有保存 provider 恢复状态的会话需要发送一条新消息才能继续。如果你此前为更新启用了会话延续只需再开启一次该设置即可在无客户端连接的情况下允许恢复。三、更新已连接的服务器三种动作与运行形态的对应关系更新提示给出的操作取决于服务器以何种方式运行动作Action你需要做什么Update server保持客户端打开等待其安装并重新连接。受支持的后台服务支持远程更新。对于桌面端托管的服务器该操作还会关闭并重新启动宿主机上的桌面应用。Update the desktop app在运行服务器的机器上更新桌面应用需要时再重新打开它。Copy update command在其宿主机上停止命令行服务器用复制到的命令重新启动保留你惯用的启动选项。3.1 后台服务使用匹配版本的 CLI 更新对于以后台服务background service方式运行的服务器请在宿主机上运行与提示中版本匹配的 CLInpx t3client-version service update把client-version替换为提示中显示的版本。关键限制只有在你的客户端正处于该 release 上时使用latest才能解决版本不匹配问题较旧的服务 launcher 可能需要先完成本次本地更新之后才支持远程更新与回滚。这条限制的根源在于 launcher 协议按 docs/internals/server-updates.md 的说明安装与预检preflight在发布不可变运行时之前于 staging 阶段完成其中预检会校验 launcher 协议——需要新回滚保证的目标运行时无法安全地在旧 launcher 下运行。升级 launcher 本身只能通过本地service update完成。3.2 前台服务器复制更新命令对于前台运行的 CLI 服务器foreground server复制到的命令是npx t3client-version。如果你平时不带浏览器运行请追加serve同时保留诸如--host或--tailscale-serve之类的启动选项。例如npx t30.0.41-preview.20260912.1595 serve --host 0.0.0.0关于服务管理的更多细节参见 background services。四、深入后台服务更新命令service子命令族定义于 apps/server/src/cli/service.ts包含四个子命令子命令说明service install以当前 CLI 版本安装后台服务service update以当前 CLI 版本更新或修复后台服务service uninstall停止并移除后台服务service status查看服务是否已安装、运行状态与日志路径核心逻辑是reconcileService它会先检查已安装服务的状态若已安装且版本与当前 CLI 一致则不做任何改动若已安装版本比当前 CLI 更新且未显式传入--allow-downgrade则直接拒绝抛出BootServiceDowngradeRefusedError。service update与service install共享同一套 reconcile 逻辑因此更新或修复其实是同一路径。与更新相关的常用选项--allow-downgrade允许用较旧的 CLI 版本替换已安装的较新服务。旧 CLI 默认拒绝替换更新的服务必须显式加上该参数。使用npx t3nightly service update可更新到 nightly 通道用精确版本号替换nightly可固定到某一版本。service status的输出会给出完整状态安装的版本、unit 路径、日志路径以及诸如已安装t3version比当前 CLI 更新之类的提示并建议下一步执行npx t3installedVersion service update修复或显式传--allow-downgrade。4.1 自包含构建与t3 update自包含构建self-contained builds以 GitHub release 归档形式下载而非通过 npm 安装因此运行服务的机器在 CLI 就位后不再需要 Node.js 或 npm。将 CLI 带到无 Node 的机器上curl -fsSL https://t3.codes/install.sh | shWindows 在 PowerShell 中运行irm https://t3.codes/install.ps1 | iex脚本会把t3放到~/.local/bin后续t3 service install会复用同一份下载。默认跟随 stable 通道可用环境变量调整T3CODE_CHANNELnightly跟随 nightly 通道T3CODE_VERSION固定精确版本T3CODE_RELEASE_BASE_URL从镜像下载。此外还有第三个通道preview由维护者从未发布的开发分支手工裁切用于演练发布流水线。这些构建可能损坏、不提供修复、也从不作为更新推送只有当显式请求该通道时安装器和t3 update才会前往该通道且会给出警告。从 apps/server/src/cli/update.ts 的实现可见从 stable/nightly 切到 preview 需要显式确认非交互脚本会被直接拒绝Refusing to install a preview build without confirmation。自包含安装就绪后t3 update可在不依赖 npm 的情况下将机器切换到更新版本下载运行中t3所属通道的最新 release、校验、并把t3launcher 指向新版本。相关命令形态t3 update # 跟随当前通道更新到最新 t3 update 0.0.41-preview.20260912.1595 # 固定精确版本 t3 update --channel nightly # 切换到其他发布通道 t3 update --allow-downgrade # 允许回退到更旧版本t3 update的降级保护逻辑位于 apps/server/src/cli/update.ts 的runUpdate若目标版本低于当前安装的 CLI 或服务版本会报错并提示加--allow-downgrade。当同一 T3 home 安装了后台服务时更新前会询问是否重启服务因为重启会中断运行中的 Agent 回合、终端与远程客户端非交互脚本中无提示必须传--yes或-y才能重启服务。手工启动的服务器不会被自动触碰命令会明确告知它仍停留在旧版本需要你自行重启。t3 uninstall是安装脚本的逆向操作它会展示将要移除的内容后台服务、t3launcher、~/.t3/runtime下的每个已下载版本确认后移除。你的项目、会话与设置保存在~/.t3/userdata不会被删除如需彻底清除请自行删除该目录。脚本场景传--yes跳过确认。五、源码视角launcher 如何安全地提交一次更新docs/internals/server-updates.md 与 apps/server/src/serviceLauncher.ts 揭示了后台服务更新的事务性设计——这也是保持客户端打开等待重连这一操作要求背后的原因。5.1 谁拥有更新权稳定 launcherserviceLauncher.ts是被 systemd 或 launchd 选中的运行时所有者也是唯一可以持久写入服务状态的组件。服务器子进程通过继承的 IPC 请求更新从不自行重写自己的服务定义或选择替代版本本地service命令可在服务停止时替换 launcher 与状态。前台 CLI 进程不会自更新。5.2 提交边界Commit boundary更新流程是一个严格的状态机launcher 在确认更新前先把待更新状态PendingServiceUpdate含updateId、fromVersion、targetVersion、dbPath持久化记录然后停止旧子进程将目标版本作为trial试验启动。trial 必须完成迁移migrations、获取依赖、绑定 HTTP并在激活门activation gate处驻留所有长生命周期根然后才上报prepared。launcher 收到prepared后持久化提交目标版本状态变为committed才回复子进程committed。此后子进程才能释放门、接受命令、发布 ready。试验超时PREPARED_TIMEOUT_MS 120_000即 2 分钟或退出则回滚到旧版本。服务状态的每次写入都采用同目录替换same-directory replacement并同时 fsync 文件与目录见writeServiceState写入临时文件 → fsync → rename → fsync 目录。无效状态会直接中止启动而不是猜测该启动哪个运行时。5.3 数据库回滚Database rollback旧子进程退出后launcher 会为 SQLite 的三个文件主文件、-wal、-shm各做一次快照。这样 trial 期间的数据库迁移就是可逆的无需编写 down 迁移。快照每个更新只做一次backupDatabaseOnce且可跨 launcher 重启存活——重试时不会覆盖以免捕获失败 trial 产生的脏数据。回滚时先写.restore-pending标记再恢复确保中断的恢复能在任一版本启动前完成。快照会保留到提交完成或恢复与终态回滚都持久化为止。SQLite 之外的附件等文件不在回滚边界内——这也呼应了更新前应完成手头工作的建议。5.4 客户端确认Client acknowledgement被接受的更新仍是pending状态。客户端在重连后将 launcher 的 update ID 与 ready 事件关联再核对结果与目标版本。仅凭重连无法区分替换成功与回滚——因此界面要求你保持客户端打开直到重连或报错。旧版服务器没有 update ID只能退化为仅按版本关联。桌面端更新另有独立的两阶段交接two-phase handoff安装桌面应用会停止其内嵌的后端因此准备阶段在连接存活时返回 token客户端收到后才提交该 token——否则后端关闭可能丢失唯一的成功 RPC 结果。安装失败时桌面端会重启已停止的后端并为同一 token 重放失败。六、如果更新失败怎么办保持客户端打开直到它重连或报告失败。服务更新失败时可以回滚到上一版本。若仍然失败按以下顺序排查重试一次界面提供的动作确认更新的是服务器的机器而不只是你正在使用的设备——这是最常被忽略的一步对于命令行服务器停止它然后用提示中显示的精确版本重新启动例如npx t3exact-version serve。后台服务相关的故障排查可先运行t3 service status查看日志路径与状态问题如linger-disabled、service-disabled、service-stopped等具体处理方式见 background services 的 Troubleshooting 章节T3 Connect 登录后的连接故障参见 remote-access.md。七、移动端更新移动端走常规渠道按 App Store 或 Google Play 的惯例安装发行版更新即可。T3 Code 移动应用还支持后台下载更新并在下次离开应用时应用重启前会先保存草稿drafts与排队消息queued messages避免更新造成状态丢失如果你长时间保持应用在前台它可能会询问是否立即安装选择Later会将更新排队留待下一个合适的时机下次进入后台时自动安装。移动端的这一机制实现在 apps/mobile/src/features/updates/app-updates.ts 中基于 expo-updates默认applyMode: background更新下载完成后在下一次进入后台时静默安装onNextBackground触发applyDeferredAppUpdateInstall。之所以选后台时机是因为重启过程中原生界面仍挂载是 expo-updates 最易崩溃的时刻——后台没有渲染内容拆除过程对用户不可见重启前调用flushPendingWrites落盘 composer 草稿与 thread outbox写失败时自动更新会中止flush-failed而不是冒着丢失未保存状态的风险重启前台停留超过 30 分钟DEFERRED_INSTALL_PROMPT_AFTER_MS 30 * 60 * 1000仍无后台机会时弹出确认框询问立即安装还是稍后对应界面中的Install Now / Later选择 Later 保持后台安装挂起回滚指令eas update:rollback会绕过提示与延迟立即应用以尽快拉回损坏的 bundle应用常驻内存数天仅启动时检查不够因此每次前台恢复且距上次后台超过 15 分钟FOREGROUND_APP_UPDATE_RECHECK_AFTER_MS时会重新检查。八、更新流程速查场景操作提示指向后台服务在宿主机运行npx t3client-version service update提示指向桌面应用在运行服务器的机器更新桌面应用必要时重新打开提示给出复制命令停止前台 CLI 服务器用复制命令含serve、--host等选项重启更新前保护会话开启 Settings → General → Continue threads after restarts先更新旧服务器更新失败重试一次 → 确认更新的是服务器机器 → 用精确版本重启命令行服务器移动端商店常规更新应用内可后台下载、离开应用时自动安装Later排队自包含构建升级宿主机上t3 update可加--channel、--yes、--allow-downgrade一句话总结先看提示指向哪台机器再按其服务器运行形态后台服务 / 桌面应用 / 前台 CLI选择对应动作保持客户端打开直到重连确认更新失败时优先检查是否更新对了机器。更底层的服务生命周期管理可继续阅读 background services 与 server updates 内部机制。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考