VoucherVault 1.30.3 介绍与选型指南

VoucherVault 是什么、能做什么、技术架构与适用边界全解，含 Stocard/OfferKit/Wallos 量化选型对比；基于官方仓库与目录站联网溯源（查询日期 2026-10-25），版本 v1.30.3。

VoucherVaultVoucherVaultDjango优惠券管理2026/10/25

VoucherVault 1.30.3 介绍与选型指南

目标：帮助读者快速理解 VoucherVault 是什么、能做什么、技术架构如何，并通过量化对比给出选型建议。本篇为认知篇，内容基于官方仓库、官方 Wiki 与第三方目录站的联网溯源（查询日期 2026-10-25），不含本地实测环节。

一、环境信息

  • 溯源方式：GitHub 仓库主页 / Releases 页面 HTML、shields.io 徽章 JSON 端点、官方 Wiki、自托管目录站（selfhostedworld / selfhostindex / winterflow.io）
  • 溯源日期：2026-10-25
  • 软件版本：v1.30.3（2026-10-09 发布，当前最新稳定版）
  • 官方仓库：https://github.com/l4rm4nd/VoucherVault
  • 官方镜像：l4rm4nd/vouchervault（Docker Hub）
  • 开源许可：GPL-3.0

⚠️ 注意：网络上部分资料将该仓库误记为 4lch4/VoucherVault，该路径在 GitHub 上并不存在（404）。经实查，官方正确仓库为 l4rm4nd/VoucherVault（维护者 LRVT），本文全部数据均以该仓库为准。

二、软件概述

VoucherVault 是一款开源自托管的 Web 应用，用于数字化存储与管理代金券（voucher）、优惠券（coupon）、会员卡（loyalty card）与礼品卡（gift card）。它解决的问题非常具体：实体卡片容易丢失、遗忘，电子券分散在邮件、短信与各类 App 中难以统一查找，且到期后无人提醒造成浪费。

VoucherVault 提供一个移动端优化的 Web 门户（支持 PWA，可添加到手机主屏像原生 App 一样使用），用户把卡券录入系统后，可以：

  • 以二维码/条形码形式展示核销码，到店直接出示手机扫码；
  • 上传卡券图片、PDF 等附件归档；
  • 记录礼品卡的消费交易历史（余额变动）；
  • 到期前通过 Apprise 通知渠道（邮件、Telegram、钉钉、企业微信等 100+ 渠道）自动提醒；
  • 多用户共享卡券（如家庭成员共享超市会员卡）；
  • 通过 REST API 把卡券统计数据接入 Home Assistant 等仪表盘。

一句话定位：自托管版的 Stocard（欧洲流行的会员卡管理商业 App），数据完全掌握在自己手里。

三、核心架构

VoucherVault 是一个典型的 Django 单体 Web 应用，架构简洁，组件分工明确：

用户浏览器/手机 PWA
        │  HTTPS
        ▼
  反向代理（可选，Nginx/Traefik）
        ▼
  uWSGI 应用服务器（Django 5.x，Python 3.12）
        ├── SQLite3（默认，单文件库）
        ├── PostgreSQL（可选，生产推荐）
        └── Redis（Celery 任务队列中间件）
                ▼
        Celery Worker + Celery Beat
        （每日 09:00 定时扫描到期卡券 → Apprise 发通知）

各层职责：

层组件职责
前端Django 模板 + PWA（django-pwa）移动端优化页面、离线 48 小时缓存、客户端摄像头扫码（1D/2D 条码自动识别类型）
应用层Django 5.2 + uWSGI业务逻辑、用户认证、OIDC SSO、卡券 CRUD、分享、文件上传
任务层Celery + django-celery-beat + Redis周期性到期检查任务（默认每天 09:00），调用 Apprise 发送到期提醒
数据层SQLite3（默认）/ PostgreSQL 16卡券、交易历史、用户、定时任务元数据持久化
通知层Apprise统一通知网关，支持邮件、Telegram、Slack、钉钉、企业微信等 100+ 渠道

💡 技术拓展：持久化数据库有两种可选——

引擎特点适用场景
SQLite3零依赖、单文件、备份即拷贝文件个人/家庭、卡券量千级以内
PostgreSQL并发写入强、生态成熟、可独立备份小团队多人共用、卡券量大、已有 PG 基础设施

两种引擎通过环境变量 DB_ENGINE 一键切换，ORM 层（Django ORM）完全屏蔽差异。本文档体系默认以 SQLite3 快速起步、PostgreSQL 作为生产进阶方案。

四、功能特性

以下特性均来自官方 README 与 Wiki（查询日期 2026-10-25）：

  • 卡券全类型管理：代金券、优惠券、礼品卡、会员卡四类统一入库，支持自定义面值与多币种（汇率通过免费 fixer.io API 获取）；
  • 核销码展示与扫描：录入时可用手机摄像头或上传图片客户端侧扫描条码（自动识别 1D/2D 码类型），核销时以 QR 码/条形码渲染出示；
  • 交易历史：礼品卡支持逐笔记账（消费/充值），实时反映余额；
  • 附件上传：每张卡券可挂图片与 PDF（如卡面照片、活动规则）；
  • 到期提醒：EXPIRY_THRESHOLD_DAYS（默认 30 天）前首次提醒、EXPIRY_LAST_NOTIFICATION_DAYS（默认 7 天）前最后一次提醒，经 Apprise 投递；
  • 多用户与分享：内置 Django 用户体系，卡券可在用户间共享/取消共享；支持 OIDC 单点登录（RS256/HS256）接入企业 IdP；
  • 多语言：英语、德语、法语、意大利语界面；
  • 明暗主题：浅色/深色主题切换；
  • PWA 离线模式：手动开启离线模式后支持 48 小时本地缓存；
  • REST API：/api/get/stats 统计端点，面向 Home Assistant 等外部仪表盘；
  • 安全设计：应用以低权限 www-data 用户运行、CSP 安全头、可配置 HSTS 与安全 Cookie。

