Unleash 8.2.0 配置参数详解

目标：系统梳理 Unleash 8.2.0 自托管部署的全部常用配置参数（环境变量），按「数据库、服务监听、认证安全、初始化、遥测、缓存与限流、策略」七类逐项给出默认值、作用与实测验证方式，并给出生产配置模板。参数含义依据官方配置文档（docs.getunleash.io，查询日期 2026-10-21），关键参数均在本机 Ubuntu 22.04 实测环境验证过实际效果，未实测项已逐条标注。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Unleash：8.2.0（官方 Docker 程序包 unleashorg/unleash-server:8.2.0，服务端口 4242，宿主侧映射 8144）
• 数据库：PostgreSQL 16
• 部署形态：Docker Compose（部署过程见 《Unleash 8.2.0 Docker Compose 部署指南》）
• 参数来源标注约定：「实测」= 本环境实际配置并验证过生效效果；「实查」= 引自官方配置文档原文（标注查询日期）；「实查+推断」= 官方给出配置对象属性、环境变量形式按官方命名规则推断，首次使用建议按文中方法核验

二、前置条件

• 已按部署指南完成 Unleash 8.2.0 + PostgreSQL 16 的最小可用部署，curl http://localhost:8144/health 返回 {"health":"GOOD"}；
• 知道 Unleash 配置的唯一入口是环境变量（或 Node.js 嵌入时的配置对象）：Unleash 没有服务器侧配置文件，改配置 = 改环境变量并重建服务实例；
• 具备管理界面 admin 账号（本文示例 admin / q1w2e3r4）或 admin 类型 API Token（本文示例 *:*.q1w2e3r4）。

三、参数查看与修改方式

3.1 修改方式（按部署形态）

# Docker Compose 形态：编辑 docker-compose.yml 的 environment 段后重建
cd /opt/unleash
vi docker-compose.yml        # 修改 environment 中的变量
docker compose up -d web     # 应用变更（重建主服务实例）

# systemd / 直接进程形态：通过 Environment= 或 export 注入
# /etc/systemd/system/unleash.service 片段：
#   [Service]
#   Environment=DATABASE_HOST=127.0.0.1
#   Environment=DATABASE_PORT=5432
#   Environment=LOG_LEVEL=info
systemctl restart unleash

⚠️ 注意：Compose 形态下修改环境变量必须用 up -d 重建（重建才重新注入）；docker compose restart 只是重启进程，不会读取新的 environment 值。

3.2 查看当前生效配置

Unleash 提供 GET /api/admin/ui-config 端点返回实例级配置视图（含版本形态与环境特性开关）：

curl -s -H 'Authorization: *:*.q1w2e3r4' http://localhost:8144/api/admin/ui-config | head -c 500

实测回显（节选）：

