Linux下安装配置Shlink短链工具教程

本文详细解析了在Linux系统上安装与配置Shlink短链接服务的两种主流方式——Docker一键部署与源码手动安装，涵盖PHP 8.4+环境验证、关键扩展启用、数据库选型（MySQL/PostgreSQL/SQLite）及权限陷阱，强调Docker部署的便捷性与源码部署的灵活性，并深入揭示了反向代理配置、时区设置、CSV数据导入格式规范等易被忽视却极易导致失败的核心细节，帮助开发者避开常见坑点，高效构建稳定可靠的短链接服务。

Shlink 在 Linux 上能直接跑，但必须满足 PHP 8.4+、Composer 和一个支持的数据库（MySQL/PostgreSQL/SQLite），缺一不可。Docker 部署最省事，源码部署更可控，但容易卡在扩展或权限上。

确认 PHP 环境是否达标

Shlink 不兼容 PHP 8.3 及更早版本，php -v 输出必须显示 8.4.x。常见坑点：

• mbstring、xml、curl、pdo_mysql（或对应数据库扩展）必须启用，php -m 里要能看到
• 如果用 Ubuntu/Debian，别只装 php 元包，得单独装扩展：sudo apt install php-mbstring php-xml php-curl php-sqlite3 php-pdo php-mysql
• SELinux 或 AppArmor 可能拦截 Web 服务器读写 /data 目录，临时关掉测试：sudo setenforce 0

Docker 部署：5 分钟跑起来

这是最推荐的方式，避免环境冲突。注意端口、数据卷和时区三个硬性配置：

• 运行命令里必须映射 -p 8080:8080，否则访问不到；若想用 80 端口，宿主机不能有其他服务占着
• -v /opt/shlink-data:/data 是持久化关键，路径要提前 mkdir -p /opt/shlink-data 并 chown 1001:1001 /opt/shlink-data
• 加 -e TZ=Asia/Shanghai 防止统计时间错乱，尤其涉及过期时间或日志分析时
• 启动后等 20 秒再执行：docker exec -it shlink shlink api-key:generate，否则会报 Connection refused

docker run -d \
  --name shlink \
  -p 8080:8080 \
  -v /opt/shlink-data:/data \
  -e TZ=Asia/Shanghai \
  --restart unless-stopped \
  shlinkio/shlink:latest

源码安装：适合需要自定义或调试的场景

不建议新手直接源码装，但如果你要改路由逻辑、加中间件或对接内部认证系统，就得走这条路：

• 克隆后别直接 composer install，先改 .env：填好 DB_DRIVER、DB_HOST、DB_NAME 等，SQLite 可跳过 host/port
• vendor/bin/shlink-installer install 会自动建表、生成 config，但失败时不会提示具体哪步错了，得看 var/log/prod.log
• Web 服务器要指向 public/ 目录，Nginx 示例中必须包含 try_files $uri /index.php?$query_string;，漏了就 404
• CLI 命令如 bin/cli short-url:list 必须在项目根目录下执行，否则报 Could not open input file: bin/cli

导入旧短链数据时的格式陷阱

CSV 导入看着简单，实际字段顺序和空值处理极敏感：

• 首行必须是纯英文标题：long_url,custom_slug,valid_since,valid_until,max_visits,tags，多一个空格或中文冒号都失败
• long_url 列绝对不能为空，https:// 必须写全，example.com 会被拒绝
• 时间字段要用 ISO 8601 格式：2026-04-20T00:00:00+08:00，2026/04/20 或 2026-04-20 00:00 全报错
• 标签用英文逗号分隔：marketing,api，不是 JSON 数组也不是分号
• 执行导入前先用小文件测：php bin/cli import:short-urls /tmp/test.csv，成功后再换全量

真正麻烦的从来不是安装，而是数据库选型和反向代理配置——比如用 Nginx 做 HTTPS 终结时，X-Forwarded-Proto 没传，所有重定向都会变成 http://；又比如选 SQLite 后并发稍高就锁表，这些细节不踩一遍根本意识不到。

今天关于《Linux下安装配置Shlink短链工具教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于Linux的内容请关注golang学习网公众号！