waoowaoo 自托管部署指南：AI 图片与视频创作工作台的安装、配置与升级实战

waoowaoo 是一个以"AI 创意工作台"为核心形态的图片与视频生成平台：你可以在右侧的 Assistant 中把一个想法逐步发展为创作 Brief 并持续产出素材，在画布上整理、精修和归档生成结果。本文基于仓库根目录的 README.md 与 docs/INSTALL.md，完整讲解其核心功能、技术栈、自托管快速启动、环境变量配置、HTTPS 证书信任、Temporal Worker 蓝绿发布与备份升级流程，并结合仓库中的 Compose 文件与部署脚本给出源码级佐证。

产品形态与核心功能

README 将产品定义为"An AI creative workspace for images and videos"，其核心工作方式围绕三条主线展开：

• 右侧 Assistant 主导创作：在一个持续进行的项目里，与右侧的 AI 助手共同打磨 Brief，并逐项生成图片与视频素材；
• 画布（Canvas）管理资产：上传参考素材、整理文件，并在画布上直接检视生成的图片与视频；
• 模型感知的参数生成：按所选模型的实际能力生成内容——包括模型感知的长宽比（aspect ratio）、时长、分辨率以及参考角色（reference roles）。

支持的生成模式与模型

具体可用性取决于所选模型。当前预览版暴露的是OpenRouter配置，可用模型包括 GPT Image 2、Nano Banana 系列、Seedance 系列，以及 MiniMax H3 / H3 Max。README 明确指出了两个使用边界：

• H3 Max 在本应用中只接受单张首帧，不接受首/尾帧对；
• 音乐（music）与配音/旁白（voiceover）控制不在本次预览范围内。

模型可用性与计费取决于供应商（provider）；请求通过用户自己的账户付费。应用 UI 目前支持中文与英文，日文、韩文版本是 README 的翻译文本。

值得补充的是，从仓库的 AI 能力组织方式看，生成能力并非散落在各处，而是由 src/lib/ai-registry 下的注册表、能力目录与定价目录统一管理（如 capabilities-catalog.ts、video-capabilities.ts），"模型感知"正是这些契约在运行期对具体模型能力进行匹配的结果；相关能力契约也有对应的 conformance 测试，例如 tests/contracts/canvas-generation-capabilities.conformance.test.ts。

精修（Refine）能力

对于已生成的图片，你可以把已有结果作为起点"精修出一个新版本"，同时保留原始结果——这意味着每一次迭代都有版本可追溯，不会因为调整而丢失前序产物。

技术栈一览

README 明确给出的技术栈如下，与仓库实际依赖基本一一对应（可对照 package.json）：

这套组合的架构意图是：Next.js 负责 Web 与 API 层，Prisma 管理 MySQL 中的应用数据，Temporal 承载需要长时间执行与可靠恢复的工作流（如 AI 生成任务的异步生命周期），Redis 承担缓存与传输，MinIO 为图片/视频等媒体提供私有对象存储，所有基础设施均可在自托管场景下通过 Docker Compose 一键拉起。

快速开始：两条安装路径

路径一：交给本地编码助手自动安装（官方推荐）

README 给出的最快捷方式，是把一段安装指令提示词（prompt）复制给具备终端访问能力的本地编码助手，由它检查机器环境、安装依赖并为你配置 Docker。该提示词的核心约束包括：

