mbrandau/url-shortener

无头URL缩短器镜像文档

镜像概述和主要用途

该镜像是一个基于Node.js、GraphQL和PostgreSQL构建的无头（无UI）URL缩短器。它专注于后端功能，通过GraphQL API提供URL缩短服务，支持自定义授权策略和统计功能，适用于需要集成URL缩短服务的后端应用场景。

核心功能和特性

• GraphQL API：提供完整的GraphQL接口，支持URL的创建、查询、更新和删除操作
• 无UI界面：纯后端服务，不包含前端界面，专注于API功能
• 可配置授权：支持细粒度权限控制，可自定义创建、读取、更新和删除操作的访问权限
• 统计功能：提供URL访问统计能力
• 灵活的ID生成：支持自定义ID生成规则，包括字符集、大小写敏感性、黑名单等配置

使用场景和适用范围

• 需要在后端服务中集成URL缩短功能的开发者
• 构建自定义URL管理系统的项目
• 对URL缩短服务有特定权限控制需求的应用
• 不需要前端界面，仅需API接口的URL缩短场景

详细配置说明

默认配置

json
{
  "access": {
    "create": ["public"],  // 创建权限，"public"表示公开访问
    "read": ["public"],    // 读取权限，"public"表示公开访问
    "update": [],          // 更新权限，空数组表示禁止访问
    "delete": []           // 删除权限，空数组表示禁止访问
  },
  "ids": {
    "alphabet": "123456789abcdefghkmnpqrstuvwxyz",  // 生成短ID使用的字符集
    "caseSensitive": false,  // ID是否区分大小写
    "preserveDeleted": true,  // 是否保留已删除的ID
    "generatorBlacklist": [],  // ID生成器黑名单
    "generatorBlacklistRegex": "ad",  // ID生成器黑名单正则表达式
    "generalBlacklist": [""]  // 通用黑名单
  }
}

部署方法

该URL缩短器依赖PostgreSQL数据库，需通过环境变量进行配置。

环境变量说明

• POSTGRES：PostgreSQL数据库连接字符串，必填
• PORT：服务端口，默认值为80

Docker Compose部署示例

yaml
version: '3'
services:
  app:
    image: mbrandau/url-shortener
    ports:
      - 8081:80  # 端口映射，宿主端口8081映射到容器端口80
    environment:
      POSTGRES: postgres://urlshortener@postgres/urlshortener  # PostgreSQL连接字符串
    links:
      - postgres  # 链接到postgres服务
    depends_on:
      - postgres  # 依赖postgres服务启动
    volumes:
      - ./config.json:/usr/src/app/config.json  # 挂载自定义配置文件
  postgres:
    image: postgres  # 使用官方PostgreSQL镜像
    environment:
      POSTGRES_USER: urlshortener  # PostgreSQL用户名
    volumes:
      - postgres:/var/lib/postgresql/data  # 持久化PostgreSQL数据
volumes:
  postgres: {}  # 定义PostgreSQL数据卷

部署注意事项

1. 需提前准备PostgreSQL数据库，或使用Docker Compose示例中的postgres服务
2. 通过POSTGRES环境变量正确配置数据库连接字符串
3. 可通过挂载config.json文件自定义权限和ID生成规则
4. 根据需要调整端口映射（默认容器端口为80）