koishi-plugin-telegraph-image-manager

在 Koishi 聊天指令中上传、浏览和管理现有 Telegraph-Image 图床。图片仍通过图床自身的上传接口存储，管理结果与网页后台共享。

适配 Koishi 4.18.11；使用官方 OneBot v11 适配器接收 QQ 图片。支持同条消息附图、引用图片消息、图片预览、直链与 Markdown、分页、重命名、收藏、黑名单、白名单和删除确认。

安装

环境要求：Koishi 4.18.11 或兼容的 Koishi 4、Node.js 18.20 以上、已启用的 http 服务，以及正常工作的 OneBot v11 适配器。建议沿用现有 Koishi 的受支持 Node.js 版本。

插件市场

在 Koishi 控制台的「插件市场」中搜索 telegraph-image-manager 并安装。插件名为 telegraph-image-manager，npm 包名为 koishi-plugin-telegraph-image-manager。新版本发布后，市场索引和所用 npm 镜像可能需要一段时间同步。

也可以在 Koishi 项目目录中使用项目原有的包管理器安装：

yarn add koishi-plugin-telegraph-image-manager

使用 npm 的项目执行 npm install koishi-plugin-telegraph-image-manager。不要混用两种包管理器。

安装包

也可从 GitHub Releases 下载 .tgz 安装包。每个版本同时提供源码压缩包和 SHA256 校验文件，变更记录见 CHANGELOG.md。

将安装包放入服务器上的 Koishi 项目目录，即包含 package.json、koishi.yml 和现有依赖锁文件的目录。使用该项目原有的包管理器安装：

yarn add ./koishi-plugin-telegraph-image-manager-0.1.2.tgz

使用 npm 的项目执行下面这一条，不要混用两种包管理器：

npm install ./koishi-plugin-telegraph-image-manager-0.1.2.tgz

Docker 部署需要把安装包放入挂载的 Koishi 项目目录，并在运行 Koishi 的容器内、该目录下执行安装。保留安装包和依赖变更所在的数据卷，确保重建容器后仍能安装依赖。

安装后重启 Koishi，在控制台的「插件配置」中添加 telegraph-image-manager 并填写下列配置。

从 0.1.0 或 0.1.1 的本地安装包升级时，在同一个 Koishi 项目内用上述命令改为按包名安装，或安装新版 .tgz，然后重启 Koishi。沿用原有插件配置即可，列表图片预览默认开启。

连接与授权

| 配置项 | 填写内容 | | --- | --- | | baseUrl | 自己部署的 Telegraph-Image 地址，例如 https://your-site.pages.dev | | adminUser | Cloudflare 中当前的 BASIC_USER，默认填 admin | | adminPassword | 当前的 BASIC_PASS，控制台显示为密码字段 | | adminUsers | 添加你自己的 onebot:QQ号，例如 onebot:123456789 | | uploadUser / uploadPassword | 公开上传时两项留空；启用上传认证时填写对应的专用凭据 |

插件不使用 Telegram Bot Token，也不需要新建机器人或修改现有 OneBot 连接。后台密码不会被写进聊天回复、下载请求或公开上传请求。

填写后启用插件。在 QQ 中发送 图床 身份 可以核对自己的管理员标识，再发送 图床 状态 检查公开配置、发送 图床 列表 验证后台认证。

默认允许 Koishi 权限等级至少为 3 的用户，以及 adminUsers 中精确匹配的用户浏览和管理图库。两者满足其一即可；QQ 群管理员身份本身不等于 Koishi 3 级权限。没有数据库时，可直接使用 adminUsers 授权。

默认普通用户可以上传。uploadAuthority 默认为 1；未使用数据库时，普通用户按 1 级处理。图床管理权限持有者始终可以上传。若只允许管理员上传，将 uploadAuthority 调为 5，并用 adminUsers 指定管理员。

