Unleash 8.2.0 Docker Compose 部署指南

目标：在 Ubuntu 22.04 服务器上用 Docker Compose 从零部署 Unleash 8.2.0 特性开关平台（Unleash 主服务 + PostgreSQL 16），覆盖版本选型、编排文件、启动验证、数据持久化、备份与升级、常见故障排查。已在 Ubuntu 22.04 / Docker Compose V2 环境实测通过，文内命令与回显均为实测记录。

一、环境信息

操作系统：Ubuntu 22.04 LTS（x86_64）
Docker：Docker Engine 24+，Compose V2（docker compose 子命令）
Unleash：8.2.0（官方最新稳定版，GitHub Releases 实查，2026-09-08 发布；查询日期 2026-10-21）
PostgreSQL：16（官方支持 PostgreSQL 10+，选用 16 稳定系列）
端口规划：宿主机 8144 → Unleash 4242（本例宿主机 4242 已被其他服务占用，故改用 8144；若 4242 空闲可直接写 4242:4242）
部署目录：/opt/unleash/（compose 文件与数据目录均在此）
演示账号：管理界面用户 admin / 密码 q1w2e3r4（生产环境请更换强口令）
演示 API Token：*:*.q1w2e3r4（admin 类型，随首启自动创建）

二、版本与镜像选型说明

Unleash 官方在 Docker Hub 发布主服务程序包 unleashorg/unleash-server，数据库使用官方 postgres 程序包。选型对照如下：

组件	本例选用	官方地址	选型理由
Unleash 主服务	`unleashorg/unleash-server:8.2.0`	hub.docker.com/r/unleashorg/unleash-server	官方唯一主服务程序包；固定版本号保证可复现与可回滚
数据库	`postgres:16`	hub.docker.com/r/library/postgres	官方支持 PostgreSQL 10+，16 为当前成熟稳定大版本

关键差异解读：

务必固定版本号（8.2.0），不要用 latest。Unleash 发布节奏快（约每月 1~2 个次版本），latest 会在重建实例时悄悄带入新版本并触发数据库结构迁移，回滚困难；固定 tag 后升级是显式动作。
Unleash 8.2.0 与 PostgreSQL 的组合无版本耦合，数据库大版本可按团队存量选择 13/14/15/16；新部署建议 16。
官方还提供 Helm Chart（artifacthub.io/packages/helm/unleash/unleash）用于 Kubernetes 场景，本文聚焦单机 Compose 部署。

三、前置条件

服务器已安装 Docker Engine 与 Compose V2 插件，验证命令：

docker --version && docker compose version

实测回显：

Docker version 24.0.7, build afdb53d
Docker Compose version v2.23.0

服务器内存 2GB 以上（Unleash 主服务与 PostgreSQL 同机部署的最低舒适配置），磁盘 10GB 以上。
可访问 Docker Hub 拉取程序包；离线环境需提前在有网环境导出程序包再导入（docker save / docker load）。
规划端口：确认 4242（或你规划的外部端口）未被占用：

ss -ltn | grep ':4242 ' || echo 'port 4242 free'

本例因 4242 被占用而选择 8144，回显（8144 空闲时无输出）：

port 4242 free

四、部署步骤

本节从零开始：建目录 → 写编排文件 → 启动 → 验证 → 创建第一个开关，全程可照抄执行。

4.1 目录准备

# 创建部署目录与数据库数据目录
mkdir -p /opt/unleash/pgdata && cd /opt/unleash

💡 说明：pgdata 将作为 PostgreSQL 数据目录挂载点，数据库文件直接落在服务器磁盘上，重建 Unleash 服务不影响开关数据。

4.2 编写 docker-compose.yml

在 /opt/unleash/ 下创建 docker-compose.yml，内容如下（实测原样）：

name: unleash-8.2.0-stack

