# 火山视频工作台

**Repository Path**: mrjkchen/volcano-video-studio

## Basic Information

- **Project Name**: 火山视频工作台
- **Description**: 火山兼容 API 视频创作工作台，React + Fastify，支持本机与独立服务器部署。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-13
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 火山视频工作台

中文多人视频创作工具，接入界云火山兼容 API，支持创作、批量任务、素材库、真人认证、团队共享与结果归档。当前版本直接运行于 Windows，文件和数据库均保存在本机，不需要 Docker。

## 本机打开

双击项目根目录 `启动本机工作台.cmd`，浏览器打开 http://localhost:5173。首次安装所需依赖已在本机准备。停止时使用 `停止本机工作台.cmd`，文件和数据库不会被清空。

开发模式可以注册自己的邮箱账号，在登录页的“本机开发邮箱”查看验证邮件，验证后登录。开发邮箱仅用于本机验收，不发送真实邮件。公网部署前必须配置 SMTP、HTTPS，关闭开发入口并另做部署安全验收。

登录后进入“设置与凭证”保存自己的界云 Bearer API Key。视频生成使用 Bearer；素材库还可选择 AK/SK。凭证经服务端加密后保存，前端不会读取已保存的明文。

如需平台管理权限，先完成自己账号的邮箱验证，然后在项目目录运行：

```powershell
pnpm exec tsx scripts/set-admin.ts 你的注册邮箱
```

重新登录后显示平台管理入口。没有内置通用管理员密码。

## 图片引用

添加图片后，在提示词输入 `@` 选择图1、图2。引用会高亮，鼠标移入可预览图片；手机可以点击“预览”。删除引用时会整块移除，支持撤销。详细交互与维护说明见 [图片引用说明](docs/image-references.md)。

## 文件在哪里

- `data/media`：上传文件、生成视频、尾帧和导出 ZIP。
- `data/postgres`：用户、任务、素材、权限等数据库。
- `data/redis`：后台队列持久数据。
- `.env`：仅本机配置与随机生成的加密密钥，不应分享。
- `work/logs`：本机服务日志。

为兼容 PostgreSQL 的 Windows 中文路径限制，本机创建 `D:\CodexRuntime\volcano-studio` 指向工程目录的 Junction。这只是同一文件夹的英文路径入口，数据库实际仍在本工程中。没有安装系统数据库服务。

本机 Redis 使用 redis-windows 社区 Windows 构建，下载版本与 SHA256 固定在 `scripts/setup-redis.ps1`；它不是 Redis 官方原生 Windows 支持承诺。

## 使用流程

1. 设置自己的凭证，选择已开通的模型或添加 Endpoint 与对应能力类型。
2. 输入提示词、选择图片或其他参考素材，调整参数。不设置的参数按接口默认处理。
3. 单条生成直接提交；批量生成支持粘贴、CSV 和逐行参数覆盖，提交前显示校验错误。
4. 浏览器关闭后，API 与 Worker 仍需保持运行，后台才能继续查询和归档。
5. 成功视频自动保存本机，可预览、下载、共享或批量打包。归档失败只重试保存，不重新生成。

本机图片可以 Base64 提交。上游素材库、视频和音频参考要求上游可访问的 URL；本地硬盘路径和 localhost 不能提供给上游。当前没有自动建立公网隧道，未配置可访问地址时界面明确提示。也可直接输入自己的 HTTPS 素材地址。

真人认证通过平台返回的 H5 链接完成，认证结果主动查询。软件不采集认证过程中的生物识别数据。模拟认证只用于测试，不会产生真实授权。

## 开发与验证

在新的 Windows 机器首次安装时，需要 Node.js 24、pnpm 11 和可用的 D 盘。将源码放到工程目录后执行：

```powershell
pnpm install --frozen-lockfile
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/setup-redis.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/start-local.ps1
```

PostgreSQL 由工程依赖提供；Redis安装脚本校验下载SHA256并解压到工程内。启动脚本生成随机本机密钥、初始化数据库、执行迁移并启动服务。当前这台机器已完成上述准备，直接双击启动即可。

源码包不含 `.env`、账号数据、视频、数据库、依赖目录和运行时二进制；在新机器安装时需要联网下载依赖。本机数据迁移应按备份恢复文档单独进行。

```powershell
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test
```

开发服务分别为 API 3001、前端 5173、PostgreSQL 55432、Redis 56379，默认只绑定本机。`pnpm dev:worker` 单独启动 Worker。真实数据库回归使用临时隔离 schema，不操作用户数据。

```powershell
$env:API_INTEGRATION='1'
$env:WORKER_INTEGRATION='1'
$env:ASSETS_INTEGRATION='1'
node --env-file=.env node_modules/vitest/vitest.mjs run
```

本地模拟完整生命周期：先运行 `pnpm dev:mock`，再运行 `pnpm exec tsx scripts/test-lifecycle.ts`。该脚本使用独立测试数据库、Redis DB 2 和本机模拟服务，不调用付费上游。

性能脚本：`pnpm exec tsx scripts/load-local.ts --duration=60`，最长支持 `--duration=1800`。实测环境及结果见 `docs/performance.md`；Windows 本机结果不能冒充规定 Linux 独立压测机验收。

## 维护

配置与维护见 `docs/architecture.md`、`docs/storage.md`、`docs/api.md` 和 `docs/acceptance.md`。停机备份脚本和恢复步骤见 `docs/backup-restore.md`。备份应同时保留数据库、media 文件夹与加密密钥；丢失密钥将无法解密已保存的上游凭证。

未提供真实上游凭证，因此实际模型开通、价格、真实生成人脸授权和公网素材可达性必须由真实环境联调确认。软件不显示未经上游返回或配置的估算费用。