docs(i18n): add Chinese documentation (#520)

This commit is contained in:
Yiling-J
2026-11-06 11:46:53 +08:00
committed by GitHub
parent a71723d455
commit 2d2ea51668
35 changed files with 3702 additions and 64 deletions
+37
View File
@@ -0,0 +1,37 @@
---
title: 概览
description: 了解 Shumai —— 现代化媒体资产协作与审阅平台。
---
## 什么是 Shumai?
**Shumai** 是一款专为创意团队、视频剪辑师、设计师及客户打造的自托管媒体协作平台。它提供集中式工作区,支持实时上传、组织与审阅各类资产(视频、音频、图像和文档)。依托内置的 AI 能力与后台转码系统,Shumai 能显著简化媒体资产管理与审阅反馈流程。
![Shumai 控制台](/screenshot.webp)
---
## 核心特性
- **安全存储**:既支持在本地服务器存储创意资产,也可直接对接任意兼容 S3 协议的云存储服务商(如 AWS S3、Cloudflare R2 或 MinIO)。
- **媒体批注与画笔**:提供精准到帧的评论工具与画笔标注,可直接在视频画面或图像上绘制草图,大幅加快审阅迭代周期。
- **版本控制**:支持将同一文件的多个历史版本折叠至单条资产记录(版本堆栈)中,保持工作区井然有序,并可随时追踪修改历史。
- **AI 智能标签与搜索**:借助 Google Gemini 在上传时自动为文件生成标签,并支持根据视觉特征或概念语义精准检索资产。
- **自定义自动化**:支持编写定制脚本构建专属后台工作流,自动化处理团队日常重复性操作。
- **代理转码**:在后台自动将大容量摄影机原片与设计文件转换为适合 Web 端流畅播放的流媒体格式。
---
## 部署规模
根据团队规模与制作吞吐量,Shumai 支持以下两种运行模式:
### 1. 单机部署(默认)
适用于小型团队、本地开发或轻量级工作流。该模式下,Web 主服务、数据库以及后台任务(如媒体转码与 AI 标签生成)均运行在单台主机上。
### 2. 大规模分布式部署
推荐用于视频上传量巨大的生产环境。该模式下,后台任务通过持久化队列管理(基于 PostgreSQL 由 DBOS 统一编排调度)。重度负载可轻松分流至专用工作节点(例如将视频转码任务交由配备高规格 CPU/GPU 的机器执行,将 AI 智能体置于独立的沙箱环境中运行)。
_注意:分布式部署需要使用兼容 S3 的云存储,以确保所有工作节点均能正常访问上传的文件。_
+218
View File
@@ -0,0 +1,218 @@
---
title: 快速入门
description: 了解如何通过 Docker、NPM 或源码快速部署并运行 Shumai。
---
Shumai 提供三种安装方式。对于大多数管理员,推荐使用 **Docker Compose**,这是部署 Shumai 最便捷迅速的方式。
---
## 方案一:Docker Compose(推荐)
使用 Docker Compose 是运行 Shumai 最快捷的方式。无需克隆仓库或手动安装依赖包。请确保已安装 [Docker](https://docs.docker.com/get-docker/) 与 [Docker Compose](https://docs.docker.com/compose/install/),随后执行以下步骤:
1. **创建工作目录**:
为配置文件与数据卷创建并进入新的目录:
```bash
mkdir shumai && cd shumai
```
2. **下载配置文件**:
根据实际需求与可用内存(RAM)选择并下载对应的 `docker-compose.yaml` 配置文件:
- **精简版(建议内存 2 GB+)**:轻量级部署方案,仅包含 Shumai 主服务与 PostgreSQL 数据库。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.yaml
```
- **含向量模型服务版(建议内存 4 GB+)**:引入基于 `shumaiOne/embedding-server`(`EmbeddingGemma 2 740M`)的本地多模态语义搜索能力。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.embedding.yaml
```
- **完整版(建议内存 8 GB+)**:全功能一体化配置,包含 `embedding-server`、`turntable-renderer`(3D 预览渲染)以及 `Gotenberg`(文档 PDF 预览代理)。
```bash
curl -o docker-compose.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/docker-compose.full.yaml
```
> [!NOTE]
> Docker Compose 默认采用 CPU 软解转码。如果服务器配备了 GPU(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API 或 Rockchip RKMPP)并希望启用 GPU 硬件加速,请参阅[硬件转码指南](/zh/configuration/hardware-transcoding)。
3. **配置环境变量**:
打开 `docker-compose.yaml`,根据部署环境调整环境变量:
- `BETTER_AUTH_URL`:Shumai 服务器的公开访问基准 URL(例如 `https://shumai.example.com` 或 `http://12.34.56.78:3000`)。主要用于:
- **密码重置链接**:生成 CLI 及用户的密码重置 URL(`{BETTER_AUTH_URL}/reset-password?token=...`)。
- **邮件通知深度链接**:通知邮件中的默认基准跳转 URL(当未设置 `APP_URL` 时生效)。
- **会话 Cookie 安全策略**:在 HTTPS 部署环境下决定是否为会话 Cookie 附加 `Secure` 标记及 `__Secure-` 前缀。
- **MCP OAuth 2.1 与服务发现**:设置 OAuth 资源标识符(`{BETTER_AUTH_URL}/mcp`)、服务发现端点(`/.well-known/...`)以及出站 MCP OAuth 的默认重定向 URI。
> [!NOTE]
> 即使未配置 `BETTER_AUTH_URL`,**邮箱/密码方式的 Web UI 登录**仍可在纯 HTTP/IP 环境下正常工作。但在生产环境、自定义域名或 HTTPS 部署中,强烈建议显式配置该变量。请注意,根据 RFC 9728 规范,远程部署使用 MCP OAuth 2.1 时必须启用 HTTPS;若使用 HTTP IP 地址或域名,MCP OAuth 2.1 将优雅降级禁用,但 Web UI 及 MCP API Token 仍可正常使用。
- `BETTER_AUTH_SECRET`:用于对会话 Cookie、JWT 以及预签名文件上传/下载 URL(本地存储模式下)进行签名的随机密钥。模板中已包含一个用于本地临时体验的默认占位符,但在**生产环境或公开网络部署中,必须生成独立的密钥**(例如执行 `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`,则应配置为:
```yaml
AWS_ENDPOINT_URL_S3: http://12.34.56.78:12345
```
该地址必须能从客户端浏览器直接访问,并包含对外暴露的端口号。
- `SHUMAI_SERVER_PORT`:控制 Shumai 服务监听的端口,默认为 `3000`。
- **外部 S3 存储**:在此 Docker Compose 配置中,Shumai 默认使用内置的本地存储服务。若需改用外部兼容 S3 的存储,请配置对应的 S3 环境变量。以下为 AWS S3 与 Cloudflare R2 的配置示例:
**AWS S3 示例:**
```yaml
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.com
```
**Cloudflare R2 示例:**
```yaml
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
```
4. **启动服务**:
```bash
docker compose up -d
```
5. **访问控制台**:
打开浏览器并访问 **`http://localhost:3000`**(若为远程部署则访问 `http://<服务器-IP>:3000`),即可进入 Shumai Web UI。
### 生产环境部署(分布式工作节点)
如果团队视频上传量较大,建议采用基于独立工作节点与兼容 S3 存储后端的分布式部署方案。该方案可将高消耗的视频转码与 AI 智能体任务分流至专用的工作节点,确保主控制台始终保持敏捷流畅。详细配置步骤请参阅[分布式工作节点部署](/zh/configuration/distributed)指南。
---
## 方案二:通过 NPM 安装
可通过 Node 包管理器(NPM)将 Shumai 作为全局服务运行。
### 系统前置依赖
为支持媒体处理与安全隔离能力,宿主机系统必须安装以下系统工具:
- **FFmpeg 与 FFprobe**:视频转码与元数据提取所必需。
- _macOS_:`brew install ffmpeg`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install ffmpeg`
- **dcraw_emu (LibRaw)**:相机 RAW 格式图片解码与预览生成所必需。
- _macOS_:`brew install libraw`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install libraw-bin`
- **智能体沙箱工具**:用于安全隔离并执行自定义自动化脚本。
- _macOS_:`brew install ripgrep`
- _Linux (Ubuntu/Debian)_:`sudo apt-get install bubblewrap socat ripgrep`
### 详细安装步骤
1. **启动数据库**:
Shumai 需要搭载 `pgvector` 扩展的 PostgreSQL 数据库。启动数据库容器:
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
2. **安装 Shumai**:
```bash
npm install -g @shumai-one/shumai
```
3. **配置环境变量**:
创建新目录并进入,随后创建 `.env` 文件:
```bash
mkdir shumai && cd shumai
```
创建包含以下变量的 `.env` 文件:
```env
DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public
BETTER_AUTH_SECRET=your-random-32-character-secret-key
BETTER_AUTH_URL=http://localhost:3000
STORAGE_BACKEND=local
AWS_ENDPOINT_URL_S3=http://localhost:3000
```
> [!TIP]
> 远程或生产环境部署时,应将 `BETTER_AUTH_URL` 设置为服务器的公网地址。`AWS_ENDPOINT_URL_S3` 则必须包含对外访问的协议协议头与端口(例如 `http://localhost:3000` 或 `http://12.34.56.78:3000`),客户端浏览器将直接使用该地址上传文件。
4. **启动 Shumai**:
> [!IMPORTANT]
> **Bun 用户请注意:** 发布的 npm 包二进制文件包含 `#!/usr/bin/env node` Shebang,因此直接执行 `shumai` 将由 Node.js 运行。若使用 Bun 安装并希望在 Bun 运行时环境下运行,请在命令前添加 `bun run --bun`(例如 `bun run --bun shumai`)。
```bash
shumai
```
在浏览器中打开 `http://localhost:3000` 即可。
---
## 方案三:源码运行(适合开发者)
若要在本地搭建 Shumai 开发环境:
1. **克隆仓库并安装依赖**:
```bash
git clone https://github.com/shumaiOne/shumai.git
cd shumai
bun install
```
2. **启动数据库**:
启动本地数据库容器(同上述 NPM 部署步骤):
```bash
docker run --name shumai_postgres \
-e POSTGRES_USER=shumai \
-e POSTGRES_PASSWORD=shumai_password \
-e POSTGRES_DB=shumai_db \
-p 5432:5432 \
-d pgvector/pgvector:pg18
```
3. **创建环境配置文件**:
在工作区根目录下创建 `.env` 文件:
```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
```
4. **编译国际化(i18n)语言包**:
```bash
bun run i18n:compile
```
> [!TIP]
> 在前端开发过程中,可在独立终端窗口运行 `bun run i18n:watch`。当修改 `packages/webui/messages/` 中的文案时,系统会自动重新编译语言包。
5. **执行数据库迁移**:
应用数据库架构迁移:
```bash
bun run db:migrate
```
6. **启动开发服务器**:
```bash
bun run dev
```
命令执行后将在 `3000` 端口启动 Web 服务,并已开启热重载(Hot-Reloading)。
+126
View File
@@ -0,0 +1,126 @@
---
title: 兼容 S3 的对象存储
description: 为 Shumai 配置 AWS S3 或任意兼容 S3 协议的对象存储服务(Cloudflare R2、MinIO、Google Cloud Storage 等)。
---
Shumai 采用 Bun 原生高性能 S3 客户端存储与分发创意资产。借助标准化 S3 API,Shumai 能够无缝对接任意兼容 S3 协议的存储提供商,包括 AWS S3、Cloudflare R2、MinIO、Google Cloud Storage 等。
生产团队强烈建议配置独立的外部 S3 存储。这样既能将存储与应用服务解耦、支持独立弹性扩容,也可为分布式媒体转码提供共享存储支持。
---
## 配置变量
若要启用兼容 S3 的存储,请在 `.env` 文件或 Docker Compose 配置中更新以下环境变量:
| 变量名 | 说明 | 必填 | 默认值 / 示例 |
| :-------------------------------- | :------------------------------------------------------------------------------------------ | :--- | :----------------------------------- |
| `STORAGE_BACKEND` | 设为 `s3` 以启用兼容 S3 的存储后端。 | 是 | `s3` |
| `S3_BUCKET` | 存放文件的 S3 存储桶名称。 | 是 | `shumai-bucket` |
| `S3_REGION` | S3 存储桶所在地域(Region)。 | 否 | `auto` |
| `S3_ACCESS_KEY_ID` | 存储服务的访问密钥 ID(Access Key ID)。 | 是 | `your-access-key-id` |
| `S3_SECRET_ACCESS_KEY` | 存储服务的私有访问密钥(Secret Access Key)。 | 是 | `your-secret-access-key` |
| `AWS_ENDPOINT_URL_S3` | 兼容 S3 的存储服务端点 URL。 | 是 | `https://s3.us-east-1.amazonaws.com` |
| `PRESIGNED_URL_EXPIRES_IN` | 生成的预签名下载链接有效期(单位:小时)。 | 否 | `5` |
| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | 生成的预签名上传链接有效期(单位:小时)。若未指定,则回退继承 `PRESIGNED_URL_EXPIRES_IN`。 | 否 | `12` |
---
## 存储服务商配置示例
以下是主流 S3 存储服务商的配置模板。可将这些变量添加至 `.env` 文件,或置于 `docker-compose.yaml` 的 `environment` 配置项中。
### AWS S3
使用标准 AWS S3 时,配置对应的服务区域端点 URL:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-shumai-bucket
S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com
```
### Cloudflare R2
Cloudflare R2 需要配合 Cloudflare Account ID 拼接端点 URL,并将地域设置为 `auto`:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-shumai-bucket
S3_ACCESS_KEY_ID=your-r2-access-key-id
S3_SECRET_ACCESS_KEY=your-r2-secret-access-key
AWS_ENDPOINT_URL_S3=https://<account-id>.r2.cloudflarestorage.com
```
### MinIO(自托管)
针对本地开发或自托管 MinIO 环境,将端点指向 MinIO 服务地址与端口(通常为 `9000`):
```env
STORAGE_BACKEND=s3
S3_BUCKET=shumai
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin
AWS_ENDPOINT_URL_S3=http://localhost:9000
```
### Google Cloud Storage (GCS)
Google Cloud Storage 提供了兼容 S3 协议的 XML API。配置 HMAC 凭据并将端点设为标准 GCS 存储域名:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-gcs-bucket
S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY
S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key
AWS_ENDPOINT_URL_S3=https://storage.googleapis.com
```
### DigitalOcean Spaces
使用 DigitalOcean Spaces 时,请将端点 URL 设置为空间对应的地域:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-spaces-bucket
S3_ACCESS_KEY_ID=your-spaces-access-key-id
S3_SECRET_ACCESS_KEY=your-spaces-secret-access-key
AWS_ENDPOINT_URL_S3=https://nyc3.digitaloceanspaces.com
```
### Supabase Storage
若要通过 S3 协议连接 Supabase Storage,请确保已在 Supabase 控制台中开启 S3 连接支持(`Settings > Storage > Enable connection via S3 protocol`)。从该设置页面复制对应的端点 URL 与地域信息:
```env
STORAGE_BACKEND=s3
S3_BUCKET=your-supabase-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-supabase-access-key-id
S3_SECRET_ACCESS_KEY=your-supabase-secret-access-key
AWS_ENDPOINT_URL_S3=https://<account-id>.supabase.co/storage/v1/s3
```
---
## 跨域资源共享(CORS)配置
由于 Shumai 通过预签名 URL 直接从用户浏览器上传文件至存储桶,因此必须在存储桶上配置**跨域资源共享(CORS)**。若未配置 CORS,文件上传将因跨域安全限制导致网络错误或源错误(Origin Error)。
请确保存储桶的 CORS 策略允许来自 Shumai 应用 URL(例如 `http://localhost:3000` 或 `https://app.shumai.one`)的请求:
### CORS JSON 策略示例(AWS S3、R2、GCS)
```json
[
{
"AllowedHeaders": ["*"],
"AllowedMethods": ["GET", "PUT", "POST", "DELETE", "HEAD"],
"AllowedOrigins": ["http://localhost:3000", "https://your-shumai-domain.com"],
"ExposeHeaders": ["ETag"],
"MaxAgeSeconds": 3000
}
]
```