源码开发

实际运行、构建和耗时验证放在远程开发机；本地 Mac 仅改代码和查看日志。默认渠道由浏览器通过同源 /api/proxy 请求本项目代理；用户新增的自定义渠道仍由浏览器请求对应的 OpenAI 兼容接口。

1. 从源码启动 Web

需要 Bun、项目专属 PostgreSQL（数据库名 infinite_canvas）、Redis，以及所测试功能需要的 Proxy、Video Dataset Engine 和 DramaClaw。先从仓库根目录生成未跟踪的环境文件，填写本开发环境自己的值；DATABASE_URL 必须指向本项目数据库，LOCAL_PROXY_BASE_URL、VIDEO_DATASET_API_URL 等服务地址必须从运行 Web 的主机可达。不要复制生产数据、密钥或媒体。

cp .env.example web/.env.local
cd web
bun install --frozen-lockfile
bun run db:migrate
bun run dev

浏览器访问 http://localhost:3000。Web 源码运行不等于后端依赖已经启动；提交生成任务前，先检查所需服务的健康接口和模型能力。bun run typecheck 与 bun test src scripts 可用于改动后的最小验证。

2. 使用 Compose 启动完整开发栈

若要在远程 Docker 主机运行完整栈，先按 .env.example 填写根目录 .env，然后使用仓库启动入口：

./scripts/start-stack.sh
./scripts/dev.sh status

启动脚本会检查必填凭据和端口，并构建 Web、Proxy、PostgreSQL、Redis、Video Dataset Engine 等服务。停止本项目开发栈使用 ./scripts/dev.sh down，不要加 -v。源码 Web 和完整 Compose Web 都默认占用 3000 端口，不要同时启动。

该编排会创建项目专属的 PostgreSQL 容器和命名卷，不发布数据库端口。主画布固定使用 infinite_canvas，不会读取其他 .env 中的外部数据库地址。

Compose 使用 /v1/live 判断本项目代理进程是否存活，因此单个外部供应商临时故障不会阻止 Web 启动。/v1/ready 会主动检查 Key、OSS、网络和供应商鉴权：远端硬故障模型列在 disabled，Key 无效但可恢复的可选模型列在 optional_unavailable，二者不影响核心就绪；启用后仍异常的核心模型列在 unavailable 并返回 503。

Priya Live 发布桥使用四个仅服务端可见的变量：PRIYA_LIVE_WEBHOOK_URL、PRIYA_LIVE_WEBHOOK_SECRET、PRIYA_LIVE_READ_TOKEN 与 PRIYA_LIVE_STATUS_READ_TOKEN。后两者方向相反，必须使用不同的至少 32 字节随机值；前者供 Priya 拉取 IC manifest/素材，后者供 IC 读取 Priya 目标角色和发布状态。priya-live-outbox-worker 只连接本项目 PostgreSQL 并读取 webhook 地址与 HMAC secret，不挂载媒体目录或其他生产秘密；它按 PRIYA_LIVE_OUTBOX_POLL_MS 派发到期事件。直传票据先在 PostgreSQL 建立 45 分钟 reservation，每次重试都会换用新的 direct-immutable 物理 key，OSS 以 create-only 条件写阻断重放覆盖；浏览器用 X-Direct-Upload-Token 请求头提交票据，禁止把票据写入 URL/query 或访问日志。finalize 只在短事务中标记 committed 并落 media_objects。Web、Proxy 与 direct-media-cleanup-worker 的 MEDIA_WORKER_INTERNAL_TOKEN 必须字节级一致且至少包含 32 个 UTF-8 字节，直传票据/回执使用 direct-upload-v1 独立 HMAC 域。清理 worker 仅删除到期且未 committed 的 reservation 对象，并在删除前等待同 key 的在途上传，不对物理前缀做盲 TTL 清理。

docker-compose.local.yml 与 docker-compose.deploy.yml 现在都只兼容性引用根 docker-compose.yml，不再维护第二份服务图。PostgreSQL 不发布宿主机端口；默认入口的代理、Video Dataset 与 DramaClaw 诊断端口只绑定 127.0.0.1。

这三个入口的数据库卷和端口是有意隔离的，不能混用：

