gitpull

插件

· 作者 MooreFoss

从 git 仓库拉取文件到文件夹。

0 本站下载 0 关注 更新于 1 周前

最新 1.4 · 1.21.11 · Paper / Spigot

一键开服(送7天)

GitPull

GitPull 1.4 是一款基于 Git 的 Spigot/Paper 数据包更新工具。玩家可以拉取代码仓库、在聊天窗口中查看进度,并在更新完成后点击消息以重新加载数据包。GitHub 推送通知通过独立的 Webhook 服务和本地事件文件进行集成。

功能特性

  • 对配置好的 URL 执行 git pull 或 git clone,无需配置 origin。
  • 支持多个仓库、分支、HTTP 代理以及执行超时设置。
  • 异步运行 Git 命令,并显示仓库信息、Git 阶段、百分比和已用时间。
  • 区分更新成功、已是最新、失败和超时的结果。
  • 提供可配置的完成音效和可点击的数据包重新加载操作。
  • 在 Webhook 拉取成功后,向拥有 gitpull.notify 权限的在线操作员或玩家发送通知。

安装与升级

要求:Java 21 或更高版本、支持 api-version: 1.21 的 Spigot/Paper 服务器,且服务器上已安装 Git。该项目基于 Spigot API 1.21.11 编译。

从项目目录构建:

.\gradlew.bat build

在 Linux/macOS 上,请使用 ./gradlew build。生成的工件位于 build/libs/gitpull-1.4.jar。

  1. 将 JAR 文件复制到服务器的 plugins 目录并启动服务器。
  2. 编辑生成的 plugins/gitpull/config.yml,替换示例中的仓库 URL、目录和分支。
  3. 运行 /pull reload 应用配置,然后运行 /pull <repository-name>。

如需升级,请停止服务器并替换旧的 JAR 文件,保留配置目录。如果服务器配置了 settings.update-folder: update,你也可以将新 JAR 放入 plugins/update/ 下,文件名需与旧 JAR 相同。它将在下次启动时替换旧文件。插件目录中仅保留一个 GitPull JAR。

/pull reload 会重新读取配置文件。正在运行的 Git 任务会保留其启动时的仓库设置。JAR 升级需要重启服务器。

命令与权限

命令 用途 权限
/pull 按配置顺序拉取所有有效的仓库 gitpull.pull
/pull <name> 拉取单个仓库;仓库名称支持 Tab 补全 gitpull.pull
/pull reload 重新加载配置和通知监听器 gitpull.pull, gitpull.reload

这些权限默认授予操作员。控制台也可以运行这些命令。仓库名称 reload 为保留字。

通知权限 用途
gitpull.notify 接收 Webhook 通知;默认授予操作员
minecraft.command.reload 显示并执行数据包重新加载操作;操作员也能看到该操作

该操作会以玩家身份运行 /minecraft:reload,服务器仍会检查命令权限。它重新加载的是数据包,而非插件 JAR。游戏内的链接当前标记为 重载数据包 (Reload datapacks);插件消息均为中文。

配置

git-command: git
http-proxy: ""
clone-if-missing: true
timeout-seconds: 300

notifications:
  sound:
    enabled: true
    id: "minecraft:entity.experience_orb.pickup"
    volume: 0.8
    pitch: 1.2

webhook-notifications:
  enabled: true
  directory: "webhook-events"
  max-age-seconds: 300

repositories:
  pack:
    repository: "https://github.com/OWNER/REPO.git"
    directory: "world/datapacks/my-pack"
    branch: "main"
设置项 含义
git-command Git 可执行文件的名称或完整路径,例如 /usr/bin/git
http-proxy 为 Git 子进程设置大小写敏感的 HTTP/HTTPS 代理环境变量。空值表示不添加任何覆盖;继承的环境变量和 Git 配置可能仍然生效。SSH URL 不使用此 HTTP 代理
clone-if-missing 允许在目标不存在,或为空且没有 Git 仓库时进行克隆
timeout-seconds 每个仓库的 Git 操作超时时间,最小值为 1 秒
repositories.<name>.repository 用于克隆和拉取的 HTTPS 或 SSH URL;现有的远程配置将被保留
repositories.<name>.directory 绝对路径,或相对于服务器世界容器(通常是服务器根目录)的路径
repositories.<name>.branch 要克隆或拉取的远程分支。留空表示使用远程默认分支;拉取操作不会切换本地分支
webhook-notifications.enabled 监听本地事件文件;可以禁用以仅支持手动使用
webhook-notifications.directory 事件目录;相对路径相对于 plugins/gitpull 解析,也支持绝对路径
webhook-notifications.max-age-seconds 通知的最大有效时长,默认 300 秒,可配置范围为 1 到 86400 秒

私有仓库使用运行游戏服务器的操作系统账户的 SSH 密钥或 HTTPS 凭据。请确认该账户能够无需交互式提示即可访问该仓库。

进度、音效与数据包重新加载

