tt/ttstd-infinite-canvas

Fork 0

Files

ddCat 73fc9d2523 docs(*): 协作与项目入口 - 按当前架构重写根文档

2026-08-22 14:37:45 +08:00

10 KiB

Raw Blame History

影策

让一个故事，从文字走向银幕

GitHub · 功能 · 文档 · 安全策略

影策是一个开源的 AI 影视与短剧创作工作台。它把自由画布、结构化分镜、角色与风格资产、图片/视频/音频生成、异步任务和本地 Agent 放在同一条创作链路里，让创作者从文字 brief 走到可复用的镜头资产。

项目仍在快速开发，数据结构和外部接口可能直接调整。默认适合个人、本地或可信环境部署；未经安全配置，不要直接作为公网多人服务使用。

当前版本以仓库根目录 VERSION 为准。

当前能力

自由画布：项目、节点、连线、框选、缩放、小地图、撤销重做、导入导出和公开只读分享。
影视工作流：剧本、角色、场景、风格板、参考素材、结构化分镜和 3D 导演台。
多媒体生成：文本、图片、视频、音频任务，支持参考图、首尾帧、运镜、视频续写、局部修改和批量生成。
任务与素材：后端异步队列、任务日志、取消/重试、账号素材库、资源引用校验和登录后的跨设备同步。
Agent 协作：画布助手、本地 Canvas Agent、MCP 工具、Codex App 插件和技能库。
管理与渠道：系统渠道、逻辑模型、用量/积分、功能开关、对象存储、响应拦截和管理后台。

详细功能清单见 docs/content/docs/overview/features.mdx，实现入口见 docs/content/docs/backend/code-map.mdx。

架构概览

浏览器（web/）
  ├─ React 工作区、画布、任务中心、素材库
  ├─ localForage/Zustand 本地状态与降级缓存
  └─ request.ts / channel relay
          │ 登录态 JSON、SSE、资源请求
          ▼
后端（backend/）
  ├─ Gin handler -> service -> repository/model
  ├─ SQLite（本地）或 PostgreSQL + Redis（部署）
  ├─ 异步任务 worker、资源存储、权限和模型中转
  └─ provider/outbound -> 外部模型渠道

本地 Agent（canvas-agent/） <-> 浏览器画布 <-> Codex MCP / 本机 CLI
Codex 插件（plugins/infinite-canvas/）负责把 MCP 接入 Codex App。

前端默认把 /api 代理到 http://127.0.0.1:8080；生产环境由网页容器的 Nginx 代理到后端，只有 web 的 3000 端口需要对外暴露。系统模型和文本任务的 SSE 只在明确的流式路径关闭代理缓冲，详见 nginx.conf 和 SSE 文档。

本地开发

环境

Bun（前端和文档站）
Go 1.25（后端）
Node.js 18+（Canvas Agent）
如使用 Docker 开发，需要 Docker Compose

宿主机启动

git clone https://github.com/ddcat-ai/open-ai-canvas.git
cd open-ai-canvas

# 开发数据必须使用 Git 忽略的目录，不要直接使用 backend/data
mkdir -p .local/project-workbench-debug .local/cache/go-build .local/cache/go-mod

# 终端一：后端
cd backend
CANVAS_BACKEND_DATA_DIR=../.local/project-workbench-debug go run ./cmd/server

# 终端二：前端
cd ../web
bun install
bun run dev

打开 http://localhost:3000，注册第一个管理员账号，再在设置中配置模型渠道。前端的 Vite 配置会把 /api 代理到本机 8080。

如需修改代理目标，设置 VITE_API_PROXY_TARGET；如生产前端与后端不共源，构建时设置 VITE_CANVAS_BACKEND_URL。用户的模型 Base URL、API Key 和模型名保存在浏览器本地，真实密钥只应发送到可信且启用 HTTPS 的自部署后端。

Docker 开发和本地构建

源码热更新（Vite HMR + Air）：

LOCAL_UID=$(id -u) LOCAL_GID=$(id -g) \
  docker compose -f docker-compose.dev.yml up --build

本地构建前后端 release 镜像：

docker compose -f docker-compose.local.yml up -d --build

两种方式都使用容器内的数据卷；源码热更新编排额外绑定 .local/project-workbench-debug，避免 Compose 静默创建另一套开发账号数据。端口冲突时可通过 CANVAS_WEB_HOST_PORT、CANVAS_BACKEND_HOST_PORT 覆盖开发端口。

私网模型和本机渠道

后端默认拒绝本机、私网和链路本地模型地址。开发时只为可信主机设置精确白名单：

CANVAS_ALLOWED_PRIVATE_UPSTREAM_HOSTS=192.168.1.10