docker-compose.deploy.yml 保留旧项目名、旧数据库密码，并把历史卷声明为显式 external volume，是为了继续挂载历史 deploy 数据；不要把项目名改成 infinite-canvas-deploy。External 声明会在卷缺失时拒绝启动，避免 Compose 静默创建空数据库。启动旧 deploy 前先只读确认卷存在：

docker compose -f docker-compose.deploy.yml config --volumes
docker volume inspect infinite_canvas_postgres_data

如果第二条命令提示卷不存在，而你预期看到旧数据，应立即停止并核对 Docker context，不要通过新建卷或自动恢复来掩盖问题。任何入口都不要执行 docker compose down -v；兼容层不会迁移、复制或删除数据库数据。

在配置了 VFE_SSH_KEY_PATH 的开发主机上，启动脚本会启用可选的 vfe profile；没有该通道时，VFE 源库会明确显示为可选依赖不可用。

源码模式的 PostgreSQL 地址使用开发主机的 127.0.0.1、localhost 或 ::1；容器内 Web 使用 Compose 服务名 postgres。两种入口都只使用本项目的 infinite_canvas 数据库。

2. 配置模型

默认本地代理的供应商 Key 只从 proxy/models.env、proxy/oss.env 或 Compose 指定的本项目代理环境文件读取，不保存在 PostgreSQL，也不会从其他项目数据库读取。前端默认显示的 sk-local 只是同源代理渠道占位值，不是供应商密钥。

HappyHorse 和国内站 Qwen/Wan 默认使用 DASHSCOPE_CN_BASE_URL。若 RICKIE_CN_KEY 属于工作空间专属端点，可单独配置 RICKIE_CN_BASE_URL=https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1，避免与 Wan 2.7 使用的 Key/端点混用。

重建后可直接查看不会产生生成费用的供应商探测结果：

curl -sS 'http://127.0.0.1:8001/v1/providers/status?refresh=true'
curl -sS http://127.0.0.1:8001/v1/ready

前者区分鉴权失败、上游不可用和 OSS 不可用；后者列出受影响的具体模型。生成请求若被供应商内容审核拒绝会返回 422，媒体地址无法下载会返回 502，不再统一伪装成内部 500。

已确认远端工作流不可用的非调度模型可通过 DISABLED_MODELS 逗号分隔配置。Krea、Qwen Edit、Face Swap 和 LTX 则以调度器 /v1/capabilities 返回的逐工作流候选为准，健康页本身 200 不代表模型可用。Key 无效的模型由主动探测暂时标记不可用；更换代理环境中的 Key 并重启后，在前端配置页点击“拉取模型”会强制重新探测并恢复。

逐模型的历史测试记录见 test-image/model-availability.md。当前运行时会直接显示调度器的最新结果；Krea 及其编辑工作流已恢复，LTX 若仍缺少工作流节点会单独显示不可用原因。

如需自定义渠道，可在右上角配置弹窗填写自己的 Base URL、API Key 和模型名。自定义渠道配置保存在当前浏览器。第三方提示词由 Next.js route 拉取并缓存在运行实例内存中；WebDAV 可选择前端直连或 Next.js 转发。

3. 启动文档站

如果需要单独调整文档站，在 docs 目录执行：

bun run dev

常见场景

• 改画布、页面和交互：主要看 web/
• 改提示词缓存或 WebDAV 代理：主要看 web/src/app/api/ 和 web/src/app/webdav-proxy/
• 改文档站内容：主要看 docs/content/docs/
• 数据库连接仅允许 127.0.0.1、localhost、::1 或 Compose 内的 postgres 服务，且数据库名必须是 infinite_canvas

恢复当前项目内的画布快照

若当前 Compose 卷中没有旧画布、且项目目录内已有 data-dump-20260730-0153 快照，可只恢复指定画布：

node scripts/restore-local-canvas.mjs ByygBA7FudmcBXTrM9N8L

恢复快照中的全部原画布：

node scripts/restore-local-canvas.mjs --all

恢复工具只接受当前项目内的 dump 目录，并校验 PostgreSQL 容器的 Compose 工作目录和代理的 infinite-canvas/media 前缀。它不会清空数据库；当前数据库中已有且包含节点的画布保持不动，缺失画布和空节点画布从快照补回。媒体上传完成后才在单个事务中合并画布和媒体元数据，结果在 localhost:3000 查看。