• 先阅读仓库 README、docs/INSTALL.md 与所选 GitHub Release；
• 使用已发布的预览 Release 及其预构建 Docker 镜像，将应用与 Codex runtime双双固定到该 Release 的不可变镜像 digest（repository@sha256:…）；
• 检查操作系统、CPU 架构、Docker Engine/Desktop、Compose v2、Git 与flock，缺失依赖时使用系统工具安装并征得同意；
• 使用全新安装目录，保留所有已有容器、文件与数据；
• 生成唯一的本地密钥并配置.env，不得打印或上传密钥；
• 遵循既有的 Worker bootstrap 流程，不要另创第二条启动路径；
• 使用同一 Release 的docker/caddy/Caddyfile与默认 Compose HTTPS 入口：SELF_HOSTED_HOST=localhost、SELF_HOSTED_HTTPS_PORT=1443；APP_HOST_PORT=13000仅做 HTTP 重定向；
• 只导出root.crt（Caddy 的本地根证书），解释其信任影响，并在浏览器所在宿主机上导入前取得用户明确同意（Windows 与 WSL 的信任体系相互独立）；绝不导出root.key，也不绕过 TLS 校验；
• 验证https://localhost:1443无证书告警，且浏览器实际使用h2（包括多标签页下的事件流；SSE 标签页并发 ≠ AI 任务并发上限）；
• 验证容器健康、应用可打开后告知本地 URL；
• 引导用户在应用内填写 OpenRouter API key，不要在聊天中索取；
• 未经用户批准不得启动付费 AI 生成。

该路径下，Caddy 由 Release 的 Compose 配置自动启动；完成本地证书信任后，浏览器打开https://localhost:1443（13000端口仅把 HTTP 重定向到 HTTPS）；源码开发模式npm run dev仍运行在http://localhost:3001。

路径二：手动安装（见 INSTALL.md）

推荐的分发形式是预构建 Docker 镜像：宿主机无需安装 Node.js、MySQL、Redis、Temporal 或 FFmpeg，应用依赖全部跑在容器内。完整的手动安装说明位于 docs/INSTALL.md，其要点如下。

机器检查与前置工具

• Docker Engine 或 Docker Desktop（运行 Linux 容器），Docker Compose2.24.4 或更新（含 v5），且支持!resetmerge 标签；
• Git 与 POSIX shell；
• flock：由既有 Worker rollout 脚本使用，Linux 通常通过util-linux提供；macOS 需安装兼容包；Windows 用户应在 WSL2 + Docker Desktop 集成下运行；
• Docker socket 访问权限允许应用为其各项目创建专属 Assistant 容器，因此必须使用可信的本地安装。

目录与文件约束

安装目录必须包含.env.example、两个 Compose 文件、docker/caddy/Caddyfile与scripts/temporal/worker-rollout.sh；不要把main分支的文件与旧 Release 混用。

启动命令序列

完成.env配置后，从安装目录依次执行（对应 docs/INSTALL.md 第 3 节）：

# 校验配置（不打印已解析配置，避免泄露密钥） docker compose config --quiet # 拉取所选的两个不可变镜像引用（应用 + Codex runtime） # docker pull <application-repository@sha256:digest> # docker pull <runtime-repository@sha256:digest> sh scripts/temporal/worker-rollout.sh bootstrap blue docker compose up -d sh scripts/temporal/worker-rollout.sh status docker compose ps -a

Compose 会初始化 MySQL、Redis、Temporal 及其 namespace、应用 schema 与私有 MinIO 存储，并以 Caddy 作为浏览器入口；rollout 脚本会在 Web 启动前建立第一个Current Worker Version。注意：不要在数据库可用前手动执行 schema push，不要用临时 Worker 命令替代 rollout 入口。

环境变量与 .env 配置详解

对于新安装，复制.env.example为.env（仅限全新安装），逐项阅读并用密码学随机密钥替换占位凭据，且永远不要把.env打印、上传或放入支持日志。以下表格整理自 .env.example 与 docs/INSTALL.md 的核心必填项：

必须生成的密钥包括：MYSQL_PASSWORD、MYSQL_ROOT_PASSWORD、REDIS_PASSWORD、TEMPORAL_MYSQL_PASSWORD、MINIO_ROOT_PASSWORD、MINIO_APP_SECRET_KEY、NEXTAUTH_SECRET、CRON_SECRET、API_ENCRYPTION_KEY。加密密钥（API_ENCRYPTION_KEY）必须在升级中保留，否则已保存的 API 凭据将无法解密。使用十六进制密钥可避免 URL 与 shell 转义问题。

