拓冰网站定制 
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你在生产实例上点下第一个 Install 按钮之前的那 30 秒就是TREK 插件管理真正的起点。装一个第三方插件看似无害——可它能读取你的行程、出站连接某个主机甚至把数据发到外部。本篇不照念文档而是先帮你建立判断力再落到每一步操作。先建立心智模型TREK 插件管理的三层信任 很多人一上来就问这个插件安全吗。更该先问的是谁在为它背书背书又只覆盖到哪一步TREK 的信任是一条递进链每一层只补齐前一层没覆盖的缺口。信任层它保证什么它不保证什么注册表背书Reviewed每个版本都过恶意软件扫描质量、可用性、无害作者签名Signed这些字节确实来自作者密钥被钉住代码具体做了什么你的批准权限 出口你同意的范围是硬边界授权范围内的意图关键点前两层是标签第三层才是你亲手划的线。Reviewed 不等于无害Signed 不等于安全——它们只回答从哪来不回答做什么。真正的边界是你批准的权限清单与出口主机详见 wiki/Plugins.md。开工前检查清单动手装任何东西前先把这几个环境变量核对一遍。它们决定了面板是否可用、插件能跑成什么样。变量作用默认值何时需要动它TREK_PLUGINS_ENABLED插件系统总开关开启想一键关停全部第三方代码时TREK_PLUGINS_DEV_LINK允许本地目录注册 热重载关闭仅本地开发且值恰为1TREK_PLUGIN_ALLOW_PRIVATE_EGRESS允许插件出口访问私网 / LAN关闭自托管服务与 TREK 同机或同局域网TREK_PLUGIN_REGISTRY_URL覆盖注册表索引地址官方注册表想指向自己 fork / 镜像总开关的判定非常直接见 kill-switch.tsconst v (process.env.TREK_PLUGINS_ENABLED || ).trim().toLowerCase(); return ![false, 0, off, no].includes(v);只要取值不是false/0/off/no大小写不敏感即开启且每次调用实时读取——改完环境变量重启立即生效。注意区分运行时开启与运行某个插件前者只是让面板可用所有已安装插件仍要逐个手动激活激活前没有任何第三方代码执行。⚠️ 把TREK_PLUGIN_ALLOW_PRIVATE_EGRESS设为on会放宽所有已安装插件的私网出口策略。只有当你信任全部插件时才该开启否则一个插件就能打到你内网的任意服务。获取插件的三条路 面板顶部用分段切换器在Installed与Discover间切换。你拿到插件的方式其实只有三条先看懂差异再选路径来源校验强度适用场景行上徽章注册表安装社区注册表SHA-256 签名 审查生产首选Reviewed/Signed/Unsigned上传旁路本地.zip安全解压 manifest 校验无 SHA/签名内部 / 私有插件Sideloaded本地开发链接构建目录manifest 校验无扫描/签名开发调试Dev-Link三条路最终都落到同一套激活逻辑区别只在信任来源注册表安装走 Discover 卡片 → 预安装审查 →Install。服务端先做版本兼容校验见 host-compat.ts装完默认off只下载、校验、解压、注册不执行任何代码。上传旁路工具栏Upload plugin或直接把.zip拖进面板。归档保持 inactive激活时仍需同意权限。它没有 SHA-256/签名校验因为没有注册表条目但仍过防 zip-slip/炸弹的安全解压、严格 manifest 校验、拒绝原生二进制上限 50 MB。本地开发链接一个路径输入框仅当TREK_PLUGINS_DEV_LINK恰为1时该入口才出现。服务端对代码目录建软链不复制并监听构建输出重建后防抖 400ms 自动重新 fork适合对着真实数据调试。旁路 / dev-link 的插件以它声明的权限原样运行与注册表插件完全一样但没有恶意软件扫描、没有签名。Sideloaded / Dev-Link 徽章只是提醒你除了你没人为此代码背书。从下载到运行启用链路上的每一步点Install后先别急着开。安装前会弹出预安装审查对话框四块信息必须逐块看完What it can access——逐条用平实语言渲染权限如Read the trips…不请求任何权限则显示Needs no special access.Connects to——manifest 声明的所有可访问主机等宽字体 chip 展示。Setup——将要求你或每个用户填写的设置项标注Instance-wide / Per user必要时Required。Details——版本、体积、所需 TREK 版本范围、审查时间、总下载量。这些信息来自服务端在审查提交点拉取的实时ManifestPreview不是插件作者自己写的介绍文字见 registry.service.ts。装完默认off。手动启用时可能撞上三类拒绝每种都有明确补救路径拒绝原因补救必需 addon 未启用ADDON_DISABLED到 Admin → Addons 开启后重试插件依赖缺失 / 版本过旧DEPENDENCY_MISSING对话框逐条列出一键Download / Update后自动重试TREK 版本不兼容TREK_VERSION_*等宿主升级或选兼容旧版本启用一个插件前会先按依赖图算出激活顺序先把所有依赖拉起来再拉起目标已安装但停用的依赖会被自动级联启用并 toast 告知你哪些被顺带打开了。整个预检是只读的任何一项不满足都不会留下半激活状态见 plugin-runtime.service.ts。有一类插件要访问只有你知道地址的自托管服务Gotify、ntfy 等。它无法预知主机名因此声明operatorEgress审查框会多出 hosts you addchip 和提示。装完打开该行⋯ → Allowed hosts逐个加主机名——加满至少一个主机前该行显示琥珀色 Add allowed host chip因为它此刻一个主机也碰不到。保存 Allowed hosts 会重启插件让它加载新出口白名单。运行中插件的白名单永远不能在原进程内热扩容出口守卫在子进程初始化时只装一次并拒绝二次 init唯一让新列表生效的方式就是重拉子进程。删除某主机后它立即失去该出口并再次重启。两个硬边界要记住未声明operatorEgress的插件永远无法被授予主机只有管理员能加主机普通用户即使凭据是自备的也不能扩大出口。让插件保持健康更新、签名与密钥轮换有更新时插件行出现Update → v{version}按钮列表上方提示{count} updates available与Update all。核心原则是更新绝不静默扩权。若新版本没申请新权限 → 透明重启到新代码。若申请了新权限 / 新出口 → TREK 先装新代码但保持关闭弹出同意框让你选Approve turn on或Keep off for now。批量更新时这些同意提示排队依次出现一个不跳。若被同意的新版本未签名会额外说明没有任何机制把它与作者绑定。resolveUpdateTarget还会挑当前 TREK 能跑的最新版本而非简单取最新避免新版本放弃支持当前宿主时把能用的插件更新坏。被阻塞的更新密钥轮换若作者的签名密钥与安装时钉住的不再匹配更新被拒行上显示Update blocked — {reason}与Review链接对话框并排展示钉住的密钥指纹与当前提供的密钥指纹TREK 分不清合法的密钥轮换和接管——从这里看两者一模一样。接受新密钥前先通过你已信任的渠道向作者确认。覆盖的边界很关键只有密钥变更可覆盖Trust the new key update按钮。签名无效、缺失或半声明只给解释没有任何覆盖按钮——服务端同样拒。/retrust端点强制这一范围见 plugins.controller.ts 与assertRetrustable只有SIGNATURE_KEY_CHANGED才允许覆盖且调用方必须回显对话框里的完整公钥防止对话框渲染后注册表条目又被换钥。重信任与更新在同一调用内完成——要么新密钥通过校验、插件落到新版本并钉住新密钥要么什么都不变杜绝钉住未验证密钥的窗口。安全撤离卸载会带走什么⋯ → Delete弹确认框This stops the plugin, removes its code, and deletes all of its data. This cannot be undone.卸载uninstall做的事停止插件进程。移除代码目录。删除plugins注册表行与设置字段。deleteDatatrue时再清插件自有数据目录、错误日志、实体元数据、每用户配置含加密密钥、OAuth 令牌与状态、迁移台账、能力审计日志、待处理的 GDPR 擦除队列。出口主机与定时任务无条件删除。原因只有一个否则之后复用同一 id 的插件会悄悄继承前人的出口权限与任务。若卸载时选择保留数据待处理的用户数据擦除义务也会保留等同 id 插件重装后继续兑现。知其所以然隔离模型到底挡住了什么隔离是这套系统真正的底气它决定了权限是真实边界而非标签每个活动插件跑在独立 OS 子进程里用 Node 权限模型--permission启动文件系统读取限定在自己代码目录。插件物理不可达JWT_SECRET、数据库连接或任何 TREK 机密。不能打开trek.db、写文件、派生子进程、用 worker 线程或加载原生模块自有数据在独立 SQLite 里且只能由 TREK 访问。只通过内部 RPC 通道与 TREK 通信未授予的调用被拒绝而非忽略。RPC 通道对插件代码封死即便跑在 fork 进程原始 IPC 原语process.send、process.on(message)也在其代码加载前被吊销既不能伪造宿主消息也不能窃听在途请求。界面跑在密封的浏览器 frame里读不到会话 cookie碰不到外围 TREK 页面。崩溃 / 挂起 / 内存耗尽时只有它自己的进程死TREK 继续运行并可重启或停用它。但边界必须点破权限约束的是它能触及什么不约束它在授权范围内想干什么。一个被允许读行程且能连某主机的插件完全可能把行程数据发过去。所以先读权限清单和出口主机再决定装。看得见的操作审计与可见性插件做了什么是可追溯的且不设管理员门槛每个用户都能在Settings → Plugins的活动日志里看到插件以其名义执行的全部操作——读过的行程/费用、写入的地点、TREK 代发的每次出站调用。这是基于哈希链的防篡改审计的用户侧。管理员在Admin → Plugins看到按插件维度的视图。端点侧同样收紧所有路由挂在Controller(api/admin/plugins)同时套JwtAuthGuardAdminGuarddev-link 再叠一层TREK_PLUGINS_DEV_LINK要求。运行时关闭时install、upload、activate、update、rescan等统一返回 503——面板不可用是有明确语义的不是静默失败。常见问题速查现象大概率原因怎么办安装按钮变Incompatible无兼容版本等 TREK 升级或选仍兼容的旧版按钮变Install {version}最新版要更新的 TREK但有兼容旧版直接装那个旧版行上显示Update blocked签名密钥变更走 Review → 回显完整公钥 → 重信任更新装了没反应 Add allowed hostchipoperatorEgress插件还没加主机加至少一个 Allowed hosts私网自托管服务连不上默认拒绝私网出口确认信任全部插件后设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon想移除但保留数据卸载默认删数据卸载时选保留数据擦除义务留待重装面板显示Plugins are disabledTREK_PLUGINS_ENABLED被关闭恢复开启并重启看不到 Link a local pluginTREK_PLUGINS_DEV_LINK非1开发环境设为1延伸阅读Plugins——插件系统全貌类型、隔离模型、依赖、活动日志Plugin-Permissions——每条权限的确切授予范围与http:outbound细节Plugin-Development——SDK 与 manifest 编写Plugin-Publishing——注册表提交流程与trek-pluginCLIAdmin-Addons——插件可能依赖的 addon 管理Environment-Variables——插件相关环境变量完整参考Security-Hardening——安全加固建议【免费下载链接】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），仅供参考 TREK 插件管理完整指南：从安装审查到签名校验与审计
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你在生产实例上点下第一个 Install 按钮之前的那 30 秒就是TREK 插件管理真正的起点。装一个第三方插件看似无害——可它能读取你的行程、出站连接某个主机甚至把数据发到外部。本篇不照念文档而是先帮你建立判断力再落到每一步操作。先建立心智模型TREK 插件管理的三层信任 很多人一上来就问这个插件安全吗。更该先问的是谁在为它背书背书又只覆盖到哪一步TREK 的信任是一条递进链每一层只补齐前一层没覆盖的缺口。信任层它保证什么它不保证什么注册表背书Reviewed每个版本都过恶意软件扫描质量、可用性、无害作者签名Signed这些字节确实来自作者密钥被钉住代码具体做了什么你的批准权限 出口你同意的范围是硬边界授权范围内的意图关键点前两层是标签第三层才是你亲手划的线。Reviewed 不等于无害Signed 不等于安全——它们只回答从哪来不回答做什么。真正的边界是你批准的权限清单与出口主机详见 wiki/Plugins.md。开工前检查清单动手装任何东西前先把这几个环境变量核对一遍。它们决定了面板是否可用、插件能跑成什么样。变量作用默认值何时需要动它TREK_PLUGINS_ENABLED插件系统总开关开启想一键关停全部第三方代码时TREK_PLUGINS_DEV_LINK允许本地目录注册 热重载关闭仅本地开发且值恰为1TREK_PLUGIN_ALLOW_PRIVATE_EGRESS允许插件出口访问私网 / LAN关闭自托管服务与 TREK 同机或同局域网TREK_PLUGIN_REGISTRY_URL覆盖注册表索引地址官方注册表想指向自己 fork / 镜像总开关的判定非常直接见 kill-switch.tsconst v (process.env.TREK_PLUGINS_ENABLED || ).trim().toLowerCase(); return ![false, 0, off, no].includes(v);只要取值不是false/0/off/no大小写不敏感即开启且每次调用实时读取——改完环境变量重启立即生效。注意区分运行时开启与运行某个插件前者只是让面板可用所有已安装插件仍要逐个手动激活激活前没有任何第三方代码执行。⚠️ 把TREK_PLUGIN_ALLOW_PRIVATE_EGRESS设为on会放宽所有已安装插件的私网出口策略。只有当你信任全部插件时才该开启否则一个插件就能打到你内网的任意服务。获取插件的三条路 面板顶部用分段切换器在Installed与Discover间切换。你拿到插件的方式其实只有三条先看懂差异再选路径来源校验强度适用场景行上徽章注册表安装社区注册表SHA-256 签名 审查生产首选Reviewed/Signed/Unsigned上传旁路本地.zip安全解压 manifest 校验无 SHA/签名内部 / 私有插件Sideloaded本地开发链接构建目录manifest 校验无扫描/签名开发调试Dev-Link三条路最终都落到同一套激活逻辑区别只在信任来源注册表安装走 Discover 卡片 → 预安装审查 →Install。服务端先做版本兼容校验见 host-compat.ts装完默认off只下载、校验、解压、注册不执行任何代码。上传旁路工具栏Upload plugin或直接把.zip拖进面板。归档保持 inactive激活时仍需同意权限。它没有 SHA-256/签名校验因为没有注册表条目但仍过防 zip-slip/炸弹的安全解压、严格 manifest 校验、拒绝原生二进制上限 50 MB。本地开发链接一个路径输入框仅当TREK_PLUGINS_DEV_LINK恰为1时该入口才出现。服务端对代码目录建软链不复制并监听构建输出重建后防抖 400ms 自动重新 fork适合对着真实数据调试。旁路 / dev-link 的插件以它声明的权限原样运行与注册表插件完全一样但没有恶意软件扫描、没有签名。Sideloaded / Dev-Link 徽章只是提醒你除了你没人为此代码背书。从下载到运行启用链路上的每一步点Install后先别急着开。安装前会弹出预安装审查对话框四块信息必须逐块看完What it can access——逐条用平实语言渲染权限如Read the trips…不请求任何权限则显示Needs no special access.Connects to——manifest 声明的所有可访问主机等宽字体 chip 展示。Setup——将要求你或每个用户填写的设置项标注Instance-wide / Per user必要时Required。Details——版本、体积、所需 TREK 版本范围、审查时间、总下载量。这些信息来自服务端在审查提交点拉取的实时ManifestPreview不是插件作者自己写的介绍文字见 registry.service.ts。装完默认off。手动启用时可能撞上三类拒绝每种都有明确补救路径拒绝原因补救必需 addon 未启用ADDON_DISABLED到 Admin → Addons 开启后重试插件依赖缺失 / 版本过旧DEPENDENCY_MISSING对话框逐条列出一键Download / Update后自动重试TREK 版本不兼容TREK_VERSION_*等宿主升级或选兼容旧版本启用一个插件前会先按依赖图算出激活顺序先把所有依赖拉起来再拉起目标已安装但停用的依赖会被自动级联启用并 toast 告知你哪些被顺带打开了。整个预检是只读的任何一项不满足都不会留下半激活状态见 plugin-runtime.service.ts。有一类插件要访问只有你知道地址的自托管服务Gotify、ntfy 等。它无法预知主机名因此声明operatorEgress审查框会多出 hosts you addchip 和提示。装完打开该行⋯ → Allowed hosts逐个加主机名——加满至少一个主机前该行显示琥珀色 Add allowed host chip因为它此刻一个主机也碰不到。保存 Allowed hosts 会重启插件让它加载新出口白名单。运行中插件的白名单永远不能在原进程内热扩容出口守卫在子进程初始化时只装一次并拒绝二次 init唯一让新列表生效的方式就是重拉子进程。删除某主机后它立即失去该出口并再次重启。两个硬边界要记住未声明operatorEgress的插件永远无法被授予主机只有管理员能加主机普通用户即使凭据是自备的也不能扩大出口。让插件保持健康更新、签名与密钥轮换有更新时插件行出现Update → v{version}按钮列表上方提示{count} updates available与Update all。核心原则是更新绝不静默扩权。若新版本没申请新权限 → 透明重启到新代码。若申请了新权限 / 新出口 → TREK 先装新代码但保持关闭弹出同意框让你选Approve turn on或Keep off for now。批量更新时这些同意提示排队依次出现一个不跳。若被同意的新版本未签名会额外说明没有任何机制把它与作者绑定。resolveUpdateTarget还会挑当前 TREK 能跑的最新版本而非简单取最新避免新版本放弃支持当前宿主时把能用的插件更新坏。被阻塞的更新密钥轮换若作者的签名密钥与安装时钉住的不再匹配更新被拒行上显示Update blocked — {reason}与Review链接对话框并排展示钉住的密钥指纹与当前提供的密钥指纹TREK 分不清合法的密钥轮换和接管——从这里看两者一模一样。接受新密钥前先通过你已信任的渠道向作者确认。覆盖的边界很关键只有密钥变更可覆盖Trust the new key update按钮。签名无效、缺失或半声明只给解释没有任何覆盖按钮——服务端同样拒。/retrust端点强制这一范围见 plugins.controller.ts 与assertRetrustable只有SIGNATURE_KEY_CHANGED才允许覆盖且调用方必须回显对话框里的完整公钥防止对话框渲染后注册表条目又被换钥。重信任与更新在同一调用内完成——要么新密钥通过校验、插件落到新版本并钉住新密钥要么什么都不变杜绝钉住未验证密钥的窗口。安全撤离卸载会带走什么⋯ → Delete弹确认框This stops the plugin, removes its code, and deletes all of its data. This cannot be undone.卸载uninstall做的事停止插件进程。移除代码目录。删除plugins注册表行与设置字段。deleteDatatrue时再清插件自有数据目录、错误日志、实体元数据、每用户配置含加密密钥、OAuth 令牌与状态、迁移台账、能力审计日志、待处理的 GDPR 擦除队列。出口主机与定时任务无条件删除。原因只有一个否则之后复用同一 id 的插件会悄悄继承前人的出口权限与任务。若卸载时选择保留数据待处理的用户数据擦除义务也会保留等同 id 插件重装后继续兑现。知其所以然隔离模型到底挡住了什么隔离是这套系统真正的底气它决定了权限是真实边界而非标签每个活动插件跑在独立 OS 子进程里用 Node 权限模型--permission启动文件系统读取限定在自己代码目录。插件物理不可达JWT_SECRET、数据库连接或任何 TREK 机密。不能打开trek.db、写文件、派生子进程、用 worker 线程或加载原生模块自有数据在独立 SQLite 里且只能由 TREK 访问。只通过内部 RPC 通道与 TREK 通信未授予的调用被拒绝而非忽略。RPC 通道对插件代码封死即便跑在 fork 进程原始 IPC 原语process.send、process.on(message)也在其代码加载前被吊销既不能伪造宿主消息也不能窃听在途请求。界面跑在密封的浏览器 frame里读不到会话 cookie碰不到外围 TREK 页面。崩溃 / 挂起 / 内存耗尽时只有它自己的进程死TREK 继续运行并可重启或停用它。但边界必须点破权限约束的是它能触及什么不约束它在授权范围内想干什么。一个被允许读行程且能连某主机的插件完全可能把行程数据发过去。所以先读权限清单和出口主机再决定装。看得见的操作审计与可见性插件做了什么是可追溯的且不设管理员门槛每个用户都能在Settings → Plugins的活动日志里看到插件以其名义执行的全部操作——读过的行程/费用、写入的地点、TREK 代发的每次出站调用。这是基于哈希链的防篡改审计的用户侧。管理员在Admin → Plugins看到按插件维度的视图。端点侧同样收紧所有路由挂在Controller(api/admin/plugins)同时套JwtAuthGuardAdminGuarddev-link 再叠一层TREK_PLUGINS_DEV_LINK要求。运行时关闭时install、upload、activate、update、rescan等统一返回 503——面板不可用是有明确语义的不是静默失败。常见问题速查现象大概率原因怎么办安装按钮变Incompatible无兼容版本等 TREK 升级或选仍兼容的旧版按钮变Install {version}最新版要更新的 TREK但有兼容旧版直接装那个旧版行上显示Update blocked签名密钥变更走 Review → 回显完整公钥 → 重信任更新装了没反应 Add allowed hostchipoperatorEgress插件还没加主机加至少一个 Allowed hosts私网自托管服务连不上默认拒绝私网出口确认信任全部插件后设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon想移除但保留数据卸载默认删数据卸载时选保留数据擦除义务留待重装面板显示Plugins are disabledTREK_PLUGINS_ENABLED被关闭恢复开启并重启看不到 Link a local pluginTREK_PLUGINS_DEV_LINK非1开发环境设为1延伸阅读Plugins——插件系统全貌类型、隔离模型、依赖、活动日志Plugin-Permissions——每条权限的确切授予范围与http:outbound细节Plugin-Development——SDK 与 manifest 编写Plugin-Publishing——注册表提交流程与trek-pluginCLIAdmin-Addons——插件可能依赖的 addon 管理Environment-Variables——插件相关环境变量完整参考Security-Hardening——安全加固建议【免费下载链接】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），仅供参考