YOURLS 1.10.6 配置参数详解

YOURLS 1.10.6 配置参数详解：config.php 参数全集与容器环境变量映射、数据库/站点/短码/认证/运维五类参数逐项说明、生产配置模板与实测验证。

YOURLSYOURLSPHPMySQL2026/10/30

YOURLS 1.10.6 配置参数详解

‍‍​​‌​> 目标：逐项讲清 YOURLS 1.10.6 的全部配置参数——user/config.php 的官方样例全集、容器形态的环境变量映射，以及源码中可用的进阶常量，每项配默认值、取值说明与实测验证。本文基于 2026-10-30 在 Ubuntu 22.04 服务器上的 1.10.6 实例（部署过程见 《YOURLS 1.10.6 Docker Compose 部署指南》）实测与官方源码实查写成。

一、环境信息

  • 操作系统：Ubuntu 22.04（IP 192.168.1.200）；
  • YOURLS：1.10.6（官方镜像内 Apache 2.4.69 + PHP 8.5.12），数据库 MySQL 8.0；
  • 配置载体：容器形态为 compose environment 环境变量（实例实测），裸机形态为 user/config.php；
  • 参数依据：官方源码包 user/config-sample.php（97 行，tag 1.10.6，2026-10-30 自 codeload.github.com 下载）、官方镜像实际生成的 user/config.php、源码 includes/Config/ 与 includes/functions-*.php 中的常量定义点；
  • 演示账号：admin / q1w2e3r4。

二、前置条件

  • 已完成一份可运行的 YOURLS 1.10.6 部署（容器或裸机均可，部署步骤见 《YOURLS 1.10.6 Docker Compose 部署指南》）；
  • 理解两个配置入口的关系：容器形态下 user/config.php 由官方镜像 entrypoint 根据环境变量生成（内容是读取 YOURLS_* 环境变量的 PHP 代码），改配置应改 compose 的 environment 后重启；裸机形态下 user/config.php 是唯一配置文件，直接编辑生效（无需重启 Web 服务，PHP 每次请求重新加载）。

三、参数查看与修改方式

3.1 查看当前生效配置

裸机/通用形态：直接读实例的配置文件（容器内路径 /var/www/html/user/config.php）：

cat /opt/yourls/user/config.php

实测回显（官方镜像 1.10.6 生成的容器版配置，节选核心段）：

define( 'YOURLS_DB_USER', getenv_container('YOURLS_DB_USER', 'root') );
define( 'YOURLS_DB_PASS', getenv_container('YOURLS_DB_PASS') );
define( 'YOURLS_DB_NAME', getenv_container('YOURLS_DB_NAME', 'yourls') );
define( 'YOURLS_DB_HOST', getenv_container('YOURLS_DB_HOST', 'mysql') );
define( 'YOURLS_DB_PREFIX', getenv_container('YOURLS_DB_PREFIX', 'yourls_') );
define( 'YOURLS_SITE', getenv_container('YOURLS_SITE', 'https://your-own-domain-here.com') );
define( 'YOURLS_HOURS_OFFSET', filter_var(getenv('YOURLS_HOURS_OFFSET'), FILTER_VALIDATE_INT) ?: 0 );
define( 'YOURLS_LANG', getenv('YOURLS_LANG') ?: '' );
define( 'YOURLS_UNIQUE_URLS', getenv('YOURLS_UNIQUE_URLS') === false ?: filter_var(getenv('YOURLS_UNIQUE_URLS'), FILTER_VALIDATE_BOOLEAN) );
define( 'YOURLS_PRIVATE', getenv('YOURLS_PRIVATE') === false ?: filter_var(getenv('YOURLS_PRIVATE'), FILTER_VALIDATE_BOOLEAN) );
define( 'YOURLS_COOKIEKEY', getenv('YOURLS_COOKIEKEY') ?: '61b8b08a4a045282f19d73274a9813e391b56fd4' );
$yourls_user_passwords = [
    getenv_container('YOURLS_USER') => getenv_container('YOURLS_PASS'),
];
define( 'YOURLS_URL_CONVERT', filter_var(getenv('YOURLS_URL_CONVERT'), FILTER_VALIDATE_INT) ?: 36 );
define( 'YOURLS_DEBUG', filter_var(getenv('YOURLS_DEBUG'), FILTER_VALIDATE_BOOLEAN) );
define( 'YOURLS_NO_VERSION_CHECK', getenv('YOURLS_NO_VERSION_CHECK') === false ?: filter_var(getenv('YOURLS_NO_VERSION_CHECK'), FILTER_VALIDATE_BOOLEAN) );
define( 'YOURLS_NOSTATS', filter_var(getenv('YOURLS_NOSTATS'), FILTER_VALIDATE_BOOLEAN) );

