自建短链服务：本地部署 Shlink 管理链接，用 cpolar 给团队临时分享统计数据

自建短链服务本地部署 Shlink 管理链接用 cpolar 给团队临时分享统计数据活动页上线前运营经常会问三个很具体的问题微信群、公众号、邮件里的链接分别有多少人点了点击高峰在哪个时间段老板远程看数据时能不能不让他登录一堆内部系统这类场景不一定要把数据交给第三方短链平台。Shlink 是一个开源自托管短链服务核心能力很直接生成短链、自定义短码、打标签、记录访问次数并在 Web 客户端里查看来源、设备、浏览器、地区等基础统计。本文用 Docker Compose 在本地跑一套 Shlink只创建测试短链和脱敏链接再用 cpolar 开一个短时 HTTPS 入口让运营、市场或老板远程验收统计面板。先把边界说清楚本文只演示测试短链不放真实客户名单、订单参数、内部后台地址不暴露数据库端口、管理密码、服务器目录和 Docker socket不把 Shlink API Key 发到大群cpolar 只短时开放 Web 客户端和 API验收结束立即关闭。长期使用请换正式域名、正式 HTTPS、访问控制、备份、反垃圾策略和权限流程。1. 准备本地目录本文选择 Shlink 作为主角不做 YOURLS 横评。Shlink 服务端负责短链跳转和统计Shlink Web Client 负责可视化管理。数据库用 MariaDB只在 Docker 内部网络里访问不映射到宿主机端口。新建目录mkdir -p ~/demo/shlink-short-url cd ~/demo/shlink-short-url生成一组演示用密码和 API Keyopenssl rand -base64 24 openssl rand -hex 32把生成结果分别填到下面的MARIADB_PASSWORD和INITIAL_API_KEY。API Key 相当于管理凭证只给参与验收的人短时使用。2. 编写 Docker Compose创建docker-compose.ymlservices: shlink-db: image: mariadb:11 container_name: shlink-demo-db restart: unless-stopped environment: MARIADB_DATABASE: shlink MARIADB_USER: shlink MARIADB_PASSWORD: ChangeMe-Shlink-DB-2026! MARIADB_ROOT_PASSWORD: ChangeMe-Root-2026! volumes: - shlink-db-data:/var/lib/mysql healthcheck: test: [CMD, healthcheck.sh, --connect, --innodb_initialized] interval: 10s timeout: 5s retries: 5 shlink: image: shlinkio/shlink:stable container_name: shlink-demo-api restart: unless-stopped depends_on: shlink-db: condition: service_healthy ports: - 127.0.0.1:8080:8080 environment: DEFAULT_DOMAIN: 127.0.0.1:8080 IS_HTTPS_ENABLED: false DB_DRIVER: maria DB_HOST: shlink-db DB_NAME: shlink DB_USER: shlink DB_PASSWORD: ChangeMe-Shlink-DB-2026! INITIAL_API_KEY: replace-with-your-temporary-api-key TIMEZONE: Asia/Shanghai shlink-web: image: shlinkio/shlink-web-client:stable container_name: shlink-demo-web restart: unless-stopped ports: - 127.0.0.1:8081:80 volumes: shlink-db-data:这里有三个安全细节MariaDB 没有ports数据库只在 Compose 内部网络可见。Shlink API 和 Web Client 都绑定到127.0.0.1不会直接暴露到局域网。INITIAL_API_KEY只用于演示和验收发给谁、什么时候撤回都要有记录。启动服务docker compose up -d查看容器状态docker compose ps确认 Shlink API 正常curl http://127.0.0.1:8080/rest/v3/health看到status为pass说明服务端和数据库连接正常。打开 Web 客户端http://127.0.0.1:8081首次进入时添加一个服务器连接Server name本地 Shlink 演示URLhttp://127.0.0.1:8080API key填写INITIAL_API_KEY连接成功后就可以在页面里创建短链、查看列表和统计。3. 创建一条测试短链为了避免把真实业务数据带进演示目标地址使用一个公开测试页。比如https://www.example.com/?utm_sourcewechatutm_mediumtestutm_campaignshlink_demo在 Web 客户端里创建短链时填写Long URL上面的测试地址Custom slugdemo-csdnTagsdemo、wechat、20260725Valid since / valid until按演示周期填写测试结束后让链接失效保存后短链地址为http://127.0.0.1:8080/demo-csdn本地验证跳转curl -I http://127.0.0.1:8080/demo-csdn返回里能看到301或302跳转以及Location: https://www.example.com/...说明短链规则已经生效。如果要模拟不同渠道可以再建两条测试短链短码标签长链接里的渠道参数demo-wechatdemo,wechatutm_sourcewechatdemo-emaildemo,emailutm_sourceemaildemo-bossdemo,boss-reviewutm_sourceboss_review这样运营验收时看到的是“不同渠道短链的访问统计”不是一堆混在一起的点击数。4. 制造几次可验证点击统计面板需要有数据。我们可以用浏览器手动点几次也可以用curl模拟不同来源和设备。下面的命令只访问本地测试短链curl -A Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) \ -e https://mp.weixin.qq.com/ \ -L http://127.0.0.1:8080/demo-csdn -o /dev/null curl -A Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/126 \ -e https://mail.example.local/campaign \ -L http://127.0.0.1:8080/demo-csdn -o /dev/null curl -A Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) Safari/605.1.15 \ -L http://127.0.0.1:8080/demo-csdn -o /dev/null回到 Shlink Web Client进入短链详情页重点看四类数据Visits总点击量是否增加。Referrers来源里是否出现微信文章、邮件活动页或空来源。Devices / Browsers移动端、桌面端、Chrome、Safari 是否被识别。Tags按wechat、email、boss-review过滤时数据是否分开。如果本地没有配置 GeoLite2 数据库地区统计会受限。库存文章和团队验收阶段重点先确认点击量、来源、设备、浏览器和标签维度正式长期环境再补齐 GeoLite2、日志保留周期和隐私说明。5. 设计一个验收口径短链统计最容易吵起来的地方不是工具能不能记录点击而是每个人对“有效点击”的理解不同。为了让远程验收更顺畅建议在开放 cpolar 之前先写清楚验收口径。可以用下面这张表作为 Demo 口径验收项通过标准备注短链跳转访问短链后能跳到指定测试页面不使用真实客户落地页标签分类wechat、email、boss-review能分开筛选每条测试短链至少一个渠道标签点击增长每次访问后统计数能增加刷新面板后核对来源识别带Referer的请求能看到来源域名空来源也要解释清楚设备识别手机、桌面端访问能进入不同设备统计用浏览器或curl -A模拟权限边界验收人只拿到临时 API Key不共享数据库密码和服务器权限这个口径的价值很大运营看渠道市场看点击老板看结论开发看数据是否可复现。大家验收的是短链统计能力不是临时搭一个完整投放系统。6. 用 API 快速核对统计Web 面板适合给非技术同事看API 适合自己核对。把 API Key 放到环境变量里避免每条命令都明文出现export SHLINK_API_KEYreplace-with-your-temporary-api-key查询短链列表curl -s \ -H X-Api-Key: $SHLINK_API_KEY \ http://127.0.0.1:8080/rest/v3/short-urls | jq查询某条短链访问统计curl -s \ -H X-Api-Key: $SHLINK_API_KEY \ http://127.0.0.1:8080/rest/v3/short-urls/demo-csdn/visits | jq这里不是把 Shlink 当 API 调试台而是用接口确认面板数据来源面板里的访问次数、来源、设备统计最终都来自短链服务自己的访问记录。验收时如果有人质疑“面板是不是缓存”可以用这两条命令现场交叉验证。7. 用 cpolar 临时开放远程验收入口远程验收有一个容易踩的坑Shlink Web Client 是前端页面它需要从浏览器访问 Shlink API。因此只开放 Web 端口还不够浏览器仍然连不到你电脑上的127.0.0.1:8080。做法是开两个 cpolar HTTPS 隧道一个给 API一个给 Web Client。在本机启动 API 隧道cpolar http 8080记录生成的 HTTPS 地址例如https://shlink-api-demo.cpolar.top再打开一个终端启动 Web Client 隧道cpolar http 8081记录 Web 地址例如https://shlink-web-demo.cpolar.top把 Web 地址发给参与验收的人。对方打开 Web Client 后添加服务器连接Server nameShlink 临时验收URLhttps://shlink-api-demo.cpolar.topAPI key单独私发临时 API Key不发到公开群然后让对方只做三件事打开短链列表确认demo-csdn、demo-wechat、demo-email等测试短链存在。进入详情页查看总访问量、来源、设备、浏览器、标签过滤结果。按验收口径截图或记录结论不修改生产链接、不新增真实投放链接。如果还要让远程同事测试短链跳转就把 API 隧道里的短码地址发给他https://shlink-api-demo.cpolar.top/demo-csdn访问后刷新统计面板点击数会增加。这里的短链仍然只指向测试地址不承载真实推广活动。8. 远程验收时怎么演示建议按固定顺序演示避免对方一上来就改链接或误删测试数据。第一步先打开 Web Client 的短链列表让对方看到三条测试短链都在demo-wechat、demo-email、demo-boss。此时重点讲清楚“短码”和“长链接”的关系短码负责对外传播长链接里可以带 UTM 参数标签用于后台筛选。第二步打开demo-csdn的详情页展示总访问量、最近访问时间、来源和设备。这里不要追求数据很漂亮演示数据本来就是可控样本重点是让对方确认“从点击到统计面板更新”的链路完整。第三步让远程同事访问一次https://shlink-api-demo.cpolar.top/demo-csdn访问完成后刷新短链详情页。看到访问次数增加就说明外网入口、短链跳转、统计写入和 Web 面板读取都跑通了。第四步切换到标签筛选。例如只看wechat标签下的短链再切到email标签。这个动作能帮助运营理解以后每个渠道单独生成短链复盘时就不用从一大堆混合点击里手工拆数据。第五步明确告诉参与验收的人这次只看测试链接和脱敏数据不在临时环境里创建正式投放链接如果需要正式投放要走长期环境的域名、权限、备份和审计流程。9. 验收结束后的收尾动作远程验收结束不要让临时入口继续挂着。按顺序处理# 1. 在运行 cpolar 的两个终端里按 CtrlC关闭临时 HTTPS 隧道 # 2. 清理本机环境变量 unset SHLINK_API_KEY # 3. 停止演示服务 cd ~/demo/shlink-short-url docker compose down如果这套环境后续还要继续用只停止容器即可如果确认演示数据也要删除再执行docker compose down -v-v会删除 MariaDB 数据卷短链和统计记录一并清空执行前要确认不需要保留。10. 长期使用时要补的生产项本文是本地演示和短时验收方案不能直接当生产上线清单。长期运行 Shlink需要补齐这些项正式域名短链域名要稳定不能依赖临时隧道地址。HTTPS使用反向代理或托管证书保证后台和短链访问都是 HTTPS。访问控制API Key 分人分用途管理离职、外包结束、活动结束后及时撤销。备份MariaDB 定期备份并验证恢复流程。反垃圾限制公开创建短链避免被滥用成垃圾链接跳板。数据合规统计数据只保留必要字段避免把用户手机号、订单号、内部 token 拼进长链接。最小暴露面数据库、宿主机目录、Docker socket、SSH、管理面板都不要直接公网开放。小结这套流程解决的是“短链统计怎么让团队快速验收”的问题Shlink 在本地负责短链、标签和访问统计Docker Compose 保证服务可复现cpolar 提供短时 HTTPS 入口让运营、市场或老板在外网查看统计面板。真正关键的不是把工具跑起来而是把边界守住只用测试短链和脱敏数据远程只开放 Web/APIAPI Key 私发给验收人验收结束关闭 cpolar。这样既能让团队看到点击量、来源、设备等基础数据又不会把数据库、管理密码和内部系统一起暴露出去。