T3 Code 后台服务完全指南systemd/launchd 服务化安装、更新与故障排查【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code本文面向需要在 Linux 或 macOS 上以“无人值守”方式长期运行 T3 Code 服务器无需保持终端打开、支持 T3 Connect 远程访问的用户与运维人员。你将掌握t3 service install / status / update / uninstall全套生命周期管理命令、自包含 CLI 的安装脚本与环境变量、Linux systemd 与 macOS launchd 两种服务管理器的底层机制以及从linger-disabled到 Full Disk Access 的一线故障排查方案。为什么需要后台服务T3 Code 的服务器server承载 agent 会话、终端命令、远程客户端连接等运行时负载。默认情况下服务器随你启动它的终端一起存在——关掉终端或 SSH 会话退出服务随之停止。将 T3 Code 安装为当前用户的系统服务后进程由系统服务管理器Linux 的 systemd user manager、macOS 的 launchd托管具备自动启动、崩溃重启、随登录/开机恢复的能力从而实现关闭终端、注销登录后服务依然在线通过 T3 Connect 随时远程接入无需保持终端服务器崩溃后由服务管理器自动拉起Restartalways/KeepAlive。注意Windows 不支持后台服务这是平台能力限制而非配置问题。服务生命周期管理命令在承载 T3 Code 的机器上执行以下命令命令定义见 apps/server/src/cli/service.ts 中serviceCommand的四个子命令任务命令安装并启动npx t3latest service install查看状态与日志位置npx t3latest service status更新或修复npx t3latest service update停止并从开机启动中移除npx t3latest service uninstall卸载不影响数据service uninstall只停止并移除服务单元你的项目、线程threads与设置都保存在 T3 home默认~/.t3下原样保留。版本语义用哪个 CLI 就用哪个版本的服务install与update使用的都是当前调用的这个 CLI 的版本。例如要装 nightly就运行npx t3nightly service update要把版本钉死把nightly替换成精确版本号即可。源码层面reconcileService 与BootServiceDowngradeRefusedErrorbootService.ts共同保证了降级保护较旧的 CLI 默认拒绝替换较新的服务除非显式传入--allow-downgrade。测试用例 service.test.ts 验证了install/update两个命令在遇到“更新的已装服务”时都会在改动任何文件之前直接拒绝并且传入--allow-downgrade后才允许继续。更新会重启服务器service update以及t3 update触发的服务更新会重启服务器进程。请先完成正在进行的 agent 任务并等待任何已在进行的远程更新结束——源码中BootServiceUpdatePendingErrorbootService.ts会在服务状态文件标记为 pending 更新时拒绝继续操作。若需与远程客户端版本对齐参见 Updating T3 Code。自包含构建无 Node 机器上的安装路径默认的npx t3...走 npm要求机器上有 Node.js/npm。而自包含self-contained构建以 GitHub Release 归档形式分发安装脚本只依赖sh、tar、sha256sum/shasum与curl/wget不需要 Node.js 或 npm见 scripts/install.sh 头部注释Windows 版 scripts/install.ps1 仅需 PowerShell 5.1。在无 Node 的机器上先安装 CLIcurl -fsSL https://t3.codes/install.sh | shWindows 在 PowerShell 中执行irm https://t3.codes/install.ps1 | iex脚本会把t3放到~/.local/binWindows 为~\.local\bin生成t3.cmdshim并解压归档到$T3CODE_HOME/runtime/versions/version——这与t3 service install使用的目录布局完全一致因此后续运行t3 service install时会复用这次下载不会重复拉取install.sh 第 15-17 行注释明确说明这一点install.ps1 第 14-15 行同理。安装脚本环境变量环境变量作用默认值T3CODE_CHANNEL跟随的发布轨道stable、nightly或previewstableT3CODE_VERSION精确版本号设置后覆盖T3CODE_CHANNEL的自动解析无T3CODE_HOMET3 home 目录~/.t3Windows~\.t3T3CODE_INSTALL_BIN_DIRt3可执行链接所在目录~/.local/binWindows~\.local\binT3CODE_RELEASE_BASE_URLRelease 下载镜像地址GitHub releases/download轨道解析逻辑install.sh 第 67-95 行按 channel 匹配 tagstable 只匹配纯vsemvernightly/preview 匹配带对应预发布标识的 tag因此stable 安装永远不会意外装到 nightly 或 preview 构建。脚本还会校验归档的 SHA256 校验和并在落盘前运行t3 --version验证可执行性。preview 轨道维护者的专用测试轨preview是第三个轨道由维护者从未发布分支手动切出用于演练发布流水线。这些构建可能损坏、不提供修复、永远不会作为更新被推送安装器和t3 update只有在显式要求该 channel 时才会进入 preview且会给出警告。install.sh 在用户未显式设置T3CODE_CHANNELpreview或T3CODE_VERSION时直接拒绝安装 preview 构建第 91-93 行t3 update侧则由 update.ts 实现——非交互脚本会被直接拒绝交互终端必须显式确认。自包含 CLI 的更新t3 update装好自包含t3后t3 update可以在无 npm 的情况下把机器切到更新版本它下载当前t3所属轨道上的最新 Release验证后重新指向t3启动器POSIX 下重写~/.local/bin/t3软链接Windows 下重写t3.cmdshim见 repointLauncher。当同一 T3 home 下安装了后台服务时t3 update会先询问是否重启服务——因为重启会中断正在运行的 agent 回合、终端与远程客户端回答no服务保持旧版本直到你之后运行t3 service update从脚本调用没有交互提示需显式传--yes才会重启服务手动启动的服务器永远不会被触碰命令会提示它仍在旧版本上由你自行重启update.ts 中findForegroundServer通过服务托管状态与进程血缘区分前台/服务进程。常用变体t3 update # 跟随当前轨道的最新版 t3 update 0.0.41-preview.20260912.1595 # 钉到精确版本 t3 update --channel nightly # 切换轨道进入 preview 需确认 t3 update --allow-downgrade # 允许回退到更旧版本关于跨轨道切换的降级保护t3 update会对比目标版本与“可执行文件版本 已装服务版本”中较新者只有显式--allow-downgrade才允许回退update.ts。t3 uninstall完整移除t3 uninstall是安装脚本的逆操作先展示将要移除的内容后台服务、t3启动器、~/.t3/runtime下下载的每个版本确认一次后删除。你的项目、线程与设置保存在~/.t3/userdata下会被保留如需一并清除请自行删除该目录。脚本场景传入--yes跳过确认。平台支持细节Linuxsystemd 用户服务Linux 依赖systemd user services。安装流程会启用 lingeringlinger使 T3 Code 在开机时启动、注销后继续运行。若启用 linger 需要管理员权限安装程序会在改动服务之前打印一条恢复命令。安装后生成的服务单元位于~/.config/systemd/user/t3code.service。从源码 renderBootServiceUnit 可以看到几个关键设计RestartalwaysRestartSec5、StartLimitIntervalSec300/StartLimitBurst5崩溃后自动重启并限流防死循环OOMPolicycontinueagent 工具调用是服务器的子进程若某个子进程被 OOM 击杀默认策略会连带停止整个单元因此显式设置为 continue仅靠Restartalways兜底主进程KillModemixed优雅关闭超时后 systemd 对 cgroup 整体 SIGKILL标准输出/错误以 append 方式写入~/.t3/userdata/logs/boot-service.logWorkingDirectory%h、单元内以EnvironmentT3CODE_HOME...显式注入 T3 home单元文件不能依赖用户 shell 的 PATH。macOSlaunchd LaunchAgentmacOS 在登录时启动服务、注销时停止。如需无人值守的远程访问请保持 Mac 登录并保持唤醒状态。通过 SSH 在无人登录屏幕的 Mac 上安装最后一步启动可能失败——但服务仍然装好了会在下次登录时启动。生成的 plist 位于~/Library/LaunchAgents/com.t3tools.t3code.service.plistcom.t3tools.t3code.service标签刻意区别于桌面应用的 bundle id避免 launchd 与 TCC 记录冲突见 bootService.ts。renderBootServicePlist 展示了与 systemd 单元对等的语义RunAtLoad登录即载入、KeepAliveThrottleInterval5对应 Restartalways、ExitTimeOut90对应 TimeoutStopSec 优雅关闭窗口、ProcessTypeInteractive退出后台任务资源节流。启动/停止通过launchctl bootstrap/launchctl bootout --wait完成launchdManager。T3 Connect 的关系T3 Connect 在引导流程中可能主动提供后台服务安装但两者独立管理退出登录 T3 Connect 不会停止或卸载该服务。这也解释了为什么要显式运行t3 service uninstall才能真正移除服务。故障排查第一步t3 service status在宿主机上运行t3 service status。它会打印日志路径在 Linux 上还会检查已装服务是否正在运行、是否已启用enable、是否允许存活到注销之后。输出格式由 formatServiceStatus 生成包含Unit:、Logs:、问题标记以及下一步修复命令当已装服务比当前 CLI 更新时它会建议使用匹配版本npx t3installedVersion service update修复而不是盲推t3latest测试 service.test.ts 覆盖了这些场景。SSH 断开后服务停止启用 lingering若服务在 SSH 会话关闭时停止检查状态输出中是否有linger-disabled。管理员可执行sudo loginctl enable-linger $(id -un)通过 SSH 执行时允许 sudo 弹出提示ssh -t your-server sudo loginctl enable-linger $(id -un)然后以普通用户身份重试服务安装。注意只用 sudo 运行loginctl这一条命令以 root 运行 T3 Code 会创建一套独立的安装和 Connect 身份。若没有管理员权限请在终端中运行t3 serve并保持该会话打开。状态问题速查表状态问题下一步linger-unavailable运行loginctl show-user $(id -un) --propertyLinger确认 systemd-logind 可用user-manager-unavailable在服务用户的登录会话中运行systemctl --user status检查发行版的 systemd 用户会话支持service-disabled或service-stopped阅读日志并查看systemctl --user status t3code.service然后使用 T3 Code 打印的修复命令上述问题码由 bootService.ts 定义并格式化——安装前的requireSystemdPrerequisites会依次探测systemctl --user show-environment与loginctl show-user ... --propertyLinger任何不可用问题都会在改动服务前以BootServicePrerequisiteError报出保证不会留下半截安装或打断正在运行的服务器。macOS 专项服务不再随登录启动时检查系统设置 → 通用 → 登录项若 agent 工作无法访问桌面、文档或下载目录可能需要为~/Library/LaunchAgents/com.t3tools.t3code.service.plist中ProgramArguments里列出的 Node 可执行文件授予完全磁盘访问权限Full Disk Access。T3 Connect 登录后失败登录 T3 Connect 之后发生的失败参见 连接故障排查。服务状态机与版本校验的底层原理t3 service status判定服务是否“current”并非只看进程在不在而是综合验证以下全部条件bootService.ts单元文件逐字节比对磁盘上的 systemd unit / plist 与当前 CLI 版本渲染出的内容完全一致launchd 忽略 PATH 字段差异运行时存在且版本匹配runtime/versions/version的入口文件与哨兵文件sentinel记录的版本等于 CLI 版本状态文件一致~/.t3/runtime/service-state.jsonSERVICE_STATE_FILE中的activeVersion等于 CLI 版本且没有 pending 更新systemd 问题集为空linger、用户管理器、enable、active 全部正常。状态文件serviceProtocol.ts记录了 launcher 协议版本、活动版本与可选的更新记录pending/committed/rolled-back/failed其中精确版本校验isExactServiceVersion仅接受完整 SemVer不接受 dist-tag 或范围与语义化版本比较compareExactServiceVersions忽略 build metadata共同支撑了降级保护与远程更新回滚的可靠性。单元内通过ExecStartruntime __service-launcher调用运行时内嵌的 launcher 子命令bootService.ts使机器端完全无需 Node 运行时。推荐工作流小结无 Node 机器先curl -fsSL https://t3.codes/install.sh | sh装 CLI或 PowerShell 的irm https://t3.codes/install.ps1 | iex再t3 service install日常检查t3 service status查看状态、问题码与日志路径~/.t3/userdata/logs/boot-service.log升级先完成正在跑的 agent 任务再npx t3目标版本 service update或在自包含环境t3 update按需--yes降级/换轨显式加--allow-downgrade进入 preview 需额外确认彻底移除t3 uninstall清掉服务、启动器与下载的运行时~/.t3/userdata下的项目数据保留。相关阅读Updating T3 Code、T3 Connect 与远程接入。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