图库权限涵盖整个图床。群内查询的结果会显示在群中，管理操作建议在私聊中执行。列表序号与分页状态按机器人、用户和会话隔离，默认 10 分钟后失效，重启也会清空。

指令

下面的 1 表示当前列表里的序号，也可写 #1。管理指令还接受完整文件 ID 或当前图床的长链接。

| 指令 | 行为 | | --- | --- | | 图床 | 显示指令菜单 | | 图床 身份 | 查看管理员标识和自身权限 | | 图床 状态 | 检查存储、后台是否启用及上传认证要求 | | 图床 上传 加图片 | 上传同一条消息中的图片；也可引用已有图片消息后发送 | | 图床 列表 | 获取带图片预览的第一页，刷新当前会话的序号 | | 图床 下一页 / 图床 上一页 | 翻页并显示对应记录的图片预览 | | 图床 查看 1 | 发送图片预览和直链 | | 图床 链接 1 | 返回直链及 Markdown | | 图床 重命名 1 新名字.png | 修改后台显示名称，允许名称包含空格 | | 图床 收藏 1 | 切换收藏状态 | | 图床 拉黑 1 | 加入黑名单 | | 图床 白名单 1 | 加入白名单，解除黑名单限制并信任该图片 | | 图床 删除 1 | 生成 60 秒有效的删除确认码 | | 图床 确认 ABC123 | 使用机器人刚返回的确认码执行删除 | | 图床 取消 | 取消当前会话的删除申请 |

如 Koishi 设置了指令前缀，需要带上原有前缀；群聊是否需要 @机器人由现有 Koishi 配置决定。可用 command 修改本插件的主指令名。

列表按 Cloudflare KV 游标顺序返回，并非按上传时间排序；内部短链接记录可能造成空页，可以继续翻页。默认每页 5 条，可配置为 1 至 20 条。

每条图片记录的序号和名称下方会附上预览图，即使没有原始文件名、名称仅为文件 ID，也能直接识别图片。QQ 客户端负责缩略显示，点击图片可查看大图。黑名单记录和非图片文件仅保留文字及序号。预览使用图床直链，OneBot 服务需要能够访问这些链接；未在图床创建额外的缩略图文件。

插件配置中的 listThumbnails 默认为开启，关闭后列表恢复为纯文字，单张 图床 查看 1 不受影响。

上传结果可以是图床短链接。管理接口需要完整文件 ID，因此短链接不能直接用于删除或重命名，需要先在列表中选择对应记录。

删除确认绑定申请时选中的完整 ID，之后翻页不会改变删除目标。确认码只允许申请者在原会话使用一次。删除调用原项目的管理接口，移除 KV 管理记录及其短链接映射，不会删除 Telegram 源文件；原有长链接可能仍然可访问，访问还可能重新生成管理记录。不要将其视为源文件彻底删除。

Cloudflare KV 存在传播延迟，刚上传或修改的记录在其他地区不一定立即可见。

网络与图片限制

• 默认每条指令最多上传 3 张图片，单张最大 20 MiB。允许 PNG、JPEG、GIF、WebP、BMP、AVIF；实际文件内容会参与格式校验。
• 下载来源默认允许 *.qpic.cn、*.qq.com、*.qq.com.cn 及图床域名。其他来源需要在 imageHosts 中添加可信域名；禁止本地文件、IP 地址、URL 内账号密码和非标准端口，重定向目标也要通过检查。
• OneBot 应提供图片的 HTTP(S) URL 或 base64 数据。仅提供缓存文件名、文件路径或合并转发外壳的消息无法直接上传。先从合并转发中取出图片，再附图或引用图片消息。
• 默认网络超时为 30 秒，包含读取响应；上传队列串行执行，上次上传结束后默认等待至少 3.5 秒再开始下一任务，最多排队 20 个任务。Telegram 存储建议保留该间隔。
• 使用 Koishi 的 http 服务及其代理配置。服务器需要能够访问 QQ 图片 CDN 和图床；OneBot 服务需要能够访问图床直链，才能发送预览。
• 本插件不会自动重试上传、收藏切换和其他写入请求。若发生超时，请先到网页后台检查结果，再决定是否重新上传或操作。