{"environment":"Open Source","flags":{"anonymiseEventLog":false,"enableLicense":false,"responseTimeWithAppNameKillSwitch":false,"maintenanceMode":false,"messageBanner":{"name":"disabled","enabled":false,"feature_enabled":false},"strictSchemaValidation":false,"personalAccessTokensKillSwitch":false,"migrationLock":true,"demo":false,"onboardingIntroTour":false,...

其中 "environment":"Open Source" 表明当前是开源版形态（企业版 License 生效后会变化），flags 里是实例级能力开关。数据库连接类参数的生效核验最直接的办法是看启动日志——连接失败会在日志中打印 DATABASE_HOST 等拼接出的连接目标。

四、参数总览

按功能域分类的参数全景（默认值均来自官方文档或实测）：

解读：Unleash 的参数面不算大，自托管必需项集中在「数据库连接 + 初始管理员 + 内网遥测开关」三处；其余参数默认值即为社区验证过的合理值，按需覆盖即可。

五、核心参数分类详解

5.1 数据库连接类（实测）

Unleash 仅支持 PostgreSQL，连接参数是唯一必配集合。两种写法二选一：分项变量（DATABASE_HOST 等）或整体 DATABASE_URL（后者优先级更高，会覆盖分项与 DATABASE_SSL）。

实测验证：本环境用分项变量（DATABASE_HOST=db、DATABASE_PORT=5432、DATABASE_NAME=unleash、DATABASE_USERNAME=unleash_user）一次启动成功，服务健康回显：

{"health":"GOOD"}

5.2 服务监听类

实测佐证：默认配置下服务监听回显（启动日志）：

[2026-10-21T11:16:55.090] [INFO] Server listening on http://0.0.0.0:4242

5.3 认证与安全类

实测佐证：登录接口实测回显（会话 Cookie 与限流头，节选）：

HTTP/1.1 200 OK
RateLimit-Policy: 10;w=60
Set-Cookie: unleash-session=s%3A8rEA08nEDAxoJh8hji1zps2VoF5mT6Ry.%2BYokeySRGLaExIYMd1u01UxeJadZdv84JVuggg%2FV0G8; Path=/; Expires=Fri, 23 Oct 2026 11:17:47 GMT; HttpOnly; SameSite=Lax

💡 说明：SameSite=Lax; HttpOnly 的会话 Cookie 配合 60 秒 10 次的登录限流（RateLimit-Limit: 10）构成开源版的基础暴力破解防护；公网暴露时建议再叠加反向代理层限流与 HTTPS。

5.4 初始化类（实测 + 排障）

实测 + 排障实录：INIT_ADMIN_API_TOKENS 是 8.2.0 上最容易踩坑的参数。本环境曾误用旧版三段式格式 *.q1w2e3r4.admin，服务启动即崩溃：

TypeError: Cannot read properties of undefined (reading 'split')
    at file:///unleash/dist/lib/create-config.js:243:42
    at Array.map (<anonymous>)
    at loadTokensFromString (file:///unleash/dist/lib/create-config.js:241:34)
    at loadInitApiTokens (file:///unleash/dist/lib/create-config.js:259:12)

改为新自描述格式 *:*.q1w2e3r4（admin 类型必须以 *:*. 开头）后启动正常，且 Token 立即可用：

curl -s -H 'Authorization: *:*.q1w2e3r4' http://localhost:8144/api/admin/api-tokens

实测回显：

{"tokens":[{"secret":"*:*.q1w2e3r4","tokenName":"admin","type":"admin","project":"*","projects":["*"],"environment":"*","expiresAt":null,"createdAt":"2026-10-21T11:16:59.237Z","alias":null,"seenAt":"2026-10-21T11:19:59.244Z","secure":false}]}

5.5 遥测与版本检查类

💡 说明：内网隔离/数据合规环境务必 CHECK_VERSION=false，否则日志会周期性出现版本检查请求失败，且实例信息会尝试出网。

5.6 缓存与限流类

实测佐证（客户端上报链路）：client Token 上报注册与指标（v8 要求 bucket.toggles 为对象而非数组）：

curl -s -X POST http://localhost:8144/api/client/register \
  -H 'Content-Type: application/json' \
  -H 'Authorization: *:development.9fb2e61830948da3eda461f606779cc13a37293288ad075e5b6c7e3d' \
  -d '{"appName":"web-demo","instanceId":"inst-1","sdkVersion":"unleash-client-node:6.0.0","connectVia":"streaming","interval":10000,"started":"2026-10-21T11:30:00Z","strategies":["default"]}' \
  -w '\nHTTP %{http_code}\n'

实测回显：

HTTP 202

5.7 策略相关配置

Unleash 的策略（strategy）不通过环境变量配置，而是数据形态配置：内置策略开箱即用，评估规则存于数据库，通过 Admin API 或管理界面挂到开关的环境上。

内置策略一览（实查官方文档 + 本地实测 flexibleRollout）：

flexibleRollout 实测记录：把默认策略从 100% 改为 25% + A/B 变体后，用 Frontend API 对 12 个 userId 做分桶评估：

# 灰度内用户拿到变体（约 25% 比例命中）
curl -s -H 'Authorization: *:development.47e03851864d27c0a2173469068f1901b03f8d71e5612217be4b7315' \
  'http://localhost:8144/api/frontend?appName=web-demo&userId=2'

实测回显（灰中用户，带变体 payload）：

{"toggles":[{"name":"checkout-new-ui","enabled":true,"variant":{"name":"variant-a","enabled":true,"payload":{"type":"string","value":"A方案"},"feature_enabled":true,"featureEnabled":true},"impressio

实测回显（未灰中用户，toggles 为空）：

{"toggles":[]}

12 个 userId 实测分布：3 个命中（≈25%），分别分到 variant-a（A方案）/ variant-b（B方案），权重 500/500 生效。

⚠️ 注意（实测排障）：新建开关默认自带一条 rollout=100 的 default 策略；再新增一条 25% 的 flexibleRollout 与它是「或」关系，全员仍会命中 100% 那条。做灰度必须修改默认策略本身（或删除多余策略），这在官方 playground 评估端点的返回里可以逐条核对（每条策略带 rollout 与 result.enabled）。

六、生产配置模板

适用场景：4 核 8GB 内存、NVMe SSD、百人级研发团队、日均开关评估百万级以内的自托管生产实例（PostgreSQL 与 Unleash 同机）。

# /opt/unleash/docker-compose.yml（environment 段生产参考，其余结构见部署指南）
    environment:
      DATABASE_HOST: db
      DATABASE_PORT: "5432"
      DATABASE_NAME: unleash
      DATABASE_USERNAME: unleash_user
      DATABASE_PASSWORD: "换成16位以上随机串"
      DATABASE_SSL: "false"
      UNLEASH_DEFAULT_ADMIN_USERNAME: admin
      UNLEASH_DEFAULT_ADMIN_PASSWORD: "换成强口令并入库到密码管理器"
      INIT_ADMIN_API_TOKENS: "*:*.换成长随机串"
      CHECK_VERSION: "false"
      UNLEASH_URL: "https://unleash.example.com"
      SECURE_HEADERS: "true"
      LOG_LEVEL: "info"
      SESSION_TTL_HOURS: "24"

模板逐项说明：

• 密码与 Token 全部落长随机串：本文示例中可读口令（q1w2e3r4 等）仅用于实验室复现，生产严禁沿用；INIT_ADMIN_API_TOKENS 的 secret 即 Token 凭据本体，泄露等于 admin 权限泄露；
• UNLEASH_URL + SECURE_HEADERS=true：域名 HTTPS 反代形态标配；子路径部署再补 BASE_URI_PATH=/unleash；
• SESSION_TTL_HOURS: 24：合规要求更严的组织可再缩短；
• LOG_LEVEL=info：排查期临时改 debug，定位完立刻回 info（debug 日志量大）；
• PostgreSQL 单独参数（shared_buffers 等）按数据库侧标准调优，Unleash 默认连接池（min 0 / max 4，实查值）对同机单实例足够，多实例部署时按 实例数 × pool.max 复核 PostgreSQL 的 max_connections。

七、常见问题

Q1：改了环境变量但没生效？

• Compose 形态必须 docker compose up -d web 重建（重新注入环境变量），restart 不会重新注入；Node.js 嵌入形态改的是进程启动环境，需重启进程。

Q2：INIT_ADMIN_API_TOKENS 启动崩溃（TypeError ... reading 'split'）

• 使用了旧三段式格式。8.2.0 要求 [type]:[project]:[environment].[secret] 新格式，admin 类型写 *:*.secret。完整排障过程见 5.4 节。

Q3：云托管 PostgreSQL（RDS 等）连接失败

• 依次核对：DATABASE_SSL=true 是否已设、DATABASE_SSL_REJECT_UNAUTHORIZED 与服务端证书链是否匹配、安全组/白名单是否放行 Unleash 出口地址。本地同机部署则保持 DATABASE_SSL=false。

Q4：内网部署日志反复报版本检查错误

• 设 CHECK_VERSION=false（见 5.5 节），消除对 version.unleash.run 的出网依赖。

Q5：反向代理子路径下界面空白或资源 404

• 未设 BASE_URI_PATH。设为与反代一致的子路径（如 /unleash）并重建；同时反代需透传 Host 头并支持 WebSocket 场景的升级头。

Q6：SDK/脚本调用 Admin API 频繁后返回 429

• 触发了客户端注册/上报限流（默认 6000 次/分钟，见 5.6 节）或登录限流（10 次/60 秒，见 5.3 节实测回显）。调整对应 *_RATE_LIMIT_PER_MINUTE 变量，或让 SDK 使用官方默认上报间隔而非高频轮询。

八、参考链接

• 官方配置总览（参数依据来源，查询日期 2026-10-21）：https://docs.getunleash.io/reference/deploy/configuring-unleash

• 官方部署入门：https://docs.getunleash.io/reference/deploy/getting-started

• 数据库配置与备份：https://docs.getunleash.io/reference/deploy/database-setup 、https://docs.getunleash.io/reference/deploy/database-backup

• 策略说明：https://docs.getunleash.io/reference/strategies

• 服务自带 OpenAPI 规范（8.2.0 实例事实源）：http://<实例地址>:4242/docs/openapi.json

• 本专栏部署篇：《Unleash 8.2.0 Docker Compose 部署指南》

• 本专栏系列：《Unleash 8.2.0 常用 CLI 命令与工具详解》、《Unleash 介绍与选型指南》。