跳转至

在线模块仓库与个人仓库维护

适用版本：包含「在线模块仓库 / 一键清理旧版本」功能的版本（基于 v1.31.76 开发；合并发布前不代表已上线）。 前置条件：管理员登录、服务器可访问公网 HTTPS 443、模块及 DataProtection 密钥目录持久化。

仓库组织

官方目录在独立公开仓库 Telegram-Panel-Modules， 主项目使用 module-repository/ Git 子模块固定其提交。 公开仓库提供 demo.kick-api 踢人/封禁演示源码及安装包；不会自动公开私有模块代码或包。 运行中的面板通过 HTTPS 读取目录，不依赖 Git、SSH 或部署目录中的子模块。

面板始终自动提供官方仓库。即使已有 repositories.json，启动后也会把官方仓库补回列表并置于首位；该系统仓库不可编辑、删除或写入用户令牌。模块管理页加载、切换或保存仓库后会自动连接并读取 index.json，失败时仍可用“连接 / 刷新目录”重试。个人 Fork、私有仓库和令牌无法凭空推断，首次添加时必须由管理员填写仓库位置和对应令牌。

公开仓库的 skills/tgpanel-module-workflow/SKILL.md 附带可分发模块开发技能，覆盖静态页面、任务合同、 轻量打包和在线目录维护。Fork 后可让 Agent 直接读取，或将整个技能文件夹复制到工具的技能目录。 Git 保存源码，Release 保存编译后的 .tpm，index.json 连接二者；面板不在线编译源码。 Fork 不会复制 Release 资产，自行修改后需要发布自己的包并更新下载 URL 和哈希。

git submodule update --init module-repository

更新关联时在模块仓库完成提交与推送，再在主项目更新 gitlink，并走 dev 验收后合并 main。 不要将个人令牌、业务配置或运行目录提交到子模块。

个人仓库最短维护流程

模块管理页的“在线模块仓库”区域提供“官方模块仓库”“Fork 创建个人仓库”和“仓库维护说明”入口， 均在新标签页打开。Fork 入口只打开 GitHub 的创建页面，不会自动创建仓库或更改面板配置。 入口随包含本次页面改动的版本生效；需要 GitHub 登录或仓库访问失败时，可直接访问下方官方仓库地址。 验收时确认三个链接分别打开公开仓库、Fork 页面和仓库 README；回滚前端版本即可撤回入口，不影响已配置仓库。

  1. Fork 官方目录仓库，或创建根目录包含 index.json 的公开/私有仓库。
  2. 按模块开发合同构建 .tpm，递增版本并验证目标宿主兼容性。
  3. 上传到个人仓库的 GitHub Release，保留旧资产用于回滚。
  4. 查询 Release 资产 API 地址，并用子模块提供的工具生成条目：
gh api repos/OWNER/REPO/releases/tags/TAG --jq '.assets[] | {name,url}'
python tools/catalog.py add /path/module.tpm https://api.github.com/repos/OWNER/REPO/releases/assets/ASSET_ID
python tools/catalog.py validate

上述 Python 命令在个人模块目录仓库中执行。add 从包内 manifest 提取 ID/名称/版本并计算 SHA-256， 仅修改本地目录，不上传文件、不读取凭据。不要覆盖已发布版本；修复需发布新版本。

  1. 提交 index.json 后，在面板添加 GitHub 仓库，填写 owner/repo、分支或标签。
  2. 私有仓库填写只针对该仓库、具备 Contents: Read 的细粒度令牌；组织令牌需先审批。
  3. 连接目录、安装、重启，再检查模块页面、创建任务和实际业务路径。目录能访问不等于模块业务可用。

私有包使用同仓库的 api.github.com/repos/OWNER/REPO/releases/assets/ID， 不要把需网页登录的 github.com/.../releases/download/... 当作私有 API 下载地址。 自托管可选择 HTTPS 目录类型；认证必须支持 Authorization: Bearer TOKEN。 Gitea 等托管服务可导出相同格式的 HTTPS 目录，但本版本没有其专用 API 适配器。

目录与安装合同

schemaVersion=1，根对象 modules 是数组；每项至少含：

字段 约束
id 稳定模块 ID，字母/数字开头，后续允许 ._-，最多 100 字符
name 展示名称，1～100 字符
version x.y.z，同 ID/版本不重复
downloadUrl 完整公网 HTTPS 443 地址，不含用户信息/片段
sha256 实际 .tpm 的 64 位十六进制 SHA-256
description 可选说明，最多 2000 字符

目录最多 2MB / 1000 项；每包最多 50MB，解压最多 200MB / 5000 项。 每次下载最多 45 秒，最多跟随 5 次重定向。安装时重新读取服务端仓库目录， 客户端只提交模块 ID、版本和用户确认过的哈希，不提交下载 URL。 若目录哈希已变更，要求刷新并重新确认；下载哈希和包内 manifest 身份必须全部一致后才安装。 复用宿主安装器检查入口、宿主版本和依赖；依赖不会自动下载。 启用失败时包保留供排查，原启用状态保持，并返回明确提示。

