From 2d2ea5166858a8f13994d5f2d79f60c1948a43cb Mon Sep 17 00:00:00 2001 From: Yiling-J Date: Fri, 6 Nov 2026 11:46:53 +0800 Subject: [PATCH] docs(i18n): add Chinese documentation (#520) --- docs/docs.json | 220 ++++++++++----- docs/zh/configuration/archive-storage.mdx | 250 ++++++++++++++++++ docs/zh/configuration/distributed.mdx | 173 ++++++++++++ docs/zh/configuration/env-variables.mdx | 161 +++++++++++ .../zh/configuration/hardware-transcoding.mdx | 233 ++++++++++++++++ docs/zh/developer/mcp-server.mdx | 222 ++++++++++++++++ docs/zh/getting-started/overview.mdx | 37 +++ docs/zh/getting-started/quickstart.mdx | 218 +++++++++++++++ docs/zh/getting-started/s3-storage.mdx | 126 +++++++++ docs/zh/using-shumai/3d-asset-support.mdx | 153 +++++++++++ docs/zh/using-shumai/agent-providers.mdx | 49 ++++ docs/zh/using-shumai/agent-sandbox.mdx | 45 ++++ docs/zh/using-shumai/agent-skills.mdx | 54 ++++ docs/zh/using-shumai/agent-tools.mdx | 164 ++++++++++++ docs/zh/using-shumai/agents-md.mdx | 53 ++++ docs/zh/using-shumai/agents.mdx | 51 ++++ docs/zh/using-shumai/asset-management.mdx | 54 ++++ docs/zh/using-shumai/collections.mdx | 55 ++++ docs/zh/using-shumai/comments.mdx | 51 ++++ docs/zh/using-shumai/email-notifications.mdx | 127 +++++++++ docs/zh/using-shumai/embedding-server.mdx | 131 +++++++++ docs/zh/using-shumai/gotenberg.mdx | 108 ++++++++ .../using-shumai/image-video-generation.mdx | 140 ++++++++++ docs/zh/using-shumai/mcp-servers.mdx | 115 ++++++++ docs/zh/using-shumai/metadata.mdx | 70 +++++ docs/zh/using-shumai/nle-and-premiere.mdx | 126 +++++++++ docs/zh/using-shumai/notifications.mdx | 54 ++++ docs/zh/using-shumai/password-reset.mdx | 60 +++++ docs/zh/using-shumai/quotas-settings.mdx | 121 +++++++++ docs/zh/using-shumai/semantic-search.mdx | 40 +++ docs/zh/using-shumai/share-links.mdx | 83 ++++++ docs/zh/using-shumai/sort-and-search.mdx | 39 +++ .../using-shumai/team-project-management.mdx | 58 ++++ docs/zh/using-shumai/transcode-settings.mdx | 81 ++++++ docs/zh/using-shumai/version-stack.mdx | 44 +++ 35 files changed, 3702 insertions(+), 64 deletions(-) create mode 100644 docs/zh/configuration/archive-storage.mdx create mode 100644 docs/zh/configuration/distributed.mdx create mode 100644 docs/zh/configuration/env-variables.mdx create mode 100644 docs/zh/configuration/hardware-transcoding.mdx create mode 100644 docs/zh/developer/mcp-server.mdx create mode 100644 docs/zh/getting-started/overview.mdx create mode 100644 docs/zh/getting-started/quickstart.mdx create mode 100644 docs/zh/getting-started/s3-storage.mdx create mode 100644 docs/zh/using-shumai/3d-asset-support.mdx create mode 100644 docs/zh/using-shumai/agent-providers.mdx create mode 100644 docs/zh/using-shumai/agent-sandbox.mdx create mode 100644 docs/zh/using-shumai/agent-skills.mdx create mode 100644 docs/zh/using-shumai/agent-tools.mdx create mode 100644 docs/zh/using-shumai/agents-md.mdx create mode 100644 docs/zh/using-shumai/agents.mdx create mode 100644 docs/zh/using-shumai/asset-management.mdx create mode 100644 docs/zh/using-shumai/collections.mdx create mode 100644 docs/zh/using-shumai/comments.mdx create mode 100644 docs/zh/using-shumai/email-notifications.mdx create mode 100644 docs/zh/using-shumai/embedding-server.mdx create mode 100644 docs/zh/using-shumai/gotenberg.mdx create mode 100644 docs/zh/using-shumai/image-video-generation.mdx create mode 100644 docs/zh/using-shumai/mcp-servers.mdx create mode 100644 docs/zh/using-shumai/metadata.mdx create mode 100644 docs/zh/using-shumai/nle-and-premiere.mdx create mode 100644 docs/zh/using-shumai/notifications.mdx create mode 100644 docs/zh/using-shumai/password-reset.mdx create mode 100644 docs/zh/using-shumai/quotas-settings.mdx create mode 100644 docs/zh/using-shumai/semantic-search.mdx create mode 100644 docs/zh/using-shumai/share-links.mdx create mode 100644 docs/zh/using-shumai/sort-and-search.mdx create mode 100644 docs/zh/using-shumai/team-project-management.mdx create mode 100644 docs/zh/using-shumai/transcode-settings.mdx create mode 100644 docs/zh/using-shumai/version-stack.mdx diff --git a/docs/docs.json b/docs/docs.json index ead133cc..2d422aab 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -21,75 +21,167 @@ ] }, "navigation": { - "groups": [ + "languages": [ { - "group": "Getting Started", - "pages": [ - "getting-started/overview", - "getting-started/quickstart", - "getting-started/s3-storage" + "language": "en", + "default": true, + "navbar": { + "links": [ + { + "label": "Changelog", + "href": "/changelog" + } + ] + }, + "groups": [ + { + "group": "Getting Started", + "pages": [ + "getting-started/overview", + "getting-started/quickstart", + "getting-started/s3-storage" + ] + }, + { + "group": "Using Shumai", + "pages": [ + "using-shumai/asset-management", + "using-shumai/comments", + "using-shumai/version-stack", + "using-shumai/sort-and-search", + "using-shumai/semantic-search", + "using-shumai/team-project-management", + "using-shumai/notifications", + "using-shumai/metadata", + "using-shumai/collections", + "using-shumai/share-links", + "using-shumai/nle-and-premiere", + "using-shumai/3d-asset-support", + "using-shumai/gotenberg", + "using-shumai/embedding-server" + ] + }, + { + "group": "Shumai Agent Settings", + "pages": [ + "using-shumai/agent-providers", + "using-shumai/image-video-generation", + "using-shumai/agents", + "using-shumai/agents-md", + "using-shumai/agent-skills", + "using-shumai/agent-tools", + "using-shumai/mcp-servers", + "using-shumai/agent-sandbox" + ] + }, + { + "group": "Team Settings", + "pages": [ + "using-shumai/transcode-settings", + "using-shumai/quotas-settings", + "using-shumai/email-notifications", + "using-shumai/password-reset" + ] + }, + { + "group": "Developer", + "pages": ["developer/mcp-server"] + }, + { + "group": "Configuration", + "pages": [ + "configuration/env-variables", + "configuration/hardware-transcoding", + "configuration/archive-storage" + ] + }, + { + "group": "Distributed Deployment", + "pages": ["configuration/distributed"] + }, + { + "group": "Releases", + "pages": ["changelog"] + } ] }, { - "group": "Using Shumai", - "pages": [ - "using-shumai/asset-management", - "using-shumai/comments", - "using-shumai/version-stack", - "using-shumai/sort-and-search", - "using-shumai/semantic-search", - "using-shumai/team-project-management", - "using-shumai/notifications", - "using-shumai/metadata", - "using-shumai/collections", - "using-shumai/share-links", - "using-shumai/nle-and-premiere", - "using-shumai/3d-asset-support", - "using-shumai/gotenberg", - "using-shumai/embedding-server" + "language": "zh", + "navbar": { + "links": [ + { + "label": "Changelog", + "href": "/changelog" + } + ] + }, + "groups": [ + { + "group": "快速入门", + "pages": [ + "zh/getting-started/overview", + "zh/getting-started/quickstart", + "zh/getting-started/s3-storage" + ] + }, + { + "group": "使用指南", + "pages": [ + "zh/using-shumai/asset-management", + "zh/using-shumai/comments", + "zh/using-shumai/version-stack", + "zh/using-shumai/sort-and-search", + "zh/using-shumai/semantic-search", + "zh/using-shumai/team-project-management", + "zh/using-shumai/notifications", + "zh/using-shumai/metadata", + "zh/using-shumai/collections", + "zh/using-shumai/share-links", + "zh/using-shumai/nle-and-premiere", + "zh/using-shumai/3d-asset-support", + "zh/using-shumai/gotenberg", + "zh/using-shumai/embedding-server" + ] + }, + { + "group": "Agent 智能体配置", + "pages": [ + "zh/using-shumai/agent-providers", + "zh/using-shumai/image-video-generation", + "zh/using-shumai/agents", + "zh/using-shumai/agents-md", + "zh/using-shumai/agent-skills", + "zh/using-shumai/agent-tools", + "zh/using-shumai/mcp-servers", + "zh/using-shumai/agent-sandbox" + ] + }, + { + "group": "团队设置", + "pages": [ + "zh/using-shumai/transcode-settings", + "zh/using-shumai/quotas-settings", + "zh/using-shumai/email-notifications", + "zh/using-shumai/password-reset" + ] + }, + { + "group": "开发者指南", + "pages": ["zh/developer/mcp-server"] + }, + { + "group": "系统配置", + "pages": [ + "zh/configuration/env-variables", + "zh/configuration/hardware-transcoding", + "zh/configuration/archive-storage" + ] + }, + { + "group": "分布式部署", + "pages": ["zh/configuration/distributed"] + } ] - }, - { - "group": "Shumai Agent Settings", - "pages": [ - "using-shumai/agent-providers", - "using-shumai/image-video-generation", - "using-shumai/agents", - "using-shumai/agents-md", - "using-shumai/agent-skills", - "using-shumai/agent-tools", - "using-shumai/mcp-servers", - "using-shumai/agent-sandbox" - ] - }, - { - "group": "Team Settings", - "pages": [ - "using-shumai/transcode-settings", - "using-shumai/quotas-settings", - "using-shumai/email-notifications", - "using-shumai/password-reset" - ] - }, - { - "group": "Developer", - "pages": ["developer/mcp-server"] - }, - { - "group": "Configuration", - "pages": [ - "configuration/env-variables", - "configuration/hardware-transcoding", - "configuration/archive-storage" - ] - }, - { - "group": "Distributed Deployment", - "pages": ["configuration/distributed"] - }, - { - "group": "Releases", - "pages": ["changelog"] } ] } diff --git a/docs/zh/configuration/archive-storage.mdx b/docs/zh/configuration/archive-storage.mdx new file mode 100644 index 00000000..bc2ac30a --- /dev/null +++ b/docs/zh/configuration/archive-storage.mdx @@ -0,0 +1,250 @@ +--- +title: 归档存储 +description: 配置二级冷存储以归档迁移原生媒体文件,同时完整保留浏览器内代理播放与即时预览。 +--- + +高分辨率摄影机素材、RAW 序列帧、母带分轨音频以及庞大的 3D 资产会迅速耗尽主存储空间。Shumai 的**归档存储**(冷存储)功能支持创作团队将庞大的母盘原始文件分流至低成本的冷存储(例如本地 NAS、AWS S3 Glacier 或 Google Cloud Storage Coldline),同时将所有媒体代理版本、预览图、音频波形文件及元数据完整保留在主存储中。 + +团队成员可在 Web 浏览器中无缝浏览、搜索、拖拽预览并审阅已归档的资产。当需要母盘制作或调色而调用原始文件时,只需一键即可将其恢复解冻至主存储。 + +--- + +## 核心工作机制 + +1. **仅归档原始文件**:系统仅将原始素材文件迁移至归档存储。预览图、缩略图及转码代理文件(如 180p 拖拽代理、1080p 可流式播放 MP4、WebP 海报图)均保留在主存储中。 +2. **高可靠持久化异步工作流**:文件的归档与恢复操作由 DBOS 管理的独立 Worker 任务队列(`archive_queue`)在后台处理。任务能够抵御网络中断、缓慢的 S3 传输以及服务器重启。 +3. **透明的资产生命周期**: + - 资产归档过程中,其状态流转为 `archiving`(归档中),完成后定格为 `archived`(已归档)。 + - 资产解冻恢复过程中,状态流转为 `restoring`(恢复中),原始文件恢复至主存储后变回 `processed`(已处理)。 + - 移至废纸篓并被永久清空的资产,其在归档存储中的原始文件也会被自动同步彻底删除。 +4. **支持文件夹与版本堆栈**:对文件夹或版本堆栈执行归档,将以递归方式归档其包含的所有文件资产;恢复文件夹或版本堆栈则会一并恢复其中包含的所有已归档文件。 + +--- + +## 存储拓扑 + +Shumai 支持灵活多样的存储架构,主存储与归档存储可分别采用不同的底层后端或服务商: + +| 拓扑模式 | 主存储 | 归档存储 | 说明 | +| :----------------------------- | :---------- | :------- | :---------------------------------------------------------------------------------------------------------------------- | +| **本地 NAS / 挂载目录** | Local 或 S3 | `local` | 将文件迁移至已挂载的网络共享目录(NFS / SMB)或二级冷备磁盘阵列。 | +| **独立 S3 存储桶 / 服务商** | S3 或 Local | `s3` | 将文件流式传输至 AWS S3、Wasabi、Backblaze B2 或 Google Cloud Storage 上的专属归档存储桶。 | +| **同一 S3 存储桶(原位分层)** | AWS S3 | `s3` | 在 AWS S3 同一存储桶内,利用冷存储类型(`GLACIER`、`GLACIER_IR`、`DEEP_ARCHIVE`)就地重新分层,无需跨网络重新上传数据。 | + +--- + +## 配置变量 + +在 `.env` 文件或 Docker Compose 配置中添加以下环境变量即可启用和配置归档存储。 + +### 通用配置 + +| 变量 | 说明 | 是否必填 | 默认值 | +| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ | :------- | :------------- | +| `ARCHIVE_STORAGE_BACKEND` | 归档存储后端:`local` 或 `s3`。未设置时,WebUI 中的归档功能保持禁用。 | 否 | 未设置(禁用) | +| `CONCURRENCY_ARCHIVE` | 后台 Worker 执行归档与恢复任务的最大并发数。 | 否 | `5` | +| `SHUMAI_WORKERS` | 应用服务器监听的 Worker 任务队列:`all`(默认)、`none`、`agent`(或 `ai`)、`transcode`、`archive`。需设置为 `all` 或 `archive` 以处理归档任务。 | 否 | `all` | +| `AUTO_ARCHIVE_INTERVAL_MINUTES` | 后台自动归档扫描任务的执行频率(单位:分钟)。支持小数值(例如测试时设为 `0.02`)。 | 否 | `60`(1 小时) | + +### 本地归档存储 + +当 `ARCHIVE_STORAGE_BACKEND=local` 时生效: + +| 变量 | 说明 | 是否必填 | 默认值 | +| :------------------- | :--------------------------------------------------------------------------------------------------- | :------- | :------------- | +| `ARCHIVE_LOCAL_ROOT` | 存储归档文件的宿主机文件系统目录路径。切勿与主存储本地目录(`./data` 或 `./data/`)重叠。 | 是 | 未设置(必填) | + +### S3 归档存储 + +当 `ARCHIVE_STORAGE_BACKEND=s3` 时生效。请注意归档存储维护专属的独立配置,**绝不会回退**至主存储的 `S3_*` 环境变量: + +| 变量 | 说明 | 是否必填 | 默认值 | +| :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :---------------------------------------- | +| `ARCHIVE_S3_BUCKET` | 归档文件的目标 S3 存储桶(可为独立存储桶,也可在同存储桶分层时与 `S3_BUCKET` 相同)。 | 是 | 未设置(必填) | +| `ARCHIVE_S3_ACCESS_KEY_ID` | 归档 S3 服务的 Access Key ID。 | 是 | 未设置(必填) | +| `ARCHIVE_S3_SECRET_ACCESS_KEY` | 归档 S3 服务的 Secret Access Key。 | 是 | 未设置(必填) | +| `ARCHIVE_AWS_ENDPOINT_URL_S3` | 归档存储的 S3 服务端点 URL(例如 MinIO、Cloudflare R2、Google Cloud Storage)。 | 否 | 未设置(AWS 标准端点) | +| `ARCHIVE_S3_REGION` | 归档存储桶所在的 S3 区域。 | 否 | `auto` | +| `ARCHIVE_S3_FORCE_PATH_STYLE` | 采用路径风格 (Path-Style) S3 URL(MinIO / 路径风格设为 `true`,虚拟主机风格设为 `false`)。 | 否 | `true` | +| `ARCHIVE_S3_STORAGE_CLASS` | 赋予归档对象的 S3 存储类别(例如 `GLACIER`、`GLACIER_IR`、`DEEP_ARCHIVE`、`COLDLINE`)。归档至同一个 S3 存储桶时此项必填且不可为 `STANDARD`。 | 否 | 未设置 | +| `ARCHIVE_S3_USE_RESTORE_OBJECT` | 控制在读取已归档对象前是否调用 S3 `RestoreObject` 接口(`auto`、`true` 或 `false`)。 | 否 | `auto` | +| `ARCHIVE_S3_RESTORE_DAYS` | 异步 Glacier 解冻恢复时,解冻的临时副本在 S3 中保持可读状态的天数。 | 否 | `1` | +| `ARCHIVE_S3_RESTORE_TIER` | S3 Glacier 解冻检索层级(`Expedited`、`Standard` 或 `Bulk`)。若所用服务商无需异步解冻,可省略此参数。 | 否 | 未设置 | +| `ARCHIVE_RESTORE_POLL_INTERVAL_MS` | 等待异步冷存储解冻期间,状态轮询检查的间隔毫秒数。 | 否 | `60000`(初始 1 分钟,后续稳定为 5 分钟) | + +--- + +## 配置示例 + +### 1. 本地 NAS / 挂载路径 + +适合配备本地网络附加存储(如群晖 Synology、威联通 QNAP、TrueNAS,或挂载至宿主机的 NFS/SMB 共享目录)的私有化部署团队: + +```env +# 主存储配置(本地磁盘或 S3) +STORAGE_BACKEND=local +LOCAL_STORAGE_PATH=./storage + +# 归档存储配置(指向挂载的 NAS 目录) +ARCHIVE_STORAGE_BACKEND=local +ARCHIVE_LOCAL_ROOT=/mnt/nas/shumai-archive +``` + +在 `docker-compose.yaml` 中,将宿主机 NAS 卷挂载至容器中: + +```yaml +services: + shumai: + volumes: + - /mnt/nas/shumai-archive:/mnt/nas/shumai-archive + environment: + ARCHIVE_STORAGE_BACKEND: local + ARCHIVE_LOCAL_ROOT: /mnt/nas/shumai-archive +``` + +--- + +### 2. AWS S3 Glacier 即时检索 (Instant Retrieval) + +AWS S3 Glacier Instant Retrieval (`GLACIER_IR`) 在提供冷存储低廉费率的同时具备**毫秒级检索延迟**。由于处于 `GLACIER_IR` 状态的对象不需要发起异步 `RestoreObject` 请求,将资产恢复至主存储可即时完成。 + +#### 同存储桶原位分层(快速路径) + +若主存储已使用 AWS S3,可在**同一个存储桶**内将文件分层归档至 `GLACIER_IR`,无需在网络中重新上传数据: + +```env +# 主存储配置 +STORAGE_BACKEND=s3 +S3_BUCKET=my-shumai-production +S3_REGION=us-east-1 +S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com + +# 归档存储配置(复用相同的存储桶与凭据,搭配冷存储类别) +ARCHIVE_STORAGE_BACKEND=s3 +ARCHIVE_S3_BUCKET=my-shumai-production +ARCHIVE_S3_REGION=us-east-1 +ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com +ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR +``` + +#### 专属归档存储桶 + +若倾向于将归档媒体文件存放在独立的 S3 存储桶中: + +```env +# 归档存储配置(独立存储桶) +ARCHIVE_STORAGE_BACKEND=s3 +ARCHIVE_S3_BUCKET=my-shumai-archive-glacier-ir +ARCHIVE_S3_REGION=us-east-1 +ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com +ARCHIVE_S3_STORAGE_CLASS=GLACIER_IR +``` + +--- + +### 3. AWS S3 Glacier 灵活检索(深度冷存储) + +对于极少访问的归档素材,AWS S3 Flexible Archive (`GLACIER`) 或 Deep Archive (`DEEP_ARCHIVE`) 可提供最大程度的存储成本节约。 + +当用户从 Glacier 恢复资产时,Shumai 会发起 `RestoreObject` 请求,将后台工作流转入 DBOS 持久化等待状态,并定期检查直至 AWS 完成文件解冻: + +```env +ARCHIVE_STORAGE_BACKEND=s3 +ARCHIVE_S3_BUCKET=my-shumai-cold-archive +ARCHIVE_S3_REGION=us-east-1 +ARCHIVE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE +ARCHIVE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY +ARCHIVE_AWS_ENDPOINT_URL_S3=https://s3.us-east-1.amazonaws.com +ARCHIVE_S3_STORAGE_CLASS=GLACIER + +# 解冻后的临时副本保持可访问状态 7 天 +ARCHIVE_S3_RESTORE_DAYS=7 + +# Glacier 检索层级:Standard(标准,3-5 小时)、Expedited(快速,1-5 分钟)或 Bulk(批量,5-12 小时) +ARCHIVE_S3_RESTORE_TIER=Standard +``` + +> [!NOTE] +> 在 Glacier 解冻恢复期间,DBOS 会在 PostgreSQL 中调度持久化等待定时器。等待 AWS 解冻文件期间,Worker 线程将完全释放,不占用任何并发执行槽位。 + +--- + +### 4. Google Cloud Storage Coldline 归档 + +Google Cloud Storage (GCS) 提供兼容 S3 的 XML API 以及 `COLDLINE`、`ARCHIVE` 等低成本存储类别。与 Glacier Instant Retrieval 类似,GCS Coldline 提供**即时访问**能力,无需异步解冻阶段: + +```env +# 主存储配置(例如 Cloudflare R2、MinIO 或标准 GCS) +STORAGE_BACKEND=s3 +S3_BUCKET=shumai-main +... + +# 基于 GCS Coldline 的归档存储 +ARCHIVE_STORAGE_BACKEND=s3 +ARCHIVE_S3_BUCKET=shumai-coldline-archive +ARCHIVE_S3_ACCESS_KEY_ID=GOOG1EXAMPLETOCKENKEY +ARCHIVE_S3_SECRET_ACCESS_KEY=your-gcs-hmac-secret-access-key +ARCHIVE_AWS_ENDPOINT_URL_S3=https://storage.googleapis.com +ARCHIVE_S3_STORAGE_CLASS=COLDLINE +``` + +> [!TIP] +> Google Cloud Storage 对象可直接读取,不接受 AWS Glacier 解冻检索参数。切勿设置 `ARCHIVE_S3_RESTORE_TIER`。若使用 GCS 的 `ARCHIVE` 存储类别,请配置 `ARCHIVE_S3_USE_RESTORE_OBJECT=false` 以跳过 S3 `RestoreObject` 调用。 + +--- + +## 资产自动归档 + +除手动按需归档外,Shumai 还支持团队基于资产生命周期策略实现冷存储自动分层。这样可以自动将庞大的原始素材文件迁移至二级冷存储,无需创作者或管理员反复手动清理。 + +### Web 端配置 + +团队所有者可在 **团队设置 > 存储** 下配置自动归档策略: + +1. **归档存储状态概览**: + - 展示服务器当前配置的归档存储后端(`local` 或 `s3`)、服务端点、存储桶或根目录。 + - 若服务端环境变量中未配置归档存储,界面将显示警告提示,且自动归档控制项保持禁用。 + - 出于安全原因,凭据与服务器私密配置不会向客户端浏览器暴露。 + +2. **资产自动归档策略**: + - **启用自动归档**:为团队开启或关闭后台自动归档功能(默认关闭;需要已配置有效的归档存储后端)。 + - **归档条件 (`method`)**: + - **超过指定天数未修改 (`not_updated`)**:以最后修改时间戳(`updatedAt`)作为判定标准。非常适合高频协作的生产工作流——只要团队成员仍在持续评论、批注或修改,文件就会保留在快速的主存储中。一旦在设定时间内未发生任何修改,资产便会自动移至冷存储。 + - **创建超过指定天数 (`after_created`)**:以初始上传/创建时间戳(`createdAt`)作为判定标准。适合有严格留存周期要求或合规场景的流水线,无论近期是否有审阅评论,素材在达到指定时间(如交付后 60 天或 90 天)后均会自动分层归档。 + - **保留时长阈值 (`days`)**:符合归档条件的资产在达到该天数阈值(介于 1 至 3650 天之间)后,将被排入归档队列。 + - **恢复后保护缓冲期 (`postRestoreGraceDays`)**: + - 当资产从归档存储恢复至主存储时,其修改时间会刷新为恢复时刻。 + - 若采用 **创建超过指定天数** 规则,早已超出阈值的文件(例如已创建 100 天的文件)原本会在下一次每小时扫描中立刻被再次归档。 + - 恢复后保护缓冲期(默认 30 天)可确保恢复的文件在主存储中至少保留指定天数后,才重新具备自动归档资格。该数值应设置得小于保留时长阈值。在此策略下,只有既超过创建保留天数、且恢复时间也已超出保护缓冲期的文件,才会被自动归档。 + +### 副本去重与安全保证 + +Shumai 利用基于内容寻址的存储键(`storage_keys`),在项目与文件夹之间实现相同文件的去重: + +- **副本保护机制**:若多条资产记录引用底层同一个存储对象(例如在文件夹或项目间复制、克隆的文件),自动归档扫描程序会检查所有关联的同源资产(Sibling Assets)。 +- **严格共识机制**:仅当**所有活跃的关联同源文件**均满足团队的自动归档条件,且处于稳定的 `processed` 状态时,底层存储文件才会执行归档。 +- **无饥饿调度**:若任一同源副本近期发生过修改或当前正处于活跃工作流中,系统将安全跳过该存储键,且不会阻塞其他符合条件资产的正常归档。 + +### 后台扫描与执行语义 + +自动归档任务在后台定期运行: + +- **扫描频率**:通过环境变量 `AUTO_ARCHIVE_INTERVAL_MINUTES` 配置(默认 `60` 分钟;支持小数值如 `0.02` 用于自动化测试)。 +- **分布式选主机制**:在候选扫描发现阶段使用 PostgreSQL 事务级咨询锁(`pg_try_advisory_xact_lock`)。在多 Pod 或多副本容器部署环境中,每个周期仅有单台服务器实例执行扫描,其他副本实例平稳跳过。 +- **竞态条件防范**:在归档过程中,候选资产通过条件 SQL 语句(`UPDATE assets SET status = 'archiving' WHERE status = 'processed'`)配合行级 `storage_keys FOR UPDATE` 锁实现原子状态流转。这彻底避免了与用户并发执行的手动归档、恢复或文件删除发生竞态冲突。 + +--- + +## Web 端表现与权限 + +- **权限控制**:仅团队 **所有者 (Owner)** 与 **编辑者 (Editor)** 可执行资产的归档与恢复操作。 +- **右键菜单**:在文件浏览器中右键点击任意文件、文件夹或版本堆栈,即可选择 **归档** 或 **从归档中恢复**。 +- **状态标识**:已归档的条目在网格卡片与列表行中均带有 `已归档` 徽标。在文件查看器中,面包屑导航栏的文件名前会显示归档图标。 +- **播放与预览**:借助主存储保留的缓存代理,视频流媒体播放、拖拽进度条、音频波形、PDF 渲染以及图片查看功能依然完全可用。 +- **下载限制**:原片下载按钮将变为禁用状态,并带有气泡提示说明原始文件已被归档。转码代理版本下载(如 1080p MP4)不受影响,依然可用。 diff --git a/docs/zh/configuration/distributed.mdx b/docs/zh/configuration/distributed.mdx new file mode 100644 index 00000000..1792099b --- /dev/null +++ b/docs/zh/configuration/distributed.mdx @@ -0,0 +1,173 @@ +--- +title: 分布式 Worker 部署 +description: 通过独立的后台 Worker、DBOS 与兼容 S3 的对象存储配置大规模生产级部署。 +--- + +在面对高并发视频处理或重度 AI 智能体调用的生产环境中,若将所有后台任务集中在单台服务器上运行,极易引发性能瓶颈。Shumai 通过由 **DBOS Transact** 统一编排的独立 Worker 节点,将 Web 控制台与后台处理彻底解耦,轻松化解瓶颈。 + +所有后台任务(媒体转码、AI 向量嵌入、智能体任务)均分发至直接托管在 PostgreSQL 中的持久化任务队列(`transcode_queue` 与 `agent_queue`)。无需部署额外的外部集群(如 Temporal)。 + +--- + +## 核心工作原理 + +在分布式部署中,Shumai 核心 Web 应用负责处理用户请求、数据库更新和文件上传,并通过 PostgreSQL 任务队列将持久化后台工作流委派给专用的 Worker 实例。 + +```mermaid +graph TD + UserUpload[用户上传视频 / 触发智能体] --> WebApp[Shumai Web UI / API] + WebApp -->|入队任务| DB[(PostgreSQL / DBOS 队列)] + DB -->|队列: transcode_queue| TranscodeWorker[转码 Worker 机器] + DB -->|队列: agent_queue| AgentWorker[智能体 Worker 机器] +``` + +- **转码 Worker**:可在配备 GPU 加速或高配 CPU 的计算实例上运行。 +- **AI 智能体 Worker**:可在隔离沙箱环境中运行,以安全执行自动化脚本。 + +> [!IMPORTANT] +> **存储配置硬性要求**:由于在分布式部署下核心应用与后台 Worker 分别运行在不同机器上,**必须配置兼容 S3 的对象存储后端**(例如 AWS S3、Cloudflare R2 或 MinIO)。此模式下不支持本地存储(`STORAGE_BACKEND=local`),因为 Worker 节点与 Web 应用无法共享本地文件系统。 + +--- + +## 第 1 步:部署核心 Web 应用 + +在主服务器上运行 PostgreSQL 和 Shumai 核心 Web 应用。 + +若需指示核心 Web 应用仅处理 API 和前端 UI 流量,而不本地消费后台 Worker 队列任务,请设置 `SHUMAI_WORKERS=none`: + +```env +DATABASE_URL=postgresql://shumai:shumai_password@localhost:5432/shumai_db?schema=public +STORAGE_BACKEND=s3 +AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com +S3_BUCKET=shumai +S3_REGION=us-east-1 +S3_ACCESS_KEY_ID=your-access-key-id +S3_SECRET_ACCESS_KEY=your-secret-access-key +SHUMAI_WORKERS=none +BETTER_AUTH_SECRET=your-random-32-character-secret-key +``` + +当使用 `SHUMAI_WORKERS=none`(或启动参数 `--workers=none`)启动时,Web 服务器将即刻启动,不会轮询或消费来自转码或智能体队列的任务。 + +--- + +## 第 2 步:配置并运行专属 Worker + +在专用 Worker 机器上,配置各 Worker 的 `.env` 文件以指向共享的 PostgreSQL 数据库与 S3 存储: + +```env +DATABASE_URL=postgresql://shumai:shumai_password@:5432/shumai_db?schema=public +STORAGE_BACKEND=s3 +AWS_ENDPOINT_URL_S3=https://your-s3-endpoint.com +S3_BUCKET=shumai +S3_REGION=us-east-1 +S3_ACCESS_KEY_ID=your-access-key-id +S3_SECRET_ACCESS_KEY=your-secret-access-key +CONCURRENCY_TRANSCODE=1 +CONCURRENCY_AGENT=5 +``` + +### 媒体转码 Worker + +在媒体处理计算节点上运行(需要预先在系统上安装 `ffmpeg` 与 `ffprobe`): + +```bash +npm install -g @shumai-one/shumai-transcode +shumai-transcode +``` + +或者,可以使用轻量级专属 Docker 镜像运行转码 Worker: + +```bash +docker run -d \ + --name shumai-transcode-worker \ + --env-file .env \ + shumaione/shumai-transcode:latest +``` + +(亦可使用一体化全功能镜像:`docker run -d --name shumai-transcode-worker --env-file .env shumaione/shumai:latest shumai-transcode`。) + +### AI 智能体 Worker + +在沙箱化智能体执行节点上运行(需要安装 `bubblewrap` 或 `sandbox-exec` 等沙箱依赖项): + +```bash +npm install -g @shumai-one/shumai-agent +shumai-agent +``` + +或者,可以使用官方 Docker 镜像运行智能体 Worker: + +```bash +docker run -d \ + --name shumai-agent-worker \ + --env-file .env \ + --cap-add=SYS_ADMIN \ + shumaione/shumai:latest shumai-agent +``` + +> [!IMPORTANT] +> **Bun 用户须知**:由于 Worker 依赖包的二进制可执行文件包含 `#!/usr/bin/env node` Shebang,直接运行 `shumai-transcode` 或 `shumai-agent` 将在 Node.js 下执行。若希望使用 Bun 运行,请在命令前加上 `bun run --bun`(例如 `bun run --bun shumai-transcode` 或 `bun run --bun shumai-agent`)。 + +--- + +## Worker 并发与多实例部署 + +### 并发调优 + +Worker 根据可配置的并发上限从 PostgreSQL 队列中拉取任务: + +- `CONCURRENCY_TRANSCODE`:单个 Worker 最大并发视频转码任务数(默认 `1`)。 +- `CONCURRENCY_AGENT`:单个 Worker 最大并发智能体及向量嵌入工作流数(默认 `5`,若搭配本地 `embedding-server` 建议设为 `1`)。 + +### 副本实例标识 + +当在多台机器或 Pod 上运行转码或智能体 Worker 的多个副本时: + +- `DbosExecutor` 会自动基于机器主机名与进程 ID 派生唯一的单实例标识,确保启动恢复时仅重新入队属于该实例的任务。 +- **自定义 Worker ID**:若需显式指定标识符,可设置 `SHUMAI_WORKERS_ID`(或 `SHUMAI_WORKER_ID`)。 +- **Kubernetes 环境**:在 Kubernetes Pod 中,可通过 Downward API(`fieldRef: { fieldPath: metadata.name }`)设置 `POD_NAME`,以在 Pod 重启期间保持稳定且唯一的单 Pod 身份标识。 + +--- + +## 基于 Kubernetes 与 AWS EKS 的弹性扩展部署 + +对于需要高吞吐媒体处理能力的生产级云端部署,Shumai 可部署在 Kubernetes 或 **AWS Elastic Kubernetes Service (AWS EKS)** 上,并借助 **KEDA (Kubernetes Event-driven Autoscaling)** 实现基于队列驱动的缩容至零(Scale-to-Zero)自动弹性伸缩。 + +```mermaid +graph TD + User([用户 / Web 浏览器]) -->|端口 80/3000| Server[Pod: shumai-server
SHUMAI_WORKERS=agent] + Server -->|入队到 transcode_queue| DB[(PostgreSQL: pgvector18
dbos.workflow_status)] + Server -->|直传 / 播放代理流| Storage[(S3 / Garage 存储)] + + KEDA[KEDA ScaledJob
PostgreSQL 触发器
min: 0, max: 10] -.->|监控队列| DB + KEDA -->|为队列派发任务| Job1[Job: shumai-transcode-1
自动排空 Worker] + KEDA -->|为队列派发任务| JobN[Job: shumai-transcode-N
自动排空 Worker] + + Job1 -->|获取源文件 / 存储代理文件| Storage + JobN -->|获取源文件 / 存储代理文件| Storage + Job1 -->|标记完成并退出 0| DB + JobN -->|标记完成并退出 0| DB + + CA[Cluster Autoscaler / Karpenter] -.->|缩容至零按需节点
0 到 10 实例| JobN +``` + +### 架构核心优势 + +- **解耦的无状态 Worker**:核心 Web 与 API 服务、数据库以及对象存储均运行在可靠的按需计算节点上(`c9g.large`,`SHUMAI_WORKERS=agent`),媒体转码任务则委派给由 PostgreSQL 中 DBOS 任务队列统一编排的后台 Worker。 +- **专用 Graviton5 按需计算实例 (`c9g.xlarge`)**:媒体编码运行在 4 vCPU / 8 GiB 内存的 AWS Graviton5 按需实例上(约 0.174 美元/小时),充分利用 ARM64 向量优化与高速 DDR5 内存,且免受竞价实例(Spot)非预期中断的影响。 +- **基于 KEDA 的队列驱动缩容至零**:KEDA 持续监听 `dbos.workflow_status` 中已入队与待处理的转码任务,并动态创建 Kubernetes `ScaledJob` 资源(支持 0 到 10 弹性伸缩)。当队列排空时,转码节点完全缩容至零(`minSize: 0`),转码计算成本降至 **0 美元/小时**。 +- **空闲超时自动排空**:Worker Pod 以并发数 `1` 持续处理排队任务。当队列彻底排空且 Pod 持续空闲 10 秒(`SHUMAI_WORKER_IDLE_TIMEOUT_MS=10000`)后,Pod 将以状态码 `0` 正常退出以触发节点缩容,在批量上传时避免了 Pod 频繁冷启动的开销。 +- **停滞任务自动恢复**:核心 Web 服务器运行内置的恢复巡检机制,可自动检测停滞或孤儿任务(例如因节点崩溃导致的任务中断)并在 DBOS 中自动恢复执行,同时设有最多 3 次重试上限以安全防范毒丸异常素材(Poison-Pill Media)。 + +### 完整部署示例与源码 + +生产就绪的完整清单文件、声明式 `eksctl` 集群配置以及分步操作指引,请参阅 Shumai 仓库中的 **[EKS 部署示例](https://github.com/shumaiOne/shumai/tree/main/eks)**: + +👉 **[在 GitHub 上查看 EKS 部署指南与清单文件](https://github.com/shumaiOne/shumai/tree/main/eks)** + +仓库包含: + +- [`eks/eks-cluster.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/eks-cluster.yaml):包含分层计算配置的完整 `eksctl` ClusterConfig。 +- [`eks/kustomization.yaml`](https://github.com/shumaiOne/shumai/blob/main/eks/kustomization.yaml):用于所有服务的一键式 Kustomize 部署文件。 +- 详细说明了如何配置公网端点、自动化 Cluster Autoscaler 以及零停机平滑停机(Graceful Shutdown)。 diff --git a/docs/zh/configuration/env-variables.mdx b/docs/zh/configuration/env-variables.mdx new file mode 100644 index 00000000..3b356892 --- /dev/null +++ b/docs/zh/configuration/env-variables.mdx @@ -0,0 +1,161 @@ +--- +title: 环境变量 +description: Shumai 全量配置参数参考指南。 +--- + +Shumai 通过环境变量配置。可以在应用工作区根目录的 `.env` 文件中定义这些变量,也可在启动 Docker 容器时直接传入。 + +--- + +## 数据库配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :------------- | :------------------------------------------------------------ | :------------------------------------------------------- | +| `DATABASE_URL` | PostgreSQL 连接 URL。目标数据库必须预先安装 `pgvector` 扩展。 | `postgresql://user:pass@localhost:5432/db?schema=public` | + +--- + +## 服务器配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :---------------------- | :------------------------------------------------------------------ | :------------- | +| `SHUMAI_SERVER_PORT` | Shumai Web 服务器监听的端口。 | `3000`(默认) | +| `MAX_REQUEST_BODY_SIZE` | 允许的最大请求体大小(例如用于大文件上传),单位为字节。默认 10GB。 | `10737418240` | + +--- + +## 认证与应用配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :------------------- | :----------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | +| `BETTER_AUTH_SECRET` | 用于对会话 Cookie 和 JWT 签名的安全随机 32 字节密钥。 | 可通过 `openssl rand -base64 32` 生成 | +| `BETTER_AUTH_URL` | Shumai 服务器的公网访问 URL。用于 MCP OAuth 2.1 端点发现、重定向流程、密码重置链接以及邮件通知。 | `http://localhost:3000`(未设置时回退至 `SHUMAI_SERVER_PORT`) | +| `APP_URL` | Web 前端应用的公网访问 URL。用于通知邮件中的深度链接(未设置时回退至 `BETTER_AUTH_URL`)。 | `https://shumai.example.com` | + +--- + +## 存储配置 + +Shumai 支持将文件存储在本地文件系统或兼容 S3 的对象存储中。 + +| 变量 | 说明 | 示例 / 默认值 | +| :-------------------------------- | :------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------- | +| `STORAGE_BACKEND` | 存储类型。使用 `local` 表示本地文件系统存储,使用 `s3` 表示兼容 S3 的云对象存储。 | `local`(默认)或 `s3` | +| `AWS_ENDPOINT_URL_S3` | S3 存储或本地存储的服务端点。浏览器据此生成文件上传链接。在远程部署或使用自定义端口时,必须包含端口号。 | `http://localhost:3000`(未设置时回退至 `SHUMAI_SERVER_PORT`) | +| `S3_BUCKET` | S3 存储桶名称。 | `shumai`(默认) | +| `S3_ACCESS_KEY_ID` | S3 访问凭据 Access Key ID。 | `minioadmin`(默认) | +| `S3_SECRET_ACCESS_KEY` | S3 访问凭据 Secret Access Key。 | `minioadmin`(默认) | +| `S3_REGION` | S3 存储区域。 | `auto`(默认) | +| `PRESIGNED_URL_EXPIRES_IN` | 生成的预签名下载链接的有效时长(单位:小时)。 | `5`(默认) | +| `PRESIGNED_UPLOAD_URL_EXPIRES_IN` | 生成的预签名上传链接的有效时长(单位:小时)。未设置时回退至 `PRESIGNED_URL_EXPIRES_IN`。 | `12`(默认) | + +### 本地存储端口配置 + +当 `STORAGE_BACKEND` 设为 `local`(默认值)时: + +- `SHUMAI_SERVER_PORT` 用于配置 Shumai Web 服务器启动并监听的端口。 +- `AWS_ENDPOINT_URL_S3` 用于配置客户端浏览器上传和下载文件所用的公网/外部访问端点。必须包含协议头(Scheme)与端口。 + +例如,若在远程服务器 `http://123.456.7.8` 上部署 Shumai,且在 Docker Compose 中配置了端口映射 `12345:3000`(即内部端口 3000 映射为宿主机外部端口 12345): + +- 将 `SHUMAI_SERVER_PORT` 设为 `3000`。 +- 将 `AWS_ENDPOINT_URL_S3` 设为 `http://123.456.7.8:12345`。 + +### 归档存储配置 + +Shumai 支持配置可选的**归档存储**(冷存储)层级(`local` NAS/挂载目录或 `s3` 存储桶/存储类型),用于将原始素材文件归档迁移,同时在主存储中保留代理版本、预览图、缩略图和元数据。 + +| 变量 | 说明 | 示例 / 默认值 | +| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------- | +| `ARCHIVE_STORAGE_BACKEND` | 归档存储类型。留空表示禁用归档存储,可选 `local` 或 `s3`。 | 未设置(禁用)、`local` 或 `s3` | +| `ARCHIVE_LOCAL_ROOT` | 当 `ARCHIVE_STORAGE_BACKEND=local` 时必填。归档原始文件的根目录(例如挂载的 NAS 目录),文件将直接存储在 `/` 下。 | `/mnt/nas/shumai-archive` | +| `ARCHIVE_AWS_ENDPOINT_URL_S3` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时的自定义 S3 归档端点(独立于 `AWS_ENDPOINT_URL_S3`)。 | `https://s3.us-east-1.amazonaws.com` | +| `ARCHIVE_S3_BUCKET` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档文件的目标 S3 存储桶(可为独立存储桶,也可与 `S3_BUCKET` 相同并配合冷存储类型使用)。 | `shumai-archive` | +| `ARCHIVE_S3_ACCESS_KEY_ID` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档存储的 S3 Access Key ID。 | `AKIA...` | +| `ARCHIVE_S3_SECRET_ACCESS_KEY` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时必填。归档存储的 S3 Secret Access Key。 | `...` | +| `ARCHIVE_S3_REGION` | 当 `ARCHIVE_STORAGE_BACKEND=s3` 时归档存储的 S3 区域。 | `auto`(默认) | +| `ARCHIVE_S3_STORAGE_CLASS` | 归档对象时附加的可选 S3 `StorageClass` 标头(支持任意标准或厂商特定的存储类型字符串;在同存储桶分层场景下必填且不可为 `STANDARD`)。 | `GLACIER_IR`、`GLACIER`、`DEEP_ARCHIVE`、`STANDARD_IA` | +| `ARCHIVE_S3_USE_RESTORE_OBJECT` | 控制在读取已归档对象前是否调用 S3 `RestoreObject` 接口(`auto`、`true` 或 `false`)。 | `auto`(默认) | +| `ARCHIVE_S3_RESTORE_DAYS` | S3 冷存储对象解冻恢复后,解冻副本保持可读状态的天数。 | `1`(默认) | +| `ARCHIVE_S3_RESTORE_TIER` | 可选的 S3 Glacier 解冻检索层级(`Expedited`、`Standard`、`Bulk`)。未设置时省略该参数,适用于拒绝 `GlacierJobParameters` 的兼容 S3 服务商。 | 未设置(默认) | +| `AUTO_ARCHIVE_INTERVAL_MINUTES` | 后台自动归档扫描任务的执行频率(单位:分钟)。支持小数值(例如测试时设为 `0.02`)。 | `60`(默认 1 小时) | + +--- + +## 工作流配置 + +用于配置 DBOS Transact 队列的后台 Worker 执行、并发限制及 Worker 实例标识。 + +| 变量 | 说明 | 示例 / 默认值 | +| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- | :---------------- | +| `SHUMAI_WORKERS` | Web 服务器监听的任务队列。可选值:`all`(默认,监听全部队列)、`none`(仅作为 API/UI 服务)、`agent`(或 `ai`)、`transcode`、`archive`。 | `all`(默认) | +| `CONCURRENCY_TRANSCODE` | Worker 执行媒体转码任务的最大并发数。 | `1`(默认) | +| `CONCURRENCY_ARCHIVE` | Worker 执行归档与解冻任务的最大并发数。 | `5`(默认) | +| `CONCURRENCY_AGENT` | Worker 执行 AI 任务的最大并发数。在运行本地 `embedding-server` 时建议设为 `1`。 | `5`(默认) | +| `SHUMAI_WORKER_ID` | 多节点部署中 Worker 副本的可选显式实例 ID(未设置时根据主机名和进程 ID 自动派生)。 | `worker-1` | +| `POD_NAME` | Kubernetes Pod 名称,用于在 StatefulSet 重启时保持稳定的各 Pod Worker 身份标识。 | `transcode-pod-0` | + +--- + +## 向量模型配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :-------------------------------- | :------------------------------------------------------------------------------- | :-------------------------------- | +| `EMBEDDING_PROVIDER` | 多模态向量模型服务商。可选值:`gemini-embedding-2`、`gemma-embedding-2-openai`。 | `gemini-embedding-2`(默认) | +| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | 兼容 OpenAI 协议的 LiteRT-LM 向量模型服务 Base URL。 | `http://embedding-server:9379/v1` | +| `ENABLE_EMBEDDING_AGENT` | 设为 `true` 时,在启动时自动为所有团队置备并启用系统向量智能体。 | `false`(默认) | +| `EMBEDDING_CHUNK_DURATION` | 生成视频向量时每个视频切片的时长(单位:秒)。 | `60.0`(默认) | +| `EMBEDDING_CHUNK_OVERLAP` | 生成视频向量时各个视频切片的重叠时长(单位:秒)。 | `5.0`(默认) | + +## 沙箱配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :----------------------------- | :--------------------------------------------------------------------------- | :-------------- | +| `ENABLE_WEAKER_NESTED_SANDBOX` | 为缺少用户命名空间权限的环境(例如某些 Docker 容器)启用弱隔离嵌套沙箱模式。 | `false`(默认) | + +--- + +## 日志配置 + +| 变量 | 说明 | 示例 / 默认值 | +| :----------- | :------------------------------------------------------------------------- | :------------- | +| `LOG_LEVEL` | Pino 日志输出级别。可选值:`debug`、`info`、`warn`、`error`。 | `info`(默认) | +| `LOG_FORMAT` | 日志输出格式风格。生产环境推荐使用 `json`,终端直观查看推荐使用 `pretty`。 | `json`(默认) | + +--- + +## 大语言模型 API 密钥 + +启动时预配给 AI 服务商的 API Key。 + +| 变量 | 说明 | 示例 / 默认值 | +| :------------------ | :------------------------------- | :------------ | +| `GEMINI_API_KEY` | Google Gemini 服务商的 API Key。 | `AIzaSy...` | +| `OPENAI_API_KEY` | OpenAI 服务商的 API Key。 | `sk-proj-...` | +| `ANTHROPIC_API_KEY` | Anthropic 服务商的 API Key。 | `sk-ant-...` | + +--- + +## 外部集成配置 + +环境变量可用于全局配置外部微服务。设置后,这些环境变量的优先级高于在 **团队设置 → 集成** 中配置的任何团队级设置,并将 WebUI 中的对应设置字段锁定为只读状态。 + +### Gotenberg 文档转换服务 + +用于将 Office 文档、HTML、Markdown 和 CSV 文件转换为高保真 PDF 代理文件,以供浏览器内直接预览。安装配置步骤请参阅 [Gotenberg 指南](/zh/using-shumai/gotenberg)。 + +| 变量 | 说明 | 示例 / 默认值 | +| :------------------------------ | :-------------------------------------------- | :---------------------- | +| `GOTENBERG_URL` | 外部 Gotenberg 转换服务的 API Base URL。 | `http://gotenberg:3000` | +| `GOTENBERG_BASIC_AUTH_USERNAME` | Gotenberg 实例启用 Basic 身份验证时的用户名。 | `admin` | +| `GOTENBERG_BASIC_AUTH_PASSWORD` | Gotenberg 实例启用 Basic 身份验证时的密码。 | `secret` | + +### 3D 转台渲染服务 + +用于将 3D 模型文件(GLB、OBJ、FBX、USD、STL、DAE)转换为交互式 360° 旋转转台视频代理、封面图以及悬浮预览雪碧图。安装配置步骤请参阅 [3D 资产支持指南](/zh/using-shumai/3d-asset-support)。 + +| 变量 | 说明 | 示例 / 默认值 | +| :--------------------------------------- | :------------------------------------------------------------------------------------ | :------------------------------- | +| `TURNTABLE_RENDERER_URL` | 外部 turntable-renderer 服务的 Base URL。 | `http://turntable-renderer:3000` | +| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | 3D 转台渲染服务启用 Basic 身份验证时的用户名(别名:`TURNTABLE_RENDERER_USERNAME`)。 | `admin` | +| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | 3D 转台渲染服务启用 Basic 身份验证时的密码(别名:`TURNTABLE_RENDERER_PASSWORD`)。 | `secret` | diff --git a/docs/zh/configuration/hardware-transcoding.mdx b/docs/zh/configuration/hardware-transcoding.mdx new file mode 100644 index 00000000..4a7defbf --- /dev/null +++ b/docs/zh/configuration/hardware-transcoding.mdx @@ -0,0 +1,233 @@ +--- +title: 硬件加速转码 +description: 利用 GPU 硬件加速显著提升视频转码速度并降低 CPU 负载。 +--- + +高分辨率摄影机录像、手机拍摄视频以及动画媒体文件需要转码为代理格式,方可在 Web 浏览器中流畅播放。Shumai 在后台自动转码这些资产,生成用于即时拖拽播放(Scrubbing)的通用 `180p` 代理文件以及全分辨率预览流。 + +硬件加速转码支持将视频编码负载分流至独立显卡或集成 GPU,大幅缩短处理耗时,并为其他系统服务释放宿主机的 CPU 核心资源。 + +Shumai 内置可用性探测机制,在系统启动时自动测试硬件编码器,并在视频处理期间提供运行时自动回退保障。若 GPU 驱动或设备节点不可用,亦或硬件编码器达到硬件物理限制(例如某些 GPU 对特定分辨率或长宽比例的限制)乃至发生驱动运行时错误,Shumai 均能无缝回退至 CPU 软件编码(`libx264`),确保用户任务不会中断失败。 + +--- + +## 支持的硬件加速后端 + +| 后端 | 硬件平台 | 容器驱动 / 设备节点 | +| :-------------- | :----------------------------------- | :----------------------------------------------- | +| **`nvenc`** | NVIDIA GPU | NVIDIA Container Toolkit (`gpu, compute, video`) | +| **`quicksync`** | Intel 核显与 Arc 独显 | `/dev/dri` 渲染节点 | +| **`vaapi`** | AMD 与 Intel GPU | `/dev/dri` 渲染节点 | +| **`rkmpp`** | 瑞芯微 Rockchip ARM SoC(如 RK3588) | `/dev/rga`、`/dev/dri`、`/dev/mpp_service` | +| **`vaapi-wsl`** | Windows 适用于 Linux 的子系统 (WSL2) | `/dev/dri`、`/dev/dxg`、`/usr/lib/wsl` | + +--- + +## 使用限制与注意事项 + +- 本文说明以 **Docker Compose** 为准。若使用其他容器编排工具(如 Kubernetes 或 Podman),需配置等效的设备透传参数。 +- **macOS 上的 Docker Desktop** 运行在 Linux 虚拟机内,不支持 Apple Silicon 的 VideoToolbox 设备透传。(直接通过 NPM 或源码在本地原生运行 Shumai 时支持 VideoToolbox 硬件加速)。 +- 硬件加速转码生成的视频码率特征与软件编码略有差异。Shumai 采用针对 Web 流媒体优化的自适应可变码率(VBR)速率控制策略,以确保画面保真度。 + +--- + +## 前置要求 + +### NVENC (NVIDIA) + +1. 确认宿主机已安装 NVIDIA 官方显卡驱动: + ```bash + nvidia-smi + ``` +2. 在宿主机上安装 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) 并重启 Docker: + ```bash + sudo apt-get install -y nvidia-container-toolkit + sudo nvidia-ctk runtime configure --runtime=docker + sudo systemctl restart docker + ``` + +### QuickSync 与 VA-API (Intel / AMD) + +1. 验证 Linux 内核已初始化 Direct Rendering Infrastructure (DRI) 渲染节点: + ```bash + ls -la /dev/dri + ``` + 输出中应包含 `card0` 和 `renderD128`(或类似节点)。 +2. Shumai 的 Docker 镜像在容器启动时会自动调整用户组权限,非 root 应用用户无需手动调整即可直接访问宿主机的 `/dev/dri` 设备,避免权限错误。 + +#### GPU 解码 + +采用 VA-API 模式时,Shumai 会在 GPU 上同时完成视频解码与尺寸缩放,帧数据全程保留在 GPU 显存内。这种方式显著快于 CPU 解码,尤其是在集成显卡上处理 4K 片源时提升尤为明显。(其他后端目前采用 CPU 解码并由 GPU 负责编码。) + +部分视频会自动切换为“CPU 解码 + GPU 编码”模式: + +- GPU 无法解码的编码格式,例如老款 Intel 芯片上的 HEVC 或 10-bit 视频。Shumai 会先尝试 GPU 解码,并在 1 秒内自动重试切换至 CPU 解码。 +- 带有旋转元数据的视频(如手机竖屏录像),以确保输出画面朝向正确。 +- 带有水印的分享链接视频以及 HDR 片源。 + +若某次 GPU 解码卡死超过 2 分钟(某些显卡驱动缺陷会导致 FFmpeg 进程挂起而非报错退出),Shumai 会中止该尝试并使用 CPU 重新解码。可通过 `SHUMAI_HW_DECODE_STALL_TIMEOUT`(单位:秒)调整此超时限制。 + +若希望全局始终使用 CPU 解码,可在 `shumai` 服务上配置环境变量 `SHUMAI_HW_DECODE=false`。 + +### WSL2 (Windows) + +- 确保系统运行 Windows 11 与 WSL2,且已在 Windows 宿主机上安装相应的 GPU 显卡驱动。 +- 使用 `vaapi-wsl` 预设,该预设会将 `/dev/dxg` 与 `/usr/lib/wsl` 映射进容器内。 + +--- + +## 使用 Docker Compose 部署配置 + +Shumai 采用模块化的 `hwaccel.transcoding.yaml` 辅助配置文件来定义硬件设备。 + +### 第 1 步:下载配置文件 + +在 Shumai 部署目录下,将 `hwaccel.transcoding.yaml` 下载至 `docker-compose.yaml` 旁: + +```bash +# 全球官方源 +curl -o hwaccel.transcoding.yaml https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml + +# 中国大陆加速镜像源 +curl -o hwaccel.transcoding.yaml https://gh-proxy.com/https://raw.githubusercontent.com/shumaiOne/shumai/main/docker-compose/local/hwaccel.transcoding.yaml +``` + +### 第 2 步:在 Docker Compose 中启用硬件加速 + +打开 `docker-compose.yaml`(或 `docker-compose-aliyun.yaml`),找到 `shumai` 服务下被注释的 `extends` 代码块,并取消注释: + +```yaml +services: + shumai: + # ... + # 硬件加速 (NVENC / QuickSync / VA-API / RKMPP) + extends: + file: hwaccel.transcoding.yaml + service: nvenc # 设置为 [nvenc, quicksync, rkmpp, vaapi, vaapi-wsl] 之一 +``` + +将 `nvenc` 替换为目标硬件后端: + +- `nvenc`:适用于 NVIDIA GPU +- `quicksync`:适用于 Intel Quick Sync +- `vaapi`:适用于 AMD 或 Intel VA-API +- `rkmpp`:适用于瑞芯微 Rockchip SoC +- `vaapi-wsl`:适用于 Windows WSL2 + +### 第 3 步:启动服务 + +重启或重新创建 Shumai 容器: + +```bash +docker compose up -d +``` + +--- + +## 单文件 Compose 配置 (Unraid / Portainer) + +若所处的容器编排管理工具不支持跨文件的 `extends` 语法,可直接将硬件配置内联写入 `docker-compose.yaml` 中的 `shumai` 服务: + + + + ```yaml + services: + shumai: + # ... + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: + - gpu + - compute + - video + ``` + + + + ```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri ``` + + + + ```yaml services: shumai: # ... devices: - /dev/dri:/dev/dri - /dev/dxg:/dev/dxg volumes: - + /usr/lib/wsl:/usr/lib/wsl environment: - LIBVA_DRIVER_NAME=d3d12 ``` + + + + ```yaml + services: + shumai: + # ... + security_opt: + - systempaths=unconfined + - apparmor=unconfined + group_add: + - video + devices: + - /dev/rga:/dev/rga + - /dev/dri:/dev/dri + - /dev/dma_heap:/dev/dma_heap + - /dev/mpp_service:/dev/mpp_service + ``` + + + +--- + +## Web 端设置 + +在 Shumai Web 端,前往 **团队设置** > **转码设置**。 + +- **自动(推荐)**:Shumai 按最优优先级顺序自动探测候选硬件编码器(`h264_nvenc` → `h264_vaapi` → `h264_qsv` → `h264_amf` → `libx264`)。若硬件加速不可用,则平滑降级至软件编码。 +- **指定编码器**:可将转码流水线显式锁定到指定编码器(如 `NVENC`、`Quick Sync`、`VA-API`)。 +- **关闭**:对所有视频任务强制使用 CPU 软件编码(`libx264`)。 + +--- + +## 验证与监控 + +### 查看转码日志 + +当上传资产开始视频转码时,Shumai 会记录一条结构化日志,明确标明所选用的编码器: + +```bash +docker compose logs -f shumai +``` + +查找包含 `Starting video transcoding` 的日志记录: + +```json +{ + "level": 30, + "time": 1790414665096, + "encoder": "h264_nvenc", + "hardwareAcceleration": "auto", + "inputFile": "/tmp/transcode-.../video.mp4", + "outputFile": "/tmp/transcode-.../video-180p.mp4", + "msg": "Starting video transcoding" +} +``` + +若硬件加速已成功初始化,`encoder` 字段将显示 `h264_nvenc`、`h264_vaapi` 或 `h264_qsv`。 + +### 监控 GPU 负载利用率 + +视频转码执行期间,可在宿主机上观察硬件资源占用情况: + +- **NVIDIA**: + ```bash + nvidia-smi + # 或 + nvtop + ``` +- **Intel**: + ```bash + sudo intel_gpu_top + ``` +- **AMD**: + ```bash + sudo radeontop + ``` diff --git a/docs/zh/developer/mcp-server.mdx b/docs/zh/developer/mcp-server.mdx new file mode 100644 index 00000000..9eb40094 --- /dev/null +++ b/docs/zh/developer/mcp-server.mdx @@ -0,0 +1,222 @@ +--- +title: Shumai MCP 服务 +description: 让 Claude Code、Cursor 或 Kiro 等外部 AI 智能体与 Shumai 项目协同工作。 +--- + +Shumai 内置了 [模型上下文协议](https://modelcontextprotocol.io)(MCP)服务。任何兼容 MCP 协议的智能体均可接入该服务,代表用户浏览项目、查看图片、视频与文档、创建文件夹以及整理资产,且调用与 Shumai 原生内置智能体完全相同的工具集。 + + + 本页面介绍如何将 **外部智能体连接至 Shumai**。若需了解如何将 Shumai + 自带智能体连接至其他外部工具,请参阅 [MCP 服务](/zh/using-shumai/mcp-servers)。 + + +--- + +## 连接客户端 + +MCP 服务采用 Streamable HTTP 传输协议,访问端点为: + +``` +https:///mcp +``` + +Shumai 支持 **OAuth 2.1**(推荐方式,提供无缝的浏览器授权体验)以及 **API Token**(适用于无头环境或不支持 OAuth 的客户端)。 + +请根据所使用的客户端选择相应配置指南: + +### Claude Code + +[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 原生支持具备 OAuth 身份验证的远程 HTTP MCP 服务。运行以下命令即可将 Shumai 添加至 Claude Code 配置: + +```bash +claude mcp add shumai --transport http https:///mcp +``` + +启动新对话时,Claude Code 会打开浏览器窗口供登录并授予 Shumai 账户访问权限,无需手动配置 API Token。 + +或者,可手动配置 `.claude/settings.json`: + +```json +{ + "mcpServers": { + "shumai": { + "type": "http", + "url": "https:///mcp" + } + } +} +``` + +或通过 `mcp-remote` 桥接 stdio: + +```bash +claude mcp add shumai -- npx -y mcp-remote https:///mcp +``` + +### Cursor + +将 Shumai 添加至 Cursor 的 MCP 配置(`~/.cursor/mcp.json` 或项目级 `.cursor/mcp.json`): + +```json +{ + "mcpServers": { + "shumai": { + "url": "https:///mcp" + } + } +} +``` + +当 Cursor 连接到服务时,会在浏览器中提示完成 OAuth 登录并授权访问。 + +若改用 API Token 验证身份,请在请求标头中传递 `Authorization`: + +```json +{ + "mcpServers": { + "shumai": { + "url": "https:///mcp", + "headers": { + "Authorization": "Bearer " + } + } + } +} +``` + +### Codex + +```bash +codex mcp add shumai --url https:///mcp +codex mcp login shumai +``` + +### VS Code + +```bash +code --add-mcp '{"name":"shumai","type":"http","url":"https:///mcp"}' +``` + +在 VS Code 的 **MCP Servers** 列表中启动该服务,并根据提示登录 Shumai。 + +### 其他客户端 + +**远程服务 (HTTP)** + +若客户端原生支持远程 HTTP MCP 服务: + +```json +{ + "mcpServers": { + "shumai": { + "url": "https:///mcp" + } + } +} +``` + +**本地桥接 (`mcp-remote` / stdio)** + +对于仅支持本地 (stdio) MCP 服务的客户端,可使用 `mcp-remote` 连接 Shumai 的远程 HTTP 端点: + +```json +{ + "mcpServers": { + "shumai": { + "command": "npx", + "args": ["-y", "mcp-remote", "https:///mcp"] + } + } +} +``` + +--- + +## 身份验证 + +Shumai 的 MCP 服务支持两种身份验证方式: + +### OAuth 2.1(推荐) + +Shumai 实现了基于动态客户端注册(Dynamic Client Registration, [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))与 OAuth 受保护资源元数据(OAuth Protected Resource Metadata, [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) / [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))规范的 OAuth 2.1。 + +- **无缝登录**:受支持的 MCP 客户端可自动发现授权端点并在浏览器中完成 OAuth 握手。 +- **访问控制**:外部智能体以调用方在 Shumai 中的既有权限执行操作。所有行为均归属于该用户账户,并在团队审计日志中标记为 `via: mcp`。 +- **清除 OAuth 缓存**:若需要在 `mcp-remote` 或 Claude Code 等 CLI 工具中重新鉴权或清除已保存的凭据,请删除本地认证缓存: + +```bash +rm -rf ~/.mcp-auth +``` + +### API Token + +API Token 适用于自动化 CI/CD 流水线、无头环境或不支持交互式 OAuth 的客户端。 + +1. 在 Shumai 中,打开 **团队设置** → **API Token**。 +2. 输入名称(例如 `ci-agent` 或 `cursor-token`),然后点击 **生成**。 +3. 在弹窗中复制 Token。该 Token 仅展示一次。 +4. 在请求头中传递该 Token:`Authorization: Bearer `(或通过 `x-api-key` 请求头)。 + + + API Token 拥有与用户本人完全相同的操作权限:智能体可执行该账户在 Shumai + 中所能执行的任意操作。请像保管密码一样妥善保管 Token,建议为每个客户端单独生成独立 + Token,若不再使用,请前往 **团队设置** → **API Token** 及时吊销。 + + +--- + +## 可用工具列表 + +| 工具 | 功能说明 | +| ------------------------- | --------------------------------------------------------------------------------------- | +| `list_projects` | 列出当前可访问的项目及其根目录文件夹。 | +| `list_assets` | 分页列出指定文件夹内的文件与子文件夹。 | +| `search_assets` | 按名称、语义含义(需启用 AI 搜索)或元数据搜索文件夹及其子文件夹。 | +| `create_folder` | 创建文件夹。 | +| `rename_asset` | 重命名文件或文件夹。 | +| `move_assets` | 将文件或文件夹移动至另一个文件夹。 | +| `copy_assets` | 将文件或文件夹复制至同团队下的另一个文件夹。 | +| `delete_asset` | 将文件或文件夹移至项目废纸篓。此操作标记为破坏性操作,客户端可据此要求用户确认。 | +| `read_asset` | 查看文件内容:图片、视频帧、PDF 页面、3D 模型视图或文本文件内容。 | +| `get_asset_render` | 获取此前仍在渲染中的 `read_asset` 任务结果。 | +| `download_asset` | 获取最多 50 个文件的下载链接:默认获取 Web 预览版本,指定 `proxy: false` 可获取原文件。 | +| `get_folder_instructions` | 读取文件夹中面向 AI 智能体的指引文件(AGENTS.md)。 | +| `create_file` | 发起向文件夹上传新文件的流程(详见 [上传文件](#上传文件))。 | +| `create_version` | 发起为已有文件上传新版本的流程。 | +| `complete_upload` | 完成由 `create_file` 或 `create_version` 发起的上传流程。 | +| `list_comments` | 列出文件上的审阅评论及其回复。 | +| `create_comment` | 在文件上添加评论(可指定时间码)或回复评论。 | +| `resolve_comment` | 将评论标记为已解决或恢复为未解决。 | +| `list_metadata_fields` | 列出项目的元数据字段(如状态、评分及自定义字段)及其候选值。 | +| `update_asset_metadata` | 设置文件的元数据值。 | +| `create_version_stack` | 将同目录下的多个文件打包为单个资产的版本堆栈。 | +| `list_versions` | 按倒序列出版本堆栈中的所有版本。 | +| `remove_version` | 将指定版本移出版本堆栈(保留原文件)。 | + +### 读取文件 + +`read_asset` 会将图片附加至调用结果中,以便 AI 模型直接识别:每次调用最多支持 8 张图片,每张大小不超过 2 MB。超出部分的图片仅以链接形式列出。每条返回结果均包含指向各图片的访问链接,有效期约为 1 小时。若客户端无法直接渲染图片,可传入 `inlineImages: false` 仅获取链接。 + +渲染视频帧或 PDF 页面通常耗时较长。若渲染耗时超过约 20 秒,`read_asset` 将返回状态 `status: "pending"` 与对应的 `taskId`;随后模型可携带该 `taskId` 调用 `get_asset_render` 获取最终渲染结果。仅发起读取任务的用户本人可获取其渲染结果。 + +### 上传文件 + +上传过程分为三个阶段,以确保大文件内容无需经由 AI 模型中转: + +1. `create_file`(或 `create_version`)返回 `uploadUrl` 与 `uploadId`。 +2. 智能体通过 HTTP `PUT` 请求将文件二进制数据上传至 `uploadUrl`,例如使用 `curl -T video.mp4 ""`。 +3. 携带 `uploadId` 调用 `complete_upload` 完成文件创建并触发后续处理(如生成预览、媒体转码)。 + +上传 URL 与 ID 的有效期约为 1 小时,且仅允许发起者本人确认完成上传。若项目配置了**创建上下文 (Creation Context)** 元数据字段(例如生成该文件所使用的 Prompt 或模型),可在调用 `create_file` 或 `create_version` 时将其作为 `metadata` 传入;通过 `list_metadata_fields` 可查询当前支持的字段。 + +智能体必须能够直接访问上传 URL。若 Shumai 配置了本地存储,该 URL 指向 Shumai 服务器;若配置了 S3 存储,则直接指向 S3 端点。 + +每次调用均遵循用户的实际权限执行:例如拥有 **审阅者 (Reviewer)** 角色的成员可以列出资产,但无法创建或重命名资产。所有操作均记录在团队审计日志中并归属至该用户,来源标记为 MCP。 + +--- + +## 故障排查 + +- **OAuth 授权已过期或失效**:清理客户端本地 OAuth 会话缓存(`rm -rf ~/.mcp-auth`),并重启 MCP 客户端重新完成鉴权。 +- **401 Unauthorized**:API Token 或 OAuth 访问令牌缺失、过期、拼写错误或已被吊销。若使用 API Token,请前往 **团队设置** → **API Token** 重新生成,并更新客户端配置。 +- **工具调用出现权限错误 (Permission errors)**:当前用户在对应团队或项目中的角色无权执行该操作。 diff --git a/docs/zh/getting-started/overview.mdx b/docs/zh/getting-started/overview.mdx new file mode 100644 index 00000000..98fc6706 --- /dev/null +++ b/docs/zh/getting-started/overview.mdx @@ -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 的云存储,以确保所有工作节点均能正常访问上传的文件。_ diff --git a/docs/zh/getting-started/quickstart.mdx b/docs/zh/getting-started/quickstart.mdx new file mode 100644 index 00000000..140d0982 --- /dev/null +++ b/docs/zh/getting-started/quickstart.mdx @@ -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://.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)。 diff --git a/docs/zh/getting-started/s3-storage.mdx b/docs/zh/getting-started/s3-storage.mdx new file mode 100644 index 00000000..e9a33e9f --- /dev/null +++ b/docs/zh/getting-started/s3-storage.mdx @@ -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://.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://.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 + } +] +``` diff --git a/docs/zh/using-shumai/3d-asset-support.mdx b/docs/zh/using-shumai/3d-asset-support.mdx new file mode 100644 index 00000000..b1c29bc7 --- /dev/null +++ b/docs/zh/using-shumai/3d-asset-support.mdx @@ -0,0 +1,153 @@ +--- +title: 基于 Turntable Renderer 的 3D 资产支持 +description: 使用 turntable-renderer 渲染交互式 3D 模型转盘预览、雪碧图快擦预览与视频代理。 +--- + +3D 模型与网格资产在各类浏览器和移动设备上往往难以实现一致的渲染效果与可靠的检查体验。Shumai 集成了 [turntable-renderer](https://github.com/shumaiOne/turntable-renderer) 独立服务——该服务通过隔离的无头 Blender 5.2 LTS 子进程,将上传的 3D 模型转换为标准化、高保真的转盘(Turntable)预览。 + +Turntable Renderer 会自动生成: + +- **1080×1080 转盘视频(`turntable.mp4`)**:时长 4 秒、共 24 帧、6 fps 的视频,在纯黑背景与暗调摄影棚布光下顺时针 360°(每帧 15°)旋转展示模型。 +- **海报缩略图(`poster.webp`)**:清晰的高清静态封面海报,用于网格卡片展示与文件即时呈现。 +- **悬停预览雪碧图(`sprite.webp`)**:快速擦动(Scrubbing)雪碧图,支持在文件列表中悬停鼠标直接旋转预览并检查模型。 +- **交互式 3D 播放器**:专用的 Web 检视器,提供 360° 标尺擦动、旋转角度微调(0° 至 345°)、播放控制,并支持针对特定角度添加评审评论与视觉批注。 + +--- + +## 支持的文件类型 + +配置 turntable-renderer 后,Shumai 会自动为以下格式生成 3D 转盘代理: + +| 格式 / 标准 | 扩展名 | +| :-------------------------------- | :-------------------------------- | +| 二进制 glTF | `.glb` | +| Universal Scene Description (USD) | `.usd`, `.usda`, `.usdc`, `.usdz` | +| Autodesk FBX | `.fbx` | +| Wavefront OBJ | `.obj` | +| 实体光刻 (STL) | `.stl` | +| COLLADA | `.dae` | + +--- + +## 配置说明 + +Shumai 支持通过 **Web 界面**或**环境变量**配置 Turntable Renderer。 + +### 1. Web 界面配置(团队设置 → 集成) + +团队所有者可直接在 Web 界面中配置 Turntable Renderer: + +1. 在侧边栏导航至**团队设置**。 +2. 切换至**集成**选项卡。 +3. 在 **3D Turntable Renderer** 下,输入**服务器地址(Server URL)**(例如 `http://turntable-renderer:3000` 或 `http://localhost:3003`)。 +4. 若服务启用了 Basic 基础认证,请输入**用户名**与**密码**。 +5. 点击**测试连接**,验证 Shumai 与渲染服务的通信状态并检查检测到的 Blender 版本。 +6. 点击**保存更改**。 + +### 2. 环境变量配置 + +也可以在运行 Shumai 或转码 Worker 的机器上通过环境变量进行全局配置: + +| 变量 | 必填 | 说明 | +| :--------------------------------------- | :--------------- | :----------------------------------------------------------------------- | +| `TURNTABLE_RENDERER_URL` | 是(启用时必填) | Turntable Renderer 基础服务地址,例如 `http://turntable-renderer:3000`。 | +| `TURNTABLE_RENDERER_BASIC_AUTH_USERNAME` | 否 | 开启 Basic 基础认证时的用户名(别名:`TURNTABLE_RENDERER_USERNAME`)。 | +| `TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD` | 否 | 开启 Basic 基础认证时的密码(别名:`TURNTABLE_RENDERER_PASSWORD`)。 | + +### 配置优先级与只读模式 + +> [!IMPORTANT] +> **环境变量优先级最高。** 一旦在运行环境中配置了 `TURNTABLE_RENDERER_URL`,Shumai 将始终优先采用环境变量中的配置。 +> +> 通过环境变量配置后,**团队设置 → 集成**中的对应设置项将显示**已通过环境变量配置(只读)**徽标,且输入框将被锁定,防止误操作或配置不一致。 + +--- + +## 部署 Turntable Renderer + +### Docker 快速上手 + +运行 turntable-renderer 最便捷的方式是使用官方预构建的 Docker 镜像: + +```bash +docker run -d --rm \ + --name turntable-renderer \ + -p 3003:3000 \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \ + shumaione/turntable-renderer:latest +``` + +> **说明**:宿主机端口 `3003` 映射至容器内部端口 `3000`。 + +### Docker Compose 配置 + +在 `docker-compose.yaml` 中添加 `turntable-renderer` 服务: + +```yaml +services: + turntable-renderer: + image: shumaione/turntable-renderer:latest + restart: unless-stopped + ports: + - '3003:3000' + environment: + TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME: admin + TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD: your_password +``` + +随后在 Shumai 中配置指向该服务: + +```bash +TURNTABLE_RENDERER_URL=http://localhost:3003 +TURNTABLE_RENDERER_BASIC_AUTH_USERNAME=admin +TURNTABLE_RENDERER_BASIC_AUTH_PASSWORD=your_password +``` + +_(若 Shumai 与 turntable-renderer 运行在同一个 Docker Compose 网络中,服务地址请填 `http://turntable-renderer:3000`)。_ + +### GPU 硬件加速 + +独立 GPU 为可选配置——turntable-renderer 的 CPU 渲染流水线在普通硬件配置下已具备足够快的处理速度。当向容器传入 GPU 资源时,系统会自动检测并启用硬件加速。 + +#### Intel / AMD(开源驱动) + +透传 DRI 渲染节点设备: + +```bash +docker run -d --rm \ + --name turntable-renderer \ + --shm-size=1gb \ + -p 3003:3000 \ + --device /dev/dri \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \ + shumaione/turntable-renderer:latest +``` + +#### NVIDIA(专有闭源驱动) + +宿主机需安装 580+ 版本显卡驱动及 NVIDIA Container Toolkit(`--runtime nvidia`): + +```bash +docker run -d --rm \ + --name turntable-renderer \ + --shm-size=1gb \ + -p 3003:3000 \ + --runtime nvidia \ + --gpus all \ + --device /dev/nvidia-modeset \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_USERNAME=admin \ + -e TURNTABLE_RENDERER_API_BASIC_AUTH_PASSWORD=your_password \ + shumaione/turntable-renderer:latest +``` + +--- + +## 未配置 Turntable Renderer 时的系统行为 + +若未配置 turntable-renderer 或服务无法连通: + +- 上传的 3D 模型仍可正常处理完成,状态标记为 `processed`。 +- 不会生成转盘视频代理、雪碧图与海报缩略图。 +- 原始 3D 文件安全完整保存,团队成员可正常下载原文件。 diff --git a/docs/zh/using-shumai/agent-providers.mdx b/docs/zh/using-shumai/agent-providers.mdx new file mode 100644 index 00000000..c2501386 --- /dev/null +++ b/docs/zh/using-shumai/agent-providers.mdx @@ -0,0 +1,49 @@ +--- +title: AI 模型服务商 +description: 将 Shumai 连接至 OpenAI、Anthropic、Gemini 或自定义 LLM 网关。 +--- + +创建用于对话或元数据自动填充的智能体时,需要选择底层的 AI 模型。可用模型与服务商在团队设置中集中统一配置。 + +> 🔒 **权限说明:** 仅**团队所有者(Team Owner)**拥有管理 AI 模型服务商的权限。若需调整配置,请点击头像进入**设置**,并在左侧导航栏中选择**服务商(Providers)**。 + +--- + +## 内置模型服务商 + +Shumai 预置了主流 LLM 服务商的配置。由于 Shumai 采用 [Pi](https://github.com/earendil-works/pi) 作为底层核心智能体框架,系统支持的服务商与模型配置会自动与 Pi 的功能生态保持同步。 + +团队所有者可自由编辑、删除或添加新服务商。所有已配置的服务商与模型参数均会在运行时直接注入 Pi 框架。 + +--- + +## 配置参考 + +### 服务商配置项 + +配置服务商时需指定以下字段: + +| 字段 | 说明 | 示例 / 备注 | +| :------------------------------ | :----------------------------------- | :-------------------------------------------------------------------------------------------- | +| **服务商名称(Provider Name)** | 唯一且易于辨识的服务商标识。 | `Ollama-Local`、`Enterprise-Gateway` | +| **基础 URL(Base URL)** | 目标 API 端点地址。 | `http://localhost:11434/v1` | +| **API 协议(API Protocol)** | 流式传输与请求载荷协议格式。 | 大多数兼容 OpenAI 的网关使用 `openai-completions`。 | +| **API 密钥(API Key)** | 身份认证令牌。本地无鉴权环境可留空。 | 支持直接填入密钥明文(`sk-...`),或指定宿主机环境变量名称(如 `MY_API_KEY`)以安全读取凭据。 | + +### 模型配置项 + +每个服务商下均可挂载多个模型。每个模型支持配置以下属性: + +| 字段 | 说明 | 示例 / 备注 | +| :-------------------------------------- | :---------------------------------------------------- | :------------------------------------- | +| **模型 ID(Model ID)** | 上游 API 所要求的精确模型标识符。 | `gpt-4o`、`claude-3-5-sonnet-20240620` | +| **显示名称(Display Name)** | 下拉菜单中面向用户展示的自定义友好名称(可选)。 | `GPT-4 Omni`、`Claude 3.5` | +| **深度推理支持(Reasoning Support)** | 开关选项,用于启用深度思考(Extended Thinking)协议。 | 适用于具备原生推理能力的模型。 | +| **上下文窗口(Context Window)** | 模型支持的最大 Token 总容量(输入 + 输出)。 | | +| **最大输出 Token(Max Output Tokens)** | 单次请求生成回复的 Token 上限。 | | +| **输入成本(Input Cost)** | 每百万输入 Token 的单价。 | 可选,用于统计使用开销与用量指标。 | +| **输出成本(Output Cost)** | 每百万输出 Token 的单价。 | 可选,用于统计使用开销与用量指标。 | + +--- + +![AI 服务商列表](/providers.webp) diff --git a/docs/zh/using-shumai/agent-sandbox.mdx b/docs/zh/using-shumai/agent-sandbox.mdx new file mode 100644 index 00000000..1d341ca6 --- /dev/null +++ b/docs/zh/using-shumai/agent-sandbox.mdx @@ -0,0 +1,45 @@ +--- +title: 智能体沙箱 +description: AI 智能体脚本的安全执行环境与网络域名限制规范。 +--- + +运行自动化脚本存在潜在的安全风险。Shumai 通过在安全且隔离的**沙箱(Sandbox)**环境中执行所有智能体技能来化解这一隐患。 + +--- + +## 沙箱安全机制 + +沙箱严格限制执行进程访问宿主机文件系统、系统进程及内部网络: + +- **环境隔离**:脚本在虚拟化的工作区容器中运行,无法篡改系统核心文件或读取其他项目数据。 +- **网络桥接管控**:来自沙箱内部的外部网络请求会受到严格监控。 + +### 文件系统访问限制 + +为保障工作区环境与敏感数据安全,沙箱实施了严密的文件级访问控制策略: + +- **读取权限**:沙箱允许读取工作区内的普通文件,但严格禁止访问敏感环境配置与证书密钥文件。禁止读取的文件模式包括:`['.env', '.env.*', '*.pem', '*.key']`。 +- **写入权限**:沙箱的写入权限受到极为严苛的限制,仅允许写入当前工作目录(cwd)下的 `.pi` 文件夹。即便在该受信任的目录内部,沙箱也严禁写入或创建匹配以下模式的敏感文件:`['.env', '.env.*', '*.pem', '*.key']`。 + +--- + +## 域名白名单 + +默认情况下,网络沙箱处于**关闭**状态(允许所有出站网络请求)。团队所有者可在沙箱设置中开启网络沙箱,以强制推行严格的域名白名单管控: + +### 允许的域名 (Allowed Domains) + +允许沙箱内脚本正常访问的域名清单。 + +- 默认白名单包含标准软件包注册表(如 npm、Python 官方源等)以及代码托管平台(如 `github.com`)。 +- 若脚本需要调用外部 API(如 `api.slack.com`),管理员须预先将其添加至白名单中。 + +### 待审批域名 (Pending Domains) + +当智能体脚本尝试访问未经授权的域名时: + +1. 网络连接将被即刻拦截。 +2. 系统会记录目标域名并将其加入**待审批域名**列表。 +3. 管理员可审阅该列表,点击**批准**将其加白,或点击**拒绝**保持拦截。 + +![智能体沙箱设置](/sandbox.webp) diff --git a/docs/zh/using-shumai/agent-skills.mdx b/docs/zh/using-shumai/agent-skills.mdx new file mode 100644 index 00000000..c15d5f68 --- /dev/null +++ b/docs/zh/using-shumai/agent-skills.mdx @@ -0,0 +1,54 @@ +--- +title: 智能体技能 +description: 通过自定义自动化工具扩展智能体能力。 +--- + +原生 AI 模型通常仅具备文本与图像处理能力。在 Shumai 中,可通过注册**技能(Skills)**为**对话智能体**与**自动填充智能体**扩展能力边界——技能即智能体在执行任务时可调用的自定义脚本。 + +--- + +## 技能运作机制 + +技能由用户自行定义,并授权给 AI 智能体使用。 + +- **面向 AI 的元数据描述**:注册技能后,AI 智能体会读取其元数据描述,理解在何种场景下、以何种方式调用该工具来解决具体问题。 +- **执行与本地缓存**:当智能体决定调用某项技能时,Shumai 会负责调度执行。新添加的技能数据首先同步至数据库;执行时,智能体会从数据库下载并在本地缓存技能文件,确保高效稳定的访问速度。 + +--- + +## 添加技能 + +向 Shumai 安装新技能的步骤如下: + +1. 前往**设置**页面并切换至**技能(Skills)**标签页。 +2. 点击**添加技能**按钮。 +3. 在弹出的对话框中选择安装方式: + - **本地上传**:选择并上传包含技能文件的 `.zip` 压缩包。 + - **GitHub 导入**:填入合法的 GitHub 仓库路径。 + +> **重要提示:** 无论采用哪种安装方式,技能包根目录下必须包含 `SKILL.md` 文件。 + +### 更新现有技能 + +若需更新技能,只需按上述步骤重新安装新版本,并保持技能名称完全一致,Shumai 便会自动覆盖旧版本。 + +--- + +## 配置环境变量 + +若自定义技能依赖环境变量(如 API 密钥、外部 Token)才能运行: + +1. 在技能列表中点击已安装的**技能卡片**打开配置弹窗。 +2. 添加所需的环境变量。 +3. _(可选)_ 为环境变量设定默认值。若未指定默认值,技能将在运行时动态读取宿主机系统环境变量。 + +--- + +## 为智能体启用技能 + +**所有技能默认均处于禁用状态。** 仅安装技能并不会赋予智能体调用权限。若需授权智能体调用已安装的技能: + +1. 前往对应的**智能体设置**。 +2. 勾选希望授权给该智能体的技能。 + +![技能列表视图](/skills.webp) diff --git a/docs/zh/using-shumai/agent-tools.mdx b/docs/zh/using-shumai/agent-tools.mdx new file mode 100644 index 00000000..e237cf2b --- /dev/null +++ b/docs/zh/using-shumai/agent-tools.mdx @@ -0,0 +1,164 @@ +--- +title: 智能体工具 +description: 为各智能体配置允许调用的工具与能力。 +--- + +Shumai 智能体配备了丰富的内置工具,支持直接操作文件系统、查看文件、提取视频帧以及执行终端命令。 + +默认情况下,新建智能体已开启绝大多数常用工具;而高危或破坏性工具(如**删除资产**)则默认禁用。团队所有者可按需开启或关闭特定工具,精准收敛智能体的操作权限。 + + + **注意:** + 禁用工具可能导致智能体或某些技能执行失败。例如,若禁用**沙箱终端**工具,几乎所有依赖命令行或脚本环境的自定义技能都将无法运行。除非团队有明确的安全策略或权限隔离要求,否则建议保持默认开启。 + + +--- + +## 可用工具清单 + +可在智能体配置弹窗中单独启闭以下工具: + +### 1. 沙箱终端 (`bash`) + +- **说明:** 允许智能体在高度隔离的环境中执行终端与 Shell 命令。 +- **重要性:** 运行自定义脚本、处理磁盘文件或调用标准 Unix 工具的核心基础。若禁用此工具,智能体将无法执行命令行代码。 + +### 2. 读取技能 (`read_skill`) + +- **说明:** 允许智能体加载并读取技能定义,以执行专属任务。 +- **重要性:** 使智能体在执行前能够审阅工作区中注册的自定义技能指令与配置。 + +### 3. 读取资产 (`read_asset`) + +- **说明:** 允许智能体检视图片、提取视频逐帧画面、渲染 PDF 文档页面以及读取文本/Markdown 文档内容。 +- **重要性:** 赋予多模态智能体查看 Shumai 中上传素材的能力,支持按帧提取视频截图、检视文档排版,并就上传的创意资产解答疑问。 +- **限制:** 单次调用最多获取 20 个视频帧或 PDF 页面。若渲染耗时超过约 1 分钟,工具会告知智能体渲染仍在处理中,而非直接报错中断。 + +### 4. 获取资产渲染结果 (`get_asset_render`) + +- **说明:** 允许智能体获取此前调用 `read_asset` 时仍在后台渲染的视频帧或文档页面。 +- **重要性:** 长视频与大体积文档渲染通常需要一定时间。借助此工具,智能体可在渲染完成后回溯获取结果,无需重头开始。该工具仅返回同一用户此前通过 `read_asset` 发起的渲染任务。 + +### 5. 浏览资产 (`list_assets`) + +- **说明:** 允许智能体列出 Shumai 中的文件夹并浏览文件。大型文件夹支持分页返回。 +- **重要性:** 为智能体呈现项目结构全貌,便于检索其他文件或定位相关资产。 + +### 6. 列出项目 (`list_projects`) + +- **说明:** 允许智能体列出当前用户在各团队中有权访问的项目,包含每个项目的根文件夹信息。 +- **重要性:** 便于智能体在浏览或创建文件前,自主查找目标项目及其根目录。 + +### 7. 创建文件夹 (`create_folder`) + +- **说明:** 允许智能体在 Shumai 中新建文件夹。 +- **重要性:** 当智能体需要整理产出内容或在自定义子目录中归档文件时不可或缺。 + +### 8. 创建文件 (`create_file`) + +- **说明:** 允许智能体在 Shumai 中创建并上传新文件。 +- **重要性:** 支持智能体生成新资产(如文本日志、转码片段、分析报告等)并直接回存至项目中。 + +### 9. 创建版本 (`create_version`) + +- **说明:** 允许智能体上传新版本并将其堆叠至 Shumai 中已有的文件上。 +- **重要性:** 支持智能体以无损方式迭代文件,通过追加版本堆栈而非生成同名重复文件来保留历史记录。 + +### 10. 生成图像 (`generate_image`) + +- **说明:** 允许智能体借助已配置的 AI 图像模型,基于文本提示词与参考图生成静态图片。 +- **重要性:** 支持智能体在 Shumai 中直接创作概念图、设计效果图、纹理贴图及插画素材。 +- **前置条件:** 必须在[图像与视频生成](/zh/using-shumai/image-video-generation)中至少配置并启用一个图像模型。若已配置的服务商下未启用任何图像模型,即便在智能体设置中开启了该工具,会话中也会自动隐藏该工具。 + +### 11. 生成视频 (`generate_video`) + +- **说明:** 允许智能体借助已配置的 AI 视频模型,基于文本提示词、静态图片动画化或关键帧过渡生成视频片段。 +- **重要性:** 支持智能体生成简短动态动画、运镜镜头及视频转场。 +- **前置条件:** 必须在[图像与视频生成](/zh/using-shumai/image-video-generation)中至少配置并启用一个视频模型。若已配置的服务商下未启用任何视频模型,即便在智能体设置中开启了该工具,会话中也会自动隐藏该工具。 + +### 12. 下载资产 (`download_asset`) + +- **说明:** 允许智能体单次最多下载 50 个工作区文件,或下载特定的 S3 存储键(如来自 `read_asset` 的视频帧)至本地 `.pi` 目录,供本地脚本或 Shell 命令进一步处理。当存在网页预览版本时,默认下载预览版(例如转码代理视频或网页压缩图);智能体亦可明确请求下载原始上传文件。不支持直接下载文件夹。 +- **重要性:** 便于执行自定义技能脚本的智能体将素材文件或转码中间产物拉取至本地磁盘。 + +### 13. 重命名资产 (`rename_asset`) + +- **说明:** 允许智能体修改 Shumai 中已有文件或文件夹的名称。 +- **重要性:** 支持智能体按照工作区的规范命名规则整理项目文件。默认开启。 + +### 14. 移动资产 (`move_assets`) + +- **说明:** 允许智能体将一个或多个资产移动到目标父文件夹中。 +- **重要性:** 支持智能体整理工作区目录层级、归档生成结果或重组项目文件夹。默认开启。 + +### 15. 删除资产 (`delete_asset`) + +- **说明:** 允许智能体将单个文件或文件夹移入废纸篓。 +- **重要性:** 赋予智能体清理陈旧或冗余资产的能力。为防止数据误删,该工具**默认处于禁用状态**,且严格限制每次只能删除单个资产。必须由团队所有者显式开启。 + +### 16. 搜索资产 (`search_assets`) + +- **说明:** 允许智能体按名称、语义含义(当团队开启 AI 语义搜索时)或状态等元数据检索指定文件夹及其子目录。 +- **重要性:** 便于智能体直接定位任务所需的目标文件,无需逐层遍历目录。 + +### 17. 复制资产 (`copy_assets`) + +- **说明:** 允许智能体将文件或文件夹(连同内部所有内容)完整复制到同团队下的另一个文件夹中。 +- **重要性:** 便于智能体在跨项目复用资产或创建工作副本时,保持原始文件不受改动。 + +### 18. 读取文件夹指令 (`get_folder_instructions`) + +- **说明:** 允许智能体读取文件夹中针对 AI 智能体设置的专属指令文件(AGENTS.md)。 +- **重要性:** 使智能体在向文件夹添加文件前,能够遵循团队预设的规范要求(如命名规则或交付物指标)。 + +### 19. 读取评论 (`list_comments`) + +- **说明:** 允许智能体读取文件上的审阅评论与回复内容,包括时间码信息。 +- **重要性:** 便于智能体根据审阅意见采取行动,例如汇总待处理问题或在新版本中落实修改建议。 + +### 20. 发表评论 (`create_comment`) + +- **说明:** 允许智能体在文件上发表评论(可指定时间码)或回复已有评论。评论将以智能体所服务用户的身份发布,并在审计日志中明确记录系智能体生成。 +- **重要性:** 支持智能体像真人团队成员一样参与审片协作。智能体在评论中提及其他成员或智能体时不会触发二次联动。 + +### 21. 解决评论 (`resolve_comment`) + +- **说明:** 允许智能体将评论标记为已解决,或重新打开已解决的评论。 +- **重要性:** 支持智能体在完成修改后及时闭环对应的反馈事项。 + +### 22. 列出元数据字段 (`list_metadata_fields`) + +- **说明:** 允许智能体查看项目支持的元数据字段定义(如状态、评级及自定义字段)与其可选项。 +- **重要性:** 告知智能体哪些字段支持检索或赋值。 + +### 23. 更新元数据 (`update_asset_metadata`) + +- **说明:** 允许智能体修改文件的元数据属性,例如更新状态或标签。只读字段不可更改。 +- **重要性:** 支持智能体实时维护文件的审阅状态及其他关键元数据属性。 + +### 24. 创建版本堆栈 (`create_version_stack`) + +- **说明:** 允许智能体将同一文件夹下的多个散落文件整合为一个资产的各版本。 +- **重要性:** 便于智能体将零散的文件版本(例如 `cut_v1.mp4` 与 `cut_v2.mp4`)整理归纳为单一版本化资产。 + +### 25. 列出版本历史 (`list_versions`) + +- **说明:** 允许智能体按时间倒序(最新版本在前)列出版本堆栈中的所有历史版本。 +- **重要性:** 便于智能体对比当前文件与历史版本之间的差异。 + +### 26. 移除版本 (`remove_version`) + +- **说明:** 允许智能体从版本堆栈中剥离某个版本。该操作不会删除文件,而是将其还原为所在文件夹中的独立文件。 +- **重要性:** 便于智能体纠正错误堆叠的版本。 + +--- + +## 配置工具权限 + +若需调整智能体可调用的工具: + +1. 前往**团队设置** > **智能体**(注意:仅团队所有者有权查看和修改此项配置)。 +2. 点击需要配置的目标智能体。 +3. 向下滚动至**技能(Skills)**区域下方,即可看到**工具(Tools)**配置面板。 +4. 切换各个工具旁边的开关以启用或禁用。 +5. 点击**保存修改**。 diff --git a/docs/zh/using-shumai/agents-md.mdx b/docs/zh/using-shumai/agents-md.mdx new file mode 100644 index 00000000..8d528f8e --- /dev/null +++ b/docs/zh/using-shumai/agents-md.mdx @@ -0,0 +1,53 @@ +--- +title: AGENTS.md 上下文与指令 +description: 为 AI 智能体提供层级化、针对特定文件夹的指令与上下文支持。 +--- + +除全局智能体系统提示词与技能外,Shumai 还支持通过 **`AGENTS.md`** 为项目与文件夹定义层级化上下文指令。 + +当 AI 智能体(如对话智能体或自动填充智能体)在项目或文件夹中执行任务时,Shumai 会自动加载对应的 `AGENTS.md` 文件,为智能体注入上下文背景、操作规范与项目专属知识。 + +--- + +## 层级遍历与上下文继承 + +Shumai 对 `AGENTS.md` 采用层级化上下文继承机制: + +- **向上回溯遍历**:当智能体处理某个文件或文件夹时,Shumai 会从当前目录沿目录树一路向上遍历,直至**项目根目录**。 +- **合并注入上下文**:沿途检索到的所有 `AGENTS.md` 文件会按序(从项目根目录至当前子目录)加载至智能体的上下文窗口中。 +- **规则分层沉淀**:可在项目根目录的 `AGENTS.md` 中约定通用的全局准则与规范,并在嵌套的各级子文件夹 `AGENTS.md` 中补充专属规则、术语词汇或自动填充指引。 + +--- + +## AGENTS.md 的典型编写内容 + +可以在 `AGENTS.md` 中编写希望智能体在当前项目或文件夹中遵循的各类指令: + +- **项目与文件夹概览**:阐述当前文件夹存放的资产类型,以及该文件夹在整个项目结构中的定位与作用。 +- **智能体行为准则**:明确智能体回答问题或发表评论时的安全红线、语气风格、排版格式要求,以及允许或禁止执行的操作。 +- **行业术语与领域知识**:约定专业词汇、缩写、品牌规范名称或项目专属行话术语。 +- **元数据与自动填充指引**:指导**自动填充智能体**如何针对本文件夹内的文件归纳摘要、生成标签或填充特定的自定义元数据字段。 + +--- + +## 查看与编辑 AGENTS.md + +### 打开编辑器 + +若需查看或编辑 `AGENTS.md`: + +1. 在 Shumai Web 应用中打开任意项目或文件夹。 +2. 点击顶部导航工具栏中的 **`AGENTS.md`** 按钮,或在文件列表中右键点击任意文件夹并选择 **AGENTS.md**。 +3. 系统将弹出专属的所见即所得 Markdown 编辑器,完整支持标题、列表、代码块、粗体/斜体以及链接等排版格式。 + +### 自动保存 + +在编辑器中修改内容时,Shumai 会在后台自动保存更改,并通过直观的状态指示器提示保存进度(`Saving...`、`Saved`)。 + +--- + +## 权限控制与只读模式 + +- **查看权限**:拥有项目只读及以上访问权限的所有团队成员均可查看 `AGENTS.md`。 +- **编辑权限**:**仅团队所有者(Team Owner)**有权创建、编辑或删除 `AGENTS.md` 文件。 +- **只读状态提示**:非团队所有者成员在工具栏中会看到明确的只读提示,告知只有团队所有者才能修改该文件的指令内容。 diff --git a/docs/zh/using-shumai/agents.mdx b/docs/zh/using-shumai/agents.mdx new file mode 100644 index 00000000..a6e884f9 --- /dev/null +++ b/docs/zh/using-shumai/agents.mdx @@ -0,0 +1,51 @@ +--- +title: AI 智能体 +description: 创建与配置专用于对话、元数据自动填充及向量索引生成的 AI 智能体。 +--- + +Shumai 借助各类专属 AI 智能体执行后台自动化任务、对话交互工作流以及语义索引构建。**仅团队所有者(Team Owner)**拥有创建、管理和修改智能体配置的权限。 + +--- + +## 智能体类型 + +Shumai 支持以下三种类型的智能体: + +### 1. 对话智能体 (Chat Agent) + +活跃于项目工作区中的交互式对话助手。 + +- 支持按需创建任意数量的对话智能体。 +- 支持在文件评论中直接使用 “@” 提及对话智能体。 +- 具备上下文感知能力:能够读取文件内容、检索项目文件夹、检查元数据以及阅读评论会话。 +- 支持为对话智能体挂载“技能”,使其能够代为写入文件、运行脚本或调用外部 API。 + +### 2. 自动填充智能体 (Autofill Agent) + +负责监听文件上传的后台智能体。系统**仅允许创建 1 个**自动填充智能体。 + +- 创建并启用后,只要上传的文件类型符合要求(图片或视频),Shumai 便会自动触发该智能体。 +- 它会深入分析文件内容(多模态图像特征、文字描述等),并自动填充所有开启了“AI 自动填充”标记的元数据字段。 + +### 3. 向量索引智能体 (Embedding Agent) + +专用于处理资产并构建搜索索引的工具型智能体。系统**仅允许创建 1 个**向量索引智能体。 + +- 创建并启用后,若新上传的文件类型符合要求(图片或视频),Shumai 会自动生成向量嵌入(Embedding)。 +- 生成的搜索索引将持久化保存,为 Shumai 的自然语言语义搜索功能提供底层支持。 +- **注意:** 向量索引智能体底层固定采用 `google-embedding-2` 模型,因此不支持自定义服务商或模型。请确保已在服务端配置 `GEMINI_API_KEY` 环境变量以保证其正常运转。 +- **切片时长(Chunk Duration):** 长视频索引时的视频切片时长可通过 `EMBEDDING_CHUNK_DURATION` 环境变量配置(默认值为 60 秒)。 + +--- + +## 配置智能体 + +若需新建或编辑智能体,请前往**团队设置** > **智能体**(注意:仅团队所有者有权修改这些配置): + +- **头像(Avatar)**:在预设头像列表中为智能体挑选专属头像。 +- **启用 / 禁用开关**:控制智能体的启停状态。若禁用向量索引智能体,语义搜索索引构建将被暂停。 +- **系统提示词 / 人设(Soul)**:定义智能体行为准则、格式规范及操作边界的核心指令。 +- **模型服务商(Model Provider)**:选择智能体运行所依托的已注册服务商与模型。_(注:向量索引智能体不开放此选项)_。 +- **分配技能(Assigned Skills)**:勾选允许该智能体调用的自定义技能。 + +![智能体配置面板](/agents.webp) diff --git a/docs/zh/using-shumai/asset-management.mdx b/docs/zh/using-shumai/asset-management.mdx new file mode 100644 index 00000000..4c77f403 --- /dev/null +++ b/docs/zh/using-shumai/asset-management.mdx @@ -0,0 +1,54 @@ +--- +title: 资产管理 +description: 了解如何在工作区中上传、整理、删除与恢复媒体资产。 +--- + +Shumai 支持便捷地将创意媒体素材导入工作区,按文件夹分类整理,并全流程管理从上传到删除的完整资产生命周期。 + +--- + +## 上传资产 + +可以通过以下三种方式将文件和文件夹上传至 Shumai: + +1. **拖拽上传**:从电脑的文件管理器中直接拖拽文件或整个文件夹,释放到 Shumai 控制台界面的任意位置。 +2. **按钮上传**:点击工具栏中的 **上传文件** 或 **上传文件夹** 按钮。 +3. **复制粘贴**:从其他网站、应用程序或剪贴板复制图片或文件,直接在 Shumai 浏览器窗口中粘贴(`Ctrl+V` 或 `Cmd+V`)即可立即上传。 + +![资产管理 - 拖拽上传](/dragdrop.webp) + +--- + +## 文件夹组织 + +上传整个文件夹时,Shumai 会在项目中完整保留并重建原始文件夹层级结构: + +- 自动创建所有子文件夹。 +- 嵌套文件保留在各自对应的子文件夹中。 +- 支持任意深度的文件夹层级嵌套上传。 + +--- + +## 上传与处理状态 + +上传启动后,资产将历经以下几种状态: + +- **上传中(Uploading)**:文件正在传输到存储服务器,界面实时显示传输进度百分比。 +- **处理中(Processing)**:文件已成功上传。Shumai 正在提取媒体参数(如分辨率、视频时长和音频编解码器)并生成便于 Web 在线流畅播放的预览代理(Proxy)。 +- **就绪(Ready)**:处理完毕。资产已完全可见、支持在线播放,并可随时添加评论、标记元数据或搜索。 + +--- + +## 删除与恢复资产 + +若某些资产不再需要,可以将其删除以整理工作区: + +### 回收站(最近删除) + +- 删除文件或文件夹后,相应资产将移至项目设置中的 **最近删除**(Recently Deleted)标签页。 +- 已删除资产会在回收站中保留 **30 天**。在此期间,可选中任意资产并点击 **恢复**(Recover)将其还原至原始位置。 +- 若需立即释放存储空间,可打开“最近删除”标签页并点击 **清空回收站**(Empty Trash)永久清除文件。 + +### 永久删除 + +在回收站保留 **30 天** 后,资产将自动永久清除。清除完成后,相关记录会从数据库中移除,文件也会从存储后端(本地文件系统或 S3 存储桶)彻底删除且无法恢复。 diff --git a/docs/zh/using-shumai/collections.mdx b/docs/zh/using-shumai/collections.mdx new file mode 100644 index 00000000..c12e7b2f --- /dev/null +++ b/docs/zh/using-shumai/collections.mdx @@ -0,0 +1,55 @@ +--- +title: 收藏集 +description: 基于元数据过滤规则与搜索条件构建动态虚拟视图。 +--- + +无需将文件复制到静态文件夹中,Shumai 采用基于查询的动态虚拟视图——**收藏集**。收藏集能根据特定条件实时动态聚合匹配的文件。 + +--- + +## 什么是收藏集? + +**收藏集**不会在磁盘上重复存储文件,而是针对项目的资产数据库执行预定义的过滤查询。每当上传新文件或更新元数据且匹配收藏集的查询条件时,该文件就会自动呈现于该收藏集中。 + +--- + +## 创建收藏集 + +支持通过以下两种方式创建收藏集: + +- **侧边栏入口**:点击项目侧边栏中**收藏集**旁的 `+` 图标打开查询构建器,配置检索规则后保存。 +- **搜索弹窗入口**:在搜索弹窗中检索和筛选文件时,点击弹窗底部的**保存为收藏集**按钮,即可将当前的搜索条件直接转换为动态收藏集。 + +--- + +## 配置收藏集过滤规则 + +创建或编辑收藏集时,需指定名称并在构建器中设置过滤查询: + +### 1. 源文件夹 + +指定起始文件夹路径。收藏集将以递归方式扫描该文件夹及其所有下级子目录。 + +### 2. 运算符与条件 + +- **逻辑运算符**:使用 **AND**(满足所有条件)或 **OR**(满足任一条件)组合多个过滤规则。 +- **字段范围**:支持标准基础字段(文件名、类型、大小)或自定义元数据字段(如“状态”或“审核结果”)。 +- **匹配规则**: + - _等于 / 不等于_:精确匹配指定值。 + - _包含 / 不包含_:模糊匹配文本子串。 + - _大于 / 小于_:设置数值或日期范围(例如上传时间在昨天之后)。 + - _为空 / 不为空_:检查字段是否存在取值。 + +### 3. 收藏集默认排序 + +为收藏集单独指定自定义排序规则(如按自定义字段“发布日期”升序排列),以覆盖项目的默认排序规则。 + +--- + +## 典型应用场景 + +- **审核工作台**:创建名为“待审核”的收藏集,筛选 `状态` 为 `审核中` 的资产。 +- **每日交付物**:过滤最近 24 小时内上传的文件。 +- **已批准资产**:筛选符合 `标签` 包含 `marketing` 且 `已批准` 为 `是` 的资产。 + +![创建收藏集](/collection.webp) diff --git a/docs/zh/using-shumai/comments.mdx b/docs/zh/using-shumai/comments.mdx new file mode 100644 index 00000000..92fa87ba --- /dev/null +++ b/docs/zh/using-shumai/comments.mdx @@ -0,0 +1,51 @@ +--- +title: 评论与标注 +description: 借助画布涂鸦与时间戳评论协同审阅媒体资产。 +--- + +Shumai 专为音视频及图像反馈打造了沉浸式审阅工作区。除了常规文字评论外,团队成员还可以添加精确到时间戳的反馈,并直接在画面上绘制标注涂鸦。 + +--- + +## 时间戳评论 + +审阅音视频文件时,可以将评论锚定在时间轴上的精确秒数或关键帧: + +1. 播放或拖动进度条定位到需要审阅的精准画面帧或时间点。 +2. 在评论输入框中输入反馈意见。 +3. 点击 **发送**(Submit)。评论将连同时间标记一同保存,并在视频时间轴上生成标记锚点。 +4. 协作者点击侧边栏中的评论卡片,播放器即可直接跳转至对应的时间点。 + +![时间戳评论](/timestamp-comment.webp) + +--- + +## 画面标注(画布涂鸦) + +为了提供清晰直观的视觉反馈,可以直接在图片或视频画面帧上绘制标注: + +1. 将视频暂停在需要标注的画面帧。 +2. 在播放器上方的标注工具栏中选择绘图工具(画笔、矩形、圆形、箭头等)。 +3. 直接在画面屏幕上绘制标注。 +4. 输入评论并点击 **发送**(Submit)。绘制的标注涂鸦将与该条评论绑定保存。 +5. 当其他成员选择该条评论时,播放器将在对应帧画面上自动叠加显示绘制的标注。 + +![画面标注](/draw_annotation.webp) + +--- + +## 评论会话(回复) + +通过直接回复反馈保持讨论条理清晰: + +- 点击任意评论下方的 **回复**(Reply)。 +- 回复内容将按层级嵌套在主评论卡片下,方便跟踪问题讨论与解决进展。 + +--- + +## 附件 + +可以在评论中附加参考文档、设计规范或其他资产: + +- 点击评论输入框内的 **回形针**(Paperclip)图标。 +- 选择要上传的文件。上传后将作为可直接下载的链接显示在评论卡片中。 diff --git a/docs/zh/using-shumai/email-notifications.mdx b/docs/zh/using-shumai/email-notifications.mdx new file mode 100644 index 00000000..8008dc46 --- /dev/null +++ b/docs/zh/using-shumai/email-notifications.mdx @@ -0,0 +1,127 @@ +--- +title: 邮件通知 +description: 配置团队 SMTP 设置,发送聚合活动摘要邮件,并执行测试邮件发送。 +--- + +Shumai 内置邮件通知系统,可将团队动态(如评论、@提及、新资产上传、状态变更以及看板任务更新)直接推送到团队成员的邮箱中。 + +为避免收件箱泛滥及通知疲劳,Shumai 不会针对单次操作即时发送零散邮件。后台投递服务会自动聚合待发送的通知,并定期发送包含内联缩略图与深度链接的批量摘要邮件。 + +--- + +## 配置 SMTP 设置 + +邮件通知由**团队所有者**在团队层级统一管理。 + +发送邮件配置步骤: + +1. 点击侧边栏的 **团队设置**。 +2. 选择 **邮件通知** 标签页。 +3. 开启 **启用邮件通知** 开关。 +4. 填写 SMTP 服务器凭据与发件人信息。 +5. 点击 **保存** 或 **保存并发送测试邮件**。 + +### SMTP 服务器设置 + +| 字段 | 说明 | 示例 / 默认值 | +| :---------------------------- | :--------------------------------------------------------------------------------------------------------------- | :----------------------------------------------- | +| **SMTP Host** | 发送邮件的 SMTP 服务器主机名或 IP 地址。 | `smtp.example.com` 或 `smtp.sendgrid.net` | +| **SMTP Port** | 连接 SMTP 服务器的端口。 | `587`(默认,STARTTLS)、`465`(SSL/TLS)或 `25` | +| **Username** | SMTP 服务器身份验证所需的用户名或 API Key。 | `user@example.com` 或 `apikey` | +| **Password** | 身份验证密码或 API Secret。 | `••••••••` | +| **SSL / TLS (SMTPS)** | 直接使用 SSL/TLS 加密连接。通常在使用端口 `465` 时需要开启。 | `Disabled`(默认禁用) | +| **Ignore Certificate Errors** | 允许使用自签名证书、无效或未验证的 TLS 证书建立连接。适用于本地测试(如 Mailpit、MailHog)或企业内部中继服务器。 | `Disabled`(默认禁用) | + +> [!TIP] +> **密码保留**:修改现有邮件配置时,若无需更改密码,可将密码输入框留空以保留当前存储的密码。出于安全考虑,系统绝不会向客户端明文返回已保存的密码。 + +### 发件人信息 + +| 字段 | 说明 | 示例 / 默认值 | +| :----------- | :------------------------------------------------------------------------------------------- | :----------------------------- | +| **From** | 显示在邮件 `From` 标头中的发件人姓名与邮箱地址。请确保 SMTP 服务商已授权代表此地址发送邮件。 | `Shumai ` | +| **Reply-To** | _(可选)_ 成员直接回复通知邮件时接收回复的邮箱地址。 | `support@example.com` | + +--- + +## 测试 SMTP 投递 + +在正式启用邮件投递前,可直接在设置页面验证配置与凭据: + +1. 点击 **保存并发送测试邮件**。 +2. 在 **发送测试邮件** 弹窗中,核对或调整发件人 `From` 地址。 +3. 点击 **发送测试邮件**。 + +Shumai 将向 SMTP 服务器发起主动握手验证(`transport.verify()`),并向当前登录的管理员邮箱发送一封样式精美的测试邮件。 + +若握手或投递失败(例如密码错误、出站端口受阻或发件人地址被拒),界面将弹出 Toast 提示并显示 SMTP 服务器返回的具体错误信息。 + +--- + +## 投递架构与摘要批量聚合 + +Shumai 采用异步批量架构投递邮件通知: + +``` +[ 团队活动 ] +(评论、上传、@提及、看板) + │ + ▼ +[ 数据库队列 ] (状态: pending) + │ + ▼ (每 3 分钟) +[ 通知后台任务 ] + │ + ├─ 筛选接收者(检查用户偏好与项目范围) + ├─ 排除本人操作与 AI 智能体 + ├─ 分组与折叠条目(超过 3 项自动聚合汇总) + ├─ 拉取头像与缩略图作为内联 CID 附件 + │ + ▼ +[ Nodemailer 传输层 ] ──> SMTP 服务器 ──> [ 成员收件箱 ] +``` + +### 1. 定期后台投递 + +通知在 PostgreSQL 中以 `pending` 状态入队。后台任务每 **3 分钟** 定期运行一次,通过原子队列锁(`FOR UPDATE SKIP LOCKED`)获取待处理通知。即便多实例并发运行,也能确保安全投递且不产生重复邮件。 + +### 2. 摘要汇总打包 + +系统不会在每次操作发生时立即发送邮件,而是在 3 分钟窗口期内收集属于同一接收者的所有通知,并将其合并为单封摘要邮件。这既能保持团队协作沟通条理清晰,又避免了高频协作时的收件箱骚扰。 + +### 3. 智能活动折叠 + +当某个事件集包含大量条目时(例如剪辑师一次性上传数十个视频片段),Shumai 会自动对其分组并折叠: + +- 若分组中包含 **3 项或更少** 条目,则逐项展示各自的缩略图与详细信息。 +- 若一次性上传 **超过 3 项**,Shumai 会将其汇总为单条简明通知(例如:_“Alice 向项目 Project Alpha 上传了 12 个新文件”_),并附带前三个文件名的预览。 + +### 4. 内联 CID 附件 + +系统从存储中提取头像及视频/图片资产缩略图,以 MIME 内联附件(`cid:...`)的形式直接嵌入邮件中。 + +与外部图片链接相比,内联 CID 附件具备以下优势: + +- 在桌面端及移动端邮件客户端(如 Apple Mail、Gmail、Outlook)中可直接显示,不受“显示远程内容”安全警告的阻拦。 +- 无需依赖公开可访问的 S3 URL 或反向代理鉴权即可正常渲染。 + +### 5. 深度链接 + +邮件中的每个通知卡片均包含深度链接操作按钮(如 **查看资产**、**查看项目** 或 **查看任务**),成员点击后可直达 Shumai 中的对应资源。 + +为确保链接跳转至公网域名而非 `localhost`,请在 Shumai 服务器上配置 `APP_URL` 或 `BETTER_AUTH_URL` 环境变量: + +```bash +APP_URL=https://shumai.example.com +``` + +--- + +## 成员偏好与过滤机制 + +邮件投递严格遵循团队权限设定与成员自主偏好: + +- **个人偏好**:团队成员可通过 **团队设置 > 通知** 自主选择接收的活动类型。若用户关闭了某分类(如普通评论或状态更新)的通知,Shumai 不会将该类条目纳入其邮件摘要中。 +- **自身操作过滤**:成员绝不会收到关于自己发布的评论、上传或任务更新的通知邮件(除非显式开启 **您的上传** 偏好,以便在自身媒体转码完成时获取提醒)。 +- **项目范围限制**:权限受限于特定项目的成员,仅会收到其所属项目内的活动邮件摘要,除非他们被显式 `@提及`。 +- **AI 智能体过滤**:系统自动将 AI 智能体账户排除在邮件通知接收人之外。 diff --git a/docs/zh/using-shumai/embedding-server.mdx b/docs/zh/using-shumai/embedding-server.mdx new file mode 100644 index 00000000..1e0493b9 --- /dev/null +++ b/docs/zh/using-shumai/embedding-server.mdx @@ -0,0 +1,131 @@ +--- +title: 向量模型服务部署 (EmbeddingGemma 2) +description: 使用 shumaiOne/embedding-server 本地离线运行多模态向量嵌入,赋能语义搜索。 +--- + +Shumai 支持通过 [shumaiOne/embedding-server](https://github.com/shumaiOne/embedding-server) 在本地私有化部署多模态向量模型服务以赋能语义搜索。该独立 Docker 服务由 Google AI Edge 的 **LiteRT-LM** 与 **EmbeddingGemma 2 740M** 强力驱动。 + +该向量模型服务为文本、图片与视频关键帧提供了统一的 768 维向量空间,并对外暴露兼容 OpenAI 标准的 HTTP API 接口(`/v1/embeddings`)。由于模型权重已预先打包至 Docker 镜像内,该服务完全支持离线和物理隔离(Air-gapped)环境运行,无需访问外网或依赖第三方云厂商 API 密钥。 + +--- + +## 模型架构与规格参数 + +| 属性 | 参数 | +| :------------- | :------------------------------------------------------- | +| **模型** | `EmbeddingGemma 2 740M` (`google/embeddinggemma-2-740m`) | +| **运行环境** | Google AI Edge LiteRT-LM (Python 3.14 Debian slim) | +| **向量维度** | 768 维(多模态:文本、图片及视频) | +| **上下文窗口** | 2,048 tokens | +| **网络模式** | 完全支持离线运行(`--network none`) | +| **API 规范** | 兼容 OpenAI 标准的 `/v1/embeddings` | + +--- + +## 视频处理与抽帧采样 + +针对视频资产,Shumai 会将其切片为标准化分段并提取关键帧: + +- **切片分段(Chunking)**:视频按 **60 秒为一个片段**进行切片,并在相邻片段边界保留 **5 秒重叠区间**,以维持剧情与视觉上下文连贯性。 +- **抽帧频率**:Shumai 从每个分段中抽取 **15 帧/分钟**。 +- **自适应帧数边界(Adaptive Frame Bounding)**: + - 针对标准宽高比视频(1:1、4:3、3:4、16:9、9:16、21:9),Shumai 抽取 15 帧,生成约 1,982 个 Prompt token,安全处于 2,048 token 上下文窗口限制内。 + - 针对非标准或特殊比例视频(如 5:3、1.4:1),Shumai 自动采样 14 帧(约 1,990 token),从数学原理上杜绝 Prompt 长度超过 2,048 token 的可能,防止向量模型服务发生内存溢出(OOM)。 + +--- + +## 重要说明:更换 Embedding 服务商将导致已有向量失效 + +> [!WARNING] +> **不同 Embedding 模型的向量空间完全互不兼容。** +> +> 若更换向量服务提供商(例如从 Google Gemini 的 1536 维向量切换到 EmbeddingGemma 的 768 维向量,反之亦然),**数据库中现存的所有向量嵌入数据将全部失效**。 +> +> 为保护生产数据库免受误操作损坏及搜索失效,**Shumai 刻意未在 Web 界面中提供切换 Embedding 提供商的开关**。该配置仅能由管理员通过环境变量(`EMBEDDING_PROVIDER` 和 `GEMMA_EMBEDDING_OPENAI_BASE_URL`)进行配置。 + +--- + +## 通过 CLI 重新生成向量数据 + +当更换 Embedding 提供商,或在已有 Shumai 生产环境中首次启用向量模型服务时,可通过管理员 CLI 命令为所有现有媒体资产重新生成向量数据: + +### Docker 容器内部执行 + +```bash +docker exec -it shumai regenerate-embeddings +``` + +### 本地 / 裸机环境执行 + +```bash +shumai regenerate-embeddings +``` + +_(或执行 `bun apps/web/src/index.ts regenerate-embeddings`)_ + +### 命令执行流程说明 + +1. **扫描团队**:遍历工作区中的所有团队。若某团队未启用(开启)向量嵌入智能体,则记录警告日志并安全跳过该团队。 +2. **清除旧向量**:清空所有符合条件的资产原有的向量数据,并取消处理中或排队中的向量任务,确保平滑过渡至新模型。 +3. **加入新任务队列**:为各活跃团队下所有符合条件的资产(图片、视频及带有渲染预览的 3D 资产)派发全新的后台 `ai_embedding` 任务。 +4. **后台异步处理**:后台 Worker 按照配置的并发上限逐步处理排队任务。 + +--- + +## 部署与配置 + +### Docker 快速上手 + +运行独立的向量模型服务容器: + +```bash +docker run -d \ + --name shumai_embedding \ + -p 9379:9379 \ + shumaione/embedding-server:latest +``` + +### Docker Compose 配置 + +在 Docker Compose 环境中,将 `embedding-server` 添加到 `docker-compose.yaml` 中,并配置 Shumai 通过 Docker 内部网络进行连接: + +```yaml +services: + embedding-server: + image: shumaione/embedding-server:latest + container_name: shumai_embedding + restart: unless-stopped + + shumai: + image: shumaione/shumai:latest + environment: + # 向量模型服务配置 + EMBEDDING_PROVIDER: gemma-embedding-2-openai + GEMMA_EMBEDDING_OPENAI_BASE_URL: http://embedding-server:9379/v1 + ENABLE_EMBEDDING_AGENT: 'true' + CONCURRENCY_AGENT: 1 + depends_on: + - embedding-server +``` + +> [!NOTE] +> 由于 Shumai 与 `embedding-server` 在 Docker 内部网络中通信,`embedding-server` 无需向宿主机映射暴露端口。 + +### 环境变量 + +| 变量 | 必填 | 说明 | 默认值 | +| :-------------------------------- | :------- | :------------------------------------------------------------------------------------------------ | :------------------------- | +| `EMBEDDING_PROVIDER` | 是 | 设置为 `gemma-embedding-2-openai` 以使用本地 LiteRT-LM 服务。 | `gemini-embedding-2` | +| `GEMMA_EMBEDDING_OPENAI_BASE_URL` | 是 | 向量模型服务的 HTTP 基础地址(例如 `http://embedding-server:9379/v1`)。 | `http://localhost:9379/v1` | +| `ENABLE_EMBEDDING_AGENT` | 否 | 启动时自动为所有团队初始化并启用系统级向量嵌入智能体。 | `false` | +| `CONCURRENCY_AGENT` | 推荐配置 | Worker 执行 AI 任务的最大并发数。运行 `embedding-server` 时**务必设为 `1`**,以防止内存开销过大。 | `5` | + +--- + +## 硬件与资源要求 + +- **内存(RAM)**: + - 建议为 `embedding-server` 容器分配至少 **4 GB+ 的独立物理内存**。 + - 运行 Lite+Embedding Compose 组合时,宿主机系统总内存建议在 **4 GB+** 以上;运行全量服务时建议在 **8 GB+** 以上。 +- **并发控制**: + - 使用 `embedding-server` 时,务必在 Shumai 配置中设置 `CONCURRENCY_AGENT=1`。并行处理多模态向量嵌入会消耗大量内存,在配置较低的机器上可能会触发系统 OOM Killer 强行终止 Docker 容器。 diff --git a/docs/zh/using-shumai/gotenberg.mdx b/docs/zh/using-shumai/gotenberg.mdx new file mode 100644 index 00000000..aca6e25a --- /dev/null +++ b/docs/zh/using-shumai/gotenberg.mdx @@ -0,0 +1,108 @@ +--- +title: 基于 Gotenberg 的文档 PDF 转换 +description: 将 Office 文档、HTML、Markdown、CSV 和 TXT 文件转换为高保真 PDF 代理文件,实现浏览器内顺畅预览。 +--- + +浏览器无法原生直接渲染 Office 文档、HTML 页面、Markdown 文件、表格以及纯文本文件。Shumai 采用基于 Docker 的开源转换服务 [Gotenberg](https://gotenberg.dev),将这些文件转为高保真 PDF 代理资产,以便在浏览器中无缝预览。 + +Gotenberg 采用以下组件完成文档转换: + +- **LibreOffice**:负责处理 Office 文档、电子表格与纯文本。 +- **无头 Chromium(Headless Chromium)**:负责渲染 HTML 与 Markdown 文件。 + +--- + +## 支持的文件类型 + +配置 Gotenberg 后,Shumai 会自动为以下格式的文件生成 PDF 预览代理: + +| 类别 | 扩展名 | 转换引擎 | +| :------------------ | :--------------------- | :---------- | +| Word 文档 | `.doc`, `.docx` | LibreOffice | +| Excel 表格 | `.xls`, `.xlsx` | LibreOffice | +| PowerPoint 幻灯片 | `.ppt`, `.pptx` | LibreOffice | +| OpenDocument | `.odt`, `.ods`, `.odp` | LibreOffice | +| 富文本(Rich Text) | `.rtf` | LibreOffice | +| HTML | `.html`, `.htm` | Chromium | +| Markdown | `.md`, `.markdown` | Chromium | +| 电子表格 / CSV | `.csv` | LibreOffice | +| 纯文本 | `.txt` | LibreOffice | + +--- + +## 配置说明 + +Shumai 支持通过 **Web 界面**或**环境变量**配置 Gotenberg。 + +### 1. Web 界面配置(团队设置 → 集成) + +团队所有者可直接在 Web 界面中配置 Gotenberg: + +1. 在侧边栏导航至**团队设置**。 +2. 切换至**集成**选项卡。 +3. 在 **Gotenberg 文档转换器**下,输入**服务器地址(Server URL)**(例如 `http://gotenberg:3000` 或 `http://localhost:3000`)。 +4. 若服务启用了 Basic 基础认证,请输入**用户名**与**密码**。 +5. 点击**测试连接**,验证与 Gotenberg 的通信状态并确认服务健康状况。 +6. 点击**保存更改**。 + +### 2. 环境变量配置 + +也可以在运行 Shumai 或转码 Worker 的机器上通过环境变量进行全局配置: + +| 变量 | 必填 | 说明 | +| :------------------------------ | :--------------- | :----------------------------------------------------- | +| `GOTENBERG_URL` | 是(启用时必填) | Gotenberg 基础服务地址,例如 `http://gotenberg:3000`。 | +| `GOTENBERG_BASIC_AUTH_USERNAME` | 否 | Gotenberg 开启 Basic 基础认证时的用户名。 | +| `GOTENBERG_BASIC_AUTH_PASSWORD` | 否 | Gotenberg 开启 Basic 基础认证时的密码。 | + +### 配置优先级与只读模式 + +> [!IMPORTANT] +> **环境变量优先级最高。** 一旦在运行环境中配置了 `GOTENBERG_URL`,Shumai 将始终优先采用环境变量中的配置。 +> +> 通过环境变量配置后,**团队设置 → 集成**中的对应设置项将显示**已通过环境变量配置(只读)**徽标,且输入框将被锁定,防止误操作或配置不一致。 + +--- + +## 部署 Gotenberg + +### Docker 快速上手 + +只需一条命令即可启动 Gotenberg 容器: + +```bash +docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8 +``` + +若需开启 Basic 基础认证: + +```bash +docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8 gotenberg --gotenberg-basic-auth-username=admin --gotenberg-basic-auth-password=secret +``` + +### Docker Compose 配置 + +在 `docker-compose.yaml` 中添加 Gotenberg 服务: + +```yaml +gotenberg: + image: gotenberg/gotenberg:8 + restart: unless-stopped + ports: + - '3000:3000' +``` + +随后在 Shumai 中配置指向该服务: + +```bash +GOTENBERG_URL=http://localhost:3000 +``` + +--- + +## 未配置 Gotenberg 时的降级表现 + +若未配置 Gotenberg 或服务无法连通,Shumai 会优雅降级: + +- **Office 文档与 HTML**:文件上传正常完成并标记为 `processed`,但不生成 PDF 代理文件。 +- **CSV、Markdown 与 TXT**:改由内置的轻量 PDF 生成器生成预览代理(排版保真度略低)。 diff --git a/docs/zh/using-shumai/image-video-generation.mdx b/docs/zh/using-shumai/image-video-generation.mdx new file mode 100644 index 00000000..36f0be89 --- /dev/null +++ b/docs/zh/using-shumai/image-video-generation.mdx @@ -0,0 +1,140 @@ +--- +title: 图像与视频生成 +description: 为内置 AI 智能体工具配置图像与视频生成服务商及模型。 +--- + +Shumai 智能体可通过内置工具——**生成图像**(`generate_image`)与**生成视频**(`generate_video`),在工作区中直接生成创意视觉资产。 + +生成视觉媒体资产需要专用的多模态基座模型支持。智能体调用这些能力前,团队所有者必须先在团队设置中配置上游服务商并启用对应模型。 + +> 🔒 **权限说明:** 仅**团队所有者(Team Owner)**拥有查看与配置媒体生成设置的权限。请点击头像进入**设置**,在左侧导航栏选择**图像/视频生成**(或直接访问 `teams//settings#image-video`)。 + +--- + +## 为何需要此项配置 + +在 **AI 服务商**中配置的对话类模型主要负责文本推理与对话交互;而图像与视频生成则依赖专用的多模态生成模型(如 DALL-E、FLUX、Gemini Image、Veo、可灵 Kling AI、Luma Ray、万象 Wan 等)。 + +**图像/视频生成**配置页面支持团队所有者: + +1. 接入并认证一个或多个受支持的图像与视频生成服务商。 +2. 选择为团队启用精选推荐模型,或注册自定义模型 ID。 +3. 设定智能体生成视觉资产时的默认模型。 + +--- + +## 工具可用性与激活规则 + + + **重要提示:** 仅在智能体配置弹窗中勾选 `generate_image` 或 `generate_video` + 还**远远不够**。只有同时满足以下三项条件,智能体才能真正调用该工具: + + +1. **服务商已配置:** 对应服务商已配置有效 API 密钥(通过服务端环境变量注入,或在团队设置中配置了自定义团队密钥)。 +2. **至少启用了一个模型:** 在已激活的服务商下,对应模态(`image` 或 `video`)**至少启用了一个模型**。 +3. **已向智能体开放工具权限:** 在**团队设置** > **智能体** > **工具**权限列表中,该工具未被禁用。 + +### 未配置模型时的系统行为 + +若已配置的服务商下未启用任何图像模型,`generate_image` 工具将从智能体的运行时环境中**彻底移除**。同理,若未启用任何视频模型,`generate_video` 工具亦会被移除。 + +在此状态下: + +- 智能体**无法调用**该生成工具。 +- 该工具不会出现在智能体的工具目录或 Prompt 提示词定义中。 +- 即便团队所有者在智能体设置弹窗中开启了**生成图像**或**生成视频**开关,只要未启用模型,智能体仍旧无法使用该工具。 + +--- + +## 支持的服务商 + +Shumai 内置支持 18 家媒体生成服务商: + +| 服务商 | 支持模态 | 默认环境变量 | +| :-------------------- | :--------- | :--------------------- | +| **OpenAI** | 图像 | `OPENAI_API_KEY` | +| **Google** | 图像, 视频 | `GEMINI_API_KEY` | +| **Google Vertex AI** | 图像, 视频 | `GOOGLE_CLOUD_API_KEY` | +| **xAI** | 图像, 视频 | `XAI_API_KEY` | +| **Fal** | 图像, 视频 | `FAL_KEY` | +| **Replicate** | 图像, 视频 | `REPLICATE_API_TOKEN` | +| **Black Forest Labs** | 图像, 视频 | `BFL_API_KEY` | +| **Kling AI** | 视频 | `KLINGAI_API_KEY` | +| **Together AI** | 图像 | `TOGETHER_API_KEY` | +| **Fireworks AI** | 图像 | `FIREWORKS_API_KEY` | +| **DeepInfra** | 图像 | `DEEPINFRA_API_KEY` | +| **Luma** | 图像 | `LUMA_API_KEY` | +| **Amazon Bedrock** | 图像 | `AWS_ACCESS_KEY_ID` | +| **Alibaba** | 视频 | `ALIBABA_API_KEY` | +| **ByteDance** | 图像, 视频 | `ARK_API_KEY` | +| **MiniMax** | 视频 | `MINIMAX_API_KEY` | +| **Prodia** | 图像, 视频 | `PRODIA_TOKEN` | +| **Azure OpenAI** | 图像 | `AZURE_API_KEY` | + +--- + +## 配置服务商与 API 密钥 + +在**媒体服务商**列表中点击任意服务商,即可打开其配置弹窗: + +### 服务商状态说明 + +- **已配置 (自定义)**:在此弹窗中填入了团队专属的 API 密钥或自定义环境变量名。 +- **已配置 (环境变量)**:系统检测到了服务端配置的默认环境变量(如 `OPENAI_API_KEY`)。除非需要覆盖该默认值,否则无需另行配置团队密钥。 +- **未配置**:未检测到可用 API 密钥。使用此服务商前必须提供 API 密钥或环境变量名。 + +### 覆盖 API 密钥 + +在服务商弹窗的 **API Key** 标签页中: + +- 输入 API 密钥明文(如 `sk-...`),或填入宿主机系统中已定义的环境变量名称。 +- 点击**清除自定义密钥**,即可恢复使用服务端默认环境变量(若存在)。 + +--- + +## 管理模型 + +在服务商配置弹窗的 **Models** 标签页中: + +### 精选模型 + +Shumai 预置了主流的精选推荐模型(如 `dall-e-3`、`fal-ai/flux/dev`、`veo-3.1-generate`、`kling-v3.0-t2v` 等)。切换模型旁边的开关,即可为团队启用或禁用该模型。 + +### 自定义模型 + +若服务商上线了新模型或支持微调模型,且未收录在精选列表中: + +1. 选择模态(**图像**或**视频**)。 +2. 输入上游服务商所要求的准确 **Model ID**。 +3. 点击**添加**。 + +### 默认模型选择机制 + +每种类型(`image` 或 `video`)中**首个启用的模型**将自动成为默认模型。当智能体调用 `generate_image` 或 `generate_video` 且未显式指定 `model` 参数时,Shumai 会自动将生成请求路由至该默认模型。 + +--- + +## 智能体如何使用生成工具 + +启用之后,智能体便可在对话或自动化工作流中调用相关工具: + +### 1. 生成图像 (`generate_image`) + +- **提示词(Prompt):** 图像的详细文本描述。 +- **模型选择:** 默认使用首个已启用的图像模型;智能体亦可按 `provider:modelId` 格式(如 `openai:dall-e-3` 或 `fal:fal-ai/flux/dev`)选用任意已启用模型。 +- **参考图输入:** 智能体可通过 `read_asset` 工具获取工作区已有资产的 S3 存储键(`s3KeyOnly: true`),并将其作为画面风格或构图参考。 +- **局部重绘(Inpainting):** 支持传入 S3 蒙版键,实现基于遮罩的局部精准重绘。 +- **控制参数:** 支持自定义宽高比(`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`)、分辨率尺寸及随机种子(Seed)。 + +### 2. 生成视频 (`generate_video`) + +- **生成模式:** + - `text_to_video`:根据动态文本提示词生成视频片段。 + - `image_to_video`:将工作区已有静态图片转化为动态视频。 + - `first_last_frame`:在首尾两帧资产之间生成流畅自然的过渡插帧。 + - `reference_to_video`:基于参考图生成视频,保持角色形象或场景环境的一致性。 +- **控制参数:** 支持设置宽高比(`16:9`、`9:16`、`1:1`、`adaptive`)、分辨率、时长、帧率(FPS)以及音效生成开关。 + +### 资产生成入库流程 + +所有生成的媒体文件起初均保存在本地沙箱目录(`.pi/`)中。随后,智能体可调用**创建文件**(`create_file`)将生成结果作为新资产上传至项目中,或调用**创建版本**(`create_version`)将其追加至已有资产的版本历史中。 diff --git a/docs/zh/using-shumai/mcp-servers.mdx b/docs/zh/using-shumai/mcp-servers.mdx new file mode 100644 index 00000000..0735e2f3 --- /dev/null +++ b/docs/zh/using-shumai/mcp-servers.mdx @@ -0,0 +1,115 @@ +--- +title: MCP 服务端 +description: 通过模型上下文协议(Model Context Protocol)将智能体连接至外部工具与 API。 +--- + +模型上下文协议(Model Context Protocol,简称 MCP)是一套开放标准,支持 AI 模型安全对接外部工具、微服务与 API。在 Shumai 中,可通过标准 HTTP 传输协议(`Streamable HTTP` 或 `SSE`)注册远程 MCP 服务端,并将其分配给 AI 智能体。 + +--- + +## Shumai 中的 MCP 运作机制 + +为避免动辄数十个复杂的参数 Schema 挤占模型的上下文窗口,Shumai 采用了高能效的 MCP 连接架构: + +- **自动发现与元数据缓存**:添加 MCP 服务端后,Shumai 会将其记录在团队配置中,并连接该端点以自动发现可用工具、服务端使用指引与描述元数据。在手动刷新服务端、完成 OAuth 鉴权或智能体首次调用其工具时,系统均会触发服务发现。这些 Schema 会缓存在数据库中,供后续秒级读取。 +- **高上下文利用率的代理工具 (`mcp`)**:已分配的 MCP 服务端会通过注入对话智能体中的统一 `mcp` 代理工具实现多路复用。智能体可按需动态检查服务状态、检索工具、查看参数 Schema 并调用函数,无需预先消耗大量 LLM Token。 +- **直连工具选项 (Direct Tools)**:对于高频调用的核心工具,可将其单独配置为**直连工具**,使其作为顶层 LLM 原生函数直接暴露给智能体,与 `mcp` 代理工具并行共存。 + +--- + +## 添加 MCP 服务端 + +在 Shumai 中注册新 MCP 服务端的步骤如下: + +1. 前往**团队设置**并点击 **MCP** 标签页。 +2. 点击**添加 MCP 服务端**。 +3. 在弹窗中输入**服务端端点 URL**(例如 `https://mcp.example.com/sse` 或 `http://localhost:8080/mcp`)。 +4. 点击**创建**。 + +> **注意:** 仅需提供**服务端端点 URL** 即可创建。Shumai 会根据 URL 自动生成占位服务名;当首次连接端点(通过编辑弹窗中的“刷新”按钮或智能体首次发起工具调用)时,系统会自动同步服务端的真实名称、运行状态、操作指引以及工具清单。 + +### 可选高级配置项 + +创建服务端后(初始弹窗仅需填入 URL),可打开编辑弹窗配置高级选项: + +- **传输协议(Transport)**:在 `Streamable HTTP`(默认)与 `Server-Sent Events (SSE)` 之间选择。 +- **认证策略(Auth Strategy)**:可选 `Auto-detect`(自动检测,默认)、`None`(无认证)、`Bearer Token` 或 `OAuth 2.0`。 +- **最低权限角色(Minimum Permission Role)**:设置调用该服务端工具所需的最低团队角色要求(`Reviewer` 审阅者、`Editor` 编辑者或 `Owner` 所有者)。 +- **直连工具(Direct Tools)**:指定需作为原生 LLM 工具直接呈现给智能体的工具名称列表。 + +--- + +## 理解工具配置机制 + +在服务端的编辑弹窗中,**工具(Tools)**列表展示了所有已发现的工具,每个工具均支持三态切换(同时提供**全部关闭** / **全部代理** / **全部直连**批量操作): + +- **关闭(Off)**:彻底排除该工具,对智能体完全不可见——既无法通过代理工具列出、搜索或调用,也无法注册为直连工具。适用于隐藏干扰项或高危工具。 +- **代理(Proxy,默认)**:工具通过统合的 `mcp` 代理工具按需调用。 +- **直连(Direct)**:工具以 `{server}_{tool}` 为前缀名称,作为顶层原生函数直接开放给智能体。 + +### `mcp` 代理工具 + +`mcp` 代理工具是注入智能体上下文的一个独立函数,它多路复用了分配给该智能体的所有 MCP 服务端。智能体无需在启动时一次性加载所有工具的完整参数 Schema,而是根据实际需要与服务端交互: + +- `mcp({})` — 查看所有已分配服务端的连接与认证状态 +- `mcp({ server: "name" })` — 列出指定服务端的可用工具 +- `mcp({ search: "query" })` — 跨服务端检索工具(默认附带参数 Schema) +- `mcp({ describe: "tool" })` — 检视指定工具的完整参数 Schema +- `mcp({ instructions: "name" })` — 查看指定服务端的使用指引 +- `mcp({ server: "name", tool: "tool_name", args: {...} })` — 调用工具(支持传入 `{server}_{tool}` 前缀名称或工具原名) +- `mcp({ action: "auth-start", server: "name" })` — 为指定服务端发起 OAuth 认证流程 + +由于上下文窗口仅被单个紧凑的工具(外加简短的服务端/工具列表)占用,即便服务端暴露数十个工具,代理模式依然能将 Token 开销降至极低。相应的权衡在于增加了一轮服务发现交互:智能体通常需要先列出或检索工具,随后再发起调用。 + +### 直连工具 (Direct Tools) + +直连工具则采用了另一种权衡取舍。被设为**直连(Direct)**的工具会被注册为原生顶层函数(如 `tavily_mcp_tavily_search`),智能体能够像调用内置工具一样直接使用它。 + +直连工具的优势: + +- **高频操作调用更快、更稳定**:完整的参数 Schema 始终驻留在上下文窗口中,智能体无需先通过代理发现,一步即可直接调用。 +- **工具感知度更高**:模型能够预先感知工具功能及其描述,更容易在恰当时机自主选用该工具。 + +开销代价:每个直连工具的 Schema 都会常驻并消耗上下文 Token,因此建议仅将高频或关键工具设为**直连**,将接口繁多的庞大 MCP 服务端保持为**代理**模式以节省上下文。直连工具同样遵循基于角色的权限校验规则,且 `mcp` 代理工具仍可继续用于服务发现、鉴权与状态检查。 + +--- + +## 身份认证模式 + +Shumai 支持多种认证策略以保障 MCP 端点的安全访问: + +### 1. 无认证 (`none`) + +用于公开或本地运行且无需认证凭据的 MCP 服务端。 + +### 2. Bearer Token (`bearer`) + +提供静态 API Token 或密钥。Shumai 会在所有传输请求的 `Authorization: Bearer ` 请求头中附带该令牌。 + +### 3. OAuth 2.0 (`oauth`) + +面向受 OAuth 身份提供商保护的 MCP 端点: + +- **授权码模式 + PKCE(Authorization Code + PKCE)**:在团队设置的服务端卡片上点击**连接**。Shumai 会弹出安全的 OAuth 授权窗口并跳转至身份提供商页面。确认授权后,浏览器会自动回调至 Shumai,完成令牌兑换并刷新服务端工具列表。 +- **客户端凭据模式(Client Credentials)**:填入 `Client ID` 与 `Client Secret`,用于自动化服务间令牌获取。 + +--- + +## 为智能体分配 MCP 服务端 + +默认情况下,新添加的 MCP 服务端**未分配给任何智能体**。若需授权智能体访问 MCP 服务端: + +1. 前往**团队设置** > **智能体**。 +2. 点击目标智能体打开配置弹窗。 +3. 向下滚动至 **MCP 服务端**区域。 +4. 勾选希望授权给该智能体的 MCP 服务端开关。 +5. 点击**保存修改**。 + +--- + +## 基于角色的访问控制 (RBAC) + +每个 MCP 服务端均支持设置**最低权限角色**(`Reviewer` 审阅者、`Editor` 编辑者或 `Owner` 所有者): + +- 当智能体尝试调用 MCP 服务端上的工具时,Shumai 会校验当前与智能体交互的用户角色。 +- 若用户角色未达到设定的最低门槛,工具执行将被拦截并返回权限不足的错误信息,杜绝越权操作。 diff --git a/docs/zh/using-shumai/metadata.mdx b/docs/zh/using-shumai/metadata.mdx new file mode 100644 index 00000000..13317d60 --- /dev/null +++ b/docs/zh/using-shumai/metadata.mdx @@ -0,0 +1,70 @@ +--- +title: 资产元数据 +description: 通过动态作用域元数据字段与 AI 自动填充能力,按需定制媒体资产属性。 +--- + +传统文件系统通常仅支持文件名、修改日期等基础属性。Shumai 支持构建贴合创意工作流的结构化元数据字段——涵盖审核状态跟踪以及技术参数自动捕获。 + +--- + +## 元数据作用域 + +侧边栏检查器按字段作用域分组显示: + +- **基础属性(系统作用域)**:Shumai 内置的核心字段,适用于所有团队与项目。其中许多参数(如分辨率、时长和编解码器)会在文件上传时自动提取。 +- **团队属性(团队作用域)**:在团队层级定义的自定义字段,由该团队下的所有项目继承。非常适合用于贯彻团队或企业级的元数据规范。 +- **自定义字段(项目作用域)**:专为单个项目工作区定义的独特元数据字段。 + +--- + +## 自定义字段类型 + +在构建或编辑元数据规范时,可选择以下自定义字段类型: + +- **文本**:单行文本输入框,用于简短字符串、代码编号或标签。 +- **长文本**:多行文本输入区,用于详细描述、摘要或备忘备注。 +- **下拉单选**:单选下拉菜单,支持为各选项配置背景颜色(例如“已通过”设为绿色,“处理中”设为黄色)。 +- **标签(多选)**:多选标签字段,支持为单个资产添加多个带有自定义颜色的标签。 +- **星级评分**:交互式星级评分组件(支持 2 至 6 星配置),用于评审打分与评级。 +- **数值**:数值字段,支持自定义小数位数(0 至 3 位小数),适用于帧率、计数或评分等数值。 +- **开关选框**:布尔开关(例如“需视效制作”)。 +- **日期**:日期选择器,支持自定义显示格式(本地格式、ISO、美式、欧式、友好易读格式)并支持记录时间。 +- **单成员**:单选用户字段,动态获取团队成员列表并展示其姓名和头像。 +- **多成员**:多选用户字段,动态获取团队成员列表,支持指派多个团队成员。 + +![资产元数据字段](/metafields.webp) + +--- + +## 默认内置字段 + +每个项目均预置了若干核心字段,并在文件上传或状态变更时自动填充: + +- **技术规格**:文件大小、格式、文件类型(视频、音频、图片、文档、文件)、分辨率宽/高、视频/音频编解码器、时长、帧率及音频采样率。 +- **协作字段**: + - **状态**:下拉单选字段,包含“需审核”(红色)、“处理中”(黄色)和“已通过”(绿色)。 + - **评分**:5 星评分体系,用于快速评审打分。 + - **关键词**:标签(多选)字段,用于分类资产。 + +--- + +## 字段设置与控制 + +### 只读字段 + +将自定义字段标记为**只读**可防止团队成员直接修改其数值。该功能非常适合通过程序或自动化集成填充的数据字段。 + +### AI 自动填充 + +在元数据字段上启用 **AI 自动填充**后,Shumai 会使用团队默认配置的 Gemini AI 模型自动分析上传的资产,并将提取的分析结果填入该字段: + +- 文本/长文本:AI 自动生成摘要、描述或镜头记录日志。 +- 单选/多选:AI 自动归类主题或打上匹配的标签。 +- 数值:AI 可输出置信度评分或其他指标。 + +### 可见性与排序 + +在元数据检查器中: + +- **可见性**:开启或关闭字段显示,保持侧边栏清爽,仅聚焦当前审核流程所需的内容。 +- **排序**:在字段设计器中拖拽字段,自由调整自定义字段区域的展示顺序。 diff --git a/docs/zh/using-shumai/nle-and-premiere.mdx b/docs/zh/using-shumai/nle-and-premiere.mdx new file mode 100644 index 00000000..5aa34da7 --- /dev/null +++ b/docs/zh/using-shumai/nle-and-premiere.mdx @@ -0,0 +1,126 @@ +--- +title: 非线性编辑 (NLE) 导出与 Premiere Pro 插件 +description: 将带时间戳的评审评论导出为常用 NLE 格式,或使用原生 Premiere Pro UXP 插件导入媒体资产并自动同步时间线标记。 +--- + +Shumai 可直接融入视频剪辑工作流。用户既能在 Web 界面中将评审意见导出为行业标准的非线性编辑系统 (NLE) 标记格式,也能通过原生 Adobe Premiere Pro UXP 插件直接导入媒体资产,并将评审评论实时同步至时间线标记。 + +--- + +## 导出评论至非线性编辑系统 (NLE) + +在音视频评审中添加的评论,可直接从 Web 界面导出至外部剪辑软件。 + +### 评论导出步骤 + +1. 在 Shumai 媒体播放器中打开任意音视频资产。 +2. 在右侧边栏中切换至**评论**选项卡。 +3. 点击**所有评论**旁边的**更多操作**(`...`)菜单。 +4. 悬停在**导出评论**上,选择对应的剪辑软件格式: + +| 格式 | 文件扩展名 | 目标软件 | +| :----------------- | :--------- | :--------------------------- | +| **Premiere Pro** | `.xml` | Adobe Premiere Pro 序列标记 | +| **Resolve** | `.edl` | DaVinci Resolve 时间线标记 | +| **FCP 10.4.0+** | `.fiojson` | Apple Final Cut Pro 标记数据 | +| **Media Composer** | `.xml` | Avid Media Composer 标记 | + +下载完成后,将标记文件导入剪辑软件,即可把所有评审批注和时间戳直接叠加到时间线上。 + +--- + +## Premiere Pro UXP 插件(实验性) + +Shumai 官方 Premiere Pro UXP 插件在 Adobe Premiere Pro 内提供了原生工作面板,剪辑师可直接浏览工作区资产、将原素材或代理媒体导入项目素材箱,并自动将评审评论同步为序列时间线标记。 + +> [!NOTE] +> **实验性功能:** +> Premiere Pro UXP 插件当前处于实验阶段。功能虽然完整,但尚未覆盖所有 Premiere Pro 小版本与操作系统环境。若遇到 Bug、异常表现或有工作流建议,欢迎在 [GitHub 提交 Issue](https://github.com/shumaiOne/shumai/issues) 或加入我们的 [Discord 社区](https://discord.gg/sUzhujK6DD) 反馈交流。 + +### 最低版本要求 + +| 软件 | 最低版本要求 | +| :--------------------- | :---------------------------------------------- | +| **Adobe Premiere Pro** | **`25.1.0`** 或更高(Premiere Pro 2025 v25.1+) | +| **Shumai 服务端** | **`0.4.6`** 或更高 | + +--- + +### 安装指南 + +支持通过 `.ccx` 打包安装程序或 Adobe UXP Developer Tools 安装 Shumai Premiere Pro 插件。 + +#### 方式一:通过 Creative Cloud (.ccx) 安装 + +推荐普通用户使用此方式,安装最便捷。 + +> [!IMPORTANT] +> **前置条件:** +> +> - 系统需预先安装 **Adobe Premiere Pro**(v25.1.0+)以及 **Adobe Creative Cloud 桌面应用程序**。 +> - Adobe Premiere Pro 必须在 Creative Cloud 桌面应用的“已安装应用程序”列表中正常识别显示。 + +1. 从代码仓库下载预构建的插件安装包 [`shumai-premiere.ccx`](https://github.com/shumaiOne/shumai/raw/main/apps/premiere-uxp/shumai-premiere.ccx)(位于源码路径 `apps/premiere-uxp/shumai-premiere.ccx`)。 +2. 双击下载的 `.ccx` 文件,或直接将其拖入 **Adobe Creative Cloud** 桌面应用。 +3. 按照 Creative Cloud 弹窗提示确认并完成安装。 +4. 启动或重启 Adobe Premiere Pro。 + +#### 方式二:通过 Adobe UXP Developer Tools (UDT) 安装 + +此方式适用于开发者或需要从源码构建的用户。 + +> [!NOTE] +> 关于 UXP Developer Tool (UDT) 的安装与配置细节,请参阅官方 [Adobe UXP Developer Tools 文档](https://developer.adobe.com/premiere-pro/uxp/getting-started/quickstart/)。 + +1. 克隆 Shumai 仓库: + ```bash + git clone https://github.com/shumaiOne/shumai.git + cd shumai + ``` +2. 安装依赖并构建 UXP 插件: + ```bash + bun install + bun run --filter @shumai/premiere-uxp build + ``` +3. 打开 **Adobe UXP Developer Tool** (UDT)。 +4. 点击 **Add Plugin** 并选中如下路径的清单文件: + ```text + apps/premiere-uxp/dist/manifest.json + ``` + _(若处于监听开发模式,则选择 `apps/premiere-uxp/public/manifest.json`)。_ +5. 启动 Adobe Premiere Pro。在 UDT 应用列表中找到 Shumai 插件,点击右侧 `•••` 菜单,选择 **Load**(或 **Load & Watch**)。 + +--- + +### 连接 Shumai 服务器 + +1. 在 Premiere Pro 中,依次点击**窗口** > **扩展** > **Shumai**(或**窗口** > **Shumai**)打开插件面板。 +2. 输入连接凭据: + - **服务端地址(Endpoint URL):** Shumai 服务器地址(例如 `http://localhost:3000` 或 `https://shumai.yourdomain.com`)。 + - **API Key:** 在 Shumai 中生成的有效 API 密钥。生成方法:在浏览器中打开 Shumai,进入**团队设置** > **开发者指南**,生成新的 API 密钥。 +3. 点击**连接**。连接成功后,凭据将保存在 Premiere Pro 本地配置中。 + +--- + +### Shumai UXP 插件核心功能 + +该插件在 Premiere Pro 中深度集成了两大核心工作流: + +#### 1. 浏览并导入资产至 Premiere Pro + +- **浏览与检索**:通过面包屑导航与即时搜索,便捷浏览 Shumai 项目、文件夹与媒体资产。 +- **按需选择下载画质**:点击任意资产上的**导入**,可自由选择: + - **原始素材(Raw)**:下载并导入完整的原始高码率母版媒体文件。 + - **视频代理(Proxy)**:下载并导入经转码优化的代理文件(如 1080p、720p、540p 或 360p MP4),剪辑播放更流畅轻快。 +- **原生目录选择**:调起系统原生文件夹选择弹窗,自主决定媒体文件在本地磁盘中的保存位置。 +- **自动导入素材箱**:文件保存到本地后,自动导入当前 Premiere Pro 活动项目的素材箱。 + +#### 2. 自动同步评论至序列标记 + +- **关联序列**:在插件文件列表中,点击任意视频资产的**关联序列**,即可将其与当前处于活动状态的时间线序列建立绑定。 +- **自动生成标记**:插件立即拉取 Shumai 中的已有评论,转换为 Premiere Pro 原生序列标记: + - **精准时间戳**:带有指定时间码的评论将精确定位在对应的帧;无时间戳的全局评论则放置在序列起始位置(`00:00:00:00`)。 + - **作者与内容**:标记名称显示评论者姓名,标记附注完整包含评论正文及层级回复内容。 + - **后台持续同步**:插件在后台自动轮询同步(每 12 秒),且在面板获得焦点或切换序列时立即触发同步。 + - **序列管理面板**:随时切换至**序列**选项卡,查看项目中所有已关联的序列、上次同步时间,支持手动即时同步或解除关联。 + - **干净解绑**:当解除资产与序列的关联时,Shumai 会精准清理其自动生成的标记,绝不影响项目中原有的其他标记。 diff --git a/docs/zh/using-shumai/notifications.mdx b/docs/zh/using-shumai/notifications.mdx new file mode 100644 index 00000000..6bef2729 --- /dev/null +++ b/docs/zh/using-shumai/notifications.mdx @@ -0,0 +1,54 @@ +--- +title: 通知中心 +description: 随时掌握评论动态、文件上传与项目最新进展。 +--- + +Shumai 内置了完善的通知系统,便于随时掌握团队动态、文件处理状态以及审阅反馈。用户可以自由定制各类事件的通知规则、在通知收件箱中查收更新,或针对特定项目单独开启/关闭通知。 + +--- + +## 通知设置 + +针对不同团队,用户可自定义个性化的通知偏好,避免干扰: + +1. 点击侧边栏中的 **团队设置**(Team Settings)。 +2. 选择 **通知**(Notifications)标签页。 +3. 切换开关以启用或禁用特定事件的通知: + +### 评论与回复 + +- **常规评论**:当有人对我参与协作的资产发表评论时发送通知。 +- **评论回复**:当有人回复我的评论会话时发送通知。 +- **@提及**:当有人在任意评论中通过 `@用户名` 提及我时发送通知。 + +### 资产与状态 + +- **本人上传**:当我上传的文件完成媒体转码并可供审阅时发送通知。 +- **他人上传**:当其他团队成员上传新资产时发送通知。 +- **状态更新**:当有人更改资产状态时发送通知(例如从“进行中”变更为“已批准”)。 + +--- + +## 项目级通知 + +若需彻底静音某个特定项目(直接 `@提及` 除外,此类通知始终会投递): + +1. 进入 **项目** 控制台。 +2. 打开 **项目设置**。 +3. 开启或关闭 **启用通知** 开关。 + +--- + +## 通知收件箱 + +- 当有未读通知时,导航栏中的 **铃铛** 图标会显示红色标记。 +- 点击铃铛图标即可打开通知动态面板。 +- 点击任意通知卡片即可将其标记为已读,并直接跳转至对应的文件与评论会话。 + +--- + +## 邮件通知 + +除应用内通知外,团队所有者还可配置 SMTP 发信服务,向团队成员定时投递批量活动摘要邮件。邮件投递引擎会严格遵循上述各成员单独配置的通知偏好。 + +详见 [邮件通知指南](/zh/using-shumai/email-notifications) 获取完整的 SMTP 配置说明、测试邮件发送流程及投递架构详情。 diff --git a/docs/zh/using-shumai/password-reset.mdx b/docs/zh/using-shumai/password-reset.mdx new file mode 100644 index 00000000..e4fcb839 --- /dev/null +++ b/docs/zh/using-shumai/password-reset.mdx @@ -0,0 +1,60 @@ +--- +title: 密码重置 +description: 管理员如何为团队成员生成安全的密码重置链接。 +--- + +考虑到标准私有化部署下 Shumai 并未强制要求配置外部邮件服务(SMTP),密码重置操作由管理员通过 Shumai CLI 安全发起。 + +--- + +## 概述 + +当用户遗忘密码时,管理员可直接在命令行中为其生成一次性密码重置链接。 + +- **链接有效期**:生成的密码重置链接有效期为 **1 小时**(`3600 秒`)。 +- **一次性使用**:重置令牌一经使用即刻永久失效。 +- **会话注销**:用户重置密码后,该账户在所有设备上的所有现有活跃会话均会自动注销。 +- **最新链接有效原则**:为同一用户生成新的重置链接后,此前生成的所有待处理链接立即失效。 + +--- + +## 生成密码重置链接 + +### 在本地宿主机 / 服务器运行 + +在 Shumai 安装目录下运行 `reset-password` 子命令: + +```bash +shumai reset-password +``` + +_(或执行 `bun apps/web/src/index.ts reset-password `)_ + +**输出示例:** + +```text +http://localhost:3000/reset-password?token=bb3xg4uO3cwN0FQv4cgUK6Hh +``` + +### 在 Docker 容器内运行 + +若 Shumai 运行在 Docker 容器中,请使用 `docker exec` 执行命令: + +```bash +docker exec -it shumai reset-password +``` + +> [!TIP] +> 系统同时支持 `shumai` 与常见易错拼写别名 `shuami`(例如 `shuami reset-password `)。 + +> [!NOTE] +> 对于远程服务器或生产环境部署,请确保环境中已配置 `BETTER_AUTH_URL`(例如 `BETTER_AUTH_URL=https://shumai.example.com`),以便 CLI 生成带有公网域名的重置链接,而非 `localhost`。 + +--- + +## 成员重置流程 + +1. 管理员通过安全的沟通渠道将生成的 URL 发送给团队成员。 +2. 用户在浏览器中打开该链接。 +3. 用户输入 **新密码** 并 **确认密码**(长度至少 3 个字符)。 +4. 点击 **重置密码** 后,密码即安全更新,所有旧的活跃会话全部失效,并跳转至 `/login` 页面重新登录。 diff --git a/docs/zh/using-shumai/quotas-settings.mdx b/docs/zh/using-shumai/quotas-settings.mdx new file mode 100644 index 00000000..e1fb1554 --- /dev/null +++ b/docs/zh/using-shumai/quotas-settings.mdx @@ -0,0 +1,121 @@ +--- +title: 资源配额 +description: 配置团队资源配额、实时监控用量并在仪表板中重置配额周期。 +--- + +AI 工作流与媒体处理工具会消耗大量算力与 API 额度。Shumai 提供了**资源配额**(Resource Quotas)体系,使团队所有者能够设置精细化的用量限制、管控成本预算,并实时监控团队成员与角色的用量情况。 + +--- + +## 概述 + +资源配额支持在指定的时间窗口(如每小时、每天或每周)内设定最大用量上限。当成员或团队达到设定的配额时,系统将安全拦截针对该资源的后续操作,直至配额周期重置。 + +配额规则配置与用量监控在界面中相互独立: + +- 若要创建和管理配额规则,请打开 **团队设置** 并切换到 **配额** 标签页。 +- 若要监控实时用量,请打开 **团队仪表板**,并在 **团队** 区域下选择 **配额**。 + +配额仪表板面向团队所有者开放。 + +--- + +## 作用域模式 + +创建或编辑配额规则时,可定义限制额度的生效方式: + +### 1. 每位成员独立配额 (Each Member) + +- **工作机制**:作用域内的每位成员均获得独立的使用额度。单名成员的消耗不会影响其他人的剩余配额。 +- **可选角色筛选**:可将配额限定为特定角色的成员(例如仅限 **编辑者 (Editor)** 或 **审阅者 (Reviewer)**),或应用于全团队。 +- **适用场景**:为每位编辑者分配每天 100,000 Token 的用量预算。 + +### 2. 全体成员共享池 (All Members - Shared Pool) + +- **工作机制**:所有符合条件的成员共同分摊一个配额总池,每位成员的消耗均从该总额中扣除。 +- **可选角色筛选**:将共享池应用于全团队成员,或仅限定特定角色。 +- **适用场景**:将团队每天在 AI 模型上的总开销上限控制在 50 美元以内。 + +### 3. 指定成员 (Selected Members) + +- **工作机制**:为选定的个别团队成员分配独立限额。 +- **适用场景**:为资深艺术家或技术总监赋予更高的限额,同时对其他人保持标准限制。 + +--- + +## 支持的资源类型 + +Shumai 在 AI 与智能体架构的多个层级上均支持配额管控: + +| 资源类型 | 说明 | 目标范围 | +| :------------------------------------------- | :------------------------------------------------------------------------------- | :------------------------------ | +| **总 Token 数 (Total Tokens)** | 在对话、评论与自动填充中消耗的 LLM 输入与输出 Token 总数。 | 团队、角色或成员 | +| **AI 成本 ($) (AI Cost ($))** | 调用 AI 模型服务商产生的美元费用开销。 | 团队、角色或成员 | +| **MCP 服务调用次数 (MCP Server Calls)** | 发送给已连接模型上下文协议 (MCP) 服务的工具调用总数。 | 目标 MCP 服务 ID | +| **沙箱 Bash 命令 (Sandboxed Bash Commands)** | 智能体在隔离沙箱内执行的 Shell 命令。 | 通配符模式(例如 `npm *`、`*`) | +| **智能体工具调用 (Agent Tool Calls)** | 对特定原生工具的调用次数(例如 `read_asset`、`download_asset`、`create_file`)。 | 工具名称 | + +### Bash 命令通配符匹配 + +在沙箱 Bash 执行中,支持使用通配符(`*` 与 `?`)限定特定的命令模式: + +- `*`:匹配任意 Bash 命令执行。 +- `npm *`:匹配任意 npm 命令(例如 `npm install`、`npm test`)。 +- `git commit*`:匹配 git commit 相关调用。 + +--- + +## 时间周期与滚动重置 + +配额支持配置以下重置周期: + +- **1 小时** (`1hour`) +- **5 小时** (`5hour`) +- **1 天** (`1day`) +- **7 天** (`7day`) + +### 惰性重置机制 + +Shumai 自动跟踪用量周期窗口。当周期窗口到期后,系统会在成员发起下一次请求时自动重置配额并开启新的周期,无需后台定时巡检任务即可无缝衔接。 + +--- + +## 监控实时用量 + +团队所有者可在团队仪表板中查看实时消耗情况: + +1. 打开 **团队仪表板**。 +2. 在 **团队** 区域下选择 **配额**。 +3. 配额规则以一级折叠卡片形式展示。 +4. 展开某条规则以查看其用量明细记录。 + +每条用量记录包含以下信息: + +- **消耗状态**:显示已用额度与总额度对比的进度条。 +- **剩余可用量**:剩余额度的百分比与具体数值。 +- **刷新倒计时**:当前活跃周期重置前的剩余时间(例如:_“45 分钟后刷新”_)。 +- **目标对象**:与该记录关联的团队共享池、角色池或具体成员。 +- **成员搜索**:对于成员级别的规则,支持按成员姓名或邮箱搜索用量记录。 + +展开规则时会加载用量记录,且在规则展开期间保持自动刷新。 + +### 手动重置用量记录 + +每条用量记录均包含 **重置用量** 操作项。确认操作后: + +- 消耗量归零。 +- 配额新周期立即开始。 +- 该周期在达到设定的配额时长后结束。 +- 例如,在 10:00 重置一个 1 天配额,将开启从 10:00 至次日 10:00 的全新周期窗口。 + +重置操作还可用于为尚未产生用量的成员或共享池初始化一条用量为零的记录。重置行为会记录在团队审计日志中。 + +--- + +## 管理配额规则 + +- **启用 / 禁用**:通过切换团队设置中任意配额卡片上的开关,可在不删除规则的情况下临时暂停或恢复执行。 +- **编辑规则**:点击团队设置中的任意配额卡片,即可更新限额、更改重置周期或调整选定的成员。 +- **删除规则**:打开团队设置中的卡片操作菜单(`⋮`)并选择 **删除**,即可移除该配额规则。 + +配额用量的监控与重置在团队仪表板中操作,而非在设置规则卡片中处理。 diff --git a/docs/zh/using-shumai/semantic-search.mdx b/docs/zh/using-shumai/semantic-search.mdx new file mode 100644 index 00000000..00368d39 --- /dev/null +++ b/docs/zh/using-shumai/semantic-search.mdx @@ -0,0 +1,40 @@ +--- +title: 语义搜索 +description: 基于 AI 向量相似度,通过视觉与文本语义查找文件。 +--- + +传统搜索依赖字符精确匹配(例如:搜索 "dog" 无法找到名为 `golden_retriever.jpg` 的文件)。Shumai 通过 **语义搜索** 解决了这一痛点,支持对文件的概念与深层语义建立索引。 + +--- + +## 语义搜索原理 + +语义搜索将文本查询词与文件内容转化为概念特征档案,使相似的构思与视觉画面在向量空间中邻近排列。 + +1. **索引生成**:上传媒体资产时,Shumai 后台智能体将扫描文件的视觉元素、文本内容或描述信息,并转化为概念特征档案。 + - **多模态向量模型服务**:Shumai 支持两类模型服务: + - **EmbeddingGemma 2(本地)**:由 `shumaiOne/embedding-server` 驱动,生成 768 维多模态向量,完全离线运行。视频按每个 60 秒分块以 **每分钟 15 帧**(非标准宽高比为 14 帧)采样。详见 [向量模型服务配置指南](/zh/using-shumai/embedding-server)。 + - **Gemini Embedding 2(云端)**:由 Google 的 `gemini-embedding-2` API 驱动,生成 1536 维向量。视频切分为 60 秒片段(去除音频,按 1 fps 采样,每块最多 32 帧)。 + - **分块配置**:管理员可通过环境变量 `EMBEDDING_CHUNK_DURATION`(默认值:60s)与 `EMBEDDING_CHUNK_OVERLAP`(默认值:5s)自定义分块时长与重叠时间。 +2. **概念匹配**:开启“语义搜索”(Semantic)开关后,Shumai 会比对查询词的概念含义与媒体资产的语义特征。 +3. **检索结果**:例如搜索“海滩日落”,即使视频文件名为 `IMG_4029.mp4`,也能成功检索到黄昏海浪拍岸的视频。 + +### 理解搜索结果 + +语义搜索与传统的关键字过滤机制有所不同: + +- **排序对比筛选**:语义搜索的表现更接近 **相关度排序** 而非严格的硬过滤。最相关的结果会优先置顶显示,但关联度较低的内容仍可能出现在列表后方(排名较低)。若需排除特定类型的文件,可配合 **筛选** 面板组合使用。 +- **视频分块结果**:由于 Shumai 采用分块机制对视频建立索引,同一个长视频可能会在搜索结果中出现多次,每条结果对应匹配到概念的具体视频片段。 +- **匹配时间戳**:当检索结果来自某个视频分块时,Shumai 会标出匹配的起止时间点。点击此类结果可直接打开视频并自动跳转到对应的时间戳位置。 + +--- + +## 启用语义搜索 + +若需使用语义搜索: + +1. 确认团队管理员已在 **团队设置** > **智能体** 下启用了 **Embedding 智能体**。 +2. 启用后,Shumai 将自动为新上传的文件建立索引。 +3. 在文件管理器的搜索框旁开启 **语义**(Semantic)开关,即可按概念语义检索资产。 + +![语义搜索开关](/semantic-search.webp) diff --git a/docs/zh/using-shumai/share-links.mdx b/docs/zh/using-shumai/share-links.mdx new file mode 100644 index 00000000..01af95b6 --- /dev/null +++ b/docs/zh/using-shumai/share-links.mdx @@ -0,0 +1,83 @@ +--- +title: 分享链接 +description: 安全地向外部客户与利益相关者分享文件和文件夹。 +--- + +Shumai 支持与未注册工作区账号的外部利益相关者协作。借助**分享链接**,可向指定人员授予特定文件夹或资产的浏览与评论权限。 + +--- + +## 创建分享链接 + +1. 选中要分享的文件或文件夹,右键单击并选择**创建新分享链接**。 +2. 在项目侧边栏中点击刚创建的**分享链接**,进入其配置页面。 +3. 在右侧边栏中配置分享链接参数: + - 添加密码保护 + - 设置过期时间 + - 开启或禁止文件下载 + - 为预览画面添加水印 + - 自定义对访客可见的元数据字段 +4. 点击侧边栏底部的**复制链接**,将链接发送给客户或外部协作者。 + +![配置分享链接](/sharelink.webp) + +--- + +## 向已有分享链接添加资产 + +创建分享链接后,无需重新生成链接即可直接追加更多文件或文件夹: + +1. 在文件浏览器中选中要添加的文件或文件夹。 +2. 直接将其拖拽到项目侧边栏对应的分享链接条目上。 +3. 分享链接将立即更新并包含新添加的资产。 + +--- + +## 安全与权限配置 + +### 有效期 + +可选设置链接失效的日期和时间。过期后,任何人访问该链接均会返回 `404 Not Found` 页面。 + +### 密码保护 + +为敏感资产配置访问密码。外部用户访问该链接时,必须输入正确的密码才能查看资产内容。 + +### 允许下载 + +控制访客是否能下载所分享的文件。当关闭**允许下载**时: + +- 公共分享页面上的所有下载按钮均会被隐藏(包括文件卡片、多选操作栏、播放器控制栏以及顶部导航栏)。 + +访客仍可在线预览文件,但无法下载原文件。该选项常与水印功能搭配使用,既能满足预览需求,又能保护资产安全。 + +### 水印保护 + +在分享链接展示的每个预览画面上叠加水印(例如“CONFIDENTIAL”机密文本标签或企业 Logo 图片)。打开水印编辑器,调整布局模块后保存即可。 + +为了控制存储成本,水印采用**按分享链接按需生成(惰性转码)**机制: + +- 仅在**分享链接开启水印**时才会触发水印转码——Shumai **不会**为工作区中的每个文件预先生成水印副本。 +- 分享链接中已包含的所有视频和图片资产将在此刻开始转码(侧边栏会显示*处理中*状态,直至转码完成)。 +- 后续向该分享链接**追加的文件和文件夹也会自动转码**,确保整个分享内容始终带有水印,无需人工干预。 +- 由于仅对通过水印链接分享的资产生成水印副本,从未分享(或仅通过无水印链接分享)的文件绝不会占用额外的水印代理文件存储空间。对于大型媒体库,这能节省极为可观的存储开销。 + +说明: + +- 仅**视频与图片**预览代理文件支持添加水印;其他媒体类型(PDF、音频等)不受影响。 +- 水印转码处理期间,系统会隐藏预览画面,避免暴露未添加水印的原始代理文件。 + +### 默认排序规则 + +为分享页面配置默认排序规则(例如按名称或版本排序),确保客户按预期的顺序浏览文件。 + +### 列可见性 + +为保护内部机密信息,可精确配置对外部用户可见的元数据列。例如: + +- **可见**:`资产名称`、`分辨率`、`下载链接`。 +- **隐藏**:`内部预算编号`、`负责人备注`、`制作成本`。 + +### 禁用链接 + +若需立即撤销访问权限,请进入项目设置中的**分享链接**选项卡,开启**已禁用**开关。后续可随时重新启用该链接。 diff --git a/docs/zh/using-shumai/sort-and-search.mdx b/docs/zh/using-shumai/sort-and-search.mdx new file mode 100644 index 00000000..ae2f15ba --- /dev/null +++ b/docs/zh/using-shumai/sort-and-search.mdx @@ -0,0 +1,39 @@ +--- +title: 排序与搜索 +description: 使用搜索对话框查找资产,并通过自定义排序规则整理文件。 +--- + +随着项目规模扩大,快速检索所需的媒体文件至关重要。Shumai 提供了功能强大的搜索对话框与灵活的排序控件。 + +--- + +## 搜索资产 + +点击工具栏中的搜索图标,即可打开专用的 **搜索对话框**。 + +![搜索对话框](/search-dialog.webp) + +### 搜索对话框特性 + +- **关键词匹配**:在文本输入框中输入关键词,即可即时过滤文件名和文件夹名。 +- **高级筛选**:点击展开筛选面板,构建多条件复合查询(例如:查找自定义字段“状态”等于“处理中”且文件类型为“视频”的文件)。 +- **语义搜索开关**:若团队管理员启用了该功能,开启“语义搜索”(Semantic)开关即可按概念含义搜索(例如:搜索“阳光海滩”即可找到海洋片段,即使文件名中并未包含这些词)。 +- **保存为合集**:便捷地将当前搜索条件转化为动态合集。点击对话框内的 **保存为合集**(Save as Collection),即可创建该合集并直接跳转至对应视图。 +- **无限滚动加载**:输入关键词或调整筛选条件时,搜索结果将实时动态加载。 + +--- + +## 资产排序与重排 + +可以通过排序下拉菜单或点击元数据列标题,切换资产列表的排序规则: + +- **自定义排序(默认)**:项目文件管理器默认采用 **自定义**(Custom)排序。在此模式下,可直接通过手动拖拽文件与文件夹,按需排列显示顺序。 +- **标准排序选项**:支持按以下维度排序: + - _最新上传_:优先展示最新上传的资产。 + - _名称_:按字母顺序排列(A-Z 或 Z-A)。 + - _大小_:按文件体积大小排序。 + - _类型_:将文件夹置顶聚合,随后展示版本堆栈与单文件。 + - _自定义列_:按动态元数据字段排序(例如:按“截止日期”或“优先级”排序)。 + +> [!NOTE] +> **拖拽重排限制**:仅当排序规则设置为 **自定义** 时,才支持手动拖拽调整顺序。若选择了其他排序选项(如按名称或大小),手动重排功能将自动禁用。 diff --git a/docs/zh/using-shumai/team-project-management.mdx b/docs/zh/using-shumai/team-project-management.mdx new file mode 100644 index 00000000..a74e0ce0 --- /dev/null +++ b/docs/zh/using-shumai/team-project-management.mdx @@ -0,0 +1,58 @@ +--- +title: 团队与项目管理 +description: 组织工作区架构、定义权限角色并管理成员。 +--- + +Shumai 采用“**团队**”与“**项目**”双层组织架构,实现精细化的文件访问控制与协作管理。 + +--- + +## 成员可见性与作用域 + +添加到团队的成员分为两种权限作用域: + +- **团队作用域(Team Scope)**:团队作用域成员默认可以查看该团队下的所有项目。 +- **项目作用域(Project Scope)**:项目作用域成员仅能查看并访问明确授权加入的特定项目。 + +--- + +## 成员角色 + +Shumai 通过权限角色控制团队与项目成员的操作权限: + +- **所有者(Owner)**:拥有全部管理权限。团队所有者可以修改团队设置、智能体技能以及 AI 提供商配置;项目所有者可以编辑项目配置、管理项目成员并生成邀请链接。 +- **编辑者(Editor)**:可以上传文件、编辑自定义元数据、创建文件夹,以及添加评论或画布标注。 +- **审阅者(Reviewer)**:仅具备只读访问权限。可以浏览媒体资产、切换版本以及发表文本评论或画布涂鸦,但无法上传/删除文件或修改元数据。 + +--- + +## 项目角色覆盖机制 + +管理员可将现有团队成员添加到特定项目中,以覆盖其原有的权限角色: + +- 在该项目内部,项目级角色的优先级高于团队级角色。 +- _示例_:若 Peter 是拥有 **编辑者** 角色(Editor)的团队成员,管理员可将其以 **审阅者** 角色(Reviewer)加入 _项目 A_。此时 Peter 在“项目 A”中仅具备审阅者权限,而在团队的其他项目中依然保持编辑者权限。 + +--- + +## 成员管理 + +所有成员管理操作均通过统一的 **成员管理弹窗**(Members Dialog)完成: + +### 1. 管理团队成员 + +- **入口**:打开 **团队控制台**,点击顶部栏中的成员列表或头像组。 +- **配置操作**: + - 在“编辑者”与“审阅者”之间调整成员角色。 + - 将成员从团队中移除。 + - **邀请新成员**:选择目标角色(编辑者或审阅者),点击 **生成链接**(Generate Link)。复制注册链接即可邀请新用户加入团队。 + +### 2. 管理项目成员 + +- **入口**:打开项目的 **文件管理器**,点击顶部工具栏中的成员头像或管理按钮。 +- **配置操作**: + - 调整项目成员角色,或将其从项目中移除。 + - **添加团队成员**:弹窗会列出尚未加入该项目的活跃团队成员。为其指定项目角色(将在该项目内覆盖其团队角色),点击 **添加**(Add)即可立即加入。 + - **邀请外部协作者**:选择目标角色(编辑者或审阅者),点击 **生成链接**(Generate Link),即可直接邀请新用户加入该特定项目。 + +![成员管理弹窗](/members.webp) diff --git a/docs/zh/using-shumai/transcode-settings.mdx b/docs/zh/using-shumai/transcode-settings.mdx new file mode 100644 index 00000000..83f962f3 --- /dev/null +++ b/docs/zh/using-shumai/transcode-settings.mdx @@ -0,0 +1,81 @@ +--- +title: 视频转码 +description: 配置视频转码策略、MP4 与 HLS 流媒体分辨率、硬件加速以及 FFmpeg 线程数。 +--- + +高分辨率摄影机格式与原生媒体文件无法在 Web 浏览器中直接播放。Shumai 在后台自动将视频资产转码为适用于网页的流式传输与预览格式。 + +团队所有者可在 **团队设置 > 视频转码** 页面自定义视频转码行为。 + +无论选择何种转码策略,Shumai 流水线都会**始终**为原始文件生成至少一个轻量级 `180p` 代理版本,以确保快速拖拽播放(Scrubbing)、缩略图生成与即时预览。 + +--- + +## 转码策略 + +**转码策略**卡片用于配置 MP4 视频转码以及 HLS 自适应流媒体。 + +### 播放与下载行为 + +Shumai 采用双格式交付策略: + +- **未启用 HLS 时**:浏览器内视频播放与文件下载均使用生成的 MP4 文件。 +- **启用 HLS 时**:浏览器内视频播放使用 HLS(HTTP Live Streaming)实现流畅的自适应码率播放,文件下载则使用生成的 MP4 文件。 + + + **存储用量提示**:启用 HLS 除生成标准 MP4 代理文件外,还会生成多码率切片文件(`.ts` / + `.m4s`)及播放列表清单,这会显著增加存储桶的容量占用。 + + +### MP4 转码 + +生成兼容 Web 的 MP4 文件,用于文件下载与标准视频播放。团队所有者可为上传的文件选择 MP4 转码模式: + +#### 1. 最佳匹配 (Best Match) + +- **工作机制**:Shumai 检测所上传视频的最长边尺寸,生成单一匹配或略低于源画质的最优分辨率,避免无谓的升采样(Upscaling)。 +- **输出产物**:生成轻量级 `180p` 代理版本以及计算得出的最佳匹配 MP4 文件。 +- **适用场景**:推荐默认选项。在保证广泛的播放与下载兼容性的同时,最大程度缩短处理耗时并节省存储空间。 + +#### 2. 多分辨率阶梯 (Multi Resolutions) + +- **工作机制**:可指定生成的目标分辨率阶梯:`480p`、`720p`、`1080p`、`1440p` 与 `2160p`。系统仅生成不超过原始分辨率的画质(绝不对内容升采样)。 +- **输出产物**:生成 `180p` 代理版本,以及所选且未超出源视频分辨率的所有分辨率文件。 +- **适用场景**:适用于需要下载多种指定分辨率的场景(例如使用 720p 快速分发共享,使用 1080p 审阅)。 + +### HLS 流媒体 + +开启 **HLS 流媒体** 开关后,Shumai 会为上传的视频生成自适应码率 HLS 分发包: + +- **分辨率阶梯**:配置 HLS 流媒体生成的目标分辨率(`480p`、`720p`、`1080p`、`1440p`、`2160p`)。系统仅生成不超过原始视频分辨率的阶梯。 +- **播放器集成**:当 HLS 可用时,Web 播放器会自动采用 HLS 流式播放,并根据客户端网络带宽动态切换码率。 + +![视频转码](/transcode.webp) + +--- + +## 硬件加速 + +为将编码负载从 CPU 分流至 GPU,Shumai 支持硬件加速视频编码: + +- **禁用(软件编码)**:使用标准 CPU `libx264` 软编器并配合恒定速率因子(CRF)。 +- **自动检测**:自动探测并启用可用的 GPU / 硬件加速能力(NVIDIA NVENC、Intel QuickSync、AMD/Intel VA-API、Apple VideoToolbox、Rockchip RKMPP)。 + +详见 [硬件加速转码指南](/zh/configuration/hardware-transcoding),获取 Docker Compose 配置、GPU 透传及驱动前置要求说明。 + +--- + +## FFmpeg 线程数 + +**FFmpeg 线程数** 滑块用于控制转码任务期间 FFmpeg 可调用的最大 CPU 线程数: + +- **自动 (0)**:FFmpeg 根据宿主机可用 CPU 核心数自动选择最优线程数。 +- **手动 (1 - 32)**:将 FFmpeg 限制为固定线程数,适用于在共享 Worker 节点上限制 CPU 资源占用。 + +--- + +## 处理架构 + +媒体转码属于高资源消耗型任务。管理员可根据扩缩容需求,选择在主服务器上直接运行转码引擎(单服务器模式),或将任务委派给专门的转码 Worker 节点(独立 Worker 模式)。 + +无论采用何种模式,负责处理的机器均须安装系统级媒体工具(`ffmpeg` 与 `ffprobe`)。关于搭建独立转码 Worker 的详细步骤,请参阅 [分布式部署指南](/zh/configuration/distributed)。 diff --git a/docs/zh/using-shumai/version-stack.mdx b/docs/zh/using-shumai/version-stack.mdx new file mode 100644 index 00000000..bd541aec --- /dev/null +++ b/docs/zh/using-shumai/version-stack.mdx @@ -0,0 +1,44 @@ +--- +title: 文件版本堆栈 +description: 将媒体资产的多个修订版本归拢至单个版本控制堆栈中。 +--- + +在创意资产协作过程中,文件通常会经历多次迭代(例如 `draft_v1.mp4`、`draft_v2.mp4`、`draft_final.mp4`)。为了防止工作区杂乱无章,Shumai 支持将这些修订版本归拢合并为一个 **版本堆栈**(Version Stack)。 + +--- + +## 什么是版本堆栈? + +**版本堆栈** 将同一文件的多个修订版本聚合为单个条目。Shumai 无需让大量相似文件堆满文件夹,而是将其折叠为一个带有版本角标(如 "V3")的条目,并提供历史版本下拉列表。 + +![版本堆栈选择器](/versionstack.webp) + +--- + +## 创建与添加版本堆栈 + +可通过以下两种交互方式创建版本堆栈或向现有堆栈添加新版本: + +- **拖拽操作**: + - _创建堆栈_:在文件列表中将一个独立文件直接拖拽覆盖到另一个独立文件上方。 + - _添加版本_:将一个独立文件直接拖拽到现有版本堆栈上方。 +- **右键菜单**: + - 右键点击任意独立文件或现有版本堆栈。 + - 在菜单中选择 **创建新版本**(Create New Version)。 + - 从电脑中选取修订版文件,直接上传至该堆栈中。 + +--- + +## 版本管理 + +### 当前活跃版本 + +位于堆栈顶部的版本为 **当前活跃版本**(Active Version)。项目控制台、搜索结果以及元数据面板中均默认展示此版本。 + +### 调整版本顺序与回退版本 + +支持提升历史版本或重新排列堆栈顺序: + +- 打开版本堆栈详情侧边栏。 +- 在列表中拖拽调整各版本顺序。拖拽到顶部的版本将自动成为当前活跃版本。 +- 若需从堆栈中移出某个文件,可直接将其拖出,或选择 **拆分堆栈**(Unstack)。该操作会将该文件作为独立文件移回父文件夹。