Redrx

一个现代化、高性能且功能丰富的自托管 URL 缩短服务，使用 Python (Flask)、PostgreSQL/SQLite、Redis 和 SQLAlchemy 构建。它具有出色的深色 UI、交互式动画、强大的安全协议以及实时的地理分析功能。

在线演示：redrx.eu

## 📖 目录 1. [✨ 功能](#-features) 2. [🏗️ 重定向与安全流程](#️-redirection--security-flow) 3. [🛠️ 技术栈](#️-tech-stack) 4. [🚀 快速开始 (Docker)](#-quick-start-docker) 5. [💻 本地开发设置](#-local-development-setup) 6. [🔧 配置与环境变量](#-configuration--environment-variables) 7. [🔌 REST API 文档](#-rest-api-documentation) 8. [🛡️ 安全与加固](#️-security-and-hardening) ## ✨ 功能 * 🔗 **自定义短码：** 完全自定义或自动生成的、易读的 base62 短键。 * 🔄 **轮换重定向：** 使用单个短链接在多个目标之间轮换目标流量（非常适合 A/B 测试或服务器负载均衡）。 * 🔒 **密码保护：** 使用经过严格密码学验证的访问密码为单个短链接加锁。 * 📅 **计划与过期：** 通过 `start_at` 和 `end_at` 参数设置严格的有效期，或使用自动的生存时间 (TTL) 限制。 * 🎨 **交互式二维码：** 自动生成可自定义的 SVG/PNG 矢量二维码，带有直接指向该短链接的完全自定义颜色。 * 📊 **分析仪表板：** 深入可视化点击计数器、浏览器类型、平台以及实时国家/地区检测（由本地 MaxMind GeoIP 提供支持）。 * 🚨 **钓鱼威慑：** 双阶段安全验证：对照实时钓鱼数据库交叉检查域名创建情况，并自动移除恶意链接。 * ⚙️ **访问控制：** 切换配置以允许/限制公开注册或匿名创建短链接。 * 📦 **严格哈希验证：** 生产锁定通过严格的 SHA-256 完整性验证 (`--require-hashes`) 来保障容器构建的安全。 ## 🏗️ 重定向与安全流程 每个链接请求在解析之前都会经过安全筛查和数据库优化： ``` graph TD A[User requests short code /ABC123] --> B{Phishing Check} B -- Is Domain Blocked? --> C[Return 403 Forbidden] B -- Safe --> D{Expired / Inactive?} D -- Expired/Future Window --> E[Return 404 Not Found] D -- Active --> F{Password Protected?} F -- Yes --> G[Prompt User for Password] G -- Invalid --> G G -- Valid --> H{Rotational Redirect?} F -- No --> H H -- Yes --> I[Resolve Rotated Target] H -- No --> J[Resolve Main URL] I --> K[Update Analytics: GeoIP / User Agent] J --> K K --> L[302 Redirect to Target] ``` ## 🛠️ 技术栈 * **核心后端：** Python 3.14, Flask, SQLAlchemy, Gunicorn (WSGI HTTP 服务器) * **数据处理：** PostgreSQL（强大的关系型存储）、Redis（快速速率限制与会话缓存）、SQLite（弹性本地回退） * **地理位置引擎：** MaxMind GeoLite2 国家/地区映射，带有自动更新本地文件的后台任务 * **实时指标：** 在 `/metrics` 上集成了 Prometheus endpoint 处理程序 * **现代前端：** HTML5, CSS3 (Bootstrap 5 深色模式主题)，自定义 Canvas API 背景动画 ## 🚀 快速开始 (Docker) 通过加载我们经过严格安全哈希验证的生产级镜像，确保安全执行： ### 使用 GHCR 镜像（推荐） 1. 使用 `docker-compose.ghcr.yml` 作为你的模板： services: app: image: ghcr.io/arumes31/redrx:latest ports: - "5000:5000" environment: - SECRET_KEY=your-production-cryptographic-secret - DATABASE_URL=postgresql://redrx:securepassword@db:5432/redrx_db - BASE_DOMAIN=short.yourdomain.com 2. 启动技术栈： docker-compose up -d ### 本地构建 ``` docker-compose up --build ``` 应用程序将启动并在 `http://localhost:5000` 上暴露服务。 ## 💻 本地开发设置 为了将开发包与生产构建安全隔离，依赖项被划分为人工可编辑的模板和严格哈希验证的锁定文件。 ### 1. 结构 * `requirements.txt`：主要的直接运行时依赖源。 * `requirements.lock.txt`：生产锁定版本，使用 SHA-256 包签名 (`--require-hashes`) 生成。 * `requirements-dev.txt`：包含 pytest 在内的开发依赖项。 * `requirements-dev.lock.txt`：开发特定的锁定文件，包含完整的依赖树和哈希。 ### 2. 环境安装 确保激活虚拟环境并运行严格的哈希验证安装： ``` # Windows PowerShell python -m venv venv .\venv\Scripts\Activate.ps1 # 安装带有 secure hashes 的 package set pip install --require-hashes -r requirements-dev.lock.txt ``` ### 3. 执行与测试 将你的本地环境设置为 debug/development 并启动： ``` # 运行 local server $env:FLASK_DEBUG="true" python run.py # 执行完整自动化 test suite（所有 checks 通过） pytest ``` ## 🔧 配置与环境变量 | 类别 | 变量 | 默认值 | 描述 | |----------|----------|---------|-------------| | **核心** | `SECRET_KEY` | - | 用于会话签名和哈希的强加密密钥。在生产环境中强制执行。 | | **域名** | `BASE_DOMAIN` | `short.example.com` | 格式化缩短 URL 时使用的基础主机字符串。 | | **GeoIP** | `MAXMIND_LICENSE_KEY` | - | 下载 GeoIP 数据集并在后台进行更新所必需。 | | **钓鱼** | `ENABLE_PHISHING_CHECK` | `true` | 启用针对实时黑名单的域名保护。 | | **钓鱼** | `ENABLE_AUTO_REMOVE_PHISHING` | `false` | 自动移除重定向到已验证的钓鱼域名的链接。 | | **数据库** | `DATABASE_URL` | - | PostgreSQL URI (例如 `postgresql://user:pass@host:5432/db`)。默认回退到 SQLite 本地文件。 | | **限制** | `RATELIMIT_STORAGE_URL` | `redis://redis:6379` | 速率限制后端。在开发环境中可以回退到本地存储 `memory://`。 | | **访问** | `DISABLE_ANONYMOUS_CREATE` | `false` | 为 true 时，只有经过身份验证的用户才能缩短链接。 | | **访问** | `DISABLE_REGISTRATION` | `false` | 为 true 时，禁用公开注册路由。 | ## 🔌 REST API 文档 有关包含参数表和系统指标的完整详细文档，请访问正在运行的 Redrx 实例上的 `/api-docs` 页面。 ### 身份验证 在请求头中包含你的个人 API 密钥（可在你的用户资料菜单中找到）： ``` X-API-KEY: your_api_key_here ``` ### 缩短 URL `POST /api/v1/shorten` **Payload：** ``` { "long_url": "https://example.com/my-long-link", "custom_code": "my-code", "code_length": 6, "preview_mode": true, "stats_enabled": true, "rotate_targets": ["https://alt1.com", "https://alt2.com"], "ios_target_url": "https://apps.apple.com/app/id123", "android_target_url": "https://play.google.com/store/apps/details?id=com.example", "password": "secret-password", "expiry_hours": 24, "start_at": "2026-06-05T22:00:00Z", "end_at": "2026-06-30T23:59:59Z" } ``` **响应 (201 Created)：** ``` { "short_code": "my-code", "short_url": "https://short.example.com/my-code", "long_url": "https://example.com/my-long-link", "rotate_targets": ["https://alt1.com", "https://alt2.com"], "ios_target_url": "https://apps.apple.com/app/id123", "android_target_url": "https://play.google.com/store/apps/details?id=com.example", "expires_at": "2026-06-06T22:00:00+00:00", "start_at": "2026-06-05T22:00:00+00:00", "end_at": "2026-06-30T23:59:59+00:00", "password_protected": true, "preview_mode": true, "stats_enabled": true } ``` ### 查询链接信息 `GET /api/v1/` **响应 (200 OK)：** ``` { "short_code": "my-code", "short_url": "https://short.example.com/my-code", "long_url": "https://example.com/my-long-link", "rotate_targets": ["https://alt1.com", "https://alt2.com"], "ios_target_url": "https://apps.apple.com/app/id123", "android_target_url": "https://play.google.com/store/apps/details?id=com.example", "preview_mode": true, "stats_enabled": true, "clicks_count": 42, "clicks": 42, "created_at": "2026-06-05T22:00:00+00:00", "expires_at": "2026-06-06T22:00:00+00:00", "start_at": "2026-06-05T22:00:00+00:00", "end_at": "2026-06-30T23:59:59+00:00", "active": true } ``` ## 🛡️ 安全与加固 - **Bandit SAST 引擎：** 持续执行自动化静态安全扫描。 - **依赖项隔离：** 单独的锁定文件将仅用于开发的代码与生产 Gunicorn 引擎隔离开来。 - **锁定验证：** 对锁定文件进行加密验证，以防御供应链攻击。 - **Dependabot 强制执行：** 自动化依赖项跟踪以获取补丁和安全更新。 ## 📄 许可证 该项目在 MIT 许可证下授权。有关详细信息，请参阅 [许可证](LICENSE)。

标签：Flask, PostgreSQL, Redis, Syscall, URL缩短, Web开发, 安全监控, 搜索引擎查询, 测试用例, 网络测绘, 自定义请求头, 自托管, 请求拦截, 逆向工具