Shlink 5.1.8 Docker Compose 部署指南

本文基于 shlinkio/shlink 5.1.8 + postgres:16-alpine 双服务栈实测（2026-10-30，Docker Compose 部署全过程与验证回显均为真实运行结果）。

一、部署前准备

宿主机已安装 Docker Engine 与 Compose 插件（安装步骤见《Docker Compose 安装与多容器编排》）。
镜像：shlinkio/shlink:5.1.8（约 465MB）与 postgres:16-alpine（约 420MB）。
端口规划：Shlink HTTP 默认容器内监听 8080；本文宿主侧映射 8132（实验环境 8080 等常用端口已被占用时的做法是换高位端口）；PostgreSQL 宿主侧映射 15432（宿主 5432 被占时的高位映射先例）。
域名规划：短链对外域名 surl.localhost:8132（生产环境换成自有域名）。

二、推荐形态：Shlink + PostgreSQL 双服务编排

工作目录创建 docker-compose.yml（以下为实测原文件）：

name: shlink-5.1.8-stack

services:
  shlink-app:
    image: shlinkio/shlink:5.1.8
    container_name: shlink-5.1.8-app
    ports:
      - "8132:8080"
    environment:
      DEFAULT_DOMAIN: "surl.localhost:8132"
      BASE_URL: "http://surl.localhost:8132"
      IS_HTTPS_ENABLED: "false"
      TIMEZONE: "Asia/Shanghai"
      DB_DRIVER: "postgres"
      DB_HOST: "shlink-db"
      DB_PORT: "5432"
      DB_NAME: "shlink"
      DB_USER: "shlink"
      DB_PASSWORD: "q1w2E3r4"
    depends_on:
      shlink-db:
        condition: service_healthy
    networks:
      - shlink-net

  shlink-db:
    image: postgres:16-alpine
    container_name: shlink-5.1.8-db
    ports:
      - "15432:5432"
    environment:
      POSTGRES_DB: "shlink"
      POSTGRES_USER: "shlink"
      POSTGRES_PASSWORD: "q1w2E3r4"
    volumes:
      - shlink-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shlink -d shlink"]
      interval: 5s
      timeout: 3s
      retries: 10
    networks:
      - shlink-net

volumes:
  shlink-db-data:

networks:
  shlink-net:
    name: shlink-5.1.8-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.56.0/24

要点说明：

DEFAULT_DOMAIN 决定生成短链的域名部分（实测生成 http://surl.localhost:8132/quzuo），必须与对外访问地址一致，否则统计里的 visitedUrl 会出现 localhost:8132 与短链域名不一致的情况（实测即如此）。
depends_on + healthcheck 保证 Shlink 在 PostgreSQL 就绪后才启动，避免首次建表失败。
自定义网络指定子网，避免与宿主机上其他 compose 栈的网段冲突。
IS_HTTPS_ENABLED=false 对应实验环境 HTTP 访问；生产环境建议前面挂反向代理做 TLS（可参考《Nginx Proxy Manager Docker Compose 部署指南》），并把该值改为 true。

三、启动与首次初始化

$ docker compose up -d
 Container shlink-5.1.8-db Started
 Container shlink-5.1.8-db Waiting
 Container shlink-5.1.8-db Healthy
 Container shlink-5.1.8-app Starting
 Container shlink-5.1.8-app Started

$ docker ps --filter name=shlink --format '{{.Names}} {{.Status}} {{.Ports}}'
shlink-5.1.8-app Up 12 seconds 0.0.0.0:8132->8080/tcp
shlink-5.1.8-db  Up 17 seconds (healthy) 0.0.0.0:15432->5432/tcp

Shlink 首次启动会自动在 PostgreSQL 里建表（无需手动执行迁移），全程约 10~20 秒。验证服务健康：

$ curl -s http://localhost:8132/rest/health
{"status":"pass","version":"5.1.8","links":{"about":"https://shlink.io","project":"https://github.com/shlinkio/shlink"}}

生成第一个 API Key（管理短链的凭证，REST API 与 Web 客户端都靠它认证）：

$ docker exec shlink-5.1.8-app shlink api-key:generate
 [OK] Generated API key: "062d8542-f251-43da-a5cc-384cff979418"
 [WARNING] Save the key in a secure location. You will not be able to get it afterwards.

四、SQLite 最简形态（单容器）

仅个人低流量场景使用，一个容器即可运行（SQLite 为默认数据库，无需任何 DB 环境变量）：

name: shlink-5.1.8-stack

services:
  shlink-app:
    image: shlinkio/shlink:5.1.8
    container_name: shlink-5.1.8-app
    ports:
      - "8132:8080"
    environment:
      DEFAULT_DOMAIN: "surl.example.com"
      IS_HTTPS_ENABLED: "true"
    volumes:
      - shlink-data:/etc/shlink/data
volumes:
  shlink-data:

注意：SQLite 数据在容器内 /etc/shlink/data，必须挂卷持久化；统计查询、备份迁移、并发写入能力都不如 PostgreSQL/MySQL 形态，想认真用统计就选独立数据库（PostgreSQL 的部署参考《PostgreSQL 18.6 Docker Compose 部署指南》）。

五、关键环境变量速查（实测有效项）

变量	说明	实测值
`DEFAULT_DOMAIN`	生成短链的域名	`surl.localhost:8132`
`BASE_URL`	服务基础地址	同上
`IS_HTTPS_ENABLED`	短链是否以 https 输出	`false`
`TIMEZONE`	时区（影响统计时间戳）	`Asia/Shanghai`（实测创建时间带 `+08:00`）
`DB_DRIVER`	`postgres` / `mysql` / `sqlite`（默认）	`postgres`
`DB_HOST` / `DB_PORT`	数据库地址端口	`shlink-db` / `5432`
`DB_NAME` / `DB_USER` / `DB_PASSWORD`	数据库三元组	`shlink` / `shlink` / `q1w2E3r4`

全量环境变量（67 项）逐项实测见《Shlink 5.1.8 配置参数详解》；更多运行参数与踩坑见《Shlink 5.1.8 常见问题与进阶实战》。

六、部署验证清单

docker ps 两个容器 Up，db 显示 healthy；
/rest/health 返回 status: pass 与正确版本号；
shlink api-key:generate 能签发 Key；
用 Key 创建一条短链并 curl 跳转（完整操作步骤见《Shlink 5.1.8 REST API 与 CLI 命令详解》）；
重启栈后短链与统计数据仍在（数据卷持久化生效）。

本文是系列第二篇，选型背景见《Shlink 5.1.8 介绍与选型指南》。