VPS Tutorials
Shlink on VPS: Private Admin, Short URLs, Analytics and Backups (2026)
Deploy Shlink with private administration and public HTTPS redirects, scope API keys, interpret cached visit data and restore mappings from consistent backups.

A short URL printed on packaging, a card or a QR code must keep resolving after the campaign ends. Self-hosting gives you control over its domain, destination and stored analytics, but continued registration, hosting and recovery remain your responsibility. It does not guarantee that links last forever or that third-party platforms accept the domain.
This guide compares Shlink, YOURLS and Kutt and deploys Shlink with a private management interface, a public redirect endpoint and a database.
| Product | Stack and fit | Verify in your selected release |
|---|---|---|
| Shlink | PHP API, separate web client, database; useful for API-driven multi-domain management | Analytics, QR, geolocation, bot handling, expiry/visit limits and any password-link requirements |
| YOURLS | PHP and database; simple personal shortening with plugins | Multi-domain, QR, geo, limits and other plugin-specific behavior |
| Kutt | Node.js service; personal/team interface | Current domain, database, limits, QR and analytics capabilities |
The original listed first-release years 2019/2009/2020 and highlighted Shlink 5.0 in January 2026; consult current changelogs rather than treating those snapshots as a latest-version recommendation. YOURLS's large plugin ecosystem does not establish that any particular extension is maintained. Container counts of 3, 2 and 2–3 are architecture examples, not universal resource rankings.
- Need APIs, analytics and multiple domains: evaluate Shlink.
- Want a small simple service: evaluate YOURLS and required plugins.
- Prefer Kutt's workflow: check its currently supported features.
- Existing
example.com: uses.example.comorgo.example.com; it needs no additional domain registration, though existing renewal costs remain. - Short extensions such as
.link,.cc,.gsand.me: check purchase, renewal, premium-name and registry conditions. The original's cheap RMB budget is not a worldwide quote. - A brand-related name such as
品牌名.linkcan remain memorable.
Check history, registrar reliability and acceptance in your actual distribution channels. The original names .tk, .ml and .ga as problematic free-domain examples; do not assume they remain free/available or that every domain in a suffix has identical reputation. Unusual suffixes can also encounter app/link-detection restrictions.
After publication, keep old domains registered and resolving even if you introduce a new brand domain. Printed links cannot be edited retrospectively.
A 1 vCPU/1 GB VPS can be a small trial budget, not a guarantee for three containers or high-QPS campaigns. Measure PHP/database/client resources, analytics growth and backups. The original's 1 Mbps estimate is for modest traffic; peaks and API use can differ.
Choose a location reachable by your visitors, and test on the platforms you use. Mainland-China routes and WeChat/QQ restrictions remain regional conditions; do not infer them from interface language.
mkdir -p ~/shlink/db && cd ~/shlink
Create docker-compose.yml. Replace all secrets, keep database/application passwords aligned and use a separate root password. Pin reviewed compatible images, and protect any client configuration containing an API key:
services:
shlink:
image: shlinkio/shlink:stable
container_name: shlink
restart: unless-stopped
environment:
DEFAULT_DOMAIN: s.example.com
IS_HTTPS_ENABLED: "true"
GEOLITE_LICENSE_KEY: 你的MaxMind密钥
DB_DRIVER: maria
DB_HOST: shlink-db
DB_PORT: 3306
DB_NAME: shlink
DB_USER: shlink
DB_PASSWORD: 换成一个强密码
INITIAL_API_KEY: 换成一串长随机字符
TZ: Asia/Shanghai
ports:
- "127.0.0.1:8080:8080"
depends_on:
- shlink-db
shlink-db:
image: mariadb:11
container_name: shlink-db
restart: unless-stopped
environment:
MARIADB_DATABASE: shlink
MARIADB_USER: shlink
MARIADB_PASSWORD: 换成一个强密码
MARIADB_ROOT_PASSWORD: 换成一个不一样的强密码
volumes:
- ./db:/var/lib/mysql
shlink-web:
image: shlinkio/shlink-web-client
container_name: shlink-web
restart: unless-stopped
environment:
SHLINK_SERVER_URL: https://s.example.com
SHLINK_SERVER_API_KEY: 跟上面的 INITIAL_API_KEY 保持一致
SHLINK_SERVER_NAME: 我的短链
ports:
- "127.0.0.1:8081:8080"
DEFAULT_DOMAIN needs a hostname such as s.example.com, not https://s.example.com/. DNS/proxy host routing must match it.
INITIAL_API_KEY bootstraps a key under the installed release's initialization rules; changing environment later is not key rotation. Inspect and rotate keys explicitly, protecting output from public logs:
docker exec -it shlink shlink api-key:list
docker exec -it shlink shlink api-key:generate
docker exec -it shlink shlink api-key:disable 旧key
SHLINK_SERVER_URL is reached by the administrator's browser, not the web-client container. Use a browser-reachable HTTPS URL or private network URL that the administrator can actually access. The web-client key can be delivered to that browser; keep its configuration and UI behind administrator access controls, preferably with limited keys where supported.
GEOLITE_LICENSE_KEY is optional and subject to MaxMind account/license and download rules. Persist appropriate geo data according to Shlink's documentation; do not assume a universal once-per-day quota. Missing geo data can reduce analytics without necessarily disabling redirects.
docker compose up -d
docker compose logs -f shlink
Check database readiness and application logs; depends_on alone does not prove database readiness. Adapt timezone and placeholder server names for your deployment, while preserving the example's intended instant/date semantics.
Point DNS and configure trusted HTTPS:
s.example.com {
encode gzip
reverse_proxy 127.0.0.1:8080
}
admin.example.com {
basicauth {
admin $2a$14$你的密码哈希
}
reverse_proxy 127.0.0.1:8081
}
Use the authentication directive supported by your Caddy version; current releases use basic_auth. Replace the hash and validate before reloading. Keep management port 8081 private and protect its proxy with basicauth or a configured access service. Do not expose an embedded administrator API key through an unprotected client.
Public visitors need the redirect routes on 8080 without an administrator login; API write routes still need their own keys and limits. Do not apply one blanket login to public campaign redirects. See Caddy or Nginx Proxy Manager.
In the web client you can configure supported options:
- A memorable
/launch2026rather than a generated/aB3xK9. - Expiry at an explicit date/time.
- A visit limit such as 1000; this counts accepted visits, not redeemed coupons at an external checkout.
- A QR code, where supported, tested before printing.
docker exec -it shlink shlink short-url:create 'https://example.com/very/long/path?utm_source=xxx' \
--custom-slug launch2026 \
--max-visits 1000 \
--valid-until 2026-12-31T23:59:59+08:00
The CLI example expires at 2026-12-31T23:59:59+08:00. It is an example instant, not a currently offered promotion. Verify flags in your selected version. REST API clients can create batches and UTM destinations; store keys privately, handle errors and avoid accidental duplicates. Review any official browser extension's permissions before supplying access credentials.
- Time distribution reflects requests that reached the service.
- Referrer classification can be missing or affected by browser/privacy behavior; QR scans are not always distinguishable from other traffic.
- Country/city estimates need geo data and are approximate, not confirmed physical locations.
- Device/browser information comes from available request metadata.
- “Unique” versus repeat visits depends on the product's method and privacy settings, not guaranteed person identification.
For editable tracked links, prefer temporary redirects such as 302 with appropriate cache policy. 302 can still be cached under some conditions; it does not guarantee every future click reaches your server. Permanent 301 caching can obscure later visits/destination changes. Check CDN/proxy Cache-Control and bypass rules rather than treating status alone as accurate counting. No redirect choice guarantees SEO outcomes.
Your domain reputation can suffer when an exposed key allows harmful destinations. Keep creation private and review unexpected links:
- Protect keys like passwords; Shlink does not require a public registration service.
- Add measured API rate limits/WAF where appropriate, without assuming they stop every abuse pattern.
- Review unfamiliar creations and traffic spikes.
- Give collaborators scoped keys supported by the installed release, never an unrestricted administrator key by default.
Public redirect access and permission to create/edit links are different capabilities.
Mappings, analytics and configuration are required to restore printed links. For a stopped physical database backup, pause application writers first, then stop the database and archive its files:
cd ~/shlink
docker compose stop shlink-db
tar czf ~/shlink-backup-$(date +%F).tar.gz db docker-compose.yml
docker compose start
Check tar success, restore service after failures, and include privately stored secrets, image/version information and other required configuration. Transfer backups off the VPS and test a restored link.
./db holds the demonstrated MariaDB files. Logical backup through mysqldump or MariaDB's matching dump utility can avoid full downtime. The original command below requires password input and is not a reliable unattended job as written:
docker exec shlink-db mariadb-dump -u shlink -p shlink > ~/shlink-$(date +%F).sql
For automation, prepare a read-only, restricted client option file inside the container, containing a dedicated backup account's credentials. Use a dump command such as mariadb-dump --defaults-extra-file=/run/secrets/backup.cnf --single-transaction shlink, supplied through Docker exec, with output redirected to a private uniquely named file. Check exit status and non-empty output. Single-transaction consistency requires transactional tables and no conflicting schema changes; test restoration, not only archive creation. Never put the real password into a public command/log.
404 redirect: check DEFAULT_DOMAIN, DNS and actual hostname/proxy mapping; domain configuration excludes scheme/slash.
Zero visits: inspect redirect/CDN caching and analytics/privacy/bot settings; changing 301 alone may not resolve it.
Client cannot reach server: inspect SHLINK_SERVER_URL from the browser's network, TLS, CORS and credentials.
Geo download fails: inspect real MaxMind error/quota/license. SKIP_INITIAL_GEOLITE_DOWNLOAD=true is an option to verify for the selected Shlink version, not a guaranteed universal bypass; defer geo initialization only if supported.
WeChat/QQ refuses a link: that channel may restrict reputation or destination. Follow its applicable appeal process; changing domains does not guarantee acceptance. Keep existing published domains alive for other visitors.
Need a new domain: introduce it alongside the old one, verify mappings and keep the old DNS/registration and service working.
Choose a durable domain and maintain private administration, monitoring and tested backups. Self-hosting keeps operational decisions with you; availability and analytics still depend on your service and external platforms.