数据库凭据需同时配置DATABASE_URL（宿主机侧 MySQL 地址，默认端口 13306）与COMPOSE_DATABASE_URL（容器侧mysql:3306），凭据含特殊字符时需 URL 编码。基础设施与 Web 的 bind 地址保持127.0.0.1（对应INFRA_BIND_ADDRESS/APP_BIND_ADDRESS）。

.env.example中还包含了几个值得注意的可调项：

• Codex runtime 资源限制：CODEX_RUNTIME_CPU_LIMIT=2、CODEX_RUNTIME_MEMORY_BYTES=2147483648（2 GiB）、CODEX_RUNTIME_PIDS_LIMIT=256、CODEX_RUNTIME_IDLE_TIMEOUT_MS=900000；
• Provider 异步执行预算：PROVIDER_GENERATION_TIMEOUT_MS=1200000（生成阶段超时）、PROVIDER_QUEUE_TIMEOUT_MS=1800000（供应商队列排队预算，默认 30 分钟，超预算作废旧请求并重试）、PROVIDER_POLL_INTERVAL_MS=3000；
• 默认工作流并发：DEFAULT_WORKFLOW_CONCURRENCY_ANALYSIS=5、DEFAULT_WORKFLOW_CONCURRENCY_IMAGE=20、DEFAULT_WORKFLOW_CONCURRENCY_VIDEO=10（数据库中用户的显式配置优先）；
• Web Search：OPENAI_API_KEY与OPENAI_WEB_SEARCH_MODEL（主 Agent 与 Creative Direction Worker 共用 OpenAI 托管 Web Search；搜索模型必须填裸的 OpenAI 模型 id，填路由键会运行期直接失败，留空使用内置默认值）；
• 出站访问限制：PROVIDER_OUTBOUND_PRIVATE_HOST_ALLOWLIST默认禁止 Provider 请求访问私网；
• 日志：LOG_FILE_MAX_BYTES=209715200（200MB）×LOG_FILE_MAX_GENERATIONS=10，日志与数据库共盘必须有界；
• 计费：自托管模式固定PROVIDER_CREDENTIAL_MODE=user-key、BILLING_MODE=OFF。

镜像 digest 的强制校验

仓库在多个层面强制"不可变 digest"约束。例如 docker-compose.yml 中 Temporal Worker 服务的 entrypoint 脚本会校验TEMPORAL_WORKER_IMAGE必须是*@sha256:*形式、digest 恰为 64 位十六进制、且不是全零占位符；scripts/temporal/worker-rollout.sh 中的require_image_digest也做了同样校验。这意味着.env.example中的全零 digest 只是让本地开发能解析 Compose 的占位符，正式 Worker 无法从它启动——这正是"用 Release 验证过的镜像引用，而不是latest"这一要求的具体落地。

自托管版 Compose 覆盖：Caddy、MinIO 与 HTTPS 入口

自托管版通过 docker-compose.self-hosted.yml 叠加在基础 docker-compose.yml 之上，主要做三件事：以 Caddy 接管浏览器入口并终止 HTTPS、将应用数据存储指向私有 MinIO、关闭应用的基础 HTTP 端口（ports: !reset []）。

Caddy 使用固定版本镜像caddy:2.11.4-alpine，其站点配置来自 docker/caddy/Caddyfile：

