shlinkio/shlink

Shlink Docker镜像文档

!https://raw.githubusercontent.com/shlinkio/shlink.io/main/public/images/shlink-hero.png

镜像概述和主要用途

Shlink是一个基于PHP的自托管URL缩短器应用，支持通过命令行界面（CLI）和REST API进行操作。它允许用户在自有域名下生成和管理短链接，实现数据本地化存储和自定义配置，适用于需要控制短链接服务的个人或组织。

核心功能和特性

• 自托管部署：可在私有服务器或容器环境中部署，数据完全自主管理
• 多数据库支持：兼容MySQL、MariaDB、PostgreSQL、Microsoft SQL Server和SQLite
• 双接口操作：提供CLI工具和REST API，满足不同场景下的管理需求
• 环境变量配置：通过环境变量实现灵活的自定义配置，无需修改代码
• 数据持久化：使用本地目录缓存必要信息，支持数据卷挂载
• API密钥管理：通过CLI生成和管理API密钥，确保接口访问安全
• URL统计：支持跟踪短链接访问数据（需配合数据库存储）

使用场景和适用范围

• 个人开发者：需要在自有域名下生成短链接，避免依赖第三方服务
• 企业/组织：内部URL管理、营销活动短链接跟踪、数据隐私保护
• 开发者集成：通过REST API将短链接功能集成到自建应用中
• 自托管服务栈：作为私有服务集群的一部分，提供URL缩短能力

详细使用方法和配置说明

前置要求

• Docker Engine 20.10+ 或兼容的容器运行时
• 数据库服务（MySQL/MariaDB/PostgreSQL等，或使用SQLite文件）
• 网络环境：确保容器可访问数据库（如需远程数据库）

Docker部署方案

1. 基础部署（docker run）

使用docker run命令快速启动容器，通过环境变量配置核心参数：

bash
docker run -d \
  --name shlink \
  -p 8080:8080 \
  -e DB_DRIVER=mysql \
  -e DB_HOST=db-host \
  -e DB_NAME=shlink \
  -e DB_USER=shlink_user \
  -e DB_PASSWORD=strong_password \
  -e SHORT_DOMAIN_HOST=short.example.com \
  -e SHORT_DOMAIN_SCHEMA=https \
  -e INITIAL_API_KEY=your_initial_api_key \
  -v shlink-data:/app/data \
  shlinkio/shlink

2. Docker Compose部署

创建docker-compose.yml文件，整合Shlink和数据库服务：

yaml
version: '3.8'

services:
  shlink:
    image: shlinkio/shlink
    container_name: shlink
    ports:
      - "8080:8080"
    environment:
      - DB_DRIVER=mysql
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_NAME=shlink
      - DB_USER=shlink_user
      - DB_PASSWORD=strong_password
      - SHORT_DOMAIN_HOST=short.example.com
      - SHORT_DOMAIN_SCHEMA=https
      - TIMEZONE=Asia/Shanghai
      - INITIAL_API_KEY=your_secure_api_key
    volumes:
      - shlink-data:/app/data
    depends_on:
      - mariadb
    restart: unless-stopped

  mariadb:
    image: mariadb:10.11
    container_name: shlink-db
    environment:
      - MYSQL_ROOT_PASSWORD=root_password
      - MYSQL_DATABASE=shlink
      - MYSQL_USER=shlink_user
      - MYSQL_PASSWORD=strong_password
    volumes:
      - mariadb-data:/var/lib/mysql
    restart: unless-stopped

volumes:
  shlink-data:
  mariadb-data:

启动服务：

bash
docker-compose up -d

核心配置参数（环境变量）

数据库配置

应用基础配置

安全配置

容器操作

生成API密钥

若未通过INITIAL_API_KEY指定初始密钥，可通过容器CLI生成：

bash
docker exec -it shlink bin/cli api-key:generate

查看容器日志

bash
docker logs -f shlink

执行CLI命令

查看所有可用CLI命令：

bash
docker exec -it shlink bin/cli list

创建短链接（通过CLI）：

bash
docker exec -it shlink bin/cli url:shorten https://example.com/long-url

数据持久化

• 使用Docker卷（如示例中的shlink-data）挂载/app/data目录，确保缓存数据和SQLite文件（如使用）持久化
• 数据库数据需通过数据库自身的持久化方案（如卷挂载）确保不丢失

API使用示例

通过REST API创建短链接（需替换{API_KEY}和{SHLINK_HOST}）：

bash
curl -X POST "http://{SHLINK_HOST}/rest/v3/short-urls" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/very/long/url", "customSlug": "my-short-link"}'

注意事项

• 权限：确保数据卷（/app/data）有正确的写入权限，容器内用户ID为1000
• 数据库迁移：升级Shlink版本时，容器会自动执行数据库迁移，请勿中断该过程
• 备份：定期备份数据库和data目录，防止数据丢失
• 性能优化：对于高流量场景，建议使用APCu缓存（需配置PHP扩展）或RoadRunner运行时

参考链接

