Chhoto URL 7.10.3 配置参数详解

目标：本文是 Chhoto URL 的配置篇，给出 v7.10.3 全部 CHHOTO_* 环境变量的口径、默认值与生效实测，覆盖短链生成风格、跳转语义、协议白名单、大小写策略、WAL/ACID 存储矩阵等核心配置组。全部结论基于容器实测与 v7.10.3 源码核对（2026-10-30），部署步骤见《Chhoto URL 7.10.3 Docker Compose 部署指南》，整体认知见《Chhoto URL 介绍与选型指南》。

一、配置机制总览

三个决定运维姿势的机制特性：

• 启动时一次性读取：所有 CHHOTO_* 环境变量在进程启动时读入内存，运行期不会热更新。任何配置变更都要重建容器（docker compose up -d 检测到环境变量变化会自动 recreate），实测重建后新配置立即生效。
• 两个官方核对入口：带认证的 GET /api/getconfig 回显生效配置 JSON，是核对配置是否按预期加载的首选；启动日志也会逐项回显关键配置（站点地址、短链风格、WAL、ACID 级别等）。
• 旧变量名兼容：v7.10.3 仍兼容历史小写变量名（如 site_url、slug_style、redirect_method），命中旧名时启动日志打 WARN 提示升级；新配置一律用 CHHOTO_ 前缀。

二、全量参数表

2.1 服务与前端

2.2 认证与身份

2.3 短链生成

2.4 跳转与协议

默认白名单为 http、https、ftp、magnet 四种（启动日志回显实测：Allowed protocols: {"ftp", "magnet", "https", "http"}）。

2.5 公开模式

2.6 SQLite 存储

三、核心参数实测

3.1 短链风格：Pair 与 UID 的量化差异

v7.10.3 源码口径：Pair 风格词表为 108 个形容词 × 241 个名词 = 26028 种组合（与 Docker 容器命名同源的词表风格），实测自动生成 buck-elastic 这类易读短链；这正是官方「数千条短链就改 UID」建议的量化依据。UID 风格基于 nanoid：

3.2 跳转方法切换

同一环境在 TEMPORARY 与默认 PERMANENT 间切换实测：TEMPORARY 时访问短链返回 307，重建为默认 PERMANENT 后同一短链返回 308——配置确实在进程启动时一次性生效，切换即意味着一次容器重建。

3.3 协议白名单

实测 CHHOTO_EXTRA_PROTOCOLS=tel 后重建：

# tel: 已入白名单，建链成功
curl -s -X POST -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"longlink": "tel:+8612345678901", "shortlink": "call-test"}' http://localhost:8130/api/new
# → {"success":true,...,"shorturl":"http://192.168.1.200:8130/call-test",...}

# file: 在白名单外，被 400 拒绝
curl -s -w " [%{http_code}]" -X POST ... -d '{"longlink": "file:///etc/passwd", ...}'
# → {"success":false,"error":true,"reason":"Invalid longlink!"} [HTTP 400]

3.4 大小写策略与存量兼容

实测 CHHOTO_ALLOW_CAPITAL_LETTERS=True 时创建大写别名 Test-Link 成功；随后把配置恢复为 False 并重建容器，存量链的访问行为：

GET /Test-Link   → 307（存量大写别名照常跳转）
GET /test-link   → 404（查询大小写敏感，小写变体不存在）

结论：大小写开关只约束新建与删除时的别名合法性校验，不影响存量数据的精确匹配跳转。上生产前想清楚要不要开大写——关掉更省心，别名大小写混用是排错重灾区。

3.5 WAL/ACID 组合矩阵

CHHOTO_SQLITE_USE_WAL_MODE 与 CHHOTO_SQLITE_ENSURE_ACID 的四种组合对应不同的 synchronous PRAGMA 级别（源码口径，启动日志实测其中两种）：

默认组合（WAL + ACID）即本专栏部署篇实测所用；不开启 WAL 时启动日志会 WARN Using DELETE journaling mode for database. WAL mode is recommended.。

3.6 过期短链的自动清理

实测证据：早前创建的一条带 expiry_time 的短链在配置变更重建容器后从 /api/all 中消失——过期短链由每小时一轮的后台清理服务（启动日志 Starting database cleanup service, will run once every hour.）在容器启动与整点清理。CHHOTO_PUBLIC_MODE_EXPIRY_DELAY 强制的到期时间走同一清理通道。

四、/api/getconfig 字段对照

GET /api/getconfig（需认证）回显的 JSON 字段与环境变量对应关系（实测原文）：

{"version":"7.10.3","site_url":"http://192.168.1.200:8130","allow_capital_letters":true,
 "public_mode":false,"public_mode_expiry_delay":0,"allowed_protocols":["magnet","ftp","http","tel","https"],
 "slug_style":"UID","slug_length":12,"try_longer_slug":true,"frontend_page_size":10}

注意 getconfig 不回显密码/API Key/OIDC 等敏感项，适合放进部署验收清单而无泄露风险。

五、配置变更实操流程

实测推荐流程（一次完整往返）：

# 1. 改 compose 环境（或叠加 override 文件）
vim compose.yaml
# 2. 重建（环境变量变化会自动 recreate，数据卷不动）
docker compose up -d
# 3. 日志确认关键配置行
docker logs chhoto-url-7.10.3-web | grep -E "redirection|slugs|protocols|pragma|journaling"
# 4. 接口确认生效配置
curl -s -H "X-API-Key: $API_KEY" http://localhost:8130/api/getconfig

本次实测同卷重建往返两轮（Pair/307 → UID/308/tel → 恢复 Pair/307），6 条短链与命中计数全程无损——配置变更不需要备份恢复，数据在 named volume 里与容器无关。

六、易错点清单

七、本专栏系列导航

• 认知与选型：《Chhoto URL 介绍与选型指南》
• 部署实操：《Chhoto URL 7.10.3 Docker Compose 部署指南》
• REST API 的完整端点与调用实测见本专栏下一篇（撰写中）。