services:
  web:
    image: unleashorg/unleash-server:8.2.0
    container_name: unleash-8.2.0-web
    ports:
      - "8144:4242"
    environment:
      # —— 数据库连接（必配）——
      DATABASE_HOST: db
      DATABASE_PORT: "5432"
      DATABASE_NAME: unleash
      DATABASE_USERNAME: unleash_user
      DATABASE_PASSWORD: unleash_pass_q1w2e3r4
      DATABASE_SSL: "false"
      # —— 初始管理员（首次启动创建）——
      UNLEASH_DEFAULT_ADMIN_USERNAME: admin
      UNLEASH_DEFAULT_ADMIN_PASSWORD: q1w2e3r4
      # —— 首启自动创建的 admin API Token（格式必须 *:*.secret）——
      INIT_ADMIN_API_TOKENS: "*:*.q1w2e3r4"
      # —— 内网/离线环境关闭版本检查上报 ——
      CHECK_VERSION: "false"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "wget", "--spider", "http://localhost:4242/health"]
      interval: 5s
      timeout: 5s
      retries: 30
    networks:
      - unleashnet

  db:
    image: postgres:16
    container_name: unleash-8.2.0-db
    environment:
      POSTGRES_DB: unleash
      POSTGRES_USER: unleash_user
      POSTGRES_PASSWORD: unleash_pass_q1w2e3r4
    volumes:
      - /opt/unleash/pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD", "pg_isready", "--username=unleash_user", "--host=127.0.0.1", "--port=5432"]
      interval: 5s
      timeout: 5s
      retries: 20
    networks:
      - unleashnet

networks:
  unleashnet:
    name: unleash-8.2.0-net
    driver: bridge

配置逐项说明：

配置项	值	说明
`name`	`unleash-8.2.0-stack`	Compose 项目名。必须显式指定，否则默认取目录名，多套栈同名时 `down` 会互相误删
`container_name`	`unleash-8.2.0-web` / `unleash-8.2.0-db`	实例固定名称，带产品+版本+用途，便于日志与监控定位
`ports: 8144:4242`	宿主 8144 → 服务 4242	4242 是 Unleash 固定服务端口；宿主侧按需选择
`DATABASE_HOST: db`	同网络内服务名	Compose 自带 DNS 按 service 名解析，不写死 IP
`DATABASE_SSL: "false"`	关闭库连接加密	同机内网部署无需 TLS；跨网/云托管数据库必须改 true
`INIT_ADMIN_API_TOKENS`	`:.q1w2e3r4`	首次启动创建 admin 类型 API Token；仅库中无任何 Token 时生效
`CHECK_VERSION: "false"`	关闭版本检查	阻止启动后向 version.unleash.run 上报，内网必配
`depends_on: service_healthy`	启动顺序控制	等 PostgreSQL 健康检查通过后再启动 Unleash，避免首次连接失败
`healthcheck`（web/db）	wget / pg_isready	让 `docker compose ps` 能展示 healthy 状态，编排级可靠启动
`volumes`	`/opt/unleash/pgdata`	数据库持久化，见第五节

4.3 启动编排栈

docker compose up -d

实测回显：

[+] Running 3/3
 ✔ Network unleash-8.2.0-net      Created
 ✔ Container unleash-8.2.0-db     Healthy
 ✔ Container unleash-8.2.0-web    Started

⚠️ 注意：首次 up 时 Unleash 会自动在 PostgreSQL 中建表并执行数据库结构迁移（内置 Knex 迁移），期间 web 状态可能显示 Created 数秒后才 Started，属正常现象。

4.4 启动过程观察

# 查看编排栈状态（等待两个服务均为 healthy）
docker compose ps

实测回显（启动约 30 秒后）：

NAME               IMAGE                           COMMAND                  SERVICE   CREATED          STATUS                    PORTS
unleash-8.2.0-db   postgres:16                     "docker-entrypoint.s…"   db        49 seconds ago   Up 47 seconds (healthy)   5432/tcp
unleash-8.2.0-web  unleashorg/unleash-server:8.2.0 "docker-entrypoint.s…"   web       41 seconds ago   Up 39 seconds (healthy)   0.0.0.0:8144->4242/tcp, [::]:8144->4242/tcp

# 跟踪主服务启动日志（观察迁移与监听）
docker compose logs web | tail -20

实测回显（节选）：

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

4.5 验证健康与登录

# 1. 健康检查端点
curl -s http://localhost:8144/health

实测回显：

{"health":"GOOD"}

# 2. 管理界面登录接口（拿到会话 Cookie 即认证链路正常）
curl -si -X POST http://localhost:8144/auth/simple/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}' | head -8

实测回显：

HTTP/1.1 200 OK
RateLimit-Policy: 10;w=60
RateLimit-Limit: 10
RateLimit-Remaining: 9
RateLimit-Reset: 60
Content-Type: application/json; charset=utf-8
ETag: W/"16c-l98T5uT3C6dnqFULUqAhEumf0uc"
Set-Cookie: unleash-session=s%3A8rEA08nEDAxoJh8hji1zps2VoF5mT6Ry.%2BYokeySRGLaExIYMd1u01UxeJadZdv84JVuggg%2FV0G8; Path=/; Expires=Fri, 23 Oct 2026 11:17:47 GMT; HttpOnly; SameSite=Lax

