VOZEB PRO 本地启动教程

适用于在 Windows 或 macOS 的 Docker Desktop 中首次启动 VOZEB PRO。本文依据官方仓库 main 分支与 v0.0.7 发布镜像编写。

项目地址：VOZEB PRO GitHub

一、适用范围

本文介绍两种启动方式：

官方 Docker Compose（推荐）：从官方仓库启动 postgres、app 和 generation-worker 三个服务。

定制发行包脚本：仅当项目包确实包含 Start-VOZEB-PRO.cmd、Stop-VOZEB-PRO.cmd 或 start-vozeb.ps1 时使用。

如果项目目录中没有上述启动脚本，请直接使用官方 Docker Compose 流程，不要按旧版脚本路径操作。

二、启动前准备

环境要求

64 位 Windows 或 macOS

Docker Desktop，且 Docker Engine 已启动

Docker Compose v2

Git（用于获取官方仓库）

能够访问 GitHub Container Registry 和模型上游的网络

Windows 建议使用 Docker Desktop 的 WSL 2 后端。安装或启用 WSL 2 后，按系统提示重启电脑。

检查项目目录

以官方仓库为例，项目根目录至少应包含：

.env.example
docker-compose.yml
Dockerfile
web
docs

若使用定制发行包，还应确认其启动脚本确实存在：

Start-VOZEB-PRO.cmd
Stop-VOZEB-PRO.cmd
start-vozeb.ps1

官方公开仓库不包含这三个 Windows 脚本，也不默认生成 deployment/admin-credentials.txt。首次管理员账号通过 /install 安装向导创建。

三、首次启动（官方 Docker Compose）

1. 获取项目并准备 `.env`

git clone https://github.com/csyqlz/VOZEB-PRO.git
Set-Location .\VOZEB-PRO
Copy-Item .env.example .env

macOS 可使用：

2. 填写必要配置

打开项目根目录的 .env，至少填写以下内容：

NEXT_PUBLIC_SITE_URL=http://localhost:3000
POSTGRES_PASSWORD=<强数据库密码>
VOZEB_PRO_ENCRYPTION_KEY=<64位十六进制密钥>
VOZEB_PRO_INSTALL_TOKEN=<至少32位的一次性安装令牌>
VOZEB_PRO_MAINTENANCE_TOKEN=<至少32位维护令牌>
VOZEB_PRO_WORKER_TOKEN=<至少32位且不同于维护令牌的Worker令牌>

可使用下面的命令生成随机密钥，并为不同变量分别生成：

openssl rand -hex 32

macOS：

注意：

VOZEB_PRO_ENCRYPTION_KEY 初始化后必须保持稳定，不要随意更换。

VOZEB_PRO_INSTALL_TOKEN 用于初始化数据库和创建首个管理员。

VOZEB_PRO_WORKER_TOKEN 必须与 VOZEB_PRO_MAINTENANCE_TOKEN 不同。

不要把真实 .env 上传、发送或截图公开。

3. 拉取镜像并启动

docker compose pull
docker compose up -d
docker compose ps

标准 Compose 会启动：

vozeb-pro
vozeb-pro-postgres
vozeb-pro-generation-worker

正常状态应大致为：

vozeb-pro                     Up / healthy
vozeb-pro-postgres            Up / healthy
vozeb-pro-generation-worker   Up

也可以执行：

docker ps --filter "name=vozeb-pro"

Docker Desktop 的 Containers 页面。该截图采集时只显示了 vozeb-pro；标准 Docker Compose 部署还应显示 PostgreSQL 与生成 Worker。

如果 Docker Desktop 中只看到 vozeb-pro，请先执行 docker compose ps 核对全部服务，而不是根据单个容器判断部署完整。

4. 完成安装向导

打开：

http://localhost:3000/install

按安装向导依次完成：

检查 PostgreSQL 连接。

输入 .env 中的一次性安装令牌。

初始化数据库表结构。

再次输入同一安装令牌，创建首个管理员账号。

使用新创建的管理员账号登录。

首次安装前，/api/health/ready 返回 503 属于正常状态；完成数据库初始化和管理员创建后，再检查它是否返回 200。

5. 检查运行状态

应用存活检查：

Invoke-WebRequest http://127.0.0.1:3000/api/health/live

预期状态码：

完整就绪检查：

Invoke-WebRequest http://127.0.0.1:3000/api/health/ready

预期状态码：