当 Git 输出阶段和百分比信息时,聊天窗口的进度更新频率最多每秒一次。如果没有新的进度,插件每 10 秒报告一次当前状态和已用时间。百分比描述的是当前的 Git 阶段,而非整体任务的完成度。

  • 手动拉取:当所有仓库都成功且至少有一个仓库被更新或克隆时,请求者会收到一次音效,最终消息提供重新加载操作。
  • Webhook 拉取:每次修订变更都会为通知接收者播放音效,并为拥有重新加载权限的玩家提供重新加载操作。
  • “已是最新”的结果仅显示文本。失败和超时不会播放成功音效。

notifications.sound 控制启用标志、命名空间声音 ID、音量(范围 0.0–1.0)和音调(范围 0.5–2.0)。默认是经验球拾取音效。另一个有效的选择是 minecraft:entity.ender_dragon.death。客户端必须拥有所选音效;播放使用“玩家”音效类别。应用更改请使用 /pull reload。

GitHub Webhook 设置

工作原理

GitHub push → HTTPS 端点 → webhook 服务 → pull-script.sh
                                                     ↓ 成功的 Git 拉取
                                              gitpull-notify.py
                                                     ↓ 事件文件
                                 plugins/gitpull/webhook-events
                                                     ↓ 每 40 ticks 轮询一次
                                      chat, sound, reload action

GitPull 不暴露 HTTP 端点。设置 webhook-notifications.enabled: true 启用文件监控;您还必须部署一个服务来接收 GitHub 请求,并配置一个脚本来发布通知。手动 /pull 命令会直接启动 Git,而不使用 Webhook。

本示例使用 Linux、adnanh/webhook 2.8+、Nginx 和 systemd。它假设已存在一个名为 minecraft 的游戏服务器操作系统账户,服务器根目录为 /srv/minecraft,仓库名称为 pack,分支为 main。请替换为您实际的值。Webhook 和游戏服务器使用相同的账户和文件系统。

1. 安装依赖项和脚本

在 Debian/Ubuntu 上,安装依赖项,然后从本项目的目录中复制脚本:

sudo apt install git python3 webhook nginx util-linux coreutils
sudo install -d -o minecraft -g minecraft /srv/gitpull
sudo install -d -o minecraft -g minecraft /srv/minecraft/plugins/gitpull/webhook-events
sudo install -o minecraft -g minecraft -m 750 deploy/pull-script.sh /srv/gitpull/pull-script.sh
sudo install -o minecraft -g minecraft -m 640 deploy/gitpull-notify.py /srv/gitpull/gitpull-notify.py
sudo sed -i 's/\r$//' /srv/gitpull/pull-script.sh /srv/gitpull/gitpull-notify.py

需要 Python 3.8 或更高版本。util-linux 提供 flock;coreutils 提供 timeout。事件文件仅对所有者可读和可写,因此此设置将 Webhook 和游戏服务器作为同一账户运行。

捆绑的 pull-script.sh 和 config-tokumei.yml 包含特定于 tokumei 部署的路径。对于其他环境,请编辑 /srv/gitpull/pull-script.sh:

脚本位置 此示例的值
exec 9> 后的锁文件 /srv/gitpull/pull.lock
cd 后的目录 /srv/minecraft/world/datapacks/my-pack
传递给 git pull 的 URL 和分支 https://github.com/OWNER/REPO.git main
-c http.proxy=... 设置您的代理,如果不需要代理则移除此参数
python3 后的脚本路径 /srv/gitpull/gitpull-notify.py
通知目录参数 /srv/minecraft/plugins/gitpull/webhook-events
通知仓库名称参数 tokumei pack,与插件配置匹配以在聊天中显示。通知名称必须包含 1–80 个 ASCII 字母、数字、_、. 或 -

最终的通知调用应为:

python3 /srv/gitpull/gitpull-notify.py /srv/minecraft/plugins/gitpull/webhook-events pack "$status" "$before" "$after"

拉取脚本需要一个现有的 Git 仓库。使用插件或手动将仓库克隆到目标目录中(作为 minecraft 用户)。捆绑的脚本使用代理 192.168.6.2:7890 和 120 秒超时。插件的 http-proxy 和 timeout-seconds 设置不会更改此脚本。

2. 配置 Webhook 端点

将其保存为 /srv/gitpull/hooks.json,并将 REPLACE_WITH_YOUR_SECRET 替换为您自己的随机密钥。此配置接受对 main 的签名推送:

[
  {
    "id": "gitpull",
    "execute-command": "/srv/gitpull/pull-script.sh",
    "command-working-directory": "/srv/gitpull",
    "http-methods": ["POST"],
    "trigger-rule": {
      "and": [
        {"match": {"type": "payload-hmac-sha256", "secret": "REPLACE_WITH_YOUR_SECRET", "parameter": {"source": "header", "name": "X-Hub-Signature-256"}}},
        {"match": {"type": "value", "value": "push", "parameter": {"source": "header", "name": "X-GitHub-Event"}}},
        {"match": {"type": "value", "value": "refs/heads/main", "parameter": {"source": "payload", "name": "ref"}}},
        {"match": {"type": "value", "value": "false", "parameter": {"source": "payload", "name": "deleted"}}}
      ]
    }
  }
]

