域名接口

域名决定短链接的 Host、协议、查询参数透传、短码生成和重复 URL 行为。接口位于 /api/v1/domains，写操作需要 owner 或 admin。

接口列表

方法	路径	说明
POST	/api/v1/domains	创建域名
GET	/api/v1/domains	当前工作区域名列表
GET	/api/v1/domains/active	启用域名列表
PUT	/api/v1/domains/:id	更新
PUT	/api/v1/domains/:id/status	启停
DELETE	/api/v1/domains/:id	删除；应先禁用

创建示例

curl -sS https://s.example.com/api/v1/domains \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Workspace-Id: 1' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "s.example.com",
    "protocol": "https",
    "site_name": "示例短链",
    "is_active": true,
    "pass_query_params": true,
    "random_suffix_length": 2,
    "enable_checksum": true,
    "enable_xor_obfuscation": false,
    "enable_anti_red": false,
    "default_start_number": 0,
    "duplicate_policy": "by_request",
    "description": "营销短链域名"
  }'

domain 只填写 Host 或 Host:port，不要包含协议、路径或 Query。protocol 只接受 http、https。

生成参数

字段	说明
random_suffix_length	随机后缀长度，范围 0–10
enable_checksum	增加校验字符
enable_xor_obfuscation	对发号 ID 做位数保持的混淆
xor_secret	可选十进制密钥；未填时由服务生成
xor_rot	旋转参数，范围 1–63；未填时生成
default_start_number	初始计数，0 表示从 1 开始

为保持历史短码规则一致，更新接口会保留创建时的随机后缀、校验、XOR 和起始值设置。需要不同策略时应创建新域名记录，而不是期待修改后追溯改变既有短码。

重复 URL 策略

• deny：同域名、同规范化目标 URL 已存在时拒绝创建。
• allow：允许为相同目标创建多条短链。
• by_request：由创建短链请求的 find_if_exists 决定返回既有短链或创建新短链。

自定义短码请求不会走“返回既有短链”逻辑。数据库还会保证同域名短码唯一。

域名上线

API 创建记录不会自动修改 DNS、签发证书或配置代理。外部请求 Host 必须与记录一致，反向代理应保留原始 Host。使用宝塔部署时详见宝塔面板安装教程。

相关章节：短链接接口、历史 Base62 ADR。