五、快速开始（最小可用示例）

官方推荐的最小部署是 SQLite 版 Docker Compose（三步）：

# 1. 建持久化目录
mkdir -p ./volume-data/database

# 2. 授权给应用运行用户（UID/GID 33）
sudo chown -R 33:33 volume-data/*

# 3. 启动栈（应用 + Redis）
docker compose -f docker/docker-compose-sqlite.yml up -d

启动后访问 http://127.0.0.1:8000，默认账号 admin，初始密码由服务首次启动时自动生成并打印到应用日志中（docker compose logs -f 可见）。完整的裸机安装与 Compose 部署实测步骤分别见本专栏《Ubuntu 22.04 安装 VoucherVault 指南》与《VoucherVault Docker Compose 部署指南》。

六、适用场景与限制

适用场景：

  • 个人/家庭：集中管理超市会员卡、电商优惠券、加油卡、礼品卡，到期不浪费；
  • 小型商户/工作室：登记发放给客户的代金券与核销码，员工共享查看；
  • 智能家居玩家：通过 REST API 把「即将到期的卡券数量」挂到 Home Assistant 仪表盘；
  • 隐私敏感用户：不希望把消费卡券数据交给商业 App（Stocard 等）的用户。

已知限制：

  • 官方仅提供 Docker 部署的一手支持（Docker Hub 镜像 + Compose 样例），裸机安装需自行组装 Python 依赖与进程托管（本专栏 B1 篇已补全此路径）；
  • 多语言不含中文界面（英/德/法/意），中文用户需适应英文界面；
  • REST API 目前只读（仅统计端点），不提供卡券 CRUD 的外部写接口；
  • 通知依赖 Apprise 外发渠道，本身不带 SMTP/IM 服务端；
  • GPL-3.0 许可：二次开发并对外提供服务时需开源衍生代码。

七、同类选型对比

卡券/会员卡数字化管理赛道的可选项分为「商业 SaaS/App」与「自托管开源」两类。以下对比数据均为 2026-10-25 实查（星数取 shields.io 徽章 JSON 端点，功能取各官方文档）：

维度VoucherVaultStocardOfferKitWallos
形态自托管 Web（Django）商业移动 App（闭源 SaaS）自托管促销引擎（开发者向）自托管 Web（订阅管理）
数据归属完全自有厂商云端完全自有完全自有
核心定位个人卡券保管+到期提醒个人会员卡保管企业促销/券码规则引擎订阅费用跟踪
条码出示/扫描支持（出示+客户端扫描录入）支持（核心功能）不涉及（API 输出核销逻辑）不支持
到期提醒Apprise 100+ 渠道App 推送需自行编排邮件/Apprise 类渠道
礼品卡余额记账支持交易历史部分支持支持（规则引擎）以订阅周期记账为主
多用户/共享支持 + OIDC SSO家庭共享有限面向租户设计多用户
REST API只读统计端点无开放 API完整读写 API + SDK有限
部署难度中（单容器+Redis 即可起步）零（应用商店）高（需开发对接）低
许可GPL-3.0闭源免费（含广告/数据变现争议）开源开源
GitHub Stars513—（闭源）较小（新项目）5k+
Docker Hub 拉取241k——高

关键差异解读：

  • vs Stocard：Stocard 是体验最成熟的商业 App，但数据存于厂商云、隐私不可控、且其商业模式依赖消费数据变现；VoucherVault 用自托管换来数据主权，代价是需要自己维护服务。注重隐私与数据自主选 VoucherVault，追求零维护选 Stocard。
  • vs OfferKit：OfferKit 是「促销规则引擎」，面向开发者设计券码发放/核销规则并嵌入自有系统；VoucherVault 是「卡券保管柜」，面向终端用户录入与出示已有卡券。两者解决的不是同一层问题。
  • vs Wallos：Wallos 跟踪的是「订阅服务」（Netflix、云服务器等周期性支出），VoucherVault 管理的是「预付卡券」（有面值、有核销码、会过期）。两者互补，可同时在家庭自托管栈中共存。

选型建议：

  • 想要「自己的 Stocard」、卡券量几十到几百张、有 Docker 主机 → 选 VoucherVault；
  • 企业要在自家电商里发券核销 → 选 OfferKit 类规则引擎；
  • 只想跟踪订阅扣费 → 选 Wallos；
  • 完全不想维护任何服务 → 用 Stocard 商业 App。

社区活跃度速览（2026-10-25 实查）：VoucherVault 创建于 2024-07，两年多发布 100+ 个版本（约每周一个 minor/patch），最新 v1.30.3 发布于 2026-10-09，最后提交在 2026 年 10 月，GitHub 513 stars / 27 forks，Docker Hub 累计拉取 241k，属「小众但持续活跃维护」的项目，跟随 Conventional Commits 规范发布。

八、参考链接