浏览器打开 http://<服务器IP>:8144，用 admin / q1w2e3r4 登录即进入管理界面（Admin UI）。

4.6 创建第一个特性开关（端到端验证）

用首启自动创建的 admin API Token 调 Admin API 在默认项目里建开关并打开，验证「写配置 → 评估生效」全链路：

# 1. 创建开关 checkout-new-ui
curl -s -X POST http://localhost:8144/api/admin/projects/default/features \
  -H 'Content-Type: application/json' \
  -H 'Authorization: *:*.q1w2e3r4' \
  -d '{"name":"checkout-new-ui","description":"新版结算页灰度发布","type":"release"}'

实测回显：

{"name":"checkout-new-ui","description":"新版结算页灰度发布","type":"release","project":"default","stale":false,"createdAt":"2026-10-21T11:20:30.549Z","impressionData":false,"archived":false}

# 2. 在 development 环境打开开关
curl -s -o /dev/null -w '%{http_code}\n' -X POST \
  http://localhost:8144/api/admin/projects/default/features/checkout-new-ui/environments/development/on \
  -H 'Authorization: *:*.q1w2e3r4'

实测回显：

至此部署闭环完成。开关创建与策略灰度的更多 API 实测见本专栏《Unleash 8.2.0 常用 CLI 命令与工具详解》；环境变量级的完整配置说明见《Unleash 8.2.0 配置参数详解》。

五、数据持久化说明

Unleash 的全部状态（开关、策略、审计事件、Token、用户）都在 PostgreSQL 中，因此持久化的关键是数据库数据目录落在服务器磁盘：

编排文件中 db 服务的 volumes: /opt/unleash/pgdata:/var/lib/postgresql/data 已把数据目录绑定到宿主机 /opt/unleash/pgdata；
验证落盘（实测）：

ls /opt/unleash/pgdata | head -8

实测回显：

base
global
pg_commit_ts
pg_dynshmem
pg_hba.conf
pg_ident.conf
pg_logical
pg_multixact

重启不丢数据验证（实测）：重启主服务后此前创建的开关仍然生效，返回内容与重启前一致：

docker compose restart web
sleep 8
curl -s -H 'Authorization: *:development.47e03851864d27c0a2173469068f1901b03f8d71e5612217be4b7315' \
  'http://localhost:8144/api/frontend?appName=web-demo&userId=2'

实测回显（重启前后一致）：

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

⚠️ 注意：迁移、删除编排栈（docker compose down）不会删除 /opt/unleash/pgdata，重新 up -d 后数据原样恢复；只有显式删除该目录才会清空全部数据，删除前务必先备份。

六、环境变量表

Unleash 以环境变量为主要配置方式（无必需配置文件）。部署必需与常用变量如下（完整参数解析见本专栏《Unleash 8.2.0 配置参数详解》）：

环境变量	默认值	说明
`DATABASE_HOST`	localhost	数据库地址（Compose 内为 `db` 服务名）
`DATABASE_PORT`	5432	数据库端口
`DATABASE_NAME`	unleash	数据库名
`DATABASE_USERNAME`	—	数据库用户
`DATABASE_PASSWORD`	—	数据库密码
`DATABASE_SSL`	false	数据库连接 TLS；云上托管库必须 true
`DATABASE_URL`	—	以上连接项的 URL 替代写法（`postgres://user:pass@host:5432/db`）
`HTTP_PORT`	4242	服务监听端口
`HTTP_HOST`	自动	监听地址，默认全部网卡
`UNLEASH_URL`	—	实例对外可发现 URL，用于邮件重置链接、集成消息链接
`UNLEASH_DEFAULT_ADMIN_USERNAME`	admin	首启创建的管理员用户名
`UNLEASH_DEFAULT_ADMIN_PASSWORD`	unleash4all	首启创建的管理员密码（务必覆盖默认值）
`INIT_ADMIN_API_TOKENS`	—	逗号分隔的 admin Token 列表，格式 `:.secret`，仅库中无 Token 时创建
`INIT_CLIENT_API_TOKENS`	—	同上，创建 client 类型 Token
`CHECK_VERSION`	true	关闭对 version.unleash.run 的版本检查上报，内网设 false
`LOG_LEVEL`	info	日志级别（debug/info/warn/error/fatal）
`BASE_URI_PATH`	/	反向代理子路径部署时设置（如 `/unleash`）
`SESSION_TTL_HOURS`	48	用户会话有效期（小时）
`SECURE_HEADERS`	false	HTTPS 反代场景开启安全响应头（HSTS/CSP）