{ # HTTP/2 multiplexes the application's long-lived event streams. servers { protocols h1 h2 } } https://{$SELF_HOSTED_HOST:localhost}:{$SELF_HOSTED_HTTPS_PORT:1443} { tls internal reverse_proxy app:3000 } http://{$SELF_HOSTED_HOST:localhost}:{$APP_HOST_PORT:13000} { redir https://{$SELF_HOSTED_HOST:localhost}:{$SELF_HOSTED_HTTPS_PORT:1443}{uri} 308 }

这段配置直接印证了 README 的三点说明：

• servers { protocols h1 h2 }明确启用 HTTP/2，以便多路复用应用的长生命周期事件流（SSE）；
• tls internal由 Caddy 自签本地 CA 证书，因此安装后需要在浏览器宿主机信任该 CA 的公开根证书；
• APP_HOST_PORT=13000仅做 308 永久重定向到 HTTPS，不是直接的应用端点。

自托管版同时注入了自托管的存储契约：S3_ENDPOINT=http://minio:9000、S3_FORCE_PATH_STYLE=true、bucket 默认waoowaoo，并覆盖了NEXTAUTH_URL（由SELF_HOSTED_HOST与SELF_HOSTED_HTTPS_PORT派生）与TRUSTED_PROXY_HOPS=1。minio-init服务会在启动时校验 bucket 命名（小写、3–63 字符）、等待 MinIO 就绪、创建 bucket，并为应用创建最小权限的 S3 策略与专用访问用户——这也是"私有 MinIO 存储"在运行期的初始化实现。

本地证书信任与浏览器验证

自托管安装的证书信任流程（docs/INSTALL.md 第 3 节）分为"导出公钥根证书"与"在宿主机导入"两步：

certificate_export_dir=$(mktemp -d) docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt "$certificate_export_dir/root.crt"

安装助手必须先说明"信任该 CA 会改变宿主机证书信任"、识别该证书来源、并在导入前获得明确批准、展示证书指纹；绝不导出root.key、复制整个 CA 目录、关闭 TLS 校验或用浏览器告警绕过作为"安装成功"。

各宿主机平台的信任方式：

随后打开https://localhost:1443（应无证书告警），http://localhost:13000应保持路径重定向到该地址。在浏览器开发者工具的 Network 面板开启Protocol列并刷新，验证包括事件流在内的请求使用h2——仅"HTTPS 地址"或命令行请求成功并不能证明浏览器协商了 HTTP/2。最后打开多个标签页验证流开启时导航与事件更新依然流畅；多个 SSE 订阅只是传输连接，不改变也不衡量配置的 AI 任务并发上限，不要仅为填满标签页而启动付费任务。

Temporal Worker 蓝绿滚动发布

自托管版使用blue/green 双 slot的 Temporal Worker 滚动发布机制，由 scripts/temporal/worker-rollout.sh 统一管理（对应 npm scripttemporal:worker:rollout）。该脚本支持四个子命令：

npm run temporal:worker:rollout -- status npm run temporal:worker:rollout -- bootstrap blue|green npm run temporal:worker:rollout -- promote blue|green npm run temporal:worker:rollout -- retire blue|green

各命令语义（摘自脚本 usage 与实现）：

• bootstrap：唯一受支持的首次激活入口，当 Deployment 尚无 Current Version 时启动第一个显式 profiled Worker，并把它设为初始 Current Version；若另一个 slot 已在运行则拒绝执行；
• promote：先证明所选 slot 不是 Current Version，再仅启动该候选，等待 Temporal 看到其 poller，然后把其不可变 build 设为 Current Version，并自动把遗留的 pinned continuous Scheduler 迁移到 AutoUpgrade；从不停止上一个 slot；
• retire：拒绝 Current Version 与任何 drainage 状态非drained的版本；执行前要求对应 slot 的 replicas 已设为 0；
• status：展示 blue/green 两 slot 的运行 build、Deployment 的 Current Version 以及遗留 Scheduler 迁移状态。

脚本在非 status 模式下会通过flock加锁串行化部署变更，并对 Worker 身份做多项防御性校验：build ID 不能是local、必须只含字母数字与._-，镜像必须是 64 位十六进制 digest。这从源码层印证了 README/INSTALL 中"遵循既有 bootstrap 流程、不要另创启动路径"的要求——docker-compose.yml 中的temporal-verify-worker-version服务也会在应用启动前强制要求 Deployment 已存在显式 Current Version。

一次版本化升级的典型序列（docs/INSTALL.md 第 4 节）：

sh scripts/temporal/worker-rollout.sh promote green # 晋升成功后，把 APP_IMAGE 更新为新 digest 并更新 Web docker compose up -d sh scripts/temporal/worker-rollout.sh status # 仅当旧版本报告 drained 后，才在 .env 中持久化 blue replicas=0： sh scripts/temporal/worker-rollout.sh retire blue

后续升级在 blue/green 之间交替；整个过程必须始终使用同一.env、同一 Compose 文件集与同一项目名。

API 配置：OpenRouter 密钥与数据边界

应用启动后，进入个人资料的API 配置页面添加你的 OpenRouter API key。供应商调用通过你自己的账户付费；请把 API key 保存在应用内，不要放进聊天记录或支持日志（仓库的 scripts/security/secret-scan.mjs 也体现了对密钥泄漏的防线）。

数据边界方面，README 明确：项目数据与媒体使用本地数据库与私有 MinIO 存储；提示词与参考素材会被发送给供应商以完成所请求的 AI 任务；受支持的内联图片引用无需公网媒体 URL（也就是说，参考图可以走应用内部传输，不必先暴露到公网）。docker-compose.self-hosted.yml中 MinIO 的"对象 API 与管理控制台都不映射宿主机端口"这一设计（见 .env.example 存储段注释）从配置层面印证了"不需要公网 IP、域名、公开 MinIO 端点或隧道"；唯一的外部依赖是 AI API 本身需要联网与供应商余额。

备份、升级与升级前置检查

升级前必须备份：数据库、MinIO volume、data目录、runtime 宿主机目录与.env密钥；并保留caddy_data/caddy_config两个命名 volume（挂载于/data与/config），删除它们可能使已信任的 CA 失效。任何 Caddy 私密状态的备份都应视为机密材料，而非证书导出；只恢复媒体或只恢复数据库都不是完整的恢复方案。绝不把docker compose down -v当作升级手段。

升级前先阅读目标 Release 的迁移说明：旧安装可能需要显式迁移，不要运行db:push --accept-data-loss，也不要在未审阅的情况下假设早期预览数据库可以直接升级。README 还提示：由于当前处于Preview release阶段，迭代很快，仍存在少量 bug 与粗糙边缘，建议加入社区反馈与跟进更新。

从源码开发与自建镜像

• 生产自定义（构建源码）：同时构建Dockerfile与Dockerfile.codex-runtime，推送到你控制的镜像仓库并解析出不可变 digest，再喂给同一套安装流程；版本化 Compose 路径不从一个本地源码目录构建 Worker slot。
• 源码开发：安装 Node.js 22+ 与 npm，配置.env并把NEXTAUTH_URL设为http://localhost:3001，然后：

npm ci npm run dev

现有的开发启动器会先构建自己的 Docker 镜像并初始化依赖，再启动应用与 Worker；开发路径继续使用http://localhost:3001，Release 的 Compose HTTPS 默认值不会改变npm run dev。开发环境应使用独立的开发项目与数据库，不要指向版本化 Release 的 Temporal namespace（.env.example 中的注释明确禁止把源码开发环境与正式 Worker slot 接入同一 namespace）。源码构建更慢，不是默认的最终用户安装路径。

许可说明

自 v0.5.0-beta.1 起，本发行版采用Elastic License 2.0（见 LICENSE）：允许个人使用、内部业务使用、修改与再分发（受其条款约束）；但向第三方提供"以托管或托管方式访问该软件大部分功能"需要单独授权。更早的 Release 保留其原始许可证；第三方组件保留各自许可证。这是 source-available 软件，而非 OSI 批准的 open source。

小结

从 README.md 到 docs/INSTALL.md，waoowaoo 的自托管链路是一条"完整且可验证"的路径：预构建镜像 + Compose 覆盖 + Caddy HTTPS 入口 + Temporal Worker 蓝绿发布，配合严格的 digest 校验与密钥管理约束。无论是交给本地编码助手自动安装，还是手动逐项配置，关键动作都可以归纳为：固定不可变镜像 digest、生成并保护全部密钥、通过 bootstrap 建立首个 Worker Current Version、信任本地根证书并用 h2 验证浏览器连接、最后在个人资料中填入 OpenRouter key。掌握以上流程后，你可以在完全本地化的数据边界内运行一个生产可用的 AI 图片与视频创作工作台。