# starvault-service

**Repository Path**: svs_2/starvault-service

## Basic Information

- **Project Name**: starvault-service
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# StarVault Server

StarVault Server 是客户端的模型理解服务端：客户端只上传轻量的「切片元数据 + 字幕 + 关键帧」，服务端根据管理后台配置的模型供应商返回切片标题、场景、主体、情绪、卖点和标签。

## 快速启动

```bash
npm start
```

默认地址：

- 管理后台：http://127.0.0.1:3000/admin
- 健康检查：http://127.0.0.1:3000/health
- 客户端接口：`POST http://127.0.0.1:3000/v1/understand`

首次启动会在 `data/config.json` 写入一个 `mock-default` 模型供应商，不需要 API Key，可用于客户端联调。

## 环境变量

| 变量 | 默认值 | 说明 |
|---|---:|---|
| `HOST` | `127.0.0.1` | 监听地址 |
| `PORT` | `3000` | 监听端口 |
| `STARVAULT_DATA_DIR` | `./data` | 配置持久化目录 |
| `DB_HOST` | `114.55.178.197` | 数据库地址 |
| `DB_PORT` | `3306` | 数据库端口 |
| `DB_USER` | `root` | 数据库用户名 |
| `DB_PASSWORD` | `Svs@2026` | 数据库密码 |
| `DB_NAME` | `starvault_db` | 数据库名 |
| `STARVAULT_AUTH_TOKEN` | 空 | 强制接口鉴权；优先级高于后台保存的 token |
| `STARVAULT_ADMIN_USERNAME` | `kris` | 管理后台登录账号 |
| `STARVAULT_ADMIN_PASSWORD` | `starvault2026` | 管理后台登录密码，生产环境建议覆盖 |
| `STARVAULT_ADMIN_SESSION_SECRET` | 管理员账号密码派生值 | 管理后台 session 签名密钥，生产环境建议设置随机长字符串 |
| `STARVAULT_ADMIN_SESSION_TTL_MS` | `43200000` | 管理后台登录保持时间，默认 12 小时 |

## 模型管理与任务配置

后台分成两层：

- 模型管理：只管理供应商、Base URL、API Key、模型名、超时等连接信息。
- 任务配置：为不同任务选择模型，并维护该任务自己的系统 Prompt。

模型管理支持两类供应商：

- `mock`：本地规则生成理解结果，适合无密钥联调。
- `openai-compatible`：调用兼容 OpenAI Chat Completions 的多模态接口。

OpenAI-compatible 常见配置：

```text
Base URL: https://api.openai.com/v1
Model: gpt-4.1-mini
API Key: sk-...
```

也可以填写完整地址，例如：

```text
Base URL: https://example.com/v1/chat/completions
```

当前内置任务：

- `understand` / 素材理解：对应 `POST /v1/understand`
- `asr-check` / ASR口播判断：对应 `POST /v1/asr-check`
- `remix` / 智能混剪：对应 `POST /v1/remix`
- `quick-video` / 快速成片：对应 `POST /v1/quick-video-tasks`
- `quick-video-match` / 快速成片素材匹配：对应 `POST /v1/quick-video-tasks/:id/match`
- `quick-video-batch` / 快速成片批量编排：对应 `POST /v1/quick-video-tasks/:id/batch`

## API 接口文档

以下所有接口基于 `http://127.0.0.1:3000`，实际使用时请替换为服务器地址。

---

### 1. 健康检查

```bash
curl http://127.0.0.1:3000/health
```

---

### 2. 管理后台登录

```bash
curl -c admin_cookies.txt -X POST http://127.0.0.1:3000/api/admin/login \
  -H 'content-type: application/json' \
  -d '{"username":"kris","password":"starvault2026"}'
```

后续管理接口使用 cookie：`-b admin_cookies.txt`

### 3. 管理后台登出

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/admin/logout
```

---

### 4. 获取公开配置

```bash
curl -b admin_cookies.txt http://127.0.0.1:3000/api/config
```

### 5. 设置鉴权 Token

```bash
curl -b admin_cookies.txt -X PUT http://127.0.0.1:3000/api/config/auth-token \
  -H 'content-type: application/json' \
  -d '{"authToken":"your-token-here"}'
```

### 6. 设置 TTS 配置

```bash
curl -b admin_cookies.txt -X PUT http://127.0.0.1:3000/api/config/tts \
  -H 'content-type: application/json' \
  -d '{
    "enabled": true,
    "provider": "aliyun",
    "appKey": "your-app-key",
    "accessKeyId": "your-access-key-id",
    "accessKeySecret": "your-access-key-secret",
    "voice": "xiaoyun"
  }'