可见官方镜像把每个参数的真实默认值都写进了生成逻辑（如 YOURLS_URL_CONVERT 默认 36、YOURLS_HOURS_OFFSET 默认 0），这正是本文参数总览的默认值依据。

3.2 修改参数（容器形态）

改 compose 的 environment 后重建服务：

cd /opt/yourls/compose
docker compose up -d

实测回显（本文在实验中把 YOURLS_UNIQUE_URLS 置 false、YOURLS_URL_CONVERT 置 62 后重建）：

 Container yourls-1.10.6-web Starting
 Container yourls-1.10.6-web Started

3.3 修改参数（裸机形态）

编辑 user/config.php 对应行保存即可（PHP-FPM/Apache mod_php 每次请求都会重新读取，无需重启服务；如装了 OPcache 预加载需另行刷新）。修改后验证方式：刷新管理后台，或用 API 触发一次读配置的行为（如创建短链观察短码进制变化）。

四、参数总览

YOURLS 1.10.6 的全部用户可配置参数（来源：config-sample.php 全集 + 官方镜像生成配置 + 源码 defined() 检查点，2026-10-30 实查）：

参数类型默认值作用域
YOURLS_DB_USER常量root数据库连接
YOURLS_DB_PASS常量空数据库连接
YOURLS_DB_NAME常量yourls数据库连接
YOURLS_DB_HOST常量localhost数据库连接
YOURLS_DB_PREFIX常量yourls_数据库连接
YOURLS_SITE常量无（必填）站点
YOURLS_LANG常量空站点
YOURLS_HOURS_OFFSET常量0站点
YOURLS_URL_CONVERT常量36短码
YOURLS_UNIQUE_URLS常量true短码
$yourls_reserved_URL数组7 个敏感词短码
YOURLS_PRIVATE常量true认证安全
$yourls_user_passwords数组空（必填）认证安全
YOURLS_COOKIEKEY常量自动随机认证安全
YOURLS_NO_HASH_PASSWORD常量未定义（false）认证安全（进阶）
YOURLS_DEBUG常量false运维开关
YOURLS_NO_VERSION_CHECK常量true（容器）运维开关
YOURLS_NOSTATS常量false运维开关
YOURLS_FAST_INIT常量未定义（false）运维开关（进阶）
YOURLS_CONFIGFILE常量未定义（自动定位）运维开关（进阶）

💡 说明：YOURLS_SITE 与 $yourls_user_passwords 是仅有的两个必填项——缺了它们 YOURLS 拒绝运行；其余参数均有合理默认值。表中「常量」指 config.php 里的 define() 项，「数组」指 PHP 数组赋值项。

五、核心参数分类详解

5.1 数据库连接参数（5 项）

官方样例原文（config-sample.php）：

/** MySQL database username */
define( 'YOURLS_DB_USER', 'your db user name' );

/** MySQL database password */
define( 'YOURLS_DB_PASS', 'your db password' );

/** The name of the database for YOURLS
 ** Use lower case letters [a-z], digits [0-9] and underscores [_] only */
define( 'YOURLS_DB_NAME', 'yourls' );

/** MySQL hostname.
 ** If using a non standard port, specify it like 'hostname:port', e.g. 'localhost:9999' or '127.0.0.1:666' */
define( 'YOURLS_DB_HOST', 'localhost' );

/** MySQL tables prefix
 ** YOURLS will create tables using this prefix (eg `yourls_url`, `yourls_options`, ...)
 ** Use lower case letters [a-z], digits [0-9] and underscores [_] only */
define( 'YOURLS_DB_PREFIX', 'yourls_' );

