特别声明:本文为原创,可自由转载、引用,但需署名作者且注明文章出处,如有侵权请联系!
QSL 卡片制作工具网络版:一个业余无线电爱好者的全栈实践

从本地 HTML 到 Cloudflare 全栈部署,一个人、一个文件、一套完整的 QSL 卡片制作与同步方案。
一、开发背景
作为一名业余无线电爱好者(BG9PZK),每次通联后都需要制作 QSL 卡片寄给对方。传统的 QSL 卡片制作要么依赖专业软件,要么用 PS 手动排版,效率低且难以在多设备间同步配置。

于是我决定自己动手,用最纯粹的技术栈——单个 HTML 文件 + Cloudflare Worker——打造一个开箱即用、支持多端同步、可 API 调用的 QSL 卡片制作工具。
为什么选择单 HTML 文件?
- 零依赖:不需要数据库、不需要后端框架,打开浏览器就能用
- 易部署:扔到任何静态托管(GitHub Pages / Cloudflare Pages / 本地文件)即可运行
- 易维护:所有逻辑在一个文件里,改完直接上传
- 离线可用:本地版完全离线,没网也能做卡片
二、实现功能
2.1 核心制作功能
| 功能 | 说明 |
|---|---|
| 正反面编辑 | 正面/背面独立编辑,一键切换 |
| 通联信息按格填写 | 对方呼号、对方QTH、日期、UTC/北京时间、频率、RST、设备、功率、天线、寄语、操作员 |
| 确认类型 | OUR QSO / YOUR SWL REPORT / EYE QSO(单选) |
| 工作模式 | FM / SSB / CW / FT8 / 自定义模式(单选+输入) |
| EYE QSO 快捷 | 一键清空除日期时间外的所有通联内容,自动填入当前时刻 |
| 回卡请求 | PSE / TNX QSL / VY 73! 勾选显示 |
| 备用信息 1-4 | 自定义名称和内容,传参即显示 |
| UTC 自动换算 | UTC 与北京时间(UTC+8)自动互算 |
| 对方呼号自动大写 | 输入时自动转大写 |
| 输入+下拉联想 | 频率、RST、设备、功率、天线、寄语、操作员支持历史记录联想 |
2.2 图片与元素
| 功能 | 说明 |
|---|---|
| 自定义底图 | 上传本地图片或粘贴图片 URL,支持铺满/完整显示两种模式 |
| 画布尺寸自定义 | 正反面独立设置导出分辨率(默认 1800×1200),支持按底图原始尺寸 |
| 电子签名 | 上传签名图片,可控制正反面显示、拖动位置、滚轮调大小 |
| 呼号印章 | 上传印章图片,同上 |
| 附加图片 A/B | 两张附加图,独立控制正反面显示 |
| 二维码 | 输入内容自动生成二维码,可控制正反面显示、位置、大小;说明文字可独立设置位置、大小、背景色 |
2.3 个人信息与颜色设置
- QTH / ADDR / PC / TEL / EMAIL / QQ / CQ / ITU / Grid,每项独立控制显示与否
- 正面/背面文字颜色独立设置
- 通联信息背景色、备用信息背景色、CQ/ITU/Grid 背景色独立设置
- 对方呼号颜色自定义
2.4 模板管理
- 存新模板 / 更新快照 / 重命名 / 删除 / 应用
- 每个模板有唯一 ID,支持
?tpl=模板ID传参套用 - 模板完整快照(含所有配置)
2.5 多端同步

分享版(未登录):
- GitHub Gist 同步配置
- 首次上传自动创建私有 Gist
- 支持"含图片"同步选项(本地版保留)
个人版(登录后):
- Cloudflare Access 邮箱认证登录
- Cloudflare KV 同步配置
- 自动加载个人底图、签名、印章、呼号、二维码默认值
- 个人图片仅存 URL(环境变量),绝不写进 HTML 源码
2.6 API 接口