```

### 7. TTS 测试

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/tts/test \
  -H 'content-type: application/json' \
  -d '{"text":"你好，这是一段 StarVault 语音合成测试。","voice":"xiaoyun"}'
```

---

### 8. 查看请求日志

```bash
curl -b admin_cookies.txt "http://127.0.0.1:3000/api/logs?limit=100"
```

### 9. 清空请求日志

```bash
curl -b admin_cookies.txt -X DELETE http://127.0.0.1:3000/api/logs
```

---

### 10. 查看用户列表

```bash
curl -b admin_cookies.txt http://127.0.0.1:3000/api/users
```

### 11. 查看邀请码列表

```bash
curl -b admin_cookies.txt http://127.0.0.1:3000/api/invites
```

### 12. 创建邀请码

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/invites \
  -H 'content-type: application/json' \
  -d '{"code":"VIP-2026","note":"VIP专属","maxUses":50}'
```

### 13. 查看用户积分明细

```bash
curl -b admin_cookies.txt http://127.0.0.1:3000/api/users/{userId}/credits
```

### 14. 给用户发放积分

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/users/{userId}/credits \
  -H 'content-type: application/json' \
  -d '{"amount":100,"reason":"活动赠送"}'
```

---

### 15. 添加/更新模型供应商

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/providers \
  -H 'content-type: application/json' \
  -d '{
    "name": "OpenAI",
    "type": "openai-compatible",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-your-key",
    "model": "gpt-4.1-mini",
    "temperature": 0.2,
    "timeoutMs": 120000,
    "activate": true
  }'
```

更新时传 `id`（不传 `apiKey` 则保留原值）：

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/providers \
  -H 'content-type: application/json' \
  -d '{"id":"provider-id","name":"OpenAI Updated","model":"gpt-4o"}'
```

### 16. 删除模型供应商

```bash
curl -b admin_cookies.txt -X DELETE http://127.0.0.1:3000/api/providers/{providerId}
```

### 17. 激活模型供应商

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/providers/{providerId}/activate
```

---

### 18. 添加/更新任务配置

```bash
curl -b admin_cookies.txt -X POST http://127.0.0.1:3000/api/tasks \
  -H 'content-type: application/json' \
  -d '{
    "id": "understand",
    "name": "素材理解",
    "providerId": "provider-id",
    "systemPrompt": "只返回 JSON，不返回 Markdown。",
    "temperature": 0.2,
    "creditCost": 1,
    "enabled": true
  }'
```

---

### 19. TTS 语音合成

用户端使用（需登录 token）：

```bash
curl -X POST http://127.0.0.1:3000/v1/tts \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{"text":"你好世界","voice":"xiaoyun","format":"mp3"}'
```

GET 方式：

```bash
curl "http://127.0.0.1:3000/v1/tts?text=你好世界&voice=xiaoyun"
```

---

### 20. 用户注册

```bash
curl -X POST http://127.0.0.1:3000/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"username":"demo","password":"secret123","inviteCode":"DEV-INVITE"}'
```

响应示例：

```json
{
  "user": { "id": "uuid", "username": "demo", "credits": 200, ... },
  "token": "hex-token",
  "expiresAt": 1718000000000
}
```

### 21. 用户登录

```bash
curl -X POST http://127.0.0.1:3000/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"demo","password":"secret123"}'
```

### 22. 获取当前用户信息

```bash
curl http://127.0.0.1:3000/v1/me \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

---

### 23. 素材理解 (POST /v1/understand)

需要用户登录 Token（消耗积分的任务）：

```bash
curl http://127.0.0.1:3000/v1/understand \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "assetId": "a_demo",
    "clips": [
      {
        "idx": 1,
        "startMs": 11000,
        "endMs": 28000,
        "transcript": "产品包装很有质感",
        "frames": ["data:image/jpeg;base64,..."]
      }
    ]
  }'
```

Multipart 方式：

```bash
curl http://127.0.0.1:3000/v1/understand \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -F 'payload={"assetId":"a_demo","clips":[{"idx":1,"startMs":11000,"endMs":28000,"transcript":"产品包装","frames":["1_0.jpg"]}]}' \
  -F 'frames=@/path/to/1_0.jpg;type=image/jpeg'
```

### 24. ASR 口播判断 (POST /v1/asr-check)

```bash
curl http://127.0.0.1:3000/v1/asr-check \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "assetId": "a_demo",
    "transcript": "大家好，今天给大家推荐一款产品..."
  }'
```

带 ASR 分段：

```bash
curl http://127.0.0.1:3000/v1/asr-check \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "assetId": "a_demo",
    "transcript": "你好世界",
    "asrSegments": [
      { "startMs": 0, "endMs": 1000, "text": "你好", "confidence": 0.95 },
      { "startMs": 1000, "endMs": 2000, "text": "世界", "confidence": 0.92 }
    ]
  }'
```