凭据与网络边界

  • repositories.json 存于模块持久化根目录；令牌用宿主 DataProtection 加密。
  • 接口只返回 hasToken，不回显明文或密文。编辑留空保留令牌，明确清除可移除；改变仓库地址清除旧令牌。
  • 令牌不会发送到跨源重定向目标；GitHub 令牌还限制在选定仓库的 API 路径下。
  • 每次实际连接检查 DNS 返回地址并固定已检查地址；禁止回环、内网、保留地址、HTTP、非 443 端口。
  • 专用下载通道不继承系统代理，以避免绕过目标地址检查；服务器必须具备直接公网访问能力。
  • 仓库配置和 DataProtection 密钥必须一起备份。密钥丢失后重新保存令牌，不要将解密失败视为空令牌继续请求。
  • 模块在宿主进程执行，哈希用于检查传输和目录一致性，不代表作者可信或模块已通过官方审核。

批量清理合同

预览列出每个非内置模块的待删版本及保留版本。执行时在安装器共享互斥锁内重新读取状态， 保护 ActiveVersion、LastGoodVersion 和 ModuleRegistry 当前进程实际加载版本，跳过内置模块。 永久删除旧安装目录及归档包；模块业务数据不在清理范围，没有回收站。 逐版本返回成功/失败，部分失败继续处理其它版本；成功删除过版本且用户开启自动重启时， 整个批次结束后只请求一次重启。空批次不重启。 安装、启用、停用、版本切换、单模块和批量清理共用互斥锁，防止覆盖 state.json。 本实现面向单个宿主进程，不支持多个面板实例同时写同一模块目录。

告警解释与修复

内置能力与公开演示

从宿主 1.31.77 的本次改动起，踢人/封禁不再内置。启动时移除旧 builtin.kick-api 状态登记， 保留 API 配置、密钥及历史任务。安装公开的 demo.kick-api 并重启后恢复 /api/kick。 页面改为 /ext/demo.kick-api/kick；旧页面及旧宿主静态资源移除。模块引用 Core 服务， 1.0.1 包限定宿主 1.31.77，旧 1.31.76 不兼容，防止重复注册 /api/kick。

升级前排空或取消/暂停未完成的旧踢人任务；未安装演示模块期间没有其执行器，旧待执行任务可能失败。 历史 external_api_kick / host.legacy 归属不批量改写，新任务归属 demo.kick-api。 回滚旧宿主前先停用外部模块并重启，避免与旧内置实现重复；再恢复配套数据备份。

builtin.tasks 保留，显示为“系统任务目录（任务中心基础能力）”。它登记十种任务、 编辑/操作能力和持续活跃重跑构建器，不是冗余演示；停用会影响标准创建、编辑、重跑和部分已有任务调度。 业务执行器仍由宿主负责，不能只凭它没有独立页面就删除。

“模块兼容性与贡献检查”包含不同问题：

  • 重复任务/API/页面定义是真实贡献冲突。
  • executor=0 或 lifecycle=0 是未找到匹配执行器/生命周期处理器，不是旧包重复加载。
  • CreateRoute 必须是模块自己 /ext/{moduleId}/... 下的安全路径。

后两类会阻止标准任务新建/重跑，不表示模块所有独立页面或历史任务都已失效。 清理旧版本不能修复缺失合同；模块作者需接入正确执行通道、生命周期和路由并重新打包。 不要通过隐藏告警、放宽数量校验或添加空生命周期处理器来绕过。

验收、失败排查与回滚

本地回归覆盖加密/令牌清除、地址限制、目录验证、manifest 身份匹配、并发安装和清理保护。 上线仍须验证容器、日志、/ui/dashboard、/api/panel/auth/me，以及公开目录、私有目录和实际包安装。 不把模拟下载测试作为私有 GitHub 实网验收。

  • 401/403：检查权限、令牌有效期、组织审批；403 也可能是 GitHub 限流。
  • 404：检查仓库、分支、根目录 index.json 和 Release 资产 ID。
  • 私网拒绝/连接失败：检查服务器 DNS、公网出口和 HTTPS 证书，不要关闭地址检查。
  • 哈希或身份错误：重新打包并发布新版本，核对资产与条目，未通过检查的包不会安装。
  • 令牌解密失败：恢复配套 DataProtection 密钥，或重新输入令牌。
  • 清理部分失败：按返回模块/版本检查磁盘权限、占用和容量，解决后重试。

回滚主程序前备份模块根目录与密钥；新仓库配置可保留，旧宿主不读取该文件。 回滚模块时停用问题版本、恢复最后可用版本或目录备份，并重启验证。 已清理版本只能从原仓库重新下载或从备份恢复。回滚目录发布可撤销 index.json 提交，不删除旧资产。