不要用 CANVAS_ALLOW_PRIVATE_UPSTREAMS=true 代替白名单。桌面本机渠道是另一项能力，只有后端绑定 127.0.0.1:8080 且设置 CANVAS_DESKTOP_LOCAL_CHANNELS_ENABLED=true 才会生效，云端和 Docker 默认不会获得该能力。

服务器部署

一键源码构建（推荐）

适用于 Linux 云服务器。脚本会安装 Docker，拉取源码，生成受保护的 .env，构建网页/后端镜像并启动 PostgreSQL、Redis、后端和网页：

curl -fsSL https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/main/scripts/install-server.sh | sudo bash

默认访问 http://服务器IP:3000。第一个注册账号会成为管理员；公开注册默认关闭。更新或排查：

cd /opt/open-ai-canvas
sudo docker compose --env-file .env \
  -f docker-compose.deploy.yml -f docker-compose.build.yml ps
sudo docker compose --env-file .env \
  -f docker-compose.deploy.yml -f docker-compose.build.yml logs -f --tail=200

直接使用 GHCR 镜像

服务器不需要源码时可使用镜像脚本：

curl -fsSL https://raw.githubusercontent.com/ddcat-ai/open-ai-canvas/main/scripts/install-server-image.sh | sudo bash

容器包不可匿名拉取时，先通过 GHCR_USERNAME 和 GHCR_TOKEN 登录 GHCR。需要固定版本或端口时，在 /opt/open-ai-canvas/.env 中设置 CANVAS_IMAGE_TAG、CANVAS_HTTP_PORT 后重新启动。

公网必做事项

先在受控网络注册首个管理员，再开放公网入口；保持 CANVAS_REGISTRATION_ENABLED=false。
设置准确的 CANVAS_CORS_ORIGINS，不要在公网使用 *。
使用 HTTPS，并保留反向代理的 Host、X-Forwarded-For、X-Forwarded-Proto。
只对 /api/tasks/:id/text-events 和系统模型事件流路径关闭缓冲、缓存和 gzip；不要把 SSE 配置复制给所有 /api/ 请求。
限制 .env、数据库、PostgreSQL/Redis 数据卷、上传目录、备份和 .settings-key 的权限；数据卷不等于备份。
后端 8080 留在 Compose 网络内，不要直接暴露到公网。

具体 Nginx/Caddy 示例和断线恢复方式见 docs/content/docs/overview/docker.mdx。

数据和安全边界

画布、项目、任务和素材登录后同步到后端；浏览器 localForage 仍承担缓存和后端不可用时的降级存储。
本地默认使用 SQLite；部署 Compose 使用 PostgreSQL 和 Redis。多实例 PostgreSQL 模式需要 REDIS_URL 用于限流、并发和熔断协调。
媒体资源可使用后端数据目录、阿里云 OSS 或腾讯云 COS。资源长期引用使用 resource:<id>，删除素材前会检查业务引用。
用户 API Key 不应出现在 URL、日志、错误上报或服务端长期明文存储中；使用真实 Key 前确认部署可信且链路为 HTTPS。
自定义渠道经后端 /api/ai/custom 中转；默认 SSRF 防护拒绝本机和私网目标，可信开发主机必须显式白名单。

安全问题请按 SECURITY.md 报告，不要在公开 Issue 中粘贴密钥、Cookie、数据库或生产日志。

Canvas Agent 和 Codex 插件

本地 Agent 用来连接网页画布与本机 Codex/CLI：

npx -y @ddcat666/open-ai-canvas-agent

仓库内开发构建：

cd canvas-agent
npm install
npm run build
node dist/index.js

启动后将终端输出的 Local URL 和 Connect token 填入画布右上角 Agent 面板。Agent 默认只监听 127.0.0.1，token 不应写入 URL、日志或任务正文。完整 MCP 工具、Codex App 插件安装和本地安全边界见 canvas-agent/README.md 与 plugins/infinite-canvas/README.md。

验证命令

项目不会在每次修改后自动执行验证；按改动范围手动运行：

# 前端
cd web && bun run build

# 后端
cd backend && go test ./...

# Canvas Agent
cd canvas-agent && npm test && npm run build

# 文档站
cd docs && bun run types:check

前端专项测试和后端集成测试较多，优先运行与改动模块相关的测试；UI 改动还应在浏览器检查关键路由、主题、弹窗、滚动和空态。验证结果必须在提交或交付说明中如实记录。

文档导航

根目录 AGENTS.md 约束协作方式；docs/index.md 是面向 AI 的文档索引。

许可证和上游

本项目采用 MIT 协议。影策基于 basketikun/infinite-canvas 的早期版本进行二次开发，上游作者和贡献者保留其对应代码的权利与署名。

10 KiB Raw Blame History Unescape Escape

影策