omniai-server/README.md

# OmniAI Key Management Server

API Key 池管理服务，支持多 Key 轮询、并发控制、自动排队。

## 部署到阿里云

### 1. 服务器准备

```bash
# 安装 Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 PM2 (进程管理)
sudo npm install -g pm2
```

### 2. 上传代码

```bash
# 将 server/ 目录上传到服务器
scp -r server/ root@your-server:/opt/omniai-server/
```

### 3. 配置

```bash
cd /opt/omniai-server
cp .env.example .env
nano .env  # 修改 JWT_SECRET、DEFAULT_ADMIN_PASSWORD 等配置
```

### 4. 安装 & 初始化

```bash
npm install
npm run init-db
```

### 5. 添加 Key

```bash
# 添加 Seedance Key (每个并发上限 10)
npm run add-key -- seedance sk-your-key-1 "Seedance 1号" 10
npm run add-key -- seedance sk-your-key-2 "Seedance 2号" 10
npm run add-key -- seedance sk-your-key-3 "Seedance 3号" 10

# 添加其他服务的 Key
npm run add-key -- grok sk-grok-key "Grok" 10
npm run add-key -- dashscope sk-dash-key "DashScope" 10

# 查看所有 Key
npm run list-keys
```

### 6. 添加用户

```bash
npm run add-user -- alice password123 user 30
npm run add-user -- bob password456 user 30
```

### 6.1 防控账号开通与封控

建议给外部/临时用户只开企业子账号，不下发任何本地 API Key，只让客户端通过 Key Server 登录、拉取远程配置和上报用量。

```bash
# 1) 用企业管理员账号注册员工账号，或由系统管理员调用接口创建企业用户。

# 2) 紧急封控：系统管理员禁用任意账号
curl -X PUT http://server:3600/api/admin/users/123 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

# 3) 企业管理员禁用本企业子账号
curl -X PUT http://server:3600/api/admin/sub-accounts/123 \
  -H "Authorization: Bearer $ENTERPRISE_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
```

禁用后，`/api/auth/me`、Key 租用、用量上报、云项目同步等受保护接口会拒绝该账号现有 Token。打受控包时可设置 `OMNIAI_DISABLE_PROJECT_EXPORT=1`，在主进程直接禁用项目导出 IPC；也可以在远程配置里下发 `securityPolicy.projectExportDisabled=true`，客户端同步配置后同样会锁定项目导出。

### 7. 启动服务

```bash
# 开发模式
npm run dev

# 生产模式 (PM2)
pm2 start src/index.js --name omniai-server
pm2 save
pm2 startup  # 开机自启
```

### 8. 防火墙

```bash
# 阿里云安全组放开端口 3600 (或你配置的端口)
# 或使用 Nginx 反向代理到 80/443
```

## API 接口

### 认证

```bash
# 登录
curl -X POST http://server:3600/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"alice","password":"password123"}'
# → { "token": "eyJ...", "user": { "id": 1, "username": "alice" } }
```

### Key 获取/释放

```bash
# 获取一个 Key
curl -X POST http://server:3600/api/keys/acquire \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"seedance"}'
# → { "leaseToken": "uuid", "apiKey": "sk-xxx", "provider": "seedance" }

# 用完归还
curl -X POST http://server:3600/api/keys/release \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"leaseToken":"uuid"}'

# 查看状态
curl http://server:3600/api/keys/status?provider=seedance \
  -H "Authorization: Bearer $TOKEN"
```

### 管理接口 (需 admin)

```bash
# 查看所有 Key
curl http://server:3600/api/admin/keys -H "Authorization: Bearer $ADMIN_TOKEN"

# 添加 Key
curl -X POST http://server:3600/api/admin/keys \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"seedance","api_key":"sk-new","label":"新Key","max_concurrency":10}'

# 禁用 Key
curl -X PUT http://server:3600/api/admin/keys/1 \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

# 查看用量日志
curl http://server:3600/api/admin/usage?limit=50 -H "Authorization: Bearer $ADMIN_TOKEN"
```

## 导入配置

将客户端的 settings 模板导入为服务端配置（所有 API key + 模型设置）：

```bash
npm run import-config -- ../resources/templates/settings-default-basic.txt default
```

这样 20 个客户端不需要手动配置任何 key，启动时自动从服务端拉取。

更新配置后，所有客户端下次启动会自动同步最新配置。

### 配置管理 API

```bash
# 获取当前配置
curl http://server:3600/api/config/profile?name=default \
  -H "Authorization: Bearer $TOKEN"

# 更新配置 (需 admin)
curl -X PUT http://server:3600/api/config/profile \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"default","config":{"provider":"gemini","apiKey":"sk-xxx",...}}'

# 列出所有配置
curl http://server:3600/api/config/profiles \
  -H "Authorization: Bearer $TOKEN"
```

## 客户端对接

Electron 客户端设置页只需填写：
- **服务器地址**: `http://your-server:3600`
- **用户名/密码**: 登录获取 Token

客户端启动时自动从服务端同步全部配置（API key、模型、端点等）。

生成视频时：
1. `POST /api/keys/acquire` → 申请并发额度
2. 直连 AI API 生成视频（用服务端下发的 key）
3. `POST /api/keys/release` → 释放额度

Key 集中管理在服务端，客户端不需要手动配置。

## 2026-04 Seedance 并发配置补充

当前客户端已经按两个独立 provider 申请槽位：

- `seedance-2.0`
- `seedance-2.0-fast`

为了保证 `Seedance 2.0` 和 `Seedance 2.0 Fast` 各自独立 `10` 并发，请按下面方式部署：

```bash
# 1. 初始化数据库
npm install
npm run init-db

# 2. 初始化两个独立池
npm run init-pools

# 3. 查看池状态
npm run list-keys
```

建议部署要求：

- `seedance-2.0` 总容量固定为 `10`
- `seedance-2.0-fast` 总容量固定为 `10`
- 两个 provider 不能混用，也不能共用同一池
- 当某个 provider 达到上限时，客户端会显示“排队中”

获取槽位示例：

```bash
curl -X POST http://server:3600/api/keys/acquire \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"seedance-2.0"}'

curl -X POST http://server:3600/api/keys/acquire \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider":"seedance-2.0-fast"}'
```