逐项说明：

  • YOURLS_DB_USER / YOURLS_DB_PASS：连接凭据。官方镜像默认用户 root；独立业务账号是更安全的做法（本文实例用 yourls / q1w2e3r4）；
  • YOURLS_DB_NAME：库名，仅允许小写字母、数字、下划线（官方注释原文约束）；
  • YOURLS_DB_HOST：主机名，非标端口直接用 host:port 形式（官方注释给出 localhost:9999 示例），没有独立的 DB_PORT 参数——这是 YOURLS 与多数软件不同的一点；
  • YOURLS_DB_PREFIX：表前缀，决定建出来的三张表名。实测本实例为默认值 yourls_，库内实际表结构：
docker exec yourls-1.10.6-mysql sh -c 'mysql -uyourls -pq1w2e3r4 yourls -e "SHOW TABLES; DESCRIBE yourls_url;"'

实测回显：

Tables_in_yourls
yourls_log
yourls_options
yourls_url
Field	Type	Null	Key	Default	Extra
keyword	varchar(100)	NO	PRI		
url	text	NO	MUL	NULL	
title	text	YES		NULL	
timestamp	timestamp	NO	MUL	CURRENT_TIMESTAMP	DEFAULT_GENERATED
ip	varchar(41)	NO	MUL	NULL	
clicks	int unsigned	NO		NULL

💡 技术拓展：表前缀的实际价值不是「安全混淆」而是一库多应用——同一 MySQL 库里跑多套独立 YOURLS 实例时，用不同前缀（如 site1_/site2_）即可隔离表集。keyword 主键长度 varchar(100) 意味着短码最长可到 100 字符，日常远用不满。

5.2 站点参数（3 项）

/** YOURLS installation URL
 ** All lowercase, no trailing slash at the end.
 ** If you define it to "https://sho.rt", don't use "https://www.sho.rt" in your browser (and vice-versa) */
define( 'YOURLS_SITE', 'https://your-own-domain-here.com' );

/** YOURLS language ... That translation file (a .mo file) must be installed in the user/language directory. */
define( 'YOURLS_LANG', '' );

define( 'YOURLS_HOURS_OFFSET', 0 );  // 容器生成配置含此项，样例文件未列

逐项说明：

  • YOURLS_SITE：全小写、末尾无斜杠（官方注释原文），它决定所有生成短链的 URL 前缀。官方注释特别提醒：定义为 https://sho.rt 后就不要用 https://www.sho.rt 访问——域名不一致会导致登录会话与跳转异常（部署篇 Q2 的排障实录即为此问题）；
  • YOURLS_LANG：语言代码，对应的 .mo 翻译文件需放入 user/languages/ 目录（官方注释写 user/language，实际目录名为 user/languages，以源码 YOURLS_LANG_DIR 定义为准）；
  • YOURLS_HOURS_OFFSET：时间显示的时区偏移小时数，整数；默认 0（UTC）。展示统计时间与东八区一致可设为 8。

5.3 短码参数（3 项）

/** Allow multiple short URLs for a same long URL
 ** Set to true to have only one pair of shortURL/longURL (default YOURLS behavior)
 ** Set to false to allow multiple short URLs pointing to the same long URL (bit.ly behavior) */
define( 'YOURLS_UNIQUE_URLS', true );

/** URL shortening method: either 36 or 62
 ** 36: generates all lowercase keywords (ie: 13jkm)
 ** 62: generates mixed case keywords (ie: 13jKm or 13JKm) */
define( 'YOURLS_URL_CONVERT', 36 );

/** Reserved keywords (so that generated URLs won't match them) */
$yourls_reserved_URL = [
    'porn', 'faggot', 'sex', 'nigger', 'fuck', 'cunt', 'dick',
];

逐项说明：

  • YOURLS_UNIQUE_URLS：true（默认）时同一长 URL 全局只允许一条短链，重复创建返回 409（1.10.5 起的状态码）；false 时同一长链可有多条短链（官方注释称为「bit.ly behavior」）。实测验证：设 false 后连建三条不同短链成功（逐条创建，仅 url 参数不同）：
curl -s "http://192.168.1.200:8134/yourls-api.php" \
  --data-urlencode 'url=https://example.org/test-1' \
  --data-urlencode 'action=shorturl' --data-urlencode 'format=json' \
  --data-urlencode 'username=admin' --data-urlencode 'password=q1w2e3r4'
