serverless-qrcode-hub 部署教程：微信群活码与短链的 Serverless 方案

微信群二维码有个天然的毛病：7 天过期、满 200 人失效。海报印出去了、公众号文章发出去了，码一失效，所有入口全废。serverless-qrcode-hub 解决的就是这一件事——给你一个永久短链，指向哪张二维码由你在后台随时改。

先纠正一个流传很广的错误：不少转载教程里的仓库地址写的是 github.com/用户名/serverless-qrcode-hub（连中文占位符都没替换），点开必然 404。正确地址是 xxnuo/serverless-qrcode-hub（Apache-2.0 许可证）。

还要注意一次架构迁移：项目早期基于 KV 存储，作者发现「KV 的免费额度太少」，已改为基于 D1 存储。基于 KV 的最后版本是 v1.2.0，官方明确标注不建议再使用；老用户升级看仓库里的 MIGRATE.md。所以网上凡是让你「创建 KV 命名空间、改 kv_namespaces」的教程，都是同一个坑。

一、它能做什么

🔗 生成永久短链接，指向微信群二维码（海报、文章里只放这一条）
😋 顺便当通用短链生成器用
🎨 自定义二维码样式与 Logo
💻 管理后台随时更新跳转目标，不用重新印物料
🔐 密码保护，别人拿到域名也进不去后台
☁️ 全程 Serverless，不需要服务器

最新一次更新是 2026-03-07：优化界面、新增自定义提示信息功能、优化桌面与移动端布局。

可以先拿官方 Demo 试手感：qrdemo.2020818.xyz（密码 demo）。

二、部署前准备

项目	说明
Cloudflare 账号	D1 与 Workers 都在这里创建
GitHub 账号	需要 Fork 仓库，Cloudflare 从你的 Fork 拉代码
自定义域名（建议）	`*.workers.dev` 在国内访问很慢，长期用建议绑定

三、第一步：创建 D1 数据库

Cloudflare 控制台 → 左侧 存储和数据库 → D1 SQL 数据库
点右上角创建

在 Cloudflare 控制台创建 D1 数据库：进入「存储和数据库 → D1 SQL 数据库」后点右上角创建

给数据库起个名字（如 qrcode_hub），位置保持默认即可——D1 会自动把数据放在离你最近的可用区域

创建完成后进入数据库详情页，复制那个 database_id，下一步要用

四、第二步：Fork 仓库

打开 xxnuo/serverless-qrcode-hub，点右上角 Fork，复制到你自己的账号下。

五、第三步：改 wrangler.toml

进入你 Fork 的仓库，打开 wrangler.toml，点编辑按钮，把 d1_databases 段里的 database_id 换成上一步复制的值：

toml

[[d1_databases]]
binding = "DB"
database_name = "qrcode_hub"
# 必须替换成你自己的 D1 数据库 id，否则跑不起来
database_id = "换成你的 database_id"

binding 必须保持 DB，这个名字是代码里写死的，改了就连不上库。

六、第四步：创建 Worker 并部署

回到 Cloudflare 控制台 → Workers 和 Pages → 创建应用程序
选择 连接到 Git，选中你刚 Fork 的仓库
直接点右下角 保存并部署

部署成功后访问分配的域名，就能看到登录页了。

七、第五步：设置访问密码（密钥变量，不是在网页里设）

这一步最容易做错。密码不是在前端页面上设置的，而是作为 Cloudflare 的 Secret 变量注入的：

进入 Workers & Pages → 你的 Worker → 设置 → 变量和机密，添加一个类型为「密钥」的变量：

变量名	类型	值
`PASSWORD`	密钥（Secret）	只含英文字母和数字，尽量长且复杂；推荐用两段随机 UUID 拼起来

保存后重新部署一次，再用这个密码登录后台。

别用 admin123 这类密码——短链后台一旦被撞开，别人就能把你的活码改成任意网址。

八、第六步：绑定自定义域名

在 Worker 详情页 → 设置 → 域和路由 → 添加自定义域，填一个托管在 Cloudflare 的子域名（如 qr.你的域名），等证书签发完成。

这样海报上印的就是 https://qr.你的域名/xxx 这种干净短链，而不是一长串 *.workers.dev。

九、日常怎么用

1. 创建一条普通短链

登录后台 → 添加普通短链 → 填路径、目标 URL、可选名称与过期时间 → 保存。

2. 创建微信群活码

登录后台 → 添加微信二维码 → 上传群二维码图片、设置路径与名称 → 保存。

之后群满了要换新码，只需回后台把这张图替换掉，之前发出去的海报和短链全部继续有效——这正是「活码」的意义。

3. 管理已有条目

后台可以查看、编辑、删除所有短链与活码，也能看到二维码的生成效果。

十、功能边界（官方 TODO，尚未实现）

知道它不做什么，比知道它做什么更重要：

定时检查过期短链、自动清理过期数据、邮件通知
访问统计（想统计点击请另配统计服务）
批量导入导出
多租户、多语言
手机端快捷更新二维码

也就是说，它是个趁手的单用户小工具，不是短链平台。要做多用户或统计，得自己二次开发。

十一、常见问题排查

现象	可能原因	处理
点开仓库 404	教程里的地址是 `用户名` 占位符	用 `xxnuo/serverless-qrcode-hub`
改了 KV 却跑不起来	新版已改 D1	按本文用 `d1_databases` 配置
部署成功但打开报错	`database_id` 没换成自己的	改 `wrangler.toml` 后重新部署
忘了密码	Secret 不可回读	重新设置 `PASSWORD` 变量后再登录
国内访问慢	用的是 `*.workers.dev`	绑定自定义域名
老版本数据要保住	从 KV 迁到 D1	按仓库 `MIGRATE.md` 操作

十二、额度与合规

D1 免费额度：项目作者的说法是「500 万次读取够用了」——相比 KV 的免费额度宽裕得多，这正是迁移的原因
合规提醒：活码本质上是一个你自己的跳转入口，请用于合规的社群运营场景，不要拿它做诱导分享或违规引流

写在最后

这个项目真正解决的，是「入口稳定性」这个被长期忽视的问题。

你会为文章配图、为域名续费，却常常忽略「海报上的二维码 7 天后就死了」。活码把这一层抽出来之后，物料和内容可以脱离二维码本身而长期有效——这才是它值得自建的理由，而不是省下那点短链服务费。

配好之后建议做两件事：把 PASSWORD 存进密码管理器；给 D1 里的数据偶尔导出一次备份——虽然内容不多，但那是你所有对外入口的映射表。

serverless-qrcode-hub 部署教程：微信群活码与短链的 Serverless 方案

摘要