18 KiB
Shumai
开源版 阅流 / 分秒帧 - 专为创意与视频团队打造的审片与管理平台。
官方网站 | 文档(英文) | 在线演示 | Discourse 论坛 | English
功能
Shumai 是一个专为广告,短剧,漫剧等各类创意团队打造的开源协作管理平台,功能上类似阅流和分秒帧,提供了协作、审片和分享等各种功能:
- 支持 S3 和本地存储:你可以把创意素材安全地存放在本地硬盘或者任意兼容 S3 的存储服务里,比如 阿里云 OSS 或 MinIO 等。
- 冷归档存储:支持将原始大文件移至冷存储(如本地挂载的 NAS、AWS S3 Glacier、Google Cloud Storage Coldline 等归档存储类型)以节省主存储成本,同时保留主存储中的预览图、代理流和元数据,不影响网页浏览与即时播放。详情请参阅归档存储文档。
- 帧级别标注和评论:支持按帧进行精确反馈,同时支持直接在视频上进行标注,让团队成员能更精确地Get到你的想法。
- 安全的分享:可以生成私密分享链接,同时还支持给分享的图片/视频添加自定义水印,并将水印配置保存为模板以便重复使用。方便给客户、同事和合作方查看。
- 细粒度权限控制:支持按团队、项目设置角色权限,方便管理不同成员的访问范围。
- 基于 DBOS 的持久化工作流:视频转码任务由 DBOS 统一持久化编排与调度,具备自动恢复和容错能力。
- Docker/K8s 弹性扩缩容部署:支持在多个实例上横向自动扩缩容视频转码工作负载。详见 EKS 部署示例。
- 自定义素材元数据:可以按你的制作流程,自由定义动态元数据字段。
- 丰富的文件格式支持:支持预览常见创意文件格式,包括图片(支持 PSD)、视频、音频和文档,同时可上传和存储任意类型的文件。
- 3D 素材预览:通过集成 turntable-renderer 支持给 GLB、FBX、OBJ、STL、USD 和 DAE 等 3D 模型生成高质量的交互式转盘预览。
- Office 与文档在线预览:通过集成 Gotenberg,自动将 Word、PPT、Excel、Markdown、HTML 和 CSV 高质量转换为 PDF,直接在浏览器里丝滑预览。
- 语义搜索:支持按画面内容或概念含义搜索素材,详见相关文档。
- 非编剪辑导出与 Premiere 插件(测试版):支持将时间戳审阅评论导出至常用非编软件(Premiere Pro XML、DaVinci Resolve EDL、Final Cut Pro、Avid Media Composer),或使用实验性的 Premiere Pro 原生 UXP 插件导入媒体素材并将评论自动同步为时间轴标记。详见相关文档。
- 内置 MCP 服务端与 CLI 工具:支持通过
/mcp将外部 AI Agent 接入 Shumai,或使用shumai-cli在终端中管理项目、素材、评论与元数据。
Shumai 不仅仅只满足于「阅流」和「分秒帧」的开源替代。随着 GPT-Image-2、Seedance 2.5 这类强大视频/图片生成模型的问世,AI已经能够生成产品级的创意素材。只需要一句提示词,AI就能直接生成或修改图片和视频,而不用再打开 Photoshop、Premiere 或者 Houdini。因此Shumai也添加了Agent相关功能:
AI 功能完全可选。 你完全可以把 Shumai 当作纯粹的开源版「阅流 / 分秒帧」来用;如果团队不需要 AI,直接忽略即可。
- Agent 是你的团队成员:你可以在素材评论区里直接用
@提到 AI Agent,像拉一个真实同事进来一起看稿一样。 - Agent 也能当你的私聊助手:你可以单独和它聊天,让它帮你查东西、做任务。
- 自定义技能和工具:你可以给 Agent 添加自己的脚本、工具和自动化能力。
- 接入外部 MCP 工具 (Model Context Protocol):通过远程 MCP 服务端为 Agent 接入外部工具与 API,支持 OAuth 鉴权与按 Agent 独立分配访问权限。
- 沙箱隔离执行:Agent 生成的脚本会在隔离环境里运行,更安全。
- AI 自动打标与补全元数据:新素材上传后,AI 可根据画面内容自动识别并填写自定义元数据字段,省去手动归档打标的麻烦。
- 资源配额:支持按成员、角色或全团队对 AI Token、成本和工具调用设置使用上限与实时用量监控。
下面是一个简短的 demo 视频,展示了 Shumai Agent 能做什么:
https://github.com/user-attachments/assets/1186067a-72c0-41b9-836f-987438f2332a
Shumai 也将项目管理融入了创意工作流程。 内置的看板可以帮助团队整理任务以及跟踪进度。
最终目标是打造一个 Agentic看板,让 Agent 和团队成员能够围绕同一个目标协同工作。目前这一功能仍在开发中: 你已经可以在看板中为 Agent 创建任务,但 Agent 目前还无法自动执行这些任务。
Note
媒体处理与存储机制: 上传媒体文件后,Shumai 始终会保留并存储原始文件。请注意,系统中显示的文件大小为原始文件的大小,不包含转码后生成的代理文件大小。无论图片还是视频,都会额外生成一张 300p 的 WebP 封面图,作为文件列表中的预览图。此外:
- 图片: 会生成一份与原图分辨率完全一致的高质量 WebP 转码版本,在保证画质的同时提升浏览性能。
- 视频: 会根据转码配置生成至少一个代理视频,同时生成雪碧图(Sprite)和一段最长 1600 帧的低分辨率转码视频,用于实现快速拖动时间轴和即时视频预览。
如果你有任何反馈或想法,欢迎在 Issue #329 中和我们交流。如果 Shumai 对你有帮助,希望能给我们点个 ⭐,或者安利给身边做视频/创意的朋友。
安装指南
以下是使用本地存储的快速安装指南。如需了解高级配置(包括 S3 兼容存储配置、分布式 worker 编排等),请参阅我们的官方文档。
方案一:使用 Docker Compose(推荐)
复制这个提示词,让agent帮你安装
请帮我在本机使用 Docker Compose 一键部署 Shumai。
请严格参考官方文档:
https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/README_CN.md
要求:
1. 只能使用 Docker Compose local方式部署,不要使用其他部署方式。
2. 部署前请先检查本机是否已安装并可正常使用 Docker 和 Docker Compose。
3. 如果本机未安装 Docker,请立即提醒用户先安装 Docker,并停止后续部署操作。不要自行安装 Docker,也不要采用其他方式部署。
4. 获取 `docker-compose-aliyun.yaml` 文件内容时,必须通过 `https://gh-proxy.com` 加速访问,不要直接访问 GitHub Raw 地址。
使用 Docker Compose 是运行 Shumai 最快的方式。你无需克隆仓库,也不需要手动安装依赖包。请确保电脑上已安装 Docker 和 Docker Compose,然后按照以下步骤操作:
-
创建一个新文件夹,用于存放配置文件和数据:
mkdir shumai && cd shumai -
根据你的需求和机器可用内存,下载对应的
docker-compose.yaml配置文件(注意所有镜像都是阿里云源,想要使用dockerhub源请参考不带aliyun的compose文件):-
轻量版(建议内存:2 GB+):包含 Shumai 核心应用与 PostgreSQL 数据库。
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.yaml -
集成语义搜索版(建议内存:4 GB+):新增基于
shumaiOne/embedding-server(EmbeddingGemma 2 740M) 的本地多模态语义搜索能力。curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.embedding.yaml -
完整版(建议内存:8 GB+):一站式全功能版本,包含
embedding-server、turntable-renderer(3D 模型交互转盘预览)与Gotenberg(文档与表格 PDF 代理转码)。curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose-aliyun.full.yaml
Note
默认的 Docker Compose 配置使用基于 CPU 的软件转码。如果你的服务器支持硬件加速(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP),请参考 硬件加速转码配置文档。
-
-
配置环境变量:
-
BETTER_AUTH_URL:Shumai 服务的外部公开访问基础地址(例如https://shumai.example.com或http://12.34.56.78:3000),主要用于:- 密码重置链接:生成 CLI 及管理员重置密码链接(
{BETTER_AUTH_URL}/reset-password?token=...)。 - 邮件通知跳转链接:作为通知邮件中深度跳转链接的基础地址(若未配置
APP_URL则回退至此)。 - 会话 Cookie 安全标记:根据是否以
https://开头决定是否为浏览器会话 Cookie 启用Secure属性和__Secure-前缀。 - MCP OAuth 2.1 与元数据发现:配置 MCP OAuth 资源标识符(
{BETTER_AUTH_URL}/mcp)、元数据发现端点,以及外部 MCP OAuth 的默认重定向地址。
Note
Web UI 的邮箱/密码基础登录在私有 IP 或局域网 HTTP 环境下即使未配置该变量也可正常使用。但在生产环境、绑定域名或启用 HTTPS 时强烈建议配置。注意:MCP OAuth 2.1 依赖 HTTPS(本地 loopback 除外);若远程部署使用 HTTP,系统会优雅禁用 MCP OAuth 2.1 并记录日志,Web UI 与基于 API Token 的 MCP 访问不受影响。
- 密码重置链接:生成 CLI 及管理员重置密码链接(
-
BETTER_AUTH_SECRET:用于对浏览器会话 Cookie、JWT 以及本地存储模式下的预签名上传/下载链接进行 HMAC 签名加密的随机密钥。模板中提供了一个默认占位值以便本地快速体验,但在生产或公开部署环境中务必生成独立的随机密钥(例如通过命令openssl rand -base64 32生成)。 -
AWS_ENDPOINT_URL_S3:默认情况下指向http://localhost:{SHUMAI_SERVER_PORT}。当你使用本地存储(即默认配置STORAGE_BACKEND: local)并在远程服务器、自定义域名或自定义端口上公开访问 Shumai 时,请将AWS_ENDPOINT_URL_S3设置为客户端浏览器上传和下载文件所使用的外部 URL。例如,如果你将
docker-compose.yaml中的端口映射从3000:3000修改为了12345:3000,且服务部署在 IP 为12.34.56.78的服务器上,请进行如下设置:AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345此地址必须能够从客户端浏览器正常访问,且必须包含对外暴露的实际端口号。
-
SHUMAI_SERVER_PORT用于控制 Shumai 服务监听的端口,默认值为3000。 -
外部 S3 存储:默认情况下,该 Docker Compose 部署会自动启用集成的本地存储。若想切换至外部 S3 兼容存储,请在
environment中配置 S3 提供商的环境变量。以下是 AWS S3 和 Cloudflare R2 的配置示例:AWS S3 示例:
STORAGE_BACKEND: s3 S3_BUCKET: your-bucket-name S3_ACCESS_KEY_ID: your-access-key-id S3_SECRET_ACCESS_KEY: your-secret-access-key AWS_ENDPOINT_URL_S3: https://s3.us-east-1.amazonaws.comCloudflare R2 示例:
STORAGE_BACKEND: s3 S3_BUCKET: your-bucket-name S3_REGION: auto S3_ACCESS_KEY_ID: your-access-key-id S3_SECRET_ACCESS_KEY: your-secret-access-key AWS_ENDPOINT_URL_S3: https://<account-id>.r2.cloudflarestorage.com
-
在后台启动所有服务:
docker compose up -d -
打开浏览器,访问
http://localhost:3000即可开始使用(若是远程部署,请访问http://<你的服务器IP>:3000)。
扩展转码 Worker(并行处理)
默认情况下,Docker Compose 部署会按顺序逐个处理视频转码任务。这是出于系统设计考虑,因为视频转码属于计算密集型任务,容易耗尽可用的 CPU 或 GPU 资源。
但在批量上传(例如一次性上传 100+ 个视频)或处理需要耗费数小时的大型原始视频素材时,长时间的转码任务可能会阻塞后续文件的处理。此时,你可以通过增加额外的机器来横向扩展转码吞吐量。每台机器依然按顺序执行任务,但增加 worker 实例能够显著提升整体的并行处理能力。
Shumai 提供了独立的转码 Worker 镜像(支持 Docker Hub 与阿里云镜像源):
-
连接准备:启动一台临时机器,确保其能够正常访问你的 PostgreSQL 数据库和存储。
-
启动 Worker:配置相同的数据库与存储连接凭据并运行容器:
阿里云镜像(国内推荐):
docker run -d --name shumai_transcode_worker \ -e DATABASE_URL="postgres://shumai:shumai_password@<postgres-host>:5432/shumai_db?sslmode=disable" \ -e STORAGE_BACKEND="s3" \ -e S3_BUCKET="your-bucket-name" \ -e AWS_ENDPOINT_URL_S3="https://s3.us-east-1.amazonaws.com" \ -e S3_ACCESS_KEY_ID="your-access-key-id" \ -e S3_SECRET_ACCESS_KEY="your-secret-access-key" \ crpi-000nkafzu6xvpwsc.cn-hongkong.personal.cr.aliyuncs.com/shumai-one/shumai-transcode:latestWorker 启动后会自动接入任务队列,并与主实例并行消费并处理积压的转码任务。
-
随时停止:当转码队列处理完毕(或不再需要额外的算力)时,只需停止或移除 Worker 容器:
docker stop shumai_transcode_worker主 Shumai 服务的运行不会受到任何影响,不需要停机。
方案二:源码编译运行(开发环境)
如果你希望在本地参与 Shumai 的开发,请按以下步骤配置开发环境:
-
克隆代码仓库并安装依赖项:
git clone https://github.com/shumaiOne/shumai.git cd shumai bun install -
启动
pgvector数据库容器:docker run --name shumai_postgres \ -e POSTGRES_USER=shumai \ -e POSTGRES_PASSWORD=shumai_password \ -e POSTGRES_DB=shumai_db \ -p 5432:5432 \ -d docker.m.daocloud.io/pgvector/pgvector:pg18 -
在项目根目录下创建一个
.env文件,填入以下基础配置:DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public BETTER_AUTH_SECRET=ySxs7DxzHDZBbeeHNPEwBuspYwipBqz5Gk5XdBjNhWw= BETTER_AUTH_URL=http://localhost:3000 STORAGE_BACKEND=local SHUMAI_SERVER_PORT=3000 AWS_ENDPOINT_URL_S3=http://localhost:3000 -
生成多语言国际化(i18n)代码:
bun run i18n:compileTip
在前端开发过程中,可以在单独的终端窗口中运行
bun run i18n:watch,在修改packages/webui/messages/下的翻译文案时自动重新编译。 -
执行数据库结构迁移:
bun run db:migrate -
启动本地开发服务器:
bun run dev
Note
如需通过 NPM 或包管理器全局安装运行 Shumai,请参考官方 NPM 安装指南。
命令行工具 (CLI)
Shumai 自带一个功能完备的命令行工具(CLI),支持你直接在终端里高效管理项目、文件夹、素材,批量上传文件/目录,以及快速创建新版本。
关于 CLI 的安装与详细使用指南,请参阅 CLI Readme。
MCP 服务器
Shumai 内置 MCP 服务器(地址为 /mcp),Claude Code、Cursor、Kiro 等外部智能体可以使用 API 令牌连接,浏览并整理你的项目。配置方法请参阅 MCP 服务器指南。
社区
感谢 LINUX DO 提供开源交流社区,欢迎佬友交流使用体验与改进建议。

