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

本文详细解析了在Linux系统上安装与配置Shlink短链接服务的两种主流方式——Docker一键部署与源码手动安装，强调PHP 8.4+、必要扩展启用、数据库适配及权限/路由等关键细节，并深入揭示了新手易踩的坑：从SELinux拦截、时区错乱、Nginx 404配置缺失，到CSV导入的时间格式陷阱和反向代理导致的HTTPS重定向失效，帮你避开那些文档不写、报错不说、调试两小时才发现的“真正麻烦”。

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短链工具教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于Linux的知识点！