修改后台密码

在 Cloudflare Pages 项目的「设置」中修改生产环境的 BASIC_PASS，然后重新部署使其生效。用户名对应 BASIC_USER。同步修改 Koishi 插件的 adminPassword / adminUser，保存并重新启用插件。公开上传时保持 uploadUser / uploadPassword 为空。

故障定位

| 现象 | 检查项 | | --- | --- | | 找不到插件 | 确认在实际 Koishi 项目中安装，并重启 Koishi；Docker 中确认目录已持久化 | | 插件未启动 | 确认启用 http 服务，地址完整且账号密码已填写 | | 没有管理权限 | 发送 图床 身份，把显示的完整标识加入 adminUsers | | 认证失败 | 检查当前 BASIC_USER / BASIC_PASS；状态命令本身不验证后台密码 | | 来源域名未被允许 | 检查 OneBot 提供的实际图片域名，按需加入 imageHosts | | 有直链但图片预览失败 | 检查 OneBot 所在服务器能否访问图片直链，以及账号发送图片是否被限制 | | 只有缓存文件名或引用取不到图片 | 检查 OneBot 的图片 URL 和 get_msg 支持；可尝试将图片与上传指令放在同条消息 | | 列表序号失效 | 在当前会话重新发送 图床 列表 | | Dashboard 未启用 | 检查图床是否绑定 img_url KV，绑定后重新部署 |

开发与验证

git clone https://github.com/Lance0174/koishi-plugin-telegraph-image-manager.git
cd koishi-plugin-telegraph-image-manager
npm ci
npm test
npm pack

源码使用 TypeScript，安装包包含编译后的 CommonJS 和类型声明。file-type 通过动态导入加载，安装包无需在服务器上编译。

测试使用 Koishi 4.18.11、官方 Mock 插件 2.6.6、官方 OneBot 适配器 6.9.4、本地 HTTP 图床测试服务和本地 WebSocket 协议端。覆盖权限、真实命令解析、图片内容上传、分页隔离、删除确认、认证隔离、超时、图片来源限制及 OneBot 双向消息转换。所有测试图片和管理操作只发生在本地测试服务中。

接口基于 cf-pages/Telegraph-Image 的现有 /upload、/api/config 与 /api/manage/*。上游代码检查版本为 ef69018df1967708ec026a671e3976f5524ff490。

本地协议测试不等于在你的服务器和实际 QQ 账号上验收；安装启用后，按“身份、状态、列表、上传一张图片、查看”的顺序完成实际连接检查。

发布

主分支和 Pull Request 会执行 CI。维护者更新 package.json、package-lock.json、变更记录和 docs/releases/v版本号.md 后，提交并推送与包版本一致的 v版本号 标签。

标签工作流会验证版本、运行测试、构建安装包、归档标签对应的源码、计算 SHA256 并发布 GitHub Release。工作流只使用仓库的内置令牌，不需要图床或 Telegram 凭据。

npm 发布由维护者单独执行，GitHub 标签工作流不会自动发布到 npm。下载对应 GitHub Release 的 .tgz 并核对 SHA256SUMS.txt，在已登录 npm 的环境中先检查发布内容，再发布同一个安装包：

npm publish ./koishi-plugin-telegraph-image-manager-0.1.2.tgz --dry-run --access public --registry https://registry.npmjs.org
npm publish ./koishi-plugin-telegraph-image-manager-0.1.2.tgz --access public --registry https://registry.npmjs.org

publishConfig 固定使用 npm 官方仓库并公开发布。npm 账号认证仅放在本机 npm 配置或专用凭据管理中，不要提交到仓库。按 Koishi 官方规范，满足命名和依赖要求的 npm 包会自动进入插件市场，通常在发布后 15 分钟内收录。