• 官方完整文档
• Docker镜像文档
• API文档
• https://github.com/shlinkio/shlink-web-client%EF%BC%88%E5%8F%AF%E7%94%A8%E4%BA%8E%E5%9B%BE%E5%BD%A2%E5%8C%96%E7%AE%A1%E7%90%86%EF%BC%89

---

本产品包含MaxMind创建的GeoLite2数据，可从[***]# Shlink Docker镜像文档

!https://raw.githubusercontent.com/shlinkio/shlink.io/main/public/images/shlink-hero.png

镜像概述和主要用途

Shlink是一款基于PHP的自托管URL缩短器，支持通过命令行界面(CLI)和REST API进行操作。该应用允许用户在自有域名下生成和管理短链接，无需依赖第三方URL缩短服务，适用于需要数据隐私保护和自定义域名的场景。

核心功能和特性

• 自托管部署：可完全部署在私有服务器，数据自主管理
• 多数据库支持：兼容MySQL、MariaDB、PostgreSQL、Microsoft SQL Server和SQLite
• 双接口操作：提供完整CLI工具和REST API，满足不同使用场景
• 环境变量配置：通过环境变量实现灵活配置，无需修改代码
• API密钥管理：支持生成和管理API访问密钥，确保接口安全
• URL访问统计：跟踪短链接访问数据（需配合数据库使用）
• 数据持久化：通过卷挂载实现配置和缓存数据持久化

使用场景和适用范围

• 个人开发者：在自有域名下创建短链接，避免依赖第三方服务
• 企业/组织：内部URL管理、营销活动短链接跟踪、数据隐私保护
• 应用集成：通过REST API将短链接功能集成到自建系统
• 自托管服务栈：作为私有服务集群的一部分，提供URL缩短能力

详细使用方法和配置说明

前置要求

• Docker Engine 20.10+ 或兼容容器运行时
• 数据库服务（可选，使用SQLite可无需独立数据库）
• 网络环境：确保容器可访问数据库（远程数据库场景）

Docker部署方案

1. 基础部署（docker run）

通过docker run快速启动，核心配置通过环境变量传递：

bash
docker run -d \
  --name shlink \
  -p 8080:8080 \
  -e DB_DRIVER=mysql \
  -e DB_HOST=数据库主机IP \
  -e DB_NAME=shlink \
  -e DB_USER=shlink_user \
  -e DB_PASSWORD=安全密码 \
  -e SHORT_DOMAIN_HOST=short.example.com \
  -e SHORT_DOMAIN_SCHEMA=https \
  -e INITIAL_API_KEY=your_secure_api_key \
  -v shlink-data:/app/data \
  shlinkio/shlink

2. Docker Compose部署

创建docker-compose.yml整合Shlink与数据库：

yaml
version: '3.8'

services:
  shlink:
    image: shlinkio/shlink
    container_name: shlink
    ports:
      - "8080:8080"
    environment:
      - DB_DRIVER=mariadb
      - DB_HOST=mariadb
      - DB_PORT=3306
      - DB_NAME=shlink
      - DB_USER=shlink_user
      - DB_PASSWORD=strong_password
      - SHORT_DOMAIN_HOST=short.example.com
      - SHORT_DOMAIN_SCHEMA=https
      - TIMEZONE=Asia/Shanghai
      - INITIAL_API_KEY=your_initial_api_key
    volumes:
      - shlink-data:/app/data
    depends_on:
      - mariadb
    restart: unless-stopped

  mariadb:
    image: mariadb:10.11
    container_name: shlink-db
    environment:
      - MYSQL_ROOT_PASSWORD=root_pass
      - MYSQL_DATABASE=shlink
      - MYSQL_USER=shlink_user
      - MYSQL_PASSWORD=strong_password
    volumes:
      - mariadb-data:/var/lib/mysql
    restart: unless-stopped

volumes:
  shlink-data:
  mariadb-data:

启动服务：

bash
docker-compose up -d

核心配置参数（环境变量）

数据库配置

应用基础配置

安全配置

容器操作指南

生成API密钥

若未设置INITIAL_API_KEY，通过CLI生成：

bash
docker exec -it shlink bin/cli api-key:generate

查看可用命令

bash
docker exec -it shlink bin/cli list

创建短链接（CLI方式）

bash
docker exec -it shlink bin/cli url:shorten https://example.com/长链接

API使用示例

通过REST API创建短链接：

bash
curl -X POST "http://localhost:8080/rest/v3/short-urls" \
  -H "Authorization: Bearer {API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"longUrl": "https://example.com/very/long/url", "customSlug": "自定义标识"}'

注意事项

• 数据权限：确保/app/data目录有写入权限（容器内用户ID 1000）
• 数据库迁移：升级镜像时会自动执行数据库迁移，请勿中断
• 备份策略：定期备份数据库和shlink-data卷数据
• 性能优化：高流量场景建议使用APCu缓存或RoadRunner运行时

参考链接

• 官方完整文档
• Docker镜像文档
• API文档
• https://github.com/shlinkio/shlink-web-client%EF%BC%88%E5%9B%BE%E5%BD%A2%E5%8C%96%E7%AE%A1%E7%90%86%E7%95%8C%E9%9D%A2%EF%BC%89

---

本产品包含MaxMind创建的GeoLite2数据，可从[***]