TREK 插件面板实操指南装一个第三方插件前必须看清的 5 道边界【免费下载链接】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 实例的运维者。TREK 是一个自托管的旅行规划应用其插件面板Admin → Plugins允许你在不改源码的前提下扩展实例功能但第三方代码进生产环境前必须过几道硬检查。读完本文你能独立完成一次插件的注册表安装、出口白名单配置、带权限变更的更新审批以及一次不留后患的卸载。装插件前先看这 4 个环境变量面板所有行为都受服务端配置约束操作前先对照这份速查表变量作用默认值TREK_PLUGINS_ENABLED插件运行时总开关取值只要不是false/0/off/no大小写不敏感即为开启开启TREK_PLUGINS_DEV_LINK允许从本地构建目录注册插件并热重载仅当值恰为1关闭TREK_PLUGIN_ALLOW_PRIVATE_EGRESS设为on后允许插件出口访问私网/内网地址关闭TREK_PLUGIN_REGISTRY_URL覆盖 Discover 视图浏览的注册表索引地址可指向自建镜像官方注册表一个容易混淆的点运行时开启不等于任何插件在跑。pluginsEnabled()在 kill-switch.ts 里于每次调用时实时读环境变量改动并重启即生效但已安装插件仍是逐个手动激活的关闭总开关只是让安装、激活、更新、rescan等操作统一返回 503磁盘上的插件保留为停用状态。预安装审查对话框怎么读四块内容的真实来源结论安装前弹出的审查对话框展示的是插件在审查提交点的 manifest 预览不是作者写的介绍文字这是你做决定前唯一可信的信息源。对话框分四块——What it can access以平实语言逐条列出的权限未请求权限时显示 Needs no special access.、Connects to声明的可访问主机等宽字体 chip、Setup标注 Instance-wide / Per user / Required 的设置项、Details版本、体积、所需 TREK 版本范围、审查时间、下载量。原因在 registry.service.ts服务端拉取审查提交点实时生成ManifestPreview权限、出口主机、operatorEgress标记、设置字段、许可证、依赖再交给前端渲染。注册表数据本身也是聚合的dist/index.json一次拉取加 30 分钟缓存CACHE_TTL失败时软降级不影响面板。工具栏的Rescan按钮则同时做两件事重扫磁盘上本地安装的插件并强制绕过这份 30 分钟缓存重新拉取注册表——刚发布的插件立即可见而不是等约 35 分钟。边界对话框告诉你能碰什么不告诉你打算拿它做什么。一个同时有行程读权限和出口主机声明的插件完全可以把读到的数据发往声明的主机——权限清单是真实边界不是安全承诺。操作者出口主机为什么必须手动加、且改完要重启结论声明了operatorEgress的插件对接你自己的 Gotify、ntfy 这类服务安装后一个主机都连不出去必须手动添加 Allowed hosts且每次白名单变更都会重启插件进程。现象上这类插件审查对话框会多出 hosts you addchip 和提示manifest 里无法预知你的服务地址所以安装后要在 ⋯ → Allowed hosts 里逐个添加没添加任何主机前插件行显示琥珀色Add allowed hostchip防止静默故障看起来像一切正常添加后 chip 变蓝并显示主机数。原因出口守卫在子进程初始化时安装一次并拒绝二次initplugin-runtime.service.ts 有明确注释运行中的白名单无法热扩容唯一生效方式是重新拉起子进程。主机名的校验规则与 manifest 出口声明一致不允许裸*、整 TLD 通配或带协议前缀。边界两条要记住未声明operatorEgress的插件永远拿不到追加主机安装时同意的范围是硬边界只有管理员能添加主机普通用户不能扩大出口。若服务与 TREK 同机或同局域网localhost、192.168.x.x还需设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon——注意这会放宽所有插件的私网出口策略只在信任全部插件时才开。启用被拒的三类错误码激活前预检全是只读的结论启用一个插件前TREK 按版本兼容 → 权限再同意 → 必需 addon → 插件依赖的顺序做只读预检assertActivatable链plugin-runtime.service.ts任何一项不满足都不会留下半激活状态。三类结构化错误码及补救路径ADDON_DISABLED必需的 addon 未开启——到 Admin → Addons 开启后重试。DEPENDENCY_MISSING插件依赖缺失或版本过旧——对话框逐条列出依赖提供一键 Download / Update装最新兼容版本后自动重试。TREK_VERSION_INCOMPATIBLE/TREK_VERSION_UNKNOWN宿主版本不匹配或插件未声明支持范围——这种没有先试试的补救只能升级实例或弃用该插件。依赖关系还有两个级联语义启用前 TREK 按依赖图算出enableOrder先拉起所有依赖已安装但停用的依赖会被自动级联启用有 toast 告知反过来停用或 addon 被关时会停用所有传递依赖它的插件——一个插件不能在依赖缺失下继续运行。边界预检保证的是要么完整激活、要么什么都不变不保证依赖插件本身无害。级联启用意味着你启用 A 时可能顺带打开了从未审查过的 B激活后值得回看一遍哪些依赖被带起来了。插件更新为什么不静默扩权密钥变更为什么是唯一可覆盖项结论TREK 的更新逻辑保证两件事——新版本请求了新权限时新代码装好但保持关闭等你批准被签名阻塞的更新中只有密钥变更可以人工覆盖。新增权限场景update()对比新版声明权限与已授予权限的差集有新增权限或出口主机就保持 inactive 并返回差集面板提示 asking for rights you havent granted yet批准对话框列出新权限与新出站连接选 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 — both look identical from here. Confirm the new key with the author through a channel you already trust before you accept it.覆盖动作Trust the new key update受三重约束服务端assertRetrustable只放行SIGNATURE_KEY_CHANGED错误码签名缺失/无效没有任何覆盖入口请求必须回显对话框展示过的完整公钥防止渲染后注册表条目又换钥重信任与更新在同一调用内原子完成——要么钉住新密钥并落到新版本要么什么都不变。详见 plugins.controller.ts 的/retrust端点。旁路上传与开发链接权限模型不变只是没有人为它背书结论Upload plugin 与 Link a local plugin 两条旁路装出来的插件运行时权限模型与注册表插件完全相同区别仅在于没人替它做恶意软件扫描、没有签名——这是标签不是更高的信任等级。上传路径工具栏按钮或直接把.zip拖进面板。归档解压到 staging 后做与注册表安装相同的硬性防护防 zip-slip/炸弹的安全解压、严格 manifest 校验、拒绝原生二进制唯独跳过 SHA-256/签名校验没有注册表条目可对照。上限 50 MB50 * 1024 * 1024 4096用相同 id 覆盖上传时旧代码先被强制停止并停用不存在旧代码未重新激活还在跑的窗口。安装结果保持 inactive激活时照常走权限同意。开发链接路径面板出现路径输入框的前提是TREK_PLUGINS_DEV_LINK的值恰为1dev-link.ts 里的严格相等判断叠加管理员与总开关两道门。它对你的构建目录做符号链接不复制、校验 manifest、注册为 inactive然后用fs.watch监听构建输出重建后防抖 400 ms 自动重新 fork。注意开发模式下 OS 权限围栏在npm run dev下是关掉的这条路径只属于开发环境。三个徽章各保证什么都不说明代码做了什么结论Reviewed、Signed、Unsigned 三个徽章都是来源标签不描述代码行为也不要指望它们降低实际风险。Reviewed——TREK 维护者对每个版本做了恶意软件扫描仅此而已不承诺质量、可用性也不是无害担保。Signed——文件已对照作者签名密钥校验且密钥被钉住校验和证明文件就是注册表担保的字节签名再进一步证明这些字节来自作者。Unsigned——文件匹配注册表担保内容但没有任何东西把它绑到作者身上。这是少了一层保证不是危险信号注册表里多数插件尚未签名所以它显示为琥珀色提示而非警报。支撑这套信任模型的底层事实wiki/Plugins.md 有完整阐述每个活动插件跑在独立 OS 子进程里以 Node--permission启动文件系统读取限定在自身代码目录JWT_SECRET、数据库连接等机密对其进程物理不可达不能打开trek.db、派生子进程或加载原生模块自有数据存独立 SQLite 且只能经 TREK 访问插件与宿主的 RPC 通道只应答 manifest 声明且已批准的能力未授予的调用被拒绝而非忽略且原始 IPC 原语在插件代码加载前被吊销无法伪造宿主消息界面跑在密封的浏览器 frame 内读不到会话 cookie插件崩溃或内存耗尽时只有它自己的进程死掉TREK 继续运行。边界全文最需要记住的一句权限列表界定插件能触及什么不约束它在授权范围内的意图。卸载删掉什么、保留什么以及谁都能看的活动日志结论卸载uninstallplugin-runtime.service.ts默认删干净唯一可保留项是插件数据目录而出口主机与定时任务无条件清除——否则日后复用同一 id 的插件会悄悄继承前任的出口权限与任务。删除范围包括插件进程、代码目录、plugins注册表行与设置字段选deleteDatatrue时再清数据目录、错误日志、实体元数据、每用户配置含加密密钥、OAuth 令牌与状态、迁移台账、能力审计日志和待处理的 GDPR 擦除队列。若选择保留数据对应的用户数据擦除义务也会保留等同 id 插件重装后继续兑现。审计侧管理员在 Admin → Plugins 看到按插件维度的视图而每个普通用户在 Settings → Plugins 的活动日志里都能查看插件以其名义执行的全部操作读取的行程/费用、写入的地点、每次出站调用该视图不设管理员门槛——这是基于哈希链的防篡改审计的用户侧入口。面板端点本身全部挂在Controller(api/admin/plugins)下叠加JwtAuthGuard与AdminGuard总开关关闭时对应操作统一 503。TREK 插件面板 Discover 视图截图交付前过一遍7 条安全操作清单安装前在审查对话框逐条读完权限与出口主机清单确认每一项都有明确用途对话框数据来自审查提交点 manifest不参考作者自述。安装后不急着激活核对插件行状态为 Off检查有无Add allowed hostchip需要出口时只给声明了operatorEgress的插件添加最小主机集合。只有对接本机/局域网服务时才设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon并记住它放宽的是所有插件。批量更新前先单插件试更留意新权限审批对话框审批逐一出现不要凭应该没变化直接放行。遇到Update blocked先通过信任渠道向作者核实新公钥再走 retrust指纹之外的任何签名问题一律拒绝覆盖。卸载走 ⋯ → Delete 并默认删除数据同 id 重装前确认旧插件的出口主机与定时任务已随卸载清除。定期用 Rescan 重扫本地插件 刷新注册表并让团队成员各自检查 Settings → Plugins 的活动日志。【免费下载链接】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 插件面板实操指南：装一个第三方插件前必须看清的 5 道边界
TREK 插件面板实操指南装一个第三方插件前必须看清的 5 道边界【免费下载链接】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 实例的运维者。TREK 是一个自托管的旅行规划应用其插件面板Admin → Plugins允许你在不改源码的前提下扩展实例功能但第三方代码进生产环境前必须过几道硬检查。读完本文你能独立完成一次插件的注册表安装、出口白名单配置、带权限变更的更新审批以及一次不留后患的卸载。装插件前先看这 4 个环境变量面板所有行为都受服务端配置约束操作前先对照这份速查表变量作用默认值TREK_PLUGINS_ENABLED插件运行时总开关取值只要不是false/0/off/no大小写不敏感即为开启开启TREK_PLUGINS_DEV_LINK允许从本地构建目录注册插件并热重载仅当值恰为1关闭TREK_PLUGIN_ALLOW_PRIVATE_EGRESS设为on后允许插件出口访问私网/内网地址关闭TREK_PLUGIN_REGISTRY_URL覆盖 Discover 视图浏览的注册表索引地址可指向自建镜像官方注册表一个容易混淆的点运行时开启不等于任何插件在跑。pluginsEnabled()在 kill-switch.ts 里于每次调用时实时读环境变量改动并重启即生效但已安装插件仍是逐个手动激活的关闭总开关只是让安装、激活、更新、rescan等操作统一返回 503磁盘上的插件保留为停用状态。预安装审查对话框怎么读四块内容的真实来源结论安装前弹出的审查对话框展示的是插件在审查提交点的 manifest 预览不是作者写的介绍文字这是你做决定前唯一可信的信息源。对话框分四块——What it can access以平实语言逐条列出的权限未请求权限时显示 Needs no special access.、Connects to声明的可访问主机等宽字体 chip、Setup标注 Instance-wide / Per user / Required 的设置项、Details版本、体积、所需 TREK 版本范围、审查时间、下载量。原因在 registry.service.ts服务端拉取审查提交点实时生成ManifestPreview权限、出口主机、operatorEgress标记、设置字段、许可证、依赖再交给前端渲染。注册表数据本身也是聚合的dist/index.json一次拉取加 30 分钟缓存CACHE_TTL失败时软降级不影响面板。工具栏的Rescan按钮则同时做两件事重扫磁盘上本地安装的插件并强制绕过这份 30 分钟缓存重新拉取注册表——刚发布的插件立即可见而不是等约 35 分钟。边界对话框告诉你能碰什么不告诉你打算拿它做什么。一个同时有行程读权限和出口主机声明的插件完全可以把读到的数据发往声明的主机——权限清单是真实边界不是安全承诺。操作者出口主机为什么必须手动加、且改完要重启结论声明了operatorEgress的插件对接你自己的 Gotify、ntfy 这类服务安装后一个主机都连不出去必须手动添加 Allowed hosts且每次白名单变更都会重启插件进程。现象上这类插件审查对话框会多出 hosts you addchip 和提示manifest 里无法预知你的服务地址所以安装后要在 ⋯ → Allowed hosts 里逐个添加没添加任何主机前插件行显示琥珀色Add allowed hostchip防止静默故障看起来像一切正常添加后 chip 变蓝并显示主机数。原因出口守卫在子进程初始化时安装一次并拒绝二次initplugin-runtime.service.ts 有明确注释运行中的白名单无法热扩容唯一生效方式是重新拉起子进程。主机名的校验规则与 manifest 出口声明一致不允许裸*、整 TLD 通配或带协议前缀。边界两条要记住未声明operatorEgress的插件永远拿不到追加主机安装时同意的范围是硬边界只有管理员能添加主机普通用户不能扩大出口。若服务与 TREK 同机或同局域网localhost、192.168.x.x还需设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon——注意这会放宽所有插件的私网出口策略只在信任全部插件时才开。启用被拒的三类错误码激活前预检全是只读的结论启用一个插件前TREK 按版本兼容 → 权限再同意 → 必需 addon → 插件依赖的顺序做只读预检assertActivatable链plugin-runtime.service.ts任何一项不满足都不会留下半激活状态。三类结构化错误码及补救路径ADDON_DISABLED必需的 addon 未开启——到 Admin → Addons 开启后重试。DEPENDENCY_MISSING插件依赖缺失或版本过旧——对话框逐条列出依赖提供一键 Download / Update装最新兼容版本后自动重试。TREK_VERSION_INCOMPATIBLE/TREK_VERSION_UNKNOWN宿主版本不匹配或插件未声明支持范围——这种没有先试试的补救只能升级实例或弃用该插件。依赖关系还有两个级联语义启用前 TREK 按依赖图算出enableOrder先拉起所有依赖已安装但停用的依赖会被自动级联启用有 toast 告知反过来停用或 addon 被关时会停用所有传递依赖它的插件——一个插件不能在依赖缺失下继续运行。边界预检保证的是要么完整激活、要么什么都不变不保证依赖插件本身无害。级联启用意味着你启用 A 时可能顺带打开了从未审查过的 B激活后值得回看一遍哪些依赖被带起来了。插件更新为什么不静默扩权密钥变更为什么是唯一可覆盖项结论TREK 的更新逻辑保证两件事——新版本请求了新权限时新代码装好但保持关闭等你批准被签名阻塞的更新中只有密钥变更可以人工覆盖。新增权限场景update()对比新版声明权限与已授予权限的差集有新增权限或出口主机就保持 inactive 并返回差集面板提示 asking for rights you havent granted yet批准对话框列出新权限与新出站连接选 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 — both look identical from here. Confirm the new key with the author through a channel you already trust before you accept it.覆盖动作Trust the new key update受三重约束服务端assertRetrustable只放行SIGNATURE_KEY_CHANGED错误码签名缺失/无效没有任何覆盖入口请求必须回显对话框展示过的完整公钥防止渲染后注册表条目又换钥重信任与更新在同一调用内原子完成——要么钉住新密钥并落到新版本要么什么都不变。详见 plugins.controller.ts 的/retrust端点。旁路上传与开发链接权限模型不变只是没有人为它背书结论Upload plugin 与 Link a local plugin 两条旁路装出来的插件运行时权限模型与注册表插件完全相同区别仅在于没人替它做恶意软件扫描、没有签名——这是标签不是更高的信任等级。上传路径工具栏按钮或直接把.zip拖进面板。归档解压到 staging 后做与注册表安装相同的硬性防护防 zip-slip/炸弹的安全解压、严格 manifest 校验、拒绝原生二进制唯独跳过 SHA-256/签名校验没有注册表条目可对照。上限 50 MB50 * 1024 * 1024 4096用相同 id 覆盖上传时旧代码先被强制停止并停用不存在旧代码未重新激活还在跑的窗口。安装结果保持 inactive激活时照常走权限同意。开发链接路径面板出现路径输入框的前提是TREK_PLUGINS_DEV_LINK的值恰为1dev-link.ts 里的严格相等判断叠加管理员与总开关两道门。它对你的构建目录做符号链接不复制、校验 manifest、注册为 inactive然后用fs.watch监听构建输出重建后防抖 400 ms 自动重新 fork。注意开发模式下 OS 权限围栏在npm run dev下是关掉的这条路径只属于开发环境。三个徽章各保证什么都不说明代码做了什么结论Reviewed、Signed、Unsigned 三个徽章都是来源标签不描述代码行为也不要指望它们降低实际风险。Reviewed——TREK 维护者对每个版本做了恶意软件扫描仅此而已不承诺质量、可用性也不是无害担保。Signed——文件已对照作者签名密钥校验且密钥被钉住校验和证明文件就是注册表担保的字节签名再进一步证明这些字节来自作者。Unsigned——文件匹配注册表担保内容但没有任何东西把它绑到作者身上。这是少了一层保证不是危险信号注册表里多数插件尚未签名所以它显示为琥珀色提示而非警报。支撑这套信任模型的底层事实wiki/Plugins.md 有完整阐述每个活动插件跑在独立 OS 子进程里以 Node--permission启动文件系统读取限定在自身代码目录JWT_SECRET、数据库连接等机密对其进程物理不可达不能打开trek.db、派生子进程或加载原生模块自有数据存独立 SQLite 且只能经 TREK 访问插件与宿主的 RPC 通道只应答 manifest 声明且已批准的能力未授予的调用被拒绝而非忽略且原始 IPC 原语在插件代码加载前被吊销无法伪造宿主消息界面跑在密封的浏览器 frame 内读不到会话 cookie插件崩溃或内存耗尽时只有它自己的进程死掉TREK 继续运行。边界全文最需要记住的一句权限列表界定插件能触及什么不约束它在授权范围内的意图。卸载删掉什么、保留什么以及谁都能看的活动日志结论卸载uninstallplugin-runtime.service.ts默认删干净唯一可保留项是插件数据目录而出口主机与定时任务无条件清除——否则日后复用同一 id 的插件会悄悄继承前任的出口权限与任务。删除范围包括插件进程、代码目录、plugins注册表行与设置字段选deleteDatatrue时再清数据目录、错误日志、实体元数据、每用户配置含加密密钥、OAuth 令牌与状态、迁移台账、能力审计日志和待处理的 GDPR 擦除队列。若选择保留数据对应的用户数据擦除义务也会保留等同 id 插件重装后继续兑现。审计侧管理员在 Admin → Plugins 看到按插件维度的视图而每个普通用户在 Settings → Plugins 的活动日志里都能查看插件以其名义执行的全部操作读取的行程/费用、写入的地点、每次出站调用该视图不设管理员门槛——这是基于哈希链的防篡改审计的用户侧入口。面板端点本身全部挂在Controller(api/admin/plugins)下叠加JwtAuthGuard与AdminGuard总开关关闭时对应操作统一 503。TREK 插件面板 Discover 视图截图交付前过一遍7 条安全操作清单安装前在审查对话框逐条读完权限与出口主机清单确认每一项都有明确用途对话框数据来自审查提交点 manifest不参考作者自述。安装后不急着激活核对插件行状态为 Off检查有无Add allowed hostchip需要出口时只给声明了operatorEgress的插件添加最小主机集合。只有对接本机/局域网服务时才设TREK_PLUGIN_ALLOW_PRIVATE_EGRESSon并记住它放宽的是所有插件。批量更新前先单插件试更留意新权限审批对话框审批逐一出现不要凭应该没变化直接放行。遇到Update blocked先通过信任渠道向作者核实新公钥再走 retrust指纹之外的任何签名问题一律拒绝覆盖。卸载走 ⋯ → Delete 并默认删除数据同 id 重装前确认旧插件的出口主机与定时任务已随卸载清除。定期用 Rescan 重扫本地插件 刷新注册表并让团队成员各自检查 Settings → Plugins 的活动日志。【免费下载链接】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），仅供参考