curl -s "http://192.168.1.200:8134/yourls-api.php" \
  --data-urlencode 'url=https://example.org/test-2' \
  --data-urlencode 'action=shorturl' --data-urlencode 'format=json' \
  --data-urlencode 'username=admin' --data-urlencode 'password=q1w2e3r4'
curl -s "http://192.168.1.200:8134/yourls-api.php" \
  --data-urlencode 'url=https://example.org/test-3' \
  --data-urlencode 'action=shorturl' --data-urlencode 'format=json' \
  --data-urlencode 'username=admin' --data-urlencode 'password=q1w2e3r4'

实测回显（提取 status 与 shorturl 字段，注意自动短码是顺序递增的）：

success http://192.168.1.200:8134/1
success http://192.168.1.200:8134/2
success http://192.168.1.200:8134/3
  • YOURLS_URL_CONVERT：自动短码的进制，只允许 36 或 62。36 进制生成全小写短码（样例 13jkm），62 进制区分大小写（样例 13jKm），短码空间更大。上例实测 62 进制下首条短码为 1——因为 YOURLS 自动短码是自增 ID 的进制编码，从 1 起步，想要随机短码需插件实现；
  • $yourls_reserved_URL：保留字数组，命中保留字的短码不可用（防止短链与后台路径如 admin 冲突或被恶意词占用）。生产环境建议把 admin、api、logout 等应用路径加进去。

5.4 认证与安全参数（4 项）

/** Private means the Admin area will be protected with login/pass as defined below.
 ** Set to false for public usage (eg on a restricted intranet or for test setups) */
define( 'YOURLS_PRIVATE', true );

/** A random secret hash used to encrypt cookies. You don't have to remember it, make it long and complicated
 ** Hint: copy from https://yourls.org/cookie */
define( 'YOURLS_COOKIEKEY', 'modify this text with something random' );

/** Username(s) and password(s) allowed to access the site. Passwords either in plain text or as encrypted hashes */
$yourls_user_passwords = [
    'username' => 'password',
];

逐项说明：

  • YOURLS_PRIVATE：true（默认）= 私密模式，管理后台需登录、API 需凭据；false = 公开模式，任何人可缩短链接（官方注释建议仅限内网或测试）。公开模式下 API 的 username/password 参数不再必需；
  • $yourls_user_passwords：账号数组，支持多账号（一个键值对一个账号）。明文密码在首次登录后会被 YOURLS 自动加密为哈希写回文件（官方特性）；本文演示实例通过容器 env 注入 admin => q1w2e3r4；
  • YOURLS_COOKIEKEY：cookie 加密盐。1.10.5 起未显式定义时自动生成不可预测值（实测容器实例自动生成了 40 位随机串 61b8b08a…）；裸机部署建议从 https://yourls.org/cookie 取一个随机值固定下来——固定盐的必要性：若每次部署重新随机，所有用户会话失效；
  • YOURLS_NO_HASH_PASSWORD（进阶）：源码 functions-auth.php 定义点注释表明，设为 true 可跳过密码哈希（保持明文），官方文档对应章节为 credentials 的「I don't want to encrypt my password」。除特殊集成需求外不建议开启。

5.5 运维开关参数（4 项）

  • YOURLS_DEBUG：默认 false。开启后页面输出内部调试信息，官方注释明确「Default is false for live site. Enable when coding or before submitting a new issue」——排障临时开、平时必关；
  • YOURLS_NO_VERSION_CHECK：是否禁用版本更新检查（后台每日向官方查询新版本）。容器生成配置默认 true（禁用检查，适合内网/低外网依赖场景）；
  • YOURLS_NOSTATS：源码 functions.php 注释原文「Logs redirects unless YOURLS_NOSTATS is defined and true」——置 true 后跳转不记录点击日志（yourls_log 表不再增长），适合超高频纯跳转场景（代价是失去点击统计）；
  • YOURLS_FAST_INIT（进阶）：源码 Config/Init.php 的注释为「Whether to end instantiating early if YOURLS_FAST_INIT is defined and true」——初始化流程提前收敛，跳过插件等非核心加载，配合轻量入口可微降开销，普通站点无需启用。

