PT守护神 发布与在线更新指南

闭源 · 私密免费分享模式。软件不开源：源码留 Private 仓库，只分发镜像/二进制/APK。

一、发布前置（一次性）

1. GitHub 仓库设 Private。源码（backend/ frontend/ mobile/）留在私有仓库，只把构建产物分发出去。Public 仓库会把这三个目录全部暴露 = 实质开源。
2. 初始化并推送：

   git init && git remote add origin git@github.com:<你>/ptpatronus.git
   git push -u origin main

3. ghcr 镜像设为 public（让用户 docker pull 免登录）：GitHub → 你的个人/组织页 → Packages → ptpatronus → Package settings → Change visibility → Public。
4. 准备 SECRET_KEY / ACTIVATION_SECRET（release 模式必填，见 docker-compose.yml）。

二、日常发版（5 步）

打 v* tag 会同时触发 4 条 CI（docker / release / flutter-release / ci）。

1. 改版本号（4 处同步；CI 会把 tag 注入镜像/二进制，这些常量是开发期与离线兜底）：
   • backend/internal/version/version.go
   • frontend/package.json（vite 从这里注入 __APP_VERSION__）
   • mobile/lib/core/version.dart
   • mobile/pubspec.yaml（version: X.Y.Z+<递增buildCode>）
2. 打 tag：git tag vX.Y.Z && git push origin vX.Y.Z（必须 v 前缀）
3. 等 CI，产出：
   • 镜像（docker.yml，tag 触发，多架构 + Trivy CRITICAL 门禁）：ghcr.io/gntv456/pt-patronus:vX.Y.Z 与 :latest
   • GitHub Release 资产：监控 Agent / Android APK / Windows zip——注意：release.yml 与 flutter-release.yml 的产物 job 当前仍为 if: false（Actions 计费额度所限，需手动删除该行恢复）， 停用期间这些产物走本地 scripts/release-local.sh 构建，完成后手动传 GitHub Release。
4. 分发：
   • docker 用户：锁定版本号拉取（推荐 docker-compose.example.yml 默认形态）： docker pull ghcr.io/gntv456/pt-patronus:vX.Y.Z（升级即改 compose 里的版本号再 up -d，可精确回滚）
   • 手机 / 桌面：从 GitHub Release 下载 APK / Windows zip → 传网盘（带提取码）→ TG 群 / 邀请论坛发链接

三、在线更新

用户部署的 PT守护神 后端会拉一份**官方 manifest（JSON）**检查更新，再经 /system/update/check 中转给各自的客户端（客户端不直连官方源，避墙、不泄露官方地址）。你作为分发者维护这一份。

3.1 配置官方源

部署时设环境变量（见 docker-compose.yml 的 environment）：

UPDATE_MANIFEST_URL: https://<你的公开地址>/update-manifest.json

把 manifest 放在一个公开可访问的 URL（gist raw、轻量仓库的 raw 文件、或你的静态站都行）。manifest 公开只含版本号 + changelog + 下载地址，下载地址指向私密网盘，软件本体仍私密。

3.2 manifest 示例

{
  "latestVersion": "0.80.06",
  "minVersion": "0.80.00",
  "releaseName": "零配置部署 + Android split APK + iOS 未签名 + 各端 CI 修复",
  "releaseNotes": "本次更新内容...\n客户端下载（蓝奏云提取码 hxpt）: https://wwazg.lanzoub.com/b03anmtyxg",
  "isForced": false,
  "publishedAt": "2026-07-05T00:00:00Z",
  "targets": {
    "docker": {
      "image": "ghcr.io/gntv456/pt-patronus:0.80.06",
      "instructions": "docker compose pull && docker compose up -d"
    },
    "android": { "url": "https://wwazg.lanzoub.com/b03anmtyxg" },
    "windows": { "url": "https://wwazg.lanzoub.com/b03anmtyxg" },
    "macos": { "url": "https://wwazg.lanzoub.com/b03anmtyxg" },
    "ios": { "url": "https://wwazg.lanzoub.com/b03anmtyxg" },
    "agent-linux-amd64": { "url": "https://github.com/gntv456/pt-patronus/releases/latest/download/ptpatronus-agent-linux-amd64" },
    "agent-linux-arm64": { "url": "https://github.com/gntv456/pt-patronus/releases/latest/download/ptpatronus-agent-linux-arm64" }
  }
}

3.3 不同形态怎么落地更新

形态	发现新版后	原因
docker 服务端	Web UI「设置→关于→检查更新」提示 + 一键复制 docker compose pull && up -d	容器不能运行中换自己镜像，是提示命令、非自动替换
手机 APP	启动自动检查 + 账户页「检查更新」，弹窗点「下载更新」调系统浏览器打开网盘	私密分发走网盘 + 提取码，外链最稳
Windows 桌面	同上，外链打开下载页	Flutter 桌面无可靠自更新机制

3.4 自托管清单（可选，覆盖官方源）

管理员可在后台 POST /api/v1/admin/update/manifest（需 admin）写一份本地清单，落盘 data/update-manifest.json，优先级高于官方源。请求体即上面的 manifest JSON；latestVersion 留空表示清除、回退官方源。适合想自己控制版本节奏的部署。

四、PT 工具的特殊考量

• 多数 PT 站禁止公开传播辅助工具 → 不要在 GitHub Public / 公开官网挂，避免站点风控或被投诉下架。
• 推荐私密分发：TG 群 + 网盘（提取码）+ 邀请制论坛。这与闭源天然契合。