解读：前三类（数据库、初始管理员、初始化 Token）是自托管部署的最小集合；CHECK_VERSION=false 是内网隔离环境的必配项；UNLEASH_URL、SECURE_HEADERS、BASE_URI_PATH 三件套只在「域名 + HTTPS 反向代理」形态下需要。

七、配置参数说明

对编排文件中出现的关键参数给出「为什么这样配」：

DATABASE_SSL: "false"：Unleash 与数据库同处一个自定义 bridge 网络内，链路不出主机，明文连接可接受；若使用云托管 PostgreSQL（RDS 等）必须改 true，必要时配合 DATABASE_SSL_REJECT_UNAUTHORIZED=true 校验服务端证书。
INIT_ADMIN_API_TOKENS: "*:*.q1w2e3r4"：给自动化脚本（CI/CD、流水线）一条不依赖人工登录的通道。该 Token 只在数据库中还没有任何 Token 时创建；创建后可在管理界面「Admin → API tokens」中轮换。secret 部分演示用 q1w2e3r4，生产请用长随机串。
healthcheck（web）：用 wget --spider 探测 /health，这是官方健康端点，返回 {"health":"GOOD"} 即存活；编排层依赖它决定 ps 显示状态与 restart: unless-stopped 的自愈判断。
healthcheck（db）：pg_isready 是 PostgreSQL 官方就绪探测工具，condition: service_healthy 保证 Unleash 首次启动时库已可接受连接——否则首启会因「数据库未就绪 + 正在迁移」而连接报错重启。
container_name 与 name：固定实例名与项目名，让 docker compose 系列命令、日志采集、监控面板都能稳定定位到这套栈；项目名含版本号（unleash-8.2.0-stack）还能在多版本并存时避免误操作。

八、配置文件挂载

Unleash 8.2.0 没有必需的配置文件——所有配置经环境变量注入（见第六、七节），因此标准部署无需挂载任何文件到主服务。需要挂载的只有：

数据库数据目录（必须）：/opt/unleash/pgdata:/var/lib/postgresql/data，见第五节；
逻辑备份产物（可选）：备份脚本输出目录，例如挂 /opt/unleash/backup:/backup 供定时 pg_dump 落盘。

# 手动逻辑备份示例（实测）：
docker compose exec db sh -c 'pg_dump -U unleash_user unleash | head -8'

实测回显：

--
-- PostgreSQL database dump
--

\restrict MZvhQgQahsx8a5jYk43NMWTRGCQlZGgFPZrCTWrMqvvgtFvXfILcsRZbE56lwk3

-- Dumped from database version 16.15 (Debian 16.15-1.pgdg13+2)
-- Dumped by pg_dump version 16.15 (Debian 16.15-1.pgdg13+2)

💡 说明：pg_dump 输出的是完整 SQL 逻辑备份，生产上重定向到带日期的文件（如 unleash_$(date +%F).sql）并配合 cron 每日执行；恢复用 psql -U unleash_user unleash < 备份文件。

九、等价 docker run

不使用 Compose 时，以下两条命令等价于上述编排（先库后服务，同网络互通）：

# 1. 创建专用网络
docker network create unleash-8.2.0-net

# 2. 启动 PostgreSQL（数据落 /opt/unleash/pgdata）
docker run -d \
  --name unleash-8.2.0-db \
  --network unleash-8.2.0-net \
  -e POSTGRES_DB=unleash \
  -e POSTGRES_USER=unleash_user \
  -e POSTGRES_PASSWORD=unleash_pass_q1w2e3r4 \
  -v /opt/unleash/pgdata:/var/lib/postgresql/data \
  postgres:16

# 3. 启动 Unleash 主服务
docker run -d \
  --name unleash-8.2.0-web \
  --network unleash-8.2.0-net \
  -p 8144:4242 \
  -e DATABASE_HOST=unleash-8.2.0-db \
  -e DATABASE_PORT=5432 \
  -e DATABASE_NAME=unleash \
  -e DATABASE_USERNAME=unleash_user \
  -e DATABASE_PASSWORD=unleash_pass_q1w2e3r4 \
  -e DATABASE_SSL=false \
  -e UNLEASH_DEFAULT_ADMIN_USERNAME=admin \
  -e UNLEASH_DEFAULT_ADMIN_PASSWORD=q1w2e3r4 \
  -e INIT_ADMIN_API_TOKENS="*:*.q1w2e3r4" \
  -e CHECK_VERSION=false \
  unleashorg/unleash-server:8.2.0