六、生产配置模板

以下为裸机形态的生产 config.php 完整模板（适用场景：2C4G 及以上的常规云主机、NVMe/SSD 磁盘、个人或团队级日均十万级跳转；演示账号 admin/q1w2e3r4，站点域名以 s.example.com 为例）：

<?php
// ---- 数据库连接：独立业务账号 + 非标端口示例 ----
define( 'YOURLS_DB_USER', 'yourls' );
define( 'YOURLS_DB_PASS', 'q1w2e3r4' );
define( 'YOURLS_DB_NAME', 'yourls' );
define( 'YOURLS_DB_HOST', '127.0.0.1:3306' );
define( 'YOURLS_DB_PREFIX', 'yourls_' );

// ---- 站点：域名必须与实际访问一致 ----
define( 'YOURLS_SITE', 'https://s.example.com' );
define( 'YOURLS_LANG', 'zh_CN' );
define( 'YOURLS_HOURS_OFFSET', 8 );

// ---- 短码：62 进制 + 允许同链多码 ----
define( 'YOURLS_UNIQUE_URLS', false );
define( 'YOURLS_URL_CONVERT', 62 );
$yourls_reserved_URL = [
    'porn', 'sex', 'fuck',
    'admin', 'api', 'images', 'css', 'js', 'logout',
];

// ---- 认证安全：私密模式 + 多账号 + 固定 cookie 盐 ----
define( 'YOURLS_PRIVATE', true );
define( 'YOURLS_COOKIEKEY', 'F5gR9wL2pQ7xTz4Kc8Vb1Nm6Hj3Ys0Dd' );
$yourls_user_passwords = [
    'admin' => 'q1w2e3r4',
];

// ---- 运维开关：生产保持调试关闭 ----
define( 'YOURLS_DEBUG', false );
define( 'YOURLS_NO_VERSION_CHECK', true );

模板要点解读：数据库用独立账号而非 root；YOURLS_DB_HOST 演示了带端口的写法；$yourls_reserved_URL 补入了后台与静态资源路径，避免自动/自选短码撞上应用路由；cookie 盐为 32 位随机串（生产请换成 https://yourls.org/cookie 生成的值）；YOURLS_NO_VERSION_CHECK 关闭外联检查。容器形态等价 compose environment 写法见部署篇第六节环境变量表，两份配置一一对应（YOURLS_HOURS_OFFSET、YOURLS_COOKIEKEY 等在 compose 里同名传递即可）。

与同类短链产品的配置面横向对比（延伸阅读）：《Shlink 5.1.8 配置参数详解》展示了现代短链的 env 全量配置风格，《Chhoto URL 7.10.3 配置参数详解》则是极简派代表——YOURLS 的 config.php 模式介于两者之间：参数少而稳，17 年未大改。

七、常见问题

Q1：改了 config.php 没生效？ 容器形态改了文件会被 env 生成逻辑覆盖或与 env 冲突——容器化配置唯一入口是 environment，改后 docker compose up -d 重建；裸机形态确认改的是 user/config.php（不是 config-sample.php），且文件无语法错误（php -l user/config.php 校验）。

Q2：登录提示密码错误？ 裸机形态明文密码首次登录后会被加密写回，之后 config 里看到的是一长串哈希，属正常现象；密码记错时直接把 $yourls_user_passwords 里对应项改回明文即可重置。容器形态密码以 env YOURLS_PASS 为准。

Q3：YOURLS_SITE 与实际访问域名不一致会怎样？ 登录后 301 回跳导致会话失效（部署篇 Q2 实录）、生成的短链前缀与实际域名不符。唯一解法：两者保持完全一致。

Q4：想让自动短码是随机串怎么办？ YOURLS_URL_CONVERT 只控制进制（36/62），自动短码始终是自增 ID 编码（实测首条为 1）。随机短码需要社区插件实现（如 random-keywords 类插件，官方 awesome 列表有收录）。

Q5：yourls_log 表太大想停止记录？ YOURLS_NOSTATS 置 true 可停止写入跳转日志（代价：点击统计失效）；更细的折衷是保留统计但定期归档该表。

八、参考链接