dwz-server Docker 部署短链接服务：多域名、A/B 测试和统计配置

1. 场景说明

团队做活动页、邀请链接、文档入口和二维码时，经常会遇到一个问题：链接创建很随意，渠道参数散落在表格和聊天记录里，活动结束后很难统计哪个入口有效。

木雷短网址（dwz-server）可以把这些入口统一管理起来。它支持短链接生成、多域名、A/B 测试、用户权限、点击统计和私有化部署。公开服务 n3.ink 使用的也是这一套短网址产品能力。

本文按 Docker 部署的方式，记录一次最小可运行配置，并说明生产模式需要检查哪些环境变量。

2. 最小 Docker Compose 配置

如果只是单机验证，可以使用 SQLite + 本地缓存，不需要先准备 MySQL 和 Redis。

yaml 复制代码

services:
  dwz-server:
    container_name: dwz-server
    image: docker.cnb.cool/mliev/dwz/dwz-server:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - "./config/:/app/config/"
    environment:
      - TZ=Asia/Shanghai
      - GIN_MODE=release

启动：

bash 复制代码

mkdir -p mliev-dwz/config
cd mliev-dwz
docker compose up -d
docker compose ps
docker compose logs -f dwz-server

首次访问：

text 复制代码

http://服务器IP:8080

安装向导会引导填写数据库、缓存和管理员账号。完成后进入后台：

text 复制代码

http://服务器IP:8080/admin/

3. 健康检查

公开接口里提供了两个健康检查地址：

bash 复制代码

curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/health/simple

/health 返回更详细的数据库、缓存和版本信息；/health/simple 更适合负载均衡探活。

4. 短链接域名配置

短链接对外展示域名由 SHORTLINK_DOMAIN 或配置文件里的 shortlink.domain 控制。

bash 复制代码

export SHORTLINK_DOMAIN=https://n3.ink

如果团队有多个品牌域名，不能只靠一个默认域名。dwz-server 还支持域名管理接口和后台域名管理：

添加 s.example.com 作为活动短链域名。
添加 go.example.com 作为产品内跳转域名。
添加 docs.example.com 作为文档入口域名。

创建短链时指定对应域名，所有域名通过 DNS 和反向代理指向同一个 dwz-server 实例即可。

5. 生产模式：MySQL / PostgreSQL + Redis

文档里给出的部署模式可以分为两类：

模式	数据库	缓存	ID 生成	适合场景
独立模式	SQLite	本地内存	本地	个人、小团队、试用
生产模式	MySQL / PostgreSQL	Redis	Redis	高并发、多实例、正式业务

生产环境建议把数据库和 Redis 显式配置出来：

yaml 复制代码

services:
  dwz-server:
    image: docker.cnb.cool/mliev/dwz/dwz-server:latest
    restart: always
    ports:
      - "8080:8080"
    volumes:
      - "./config/:/app/config/"
    environment:
      - TZ=Asia/Shanghai
      - SERVER_MODE=release
      - DATABASE_DRIVER=mysql
      - DATABASE_HOST=mysql
      - DATABASE_PORT=3306
      - DATABASE_NAME=dwz_db
      - DATABASE_USERNAME=dwz
      - DATABASE_PASSWORD=please-change-me
      - CACHE_DRIVER=redis
      - ID_GENERATOR_DRIVER=redis
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=please-change-me
      - SHORTLINK_DOMAIN=https://your.short.domain
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8.0
    restart: always
    environment:
      - MYSQL_DATABASE=dwz_db
      - MYSQL_USER=dwz
      - MYSQL_PASSWORD=please-change-me
      - MYSQL_ROOT_PASSWORD=please-change-me-too
    volumes:
      - "./data/mysql:/var/lib/mysql"

  redis:
    image: redis:7-alpine
    restart: always
    volumes:
      - "./data/redis:/data"

多实例部署时，CACHE_DRIVER 和 ID_GENERATOR_DRIVER 都建议使用 Redis。否则每个实例的本地缓存和本地 ID 计数互相独立，容易出现缓存不一致或 ID 冲突。

6. A/B 测试接口

dwz-server 支持同一短链接绑定多个目标 URL。创建 A/B 测试时，可以设置策略：

equal：平均分配。
weighted：按权重分配。
custom：自定义策略。

示例：

http 复制代码

POST /api/v1/ab_tests
Content-Type: application/json

{
  "short_link_id": 42,
  "name": "落地页版本测试",
  "strategy": "weighted",
  "variants": [
    { "name": "old", "target_url": "https://example.com/a", "weight": 80 },
    { "name": "new", "target_url": "https://example.com/b", "weight": 20 }
  ]
}

适用场景：

活动页新版小流量验证。
定价页按钮和文案对比。
不同渠道落地页效果比较。
同一个二维码入口背后做分流。

7. 点击统计与分析

点击统计接口支持原始事件列表和聚合分析。

http 复制代码

GET /api/v1/click_statistics?short_link_id=42&page=1&page_size=50

聚合维度包括：

day
hour
country
region
city
device
os
browser
referrer

如果团队做渠道复盘，建议不要只看总点击数，而是按渠道域名、短码和 referrer 拆开看。

8. 常见问题

8.1 8080 端口被占用

可以通过环境变量调整监听端口：

bash 复制代码

SERVER_ADDR=:9090

8.2 JWT_SECRET 忘了改

生产环境必须修改 JWT_SECRET。如果服务运行后再修改，已签发 Token 会失效，用户需要重新登录，但数据不会丢。

8.3 HTTPS 怎么做

建议在 dwz-server 前面放 Nginx、Caddy 或 Traefik 做 TLS 终止。应用本身继续监听 HTTP。

8.4 单实例性能够不够

文档给出的参考值是：独立模式约 1000-3000 QPS；生产模式单实例 10000+ QPS。实际值取决于机器配置、数据库和缓存状态。

9. 小结

短网址系统不是只解决"链接太长"。对团队来说，它还要解决链接创建、域名管理、权限控制、A/B 测试、点击统计和私有化部署。

如果只是试用，SQLite + 本地缓存能很快跑起来；如果进入生产，建议使用 MySQL / PostgreSQL + Redis，并在前面接 HTTPS 反向代理。