TREK 插件管理管理员一次装对、更得放心、删得干净的操作手册【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREK如果你要在一台自托管的 TREK 实例上装第三方插件又怕装出问题这篇就是为你写的按找到 → 审查 → 激活 → 更新 → 移除的真实操作路径把 Admin → Plugins 面板管理员插件面板配置里每一步会触发什么、会被什么拦住讲清楚顺带把隔离与审计的边界说透。装之前管理员身份和运行时总开关打开面板前有两道硬门槛。第一你是管理员——服务端所有插件路由同时挂在JwtAuthGuard和AdminGuard之下见 plugins.controller.ts普通账号连面板都进不去。第二插件运行时得是开的。运行时由TREK_PLUGINS_ENABLED控制默认开启kill-switch.ts 里的逻辑是取值只有是false、0、off、no大小写不敏感才算关其余一律算开且每次调用时实时读取环境变量改完重启服务立即生效。要特别分清一件事运行时开着 ≠ 插件在运行。所有已安装插件默认处于关闭状态必须逐个手动激活激活之前没有任何第三方代码执行。运行时被关掉时面板顶部会提示The plugin runtime is turned off. No plugin can run until an admin enables it.已安装插件仍留在磁盘上停用、无害总开关重新打开即可恢复。插件相关的环境变量一共四个变量作用TREK_PLUGINS_ENABLED插件系统总开关默认开启只有false/0/off/no才关闭TREK_PLUGINS_DEV_LINK仅当值恰为1时Link a local plugin 入口才出现开发链接见后文旁路一节TREK_PLUGIN_ALLOW_PRIVATE_EGRESS设为on才允许插件出口访问私网地址如localhost默认拒绝私网出口且会放宽所有已装插件的私网策略只在信任全部插件时开TREK_PLUGIN_REGISTRY_URL覆盖 Discover 视图的注册表索引地址可指向自建的 fork 或镜像两个视图里Rescan 到底做了什么面板顶部的分段切换器只有两个视图Installed——本实例已安装的插件带数量统计额外提供Status筛选Active / Off / Update available / Error。Discover——社区注册表以卡片浏览每张卡片带图标、作者、类型、Reviewed/Signed / Unsigned徽章、最新版本与下载量。两个视图共享同一套工具栏Search plugins…搜索、Type筛选Widget / Page / Integration / Trip page、Sort、Upload plugin以及Rescan。Rescan 值得单独说它同时做两件事——重新扫描磁盘上的本地插件并强制拉取远程注册表绕过 30 分钟的服务器缓存和 GitHub CDN。为什么要绕缓存注册表索引的缓存 TTL 是 30 分钟CACHE_TTL 30 * 60 * 1000见 registry.service.ts不点 Rescan 的话刚发布的插件最长要等约半小时才会出现。拉取的是聚合的dist/index.json而不是逐个调 GitHub API避免速率限制且注册表请求失败时软降级——面板照常能用只是 Discover 列表不刷新。安装三步以及版本不兼容时的降级注册表安装固定三步切到Discover点中一张插件卡片。阅读弹出的预安装审查对话框下一节。点Install。版本兼容有自动降级逻辑服务端用hostSatisfies对比 manifest 声明的trek版本范围与当前宿主版本见 host-compat.ts最新版本要求比你的 TREK 更新但存在仍兼容的旧版本 → 按钮变成Install {version}装那个兼容版本所有版本都不兼容 → 按钮变成Incompatible且禁用。两种情况对话框都会用琥珀色提示条把原因写在明面上不会藏在 tooltip 里。另外记住安装流程只做下载、校验、安全解压、重新校验 manifest、以 inactive 注册不执行任何内容装完就是关闭状态——安装不等于运行这个原则贯穿全文后面的更新、旁路加载都遵守它。审查对话框里读哪四类信息What it can access——请求的权限逐条平实翻译如 Read the trips…未识别的权限代码原样展示不请求权限则显示Needs no special access.Connects to——manifest 声明的全部可访问出口主机等宽字体 chip。Setup——插件会向你或每个用户要的配置项标注Instance-wide/Per user必要时标Required。Details——版本、体积、所需 TREK 版本范围、审查时间、总下载量。关键一点这些内容不是作者写的介绍文字。服务端会在插件的审查提交点拉取实时 manifest 生成预览ManifestPreview权限列表、出口主机、operatorEgress标记、设置字段都来自这份预览。对话框底部另有 Source repository、Report an issue、Homepage 三个链接。自托管服务插件Allowed hosts有一类插件要连只有你自己知道地址的服务自托管的 Gotify、ntfy 之类。这类插件的 manifest 声明operatorEgress审查对话框会多一个 hosts you addchip并提示This plugin talks to a service only you can name. After installing, add the hosts it may reach under ⋯ → Allowed hosts. It can reach no others.安装后在插件行的⋯ → Allowed hosts逐个添加主机名。三个必须知道的点保存后会重启插件让新白名单生效。运行中插件的出口守卫在子进程初始化时一次性安装、且拒绝二次init所以白名单无法热扩容唯一办法就是重新拉起子进程plugin-runtime.service.ts 中有明确注释。添加第一个主机之前插件行挂着琥珀色Add allowed hostchip——此时它一个主机也够不到不提示会像静默故障有了主机后 chip 变蓝并显示数量。主机名校验与 manifest 出口声明同一套规则裸*、整 TLD 通配、带协议前缀一律拒绝。边界同样硬未声明operatorEgress的插件永远拿不到任何主机——安装时你同意的范围就是硬边界只有管理员能添加主机普通用户即使凭据是自己提供的也不行服务若和 TREK 同机或在同一局域网还得先设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon该变量的全局放宽性质见上文表格。激活与停用装好了却不运行怎么办每行插件有一个Enable plugin开关行首的彩色圆点反映运行时健康绿 active、蓝闪 starting、红 error、淡 inactive、琥珀 disabled/incompatible。启用被拒时原因都是结构化的每种都给了明确的补救路径错误码定义在 plugin-runtime.service.ts 中服务端按版本兼容 → 权限再同意 → 必需 addon → 插件依赖的顺序做只读预检任何一项不满足都不会留下半激活状态ADDON_DISABLED必需的 addon 没开。toast 会报 addon 名称去 Admin → Addons 打开后重试。DEPENDENCY_MISSING插件依赖缺失或版本过旧。对话框逐条列出每个依赖提供一键Download / Update装好最新兼容版本后自动重试启用。TREK_VERSION_INCOMPATIBLE/TREK_VERSION_UNKNOWN当前 TREK 版本不在插件声明的支持范围内或插件压根没声明。还有两条级联规则都是自动的你只需知道结果启用一个插件前按依赖图算出enableOrder依赖先起、目标后起已被停用的依赖会被自动级联启用toast 告诉你哪些被顺带打开了。反过来某个 addon 被关掉时依赖它的插件自动停用deactivateForDisabledAddon并且传递停用所有依赖它的插件同理停用某插件也会级联停用依赖它的插件——一个插件不能在依赖缺失时继续跑。每行的⋯菜单里Restart仅活动插件、View error log、Allowed hosts、Source repository / Report an issue仅注册表来源、Delete。更新被挡住时先分清是权限还是密钥列表上方出现 {count} updates available for your plugins. 时可以点Update all批量处理或在单行点Update → v{version}。服务端update()会先算权限差集无新增权限、无新增出口主机 → 透明重启到新代码无感知有任何新增 → 新代码装上但插件保持关闭行上显示{name} v{version} is asking for rights you havent granted yet. The new version is installed but stays off until you approve it.对话框列出Newly requested permissions与New outbound connections由你选Approve turn on或Keep off for now。批量更新时这些同意提示排队逐个出现不会跳过一个若被同意的新版本未签名对话框会额外说明没有任何机制把这个版本与其作者绑定。另外resolveUpdateTarget选的是当前 TREK 能运行的最新版本而不是盲目取最新版——避免新版放弃支持当前宿主时把正在正常工作的插件更新坏。签名密钥轮换唯一可以覆盖的情形作者的签名密钥与安装时钉住的密钥TOFU 首装信任不再匹配时更新被拒行上显示Update blocked — {reason}和Review链接。对话框并排展示钉住的密钥指纹与当前提供的密钥指纹并提醒TREK cannot tell a legitimate key rotation apart from a takeover. Confirm the new key with the author through a channel you already trust before you accept it.覆盖的边界必须记牢只有SIGNATURE_KEY_CHANGED密钥轮换可以被覆盖入口是Trust the new key update签名无效SIGNATURE_INVALID、缺失SIGNATURE_MISSING、半声明SIGNATURE_INCOMPLETE三种情形面板只给解释没有任何覆盖按钮——服务端 signature-status.ts 只把SIGNATURE_KEY_CHANGED列为RETRUSTABLE_CODE其余情形 API 也拒绝。retrust 端点还要求你回显对话框中展示的完整公钥指纹仅供肉眼比对太弱服务端用assertRetrustable重新推导条件防止对话框渲染后注册表条目又被换钥重信任与更新在同一次调用内完成要么一起成功要么什么都不变不存在钉住未验证密钥的中间窗口。卸载时删到什么程度⋯ → Delete的确认文案是This stops the plugin, removes its code, and deletes all of its data. This cannot be undone.卸载uninstall见 plugin-runtime.service.ts依次做停止插件进程 → 移除代码目录 → 删掉plugins注册表行与设置字段。deleteDatatrue时再清插件数据目录、错误日志、实体元数据、每用户配置含加密密钥、OAuth 令牌与状态、迁移台账、能力审计日志以及待处理的 GDPR 擦除队列。出口主机与定时任务无条件删除选保留数据也照删——否则将来复用同一个 id 的插件会悄悄继承这些权限但如果你选择保留数据那些待处理的用户数据擦除义务会跟着保留等同 id 插件重装后继续兑现。旁路加载Upload 与 Dev-Link 的差别不经过注册表装插件有两条路面板上用Sideloaded/Dev-Link徽章区分Upload plugin——工具栏按钮或直接把.zip拖进面板。归档解压到 staging 后走与注册表安装相同的硬防护防 zip-slip / zip-bomb 的安全解压、严格 manifest 校验、拒绝原生二进制唯一不做的是 SHA-256 与签名校验没有注册表条目可对照。上传上限 50 MBMAX_UPLOAD_BYTES 50 * 1024 * 1024 4096。用相同 id 覆盖上传时旧代码先被强制停止并停用绝不允许代码换了、旧版本还在跑。Link a local plugin——一个路径输入框把本地构建目录注册为插件并对真实数据热重载。仅开发用途只有服务端设了TREK_PLUGINS_DEV_LINK1入口才出现。link()对代码目录做符号链接不复制校验 manifest、拒绝原生二进制、注册为 inactive并用fs.watch盯构建输出重建后防抖 400 ms 自动重新 fork。对这两条路要诚实徽章只是来源标签不带来任何额外检查、不同沙箱或额外限制——旁路插件以它声明的权限原样运行和注册表插件同权只是没有恶意软件扫描、没有签名。徽章的唯一作用是让你一眼看出除了你自己没有人为这份代码背书。徽章到底担保什么以及权限审计Discover 卡片和插件行上的徽章各有精确含义别高估Reviewed——TREK 维护者对每一个版本做了恶意软件扫描。它不担保质量不担保能用更不是无害证明。Signed——文件已对照作者签名密钥校验且该密钥在首装时被钉住TOFU校验和证明文件是注册表担保的字节签名进一步证明这些字节来自作者。Unsigned——文件与注册表担保的字节一致但没有东西把它绑定到作者。注册表里大多数插件目前未签名所以这是琥珀色提示不是警报。再说一次徽章都不说明代码在干什么。权限清单和出口主机才说明安装前务必读完。隔离层面已批准的权限列表是真实边界而不是标签每个活动插件跑在独立 OS 子进程里由 Node 权限模型--permission拉起文件系统读取限定在自己的代码目录JWT_SECRET、数据库连接等 TREK 机密对它物理不可达不能开trek.db、写文件、派生子进程、用 worker 线程或加载原生模块自有数据放在独立 SQLite 文件里只能经由 TREK 访问与宿主的唯一通道是内部 RPC未授予的调用被拒绝而非忽略RPC 通道本身也是封死的——原始 IPC 原语process.send、process.on(message)在插件代码加载前就被吊销既不能伪造宿主消息也不能窃听在途请求页面/组件界面跑在密封的浏览器 frame 里读不到会话 cookie也够不到外围 TREK 页面插件崩溃、挂起、内存耗尽死的只有它自己的进程TREK 继续运行并可重启或停用它。但边界只约束能触及什么不约束授权范围内的意图一个被允许读行程、又允许连某主机的插件完全可能把行程数据发过去。这就是为什么审查对话框里权限与出口主机必须一起读。审计上任何用户都能在Settings → Plugins的活动日志里看到插件以自己名义执行的每个操作——读过的行程与费用、写过的地点、宿主代发的每次出站调用。这个视图不设管理员门槛管理员在 Admin → Plugins 看到的是按插件维度的同一份哈希链防篡改数据。更多权限细节可查 wiki/Plugin-Permissions.md。【免费下载链接】TREKA self-hosted travel/trip planner with real-time collaboration, interactive maps, PWA support, SSO, budgets, packing lists, and more.项目地址: https://gitcode.com/GitHub_Trending/nomad22/TREK创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考