---

### 25. 智能混剪 - 创建任务 (POST /v1/remix)

异步接口，返回 202 和任务 ID：

```bash
curl http://127.0.0.1:3000/v1/remix \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "projectId": "project-001",
    "projectName": "我的混剪项目",
    "requirement": "帮我剪一些投放素材",
    "constraints": { "targetDurationMs": 30000, "maxClips": 5 },
    "clips": [
      {
        "clipId": "c1",
        "assetId": "a1",
        "cutMethod": "asr",
        "startMs": 0,
        "endMs": 10000,
        "title": "口播片段",
        "summary": "产品介绍",
        "tags": [{ "name": "口播", "dim": "scene" }]
      }
    ]
  }'
```

### 26. 智能混剪 - 查看任务列表

```bash
curl http://127.0.0.1:3000/v1/remix-tasks \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

### 27. 智能混剪 - 查看任务详情

```bash
curl http://127.0.0.1:3000/v1/remix-tasks/{taskId} \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

### 28. 智能混剪 - 删除任务

```bash
curl -X DELETE http://127.0.0.1:3000/v1/remix-tasks/{taskId} \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

---

### 29. 快速成片 - 创建任务 (POST /v1/quick-video-tasks)

异步接口，返回 202 和任务 ID：

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "projectId": "project-001",
    "projectName": "我的快速成片",
    "requirement": "生成3条15秒的短视频",
    "sourceType": "script",
    "source": {
      "title": "产品介绍",
      "text": "这是一款好用的产品..."
    },
    "clips": [
      {
        "clipId": "c1",
        "assetId": "a1",
        "cutMethod": "asr",
        "startMs": 0,
        "endMs": 10000,
        "title": "片段1",
        "summary": "产品外观"
      }
    ],
    "constraints": { "targetDurationMs": 15000, "aspectRatio": "9:16" },
    "options": { "bgm": true, "subtitle": true }
  }'
```

### 30. 快速成片 - 查看任务列表

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

### 31. 快速成片 - 查看任务详情

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks/{taskId} \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

### 32. 快速成片 - 删除任务

```bash
curl -X DELETE http://127.0.0.1:3000/v1/quick-video-tasks/{taskId} \
  -H 'Authorization: Bearer <USER_TOKEN>'
```

### 33. 快速成片 - 重试任务

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks/{taskId}/retry \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "projectId": "project-001",
    "projectName": "重新生成",
    "requirement": "重新生成",
    "sourceType": "script",
    "source": { "title": "产品介绍", "text": "这是一款产品..." },
    "clips": [],
    "constraints": { "targetDurationMs": 15000 },
    "options": {}
  }'
```

### 34. 快速成片 - 素材匹配

在任务 plan_ready 后调用：

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks/{taskId}/match \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "clips": [
      {
        "clipId": "c1",
        "assetId": "a1",
        "startMs": 0,
        "endMs": 10000,
        "title": "匹配片段",
        "summary": "素材摘要"
      }
    ]
  }'
```

### 35. 快速成片 - 批量编排

在任务 match_ready 后调用：

```bash
curl http://127.0.0.1:3000/v1/quick-video-tasks/{taskId}/batch \
  -X POST \
  -H 'Authorization: Bearer <USER_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
    "clips": [],
    "exportOptions": { "format": "mp4", "resolution": "1080x1920" },
    "options": { "bgm": true, "subtitle": true }
  }'
```

---

## 鉴权

管理后台默认需要访问 `/admin/login` 登录。默认管理员账号可通过环境变量覆盖：

```text
STARVAULT_ADMIN_USERNAME=kris
STARVAULT_ADMIN_PASSWORD=starvault2026
STARVAULT_ADMIN_SESSION_SECRET=replace-with-random-secret
```

在后台保存访问令牌，或设置 `STARVAULT_AUTH_TOKEN` 后，客户端接口可继续使用：

```http
Authorization: Bearer <TOKEN>
```

客户端接口 `/v1/*` 使用用户登录 token。`/v1/auth/register` 与 `/v1/auth/login` 是公开入口。

## 用户与积分

客户端注册：

```bash
curl -s http://127.0.0.1:3000/v1/auth/register \
  -H 'content-type: application/json' \
  -d '{"username":"demo","password":"secret123","inviteCode":"DEV-INVITE"}'
```

客户端登录：

```bash
curl -s http://127.0.0.1:3000/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"username":"demo","password":"secret123"}'
```

管理后台支持：

- 创建邀请码。
- 查看用户列表和手机号预留字段。
- 给用户发放积分。
- 查看用户积分增删流水。
- 设置每个任务的消耗积分值。

## 测试

```bash
npm test
```