推荐用docker部署shlink是因为其封装了php 8.2+、apache、sqlite/postgresql和redis等全部依赖，避免手动配置php.ini扩展、时区、opcache等常见报错；非docker方式需自行确保php版本与扩展、web服务器转发、数据库权限及storage目录可写等复杂条件。
Shlink 不是 apt/yum 直接装的软件，必须用 Docker 或手动部署 PHP 环境；官方明确不支持系统包管理器安装，硬走 apt install shlink 会失败。
为什么推荐用 Docker 部署 shlink 而不是源码安装
Docker 封装了 PHP 8.2+、Apache、SQLite/PostgreSQL 和 Redis 依赖，避免手动配 php.ini 扩展（如 ext-pdo_pgsql、ext-json）、时区、OPcache 等常见报错。非 Docker 方式需自行确保：
• php -v ≥ 8.2 且启用 curl、mbstring、xml
• Web 服务器（Nginx/Apache）正确转发 PATH_INFO
• 数据库用户有建表权限
• storage/ 目录可写且 SELinux/AppArmor 不拦截
docker run 启动 Shlink 的最小可行命令
以下命令用 SQLite 存储、监听宿主机 8080 端口，适合测试或轻量使用：
docker run -d \ --name shlink \ -p 8080:8080 \ -v /opt/shlink/data:/var/www/shlink/data \ -e SHORT_DOMAINS="s.example.com" \ -e DEFAULT_SHORT_DOMAIN="s.example.com" \ --restart=unless-stopped \ shlinkio/shlink:stable
关键点说明：
• /opt/shlink/data 必须提前 mkdir -p 并确保属主为 1001（容器内 shlink 用户 UID）
• SHORT_DOMAINS 必须是真实可解析的域名，否则前端跳转 404
• 若换 PostgreSQL，需额外加 -e DATABASE_URL="pgsql://user:pass@host:5432/shlink" 并连通网络
• 首次启动后，用 docker exec -it shlink shlink short-url:generate --long-url https://example.com 测试生成
Nginx 反向代理到 localhost:8080 的必要配置
直接暴露 :8080 不安全，建议用 Nginx 做 TLS 终止和路径收敛。核心配置段如下：
server {
listen 443 ssl http2;
server_name s.example.com;
ssl_certificate /etc/letsencrypt/live/s.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/s.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_redirect off;
}
}
漏掉这些容易出问题：
• 缺 X-Forwarded-Proto → 后端生成的短链接仍是 http://
• 缺 Host 头 → shlink 无法识别 SHORT_DOMAINS 中的域名
• 没开 http2 或没配证书 → 浏览器提示不安全或跳转失败
首次登录后台和 API 密钥初始化
容器启动后访问 https://s.example.com 会自动跳转到 Web UI，但默认无账号。必须先执行：
docker exec -it shlink shlink user:create --username admin --password 'your_strong_pass'
然后才能登录。API 访问需额外生成密钥：
docker exec -it shlink shlink api-key:generate --description "cli-script"
返回的 api_key 字符串要存好——它不会再次显示，且没有管理界面重置入口。如果误删或忘记，只能进容器手动删 /var/www/shlink/data/config/api_keys.json 并重新生成。
真正卡住人的地方往往不是安装步骤，而是域名解析、反代头字段、容器数据目录权限这三处；调不通时优先检查 docker logs shlink 里有没有 PDOException 或 Permission denied，而不是重装。