/api/health/ready 会检查数据库、安装状态和生成 Worker 心跳。若返回 503，请查看响应体和容器日志。

6. 打开本地页面

主应用地址：

http://localhost:3000

也可以使用：

http://127.0.0.1:3000

本地页面默认使用 http://，不要强行改成 https://。

四、使用定制发行包脚本（可选）

仅当项目包中确实存在启动脚本时使用。

双击启动

打开 VOZEB PRO 项目文件夹。

双击 Start-VOZEB-PRO.cmd。

如果 Docker Desktop 尚未启动，脚本可能尝试自动启动。

等待脚本完成，再用 docker compose ps 核对服务状态。

PowerShell 启动

Set-Location '<项目目录>'
.\start-vozeb.ps1

如果发行包使用 deployment 子目录保存 Compose 文件，则需要进入该目录：

Set-Location '<项目目录>\deployment'
docker compose up -d

自定义脚本和 admin-credentials.txt 属于发行包附加能力，不是官方仓库的通用启动步骤。

五、关闭与重启

标准 Compose

docker compose down

该命令会停止并删除容器，但不会删除命名数据卷。

不要执行 docker compose down -v，除非你确认要删除数据库和媒体数据。

定制脚本

如果项目包包含停止脚本，可双击：

Stop-VOZEB-PRO.cmd

重启

普通重启使用：

docker compose up -d

修改 .env 后，至少重新创建受影响的服务。例如只修改主应用配置时：

docker compose up -d --force-recreate app

六、常用检查命令

查看服务：

docker compose ps

查看主应用日志：

docker compose logs --tail 100 app

持续查看主应用日志：

docker compose logs -f app

查看数据库日志：

docker compose logs --tail 100 postgres

查看生成 Worker 日志：

docker compose logs --tail 100 generation-worker

检查数据库：

docker compose exec postgres pg_isready -U vozeb_pro -d vozeb_pro

七、常见问题

页面提示“无法访问”或“拒绝连接”

确认 Docker Desktop 已启动。

执行 docker compose ps，确认 vozeb-pro 处于运行状态。

查看日志：docker compose logs --tail 100 app。

检查 .env 是否存在必填变量缺失。

启动后仍停留在安装页

这通常表示数据库尚未初始化或尚未创建首个管理员。请使用 .env 中的 VOZEB_PRO_INSTALL_TOKEN 完成 /install 向导。

健康检查返回 503

/install 尚未完成时属于正常。

已完成安装仍返回 503 时，检查数据库连接和生成 Worker 心跳。

执行 docker compose logs --tail 100 app 和 docker compose logs --tail 100 generation-worker 查看原因。

管理员密码错误或不知道密码

首次管理员通过 /install 创建，不要猜测密码。

如果发行包明确提供 deployment/admin-credentials.txt，可以查看其中的用户名和密码。官方仓库标准流程不生成该文件。

Docker Desktop 无法启动

确认 Windows 已启用 WSL 2，或检查 macOS 的 Docker Desktop 服务状态。完成系统级安装或重启后再启动 VOZEB PRO。

图生视频失败

本地页面能打开，并不代表外部模型服务能够读取本机图片。图生视频需要：

可被上游访问的公网 HTTPS 地址

正确的 NEXT_PUBLIC_SITE_URL

持续运行的公网隧道

修改配置后重新创建主应用容器

详细步骤见 VOZEB PRO 图生视频公网配置。

八、下一步

本地应用启动完成后，继续配置：

在后台接入脑生云模型渠道。

配置文本、图片和视频逻辑模型。

在“创作 Agent”与画布中验证生成。

如需用本地图片生成视频，配置公网图片访问。

VOZEB 本地启动教程

VOZEB PRO 本地启动教程#

一、适用范围#

二、启动前准备#

环境要求#

检查项目目录#

三、首次启动（官方 Docker Compose）#

1. 获取项目并准备 .env#

2. 填写必要配置#

3. 拉取镜像并启动#

4. 完成安装向导#

5. 检查运行状态#

6. 打开本地页面#

四、使用定制发行包脚本（可选）#

双击启动#

PowerShell 启动#

五、关闭与重启#

标准 Compose#

定制脚本#

重启#

六、常用检查命令#

七、常见问题#

页面提示“无法访问”或“拒绝连接”#

启动后仍停留在安装页#

健康检查返回 503#

管理员密码错误或不知道密码#

Docker Desktop 无法启动#

图生视频失败#

八、下一步#