本篇原文来自 https://howtomakehub.pages.dev/，作者 @Yukino_fox ，基于 CC-BY-SA 4.0 获得许可，使用 DeepSeek 网页版整合到了一个页面并优化了措辞。
这几天主要作者 MM 在外不能正常更新所以随便写点东西。
HowToMakeHub 搭建指南
什么是 Hub
Hub 是一个托管在 GitHub 上的图片仓库，配合 koishi-plugin-hub-pusl 插件使用，可以实现：
- Push：在 QQ 群内发送命令 + 图片，Bot 自动上传图片到 Hub 仓库并创建 Pull Request
- Pull：在 QQ 群内发送命令，Bot 从 Hub 仓库随机拉取一张图片发送到群内
Hub 的优势
- 审核机制：图片通过 PR 提交，仓库管理员审核后才合并，确保内容合规
- 去重：同文件名的图片会被拒绝推送，避免重复
- 历史记录：所有图片的提交历史都在 GitHub 上可追溯
- 无重复拉取：Bot 按群记录已发送的图片，避免重复发送同一张图
工作流程
群友发送: nwtf-push 请输入文本 [图片]
↓
Bot 下载图片
↓
检查上游仓库是否已存在同名文件 → 有则拒绝
↓
检查 Token 用户下是否有 Fork → 没有则自动 Fork
↓
同步 Fork 到上游最新
↓
在 Fork 上创建分支并上传图片
↓
从 Fork 向上游创建跨仓库 PR
↓
管理员审核 PR → 合并
↓
群友可通过 nwtf-pull 拉取到这张图片仓库结构
一个标准的 Hub 仓库结构如下：
your-hub-repo/
├── images/
│ ├── 可爱小猫.png
│ ├── 风景照.jpg
│ └── ...
└── README.md所有图片存放在 images/ 目录下，文件名即图片标题。
插件使用
koishi-plugin-hub-pusl 是一个 Koishi 插件，用于在 QQ 群内推送图片到 Hub 仓库并创建 PR，或随机拉取图片到群内。
安装
将插件目录复制到 Koishi 项目的 external/ 下：
cp -r /path/to/HubPuslBot /path/to/koishi/external/koishi-plugin-hub-pusl
cd /path/to/koishi
npm install ./external/koishi-plugin-hub-pusl或者使用 npm pack 打包后安装：
cd /path/to/HubPuslBot
npm pack
cd /path/to/koishi
npm install /path/to/HubPuslBot/koishi-plugin-hub-pusl-0.1.0.tgz配置
| 配置项 | 必填 | 默认值 | 说明 |
|---|---|---|---|
commandPrefix | 是 | nwtf | 命令前缀，命令为 {prefix}-push 和 {prefix}-pull |
githubToken | 是 | - | GitHub Personal Access Token，需要 repo 权限 |
githubRepo | 是 | - | 上游仓库，格式：owner/repo |
baseBranch | 否 | main | PR 目标分支 |
githubMirror | 否 | "" | 镜像前缀，用于 pull 下载图片，例如 https://gh-proxy.org/ |
allowedGroups | 否 | [] | 允许使用的群号列表，为空则允许所有群 |
adminUsers | 否 | [] | 允许 push 的用户 QQ 号，为空则允许所有人 |
imageDir | 否 | images | 图片在仓库中的目录 |
maxFileSize | 否 | 20 | 最大允许图片大小（MB） |
historyPath | 否 | ./hub-pusl-history.json | 群拉取记录文件路径 |
配置示例
plugins:
hub-pusl:
commandPrefix: nwtf
githubToken: ghp_xxxxxxxxxxxx
githubRepo: NoWayToFix/NWTFhub
baseBranch: main
githubMirror: 'https://gh-proxy.org/'
allowedGroups:
- '123456789'
adminUsers:
- '987654321'
imageDir: images
maxFileSize: 20命令
push
nwtf-push <标题> [附带图片]将图片推送到 Hub 仓库并创建 PR。
- 标题会成为文件名（例如
可爱小猫→可爱小猫.png） - 图片可以随命令发送，也可以引用一条带图片的消息
- 同名文件会被拒绝，需要更换标题
- Bot 会自动 Fork 上游仓库，在 Fork 上创建分支并上传，然后创建跨仓库 PR
示例：
nwtf-push 可爱小猫 [发送一张猫的图片]Bot 返回：
图片已推送，PR：https://github.com/NoWayToFix/NWTFhub/pull/1pull
nwtf-pull从 Hub 仓库随机拉取一张图片发送到群内。
- 不会重复发送已发过的图片
- 所有图片都发过后，自动重置记录循环
- 先发送文件名（例如
可爱小猫.png），再发送图片
hub-web 搭建教程
本教程将带你使用 HubWeb-template 模板仓库，通过 Fork 快速搭建一个 hub-web 画廊网站。
前置条件
- Node.js 18+
- 一个已创建好的 Hub 仓库（参考上方「创建你的 Hub」）
- 一个 GitHub 账号
我们提倡 hub 和 hub-web 分开
Hub（图片仓库）和 hub-web（画廊网站）应该是 两个独立的 GitHub 仓库。
- Hub 仓库（如
NoWayToFix/NWTFhub）：纯图片存储，Bot 操作的对象 - hub-web（如
NoWayToFix/NWTFhub-web）：画廊网站，展示图片
不要把 web 代码放进 Hub 仓库，也不要把图片放进 web 仓库。
为什么要分开？
- 职责分离：Hub 只管图片，web 只管展示
- 部署灵活：web 部署到 Cloudflare Pages / Vercel，Hub 保持在 GitHub
- 审核不受影响：Bot 创建的 PR 在 Hub 仓库中审核，web 不参与
- 独立迭代：改网站样式不需要动 Hub，加图片不需要动 web
步骤 1：Fork 模板仓库
- 打开 HubWeb-template
- 点击右上角的 Fork 按钮
- 在弹出页面中，Owner 选择你的 GitHub 账号，Repository name 填写你的 hub-web 仓库名（例如
NWTFhub-web） - 点击 Create fork
Fork 完成后，你会得到一个属于自己的 hub-web 仓库，例如 your-username/NWTFhub-web。
步骤 2：配置 Hub 仓库地址
进入你 Fork 后的仓库，编辑 package.json，找到 getphotos 脚本：
"getphotos": "shx rm -rf temp_repo public/imgs && (git clone --depth 1 https://github.com/YOUR-USERNAME/YOUR-HUB-REPO temp_repo && shx mkdir -p public/imgs && shx cp -r temp_repo/images/* public/imgs/ && shx rm -rf temp_repo) || shx mkdir -p public/imgs"将 YOUR-USERNAME/YOUR-HUB-REPO 替换为你的 Hub 仓库地址，例如 NoWayToFix/NWTFhub。
提交修改：
git add package.json
git commit -m "config: update hub repo address"
git push步骤 3：本地运行
克隆你 Fork 后的仓库到本地：
git clone https://github.com/your-username/NWTFhub-web.git
cd NWTFhub-web安装依赖：
npm install启动开发服务器：
npm run dev打开浏览器访问 http://localhost:5173，你应该能看到瀑布流画廊。如果 Hub 仓库里已经有图片，它们会被自动拉取并展示出来。