/api/card:一键出卡,支持 GET/POST,传通联参数自动生成卡片/api/sync:个人版配置云端同步/api/me:登录态与个人配置查询/api/notice:公告获取- 支持
auto=1自动下载 PNG,side=both/both2导出合并图或两张图 - 完整参数文档:API 使用文档
2.7 其他
- 自动保存:所有配置自动保存到浏览器 localStorage
- 配置导入/导出:JSON 文件备份与迁移
- 定位模式:快捷键 E 拖动元素、滚轮调字号、X 导出当前面
- 恢复默认布局:一键还原所有元素位置
- 系统公告:Worker 环境变量配置,页面顶部横幅显示
- 使用说明:内置详细使用说明 + GitHub Token 获取教程
三、主要界面
3.1 主界面
- 顶部:标题、公告横幅、AUTO-SAVE 状态、登录/退出按钮
- 左侧:正面/背面切换、使用说明、确认类型/工作模式、通联信息表单
- 右侧:实时预览、导出按钮、保存/导入配置、定位模式
- 底部:个人信息与颜色设置、模板管理、在线同步
3.2 通联信息表单
按格填写,顺序清晰:对方呼号 → 日期时间 → 频率/RST → 设备/功率/天线 → 对方QTH → 寄语 → 操作员。
3.3 功能面板
折叠式面板,节省空间:回卡请求、电子签名、呼号印章、附加图片A/B、二维码、个人信息与颜色设置、背面底图、模板管理、在线同步。
3.4 效果展示(个人版)
登录个人版后,自动加载个人底图和配置,通联信息实时叠加显示在卡片上。
四、如何使用
4.1 快速上手(3 步出卡)
- 填通联信息:填写对方呼号、日期时间、频率等字段
- 预览确认:右侧实时预览,确认无误
- 导出:点"导出当前面"或"导出合并图"保存 PNG
4.2 登录个人版
- 点右上角"登录"
- 通过 Cloudflare Access 邮箱验证
- 自动加载个人配置(底图、签名、印章、呼号、二维码)
- 同步走 Cloudflare KV,多设备一致
4.3 GitHub 同步(分享版)
- 展开"在线同步"面板
- 填写 GitHub Token(获取方法)
- 点"上传":首次自动创建私有 Gist 并回填 Gist ID
- 换设备后填同样的 Token + Gist ID,点"下载"即可同步
4.4 API 一键出卡
https://qsl.ttdd.top/api/card?call=BG5XYZ&date=20260904&freq=145.5&mode=FM&auto=1打开链接自动生成并下载 PNG 卡片。
五、技术实现
5.1 技术栈
- 前端:纯 HTML + CSS + 原生 JavaScript(零框架、零构建)
- Canvas 渲染:html2canvas 导出 PNG
- 二维码:qrcode.js 纯前端生成
- 后端:Cloudflare Worker(单文件 JS)
- 存储:Cloudflare KV(个人版配置)、GitHub Gist(分享版配置)
- 认证:Cloudflare Access(零信任邮箱认证)
- 托管:Cloudflare Pages(静态 HTML)
5.2 隐私设计
- 个人图片只存 URL:通过 Worker 环境变量注入,绝不写进 HTML 源码
- 分享版完全脱敏:未登录时使用占位图,不含任何个人信息
- 本地上传图片仅存本地:localStorage + 导出配置带图,不上传服务器
- Cloudflare Access 保护:个人版端点仅本人邮箱可访问
六、部署方式
6.1 文件结构
/ (Cloudflare Pages 根目录)
├── index.html ← 主页面(分享版+个人版合并)
├── api-doc.html ← API 使用文档
└── _worker.js ← Cloudflare Worker(或单独部署)6.2 Worker 环境变量
| 变量 | 说明 |
|---|---|
FRONT_IMG / BACK_IMG | 正反面底图 URL |
SIG_IMG / STAMP_IMG | 签名/印章图片 URL |
IMGA_IMG / IMGB_IMG | 附加图 A/B URL |
MY_CALL | 我的呼号 |
QR_TEXT / QR_CAP | 二维码默认内容/说明 |
ANNOUNCEMENT | 系统公告 |
6.3 Cloudflare Access 配置
- 创建应用保护
/api/me和/api/sync - 策略:仅允许本人邮箱
/api/card和/api/notice保持公开
七、总结
这个项目从一个简单的本地 HTML 工具开始,逐步演进为支持多端同步、API 调用、个人/分享双模式的完整应用。整个过程中坚持几个原则:
- 单文件优先:能不拆就不拆,降低维护成本
- 隐私第一:个人信息绝不进公开源码
- 渐进增强:本地版离线可用,网络版锦上添花
- API 友好:所有功能都能通过参数调用,方便自动化
项目地址:https://qsl.ttdd.top
API 文档:https://qsl.ttdd.top/api-doc.html
呼号:BG9PZK · 73!
















评论列表 (已有0条评论)
消灭零回复