使该文件对 minecraft 用户可读,例如使用 sudo chown minecraft:minecraft /srv/gitpull/hooks.json 和 sudo chmod 600 /srv/gitpull/hooks.json。

此示例在接受请求后立即响应。Git 结果将记录到服务日志和事件文件中。请参阅 官方 Webhook 字段参考。

创建 /etc/systemd/system/gitpull-webhook.service:

[Unit]
Description=GitPull Webhook
After=network-online.target
Wants=network-online.target

[Service]
User=minecraft
Group=minecraft
WorkingDirectory=/srv/gitpull
ExecStart=/usr/bin/webhook -ip 127.0.0.1 -port 9000 -hooks /srv/gitpull/hooks.json -hotreload -verbose
Restart=on-failure

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now gitpull-webhook

如果您已经在运行 Webhook,请将钩子添加到其现有的 hooks 数组中,而不是在同一端口上启动另一个进程。如果更改了其 systemd 启动参数,请重启该服务。

3. 设置 HTTPS

将您的域名指向服务器并获得有效的 TLS 证书。添加并启用 Nginx 站点,替换域名和证书路径:

server {
    listen 443 ssl;
    server_name hooks.example.com;
    ssl_certificate /etc/letsencrypt/live/hooks.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hooks.example.com/privkey.pem;

    location = /hooks/gitpull {
        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
sudo nginx -t
sudo systemctl reload nginx

允许在 443 端口接收传入的 HTTPS 流量。Webhook 仅监听本地回环地址(localhost)的 9000 端口。

4. 配置 GitHub 仓库

在仓库中打开 Settings → Webhooks → Add webhook:

字段 值
Payload URL https://hooks.example.com/hooks/gitpull
Content type application/json
Secret 与 hooks.json 中相同的密钥
SSL verification Enabled
Events Just the push event
Active Enabled

你需要拥有管理仓库 Webhook 的权限。请确保在 GitHub 和 Nginx 中一致使用 gitpull 作为 hook ID 和端点后缀。如果你更改了分支,请同时更新脚本、插件配置以及 refs/heads/main 过滤器。

5. 启用游戏内通知并验证

将插件配置设置为:

webhook-notifications:
  enabled: true
  directory: "webhook-events"
  max-age-seconds: 300

这将解析为 /srv/minecraft/plugins/gitpull/webhook-events,并且必须与 Python 编写器的目录匹配。运行 /pull reload,以操作员身份加入游戏,并将一个文本文件(非数据包资源)推送到 main。

检查服务日志:

sudo journalctl -u gitpull-webhook -n 50 --no-pager

更新时会产生 AUTOPULL_RESULT UPDATED <旧版本> <新版本>;若无变化则产生 AUTOPULL_RESULT UNCHANGED <版本>。插件通常在约 2 秒内发送通知,随后删除事件文件。验证完成后,请删除并推送测试文件以检查第二次通知。

已知限制和故障排除

  • 并发 Webhook 和手动拉取: 脚本中的 flock 仅协调 Webhook 脚本。插件会防止并发的插件任务,但两条路径不共享锁。避免同时对同一仓库运行两者;否则可能出现 Git 锁冲突或拉取失败。
  • Webhook 故障通知: 只有成功的更新和已经是最新的结果才会生成事件文件。请检查 Webhook 日志以查看故障、超时和忙(busy)结果。HTTP 200 仅表示请求已确认。
  • 无游戏内通知: 请检查插件是否已加载、事件路径是否匹配、服务账户是否有读写权限,以及玩家是否为操作员或拥有 gitpull.notify 权限。过期的事件会被删除;格式错误的事件文件会被重命名为 .invalid。如果没有符合条件的玩家在线,事件将被记录并消耗,不会在玩家登录时重放。
  • 无声音或重载动作: “已是最新”的结果不会触发任何操作。该动作需要重载权限;手动批量操作也要求所有仓库都成功。客户端音频设置和声音资源决定了播放是否可闻。
  • 文件已更新但游戏玩法未改变: GitPull 不会自动重载数据包。请点击重载动作或运行 /minecraft:reload。这将重载启用的数据包,而不仅仅是更新的仓库。
  • 目录或认证错误: 克隆操作不会覆盖非空且非 Git 仓库的目录。请为实际运行脚本或游戏服务器的账户配置私有仓库凭据。
  • 其他部署限制: 捆绑的 Webhook 脚本针对 Linux 和单个仓库。GitPull 的监听器消费的是文件,而非远程 HTTP 回调。单独的部署需要一个写入者和插件均可访问的通知目录。

开发检查

gradlew build 会编译插件并运行 Java 测试。在 Linux 上,可分别使用以下命令测试 Webhook 脚本和事件写入器:

python3 deploy/test_webhook.py "$(pwd)/deploy/pull-script.sh" "$(pwd)/deploy/gitpull-notify.py"

该测试使用临时 Git 仓库和一个独立的本地 Webhook 进程。它涵盖了更新、未更改的仓库、繁忙执行、失败、超时以及成功的事件发布等场景。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源