clockworknowledge/qr-redirector

QR Redirector镜像说明

镜像概述

qr-redirector是一个轻量级FastAPI服务，旨在解决打印QR码后无法灵活变更目标链接的问题。它通过固定公共ID链接维持QR码稳定性，后端可动态修改重定向目标，无需重新生成或打印QR码。

核心功能

• 提供GET /a/{public_id}接口，支持302/307临时重定向至动态目标
• 存储映射关系：生产环境使用PostgreSQL，本地开发可fallback到SQLite
• 管理员API安全：通过X-Admin-Key请求头验证管理操作权限
• 目标验证：通过ALLOWED_REDIRECT_HOSTS限制合法重定向目标主机
• 解析器模式：支持ALLOWED_RESOLVER_HOSTS和RESOLVER_HMAC_SECRET配置实现安全解析
• 监控与日志：结构化记录重定向事件，提供/health健康检查接口
• QR码生成：支持PNG/SVG格式单个生成及批量导出

使用场景

• 营销物料：印刷品QR码可动态指向不同活动页面或促销链接
• 活动管理：临时活动QR码可在结束后重定向至归档页面
• 企业内部：员工工牌/文档QR码可灵活指向更新后的内部资源
• 产品包装：包装QR码可长期指向最新用户指南或售后支持页面

配置说明

部署示例

Docker Run命令

bash
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql://user:password@db:5432/qr_redirector" \
  -e X_ADMIN_KEY="your_secure_admin_key" \
  -e ALLOWED_REDIRECT_HOSTS="example.com,yourdomain.com" \
  clockworknowledge/qr-redirector

Docker Compose示例

yaml
version: '3.8'
services:
  qr-redirector:
    image: clockworknowledge/qr-redirector
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: "postgresql://user:password@db:5432/qr_redirector"
      X_ADMIN_KEY: "your_secure_admin_key"
      ALLOWED_REDIRECT_HOSTS: "example.com,yourdomain.com"
    depends_on:
      - db
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
      POSTGRES_DB: qr_redirector
    volumes:
      - postgres_data:/var/lib/postgresql/data
volumes:
  postgres_data: