hypothesis/bouncer

Hypothesis Link Bouncer Service 镜像文档

1. 镜像概述和主要用途

Hypothesis Link Bouncer Service 是一个轻量级链接跳转服务，主要用于管理和重定向各种来源的链接请求。该服务能够跟踪链接点击、实施访问控制，并提供灵活的链接路由规则配置，适用于需要集中管理链接分发和访问分析的场景。

2. 核心功能和特性

• 链接重定向：支持多种重定向策略（301、302、307）
• 点击跟踪：记录访问来源、时间和用户代理信息
• 访问控制：基于IP、地理位置和用户代理的访问限制
• 规则引擎：自定义链接匹配和路由规则
• API支持：完整的RESTful API用于管理链接和查看统计
• 高可用性：轻量级设计，支持水平扩展
• 数据持久化：支持SQLite和PostgreSQL数据库后端

3. 使用场景和适用范围

• 营销活动链接管理：统一管理不同渠道的营销链接，跟踪效果
• 内部资源访问控制：安全地共享内部文档和资源链接
• 短链接服务：创建和管理自定义短链接
• 链接生命周期管理：设置链接过期时间和访问次数限制
• A/B测试：为不同用户群体提供不同的链接目标
• 内容分发：根据用户位置或设备类型提供个性化内容链接

4. 使用方法和配置说明

4.1 基本使用方法

4.1.1 使用Docker Run启动

bash
docker run -d \
  --name link-bouncer \
  -p 8080:8080 \
  -e DATABASE_URL=sqlite:///data/bouncer.db \
  -e SECRET_KEY=your-secret-key \
  -v ./data:/app/data \
  hypothesis/link-bouncer:latest

4.1.2 使用Docker Compose部署

yaml
version: '3.8'

services:
  link-bouncer:
    image: hypothesis/link-bouncer:latest
    container_name: link-bouncer
    restart: always
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=postgresql://user:password@db:5432/bouncer
      - SECRET_KEY=your-secret-key
      - LOG_LEVEL=info
      - REDIRECT_DEFAULT=302
    volumes:
      - ./data:/app/data
    depends_on:
      - db
  
  db:
    image: postgres:14
    container_name: link-bouncer-db
    restart: always
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=bouncer
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

4.2 环境变量配置

4.3 配置文件说明

服务支持通过挂载配置文件进行高级设置，默认配置路径为/app/config.yml。典型配置文件结构：

yaml
server:
  port: 8080
  workers: 4
  timeout: 30s

database:
  url: sqlite:///data/bouncer.db
  pool_size: 10

tracking:
  enabled: true
  exclude:
    - 192.168.0.0/16
    - 10.0.0.0/8

redirect:
  default_status: 302
  trusted_proxies:
    - 10.0.0.0/8

rules:
  - pattern: ^/go/(.*)$
    target: https://example.com/$1
    status: 301
    allowed_ips:
      - 192.168.1.0/24

5. API 接口说明

服务提供以下主要API端点：

5.1 链接管理

GET    /api/links         - 获取所有链接列表
POST   /api/links         - 创建新链接
GET    /api/links/{id}    - 获取单个链接详情
PUT    /api/links/{id}    - 更新链接信息
DELETE /api/links/{id}    - 删除链接
GET    /api/links/{id}/stats - 获取链接统计数据

5.2 健康检查

GET    /health            - 服务健康检查
GET    /metrics           - 性能指标(Prometheus格式)

6. 数据持久化

为确保数据不丢失，建议挂载数据卷到容器的/app/data目录。对于生产环境，推荐使用PostgreSQL数据库而非默认的SQLite。

7. 安全注意事项

• 务必设置强密码的SECRET_KEY
• 生产环境中建议启用HTTPS (可配合反向代理如Nginx实现)
• 限制ADMIN_USER的访问IP
• 定期轮换数据库凭证
• 监控/metrics端点以检测异常流量模式

8. 故障排除

• 服务无法启动：检查数据库连接和文件权限
• 链接重定向失败：检查规则配置和目标URL可达性
• 统计数据不更新：验证tracking.enabled配置是否为true
• 性能下降：检查数据库连接池配置和系统资源使用情况

9. 版本信息

• 最新稳定版本: hypothesis/link-bouncer:latest
• 所有版本可在 https://hub.docker.com/r/hypothesis/link-bouncer 查看

10. 相关资源

• https://github.com/hypothesis/link-bouncer
• 完整API文档
• https://github.com/hypothesis/link-bouncer/tree/main/examples