⚠️ 注意：docker run 方式没有编排级健康检查与启动顺序控制，需等 PostgreSQL 就绪（约 10 秒）再启动主服务，否则主服务会因连接失败退出重试。生产建议用 Compose（或 systemd 单元托管 docker compose up -d）。

十、常用运维命令

以下命令均在部署目录 /opt/unleash/ 下执行：

# 状态总览（healthy 即正常）
docker compose ps

# 跟踪主服务日志（Ctrl+C 退出，不影响服务）
docker compose logs -f web

# 重启单个服务（改环境变量后必须重建而非 restart，见下方说明）
docker compose restart web

# 修改编排文件后应用变更（会重建有变化的实例）
docker compose up -d

# 停止 / 恢复整套栈（数据保留在 /opt/unleash/pgdata）
docker compose stop
docker compose start

# 彻底移除栈（不删数据目录）
docker compose down

升级流程（8.2.0 → 后续版本）：

# 1. 先做数据库备份
docker compose exec db sh -c 'pg_dump -U unleash_user unleash' > /opt/unleash/backup/unleash_before_upgrade.sql

# 2. 编辑 docker-compose.yml，把 image 的 tag 改为目标版本（如 8.3.0）

# 3. 拉取新程序包并重建主服务
docker compose pull web
docker compose up -d web

# 4. 验证：新版本号出现在日志与健康检查
docker compose logs web | grep -i 'listening'
curl -s http://localhost:8144/health

⚠️ 注意：Unleash 启动时自动执行数据库结构迁移，升级后不可直接回退旧版本（旧代码遇到新表结构可能出错）；回退必须连数据一起回退（恢复第 1 步的备份）。建议逐个小版本跟进，跨多个大版本升级前查阅官方 Migration Guide。

十一、常见问题（排障实录）

Q1：启动即退出，日志报 TypeError: Cannot read properties of undefined (reading 'split')

现象（实测日志）：

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)
    ...

原因：INIT_ADMIN_API_TOKENS 使用了旧版三段式格式（如 *.q1w2e3r4.admin，[project].[secret].[type]）。Unleash 新版要求自描述新格式 [type]:[project]:[environment].[secret]，旧格式解析时字段缺失导致启动崩溃。
解决：改为 *:*.q1w2e3r4（admin 类型必须以 *:*. 开头，作用于全部项目与环境），docker compose up -d 重建后正常。

Q2：web 服务反复重启，日志见数据库连接失败

原因：PostgreSQL 尚未就绪（尤其首次启动建库时），主服务连不上库即退出重试。
解决：编排文件中保留 depends_on: { db: { condition: service_healthy } } 与 db 的 pg_isready 健康检查，由编排层保证启动顺序；不要删掉 healthcheck。

Q3：端口 4242 被占用导致启动失败

现象：docker compose up -d 报端口绑定错误，或浏览器访问不通。
解决：改 ports 左侧的宿主端口（如本例 8144:4242），选择前用 ss -ltn | grep ':8144 ' 确认空闲；服务内侧 4242 不用改。

Q4：忘记 admin 密码

方法一（环境变量尚未生效建过用户时）：首次启动前在编排中设置 UNLEASH_DEFAULT_ADMIN_PASSWORD；
方法二（已有用户）：让另一位 Unleash Admin 在「Admin → Users」中重置；开源版无邮件 SMTP 配置时用 reset-password 管理接口或直接在数据库层面处理，详见官方文档 Securing Unleash 一节。

Q5：服务器无法访问外网，启动后日志反复出现版本检查错误

原因：默认启动后会请求 https://version.unleash.run 做版本核对（携带实例 ID 的匿名统计）。
解决：编排文件加 CHECK_VERSION: "false" 重建，本例已默认配置。

Q6：INIT_ADMIN_API_TOKENS 设置了但没生效

原因：初始化 Token 仅在数据库中不存在任何 API Token 时创建。若首次启动时已生成过 Token（或手工创建过），后续再改该变量不会追加。
解决：登录管理界面在「Admin → API tokens」中手工创建，或调用 Admin API 创建（见本专栏命令详解篇）。

十二、参考链接

官方部署入门（三种方式与默认管理员说明）：https://docs.getunleash.io/reference/deploy/getting-started
官方配置总览：https://docs.getunleash.io/reference/deploy/configuring-unleash
数据库备份指南：https://docs.getunleash.io/reference/deploy/database-backup
Docker Hub（主服务程序包）：https://hub.docker.com/r/unleashorg/unleash-server
官方仓库 docker-compose 参考：https://github.com/Unleash/unleash
版本发布页（8.2.0）：https://github.com/Unleash/unleash/releases
本专栏系列：《Unleash 介绍与选型指南》。