系统配置要求

<title>系统配置要求</title>

# 系统配置要求

本文档说明运行 ZJT Server 的硬件和软件配置要求。

> **重要说明**：本服务仅作为接口调用的中间层，视频生成、LLM 等计算密集型任务均由外部 API 服务完成。因此服务本身对硬件要求较低。

---

## 部署模式说明

### 单机版（个人使用）

- 适用场景：个人开发、测试、小规模内容创作
- 用户数量：1-3 账号
- 部署方式：本机直接运行

### 多用户版（团队使用）

- 适用场景：团队协作、工作室、商业部署
- 用户数量：10+ 账号
- 部署方式：独立服务器 + 多客户端访问

---

## 单机版配置要求

### 最低配置（仅满足基本运行）

| 组件 | 最低要求 |
|-|-|
| **操作系统** | Windows 10 64位 / Windows 11 64位 / Ubuntu 20.04+ |
| **CPU** | 双核 2.0 GHz+ |
| **内存** | 2 GB RAM |
| **存储空间** | 5 GB 可用空间 |
| **网络** | 稳定互联网连接（调用外部 API 必需） |

### 推荐配置（流畅运行）

| 组件 | 推荐要求 |
|-|-|
| **操作系统** | Windows 11 64位 / Ubuntu 22.04+ |
| **CPU** | 四核 2.5 GHz+ |
| **内存** | 4 GB RAM |
| **存储空间** | 10 GB+ 可用空间（SSD） |
| **网络** | 稳定宽带连接 |

---

## 多用户版配置要求

### 最低配置（团队小规模使用）

| 组件 | 最低要求 |
|-|-|
| **操作系统** | Windows 11 64位/Windows Server 2019+ / Ubuntu 20.04 LTS+ |
| **CPU** | 4 核 |
| **内存** | 8 GB RAM |
| **存储空间** | 50 GB+ 可用空间 |
| **网络** | 稳定网络连接 |
| **带宽** | 上行/下行各 10 Mbps+ |

### 推荐配置（企业级部署）

| 组件 | 推荐要求 |
|-|-|
| **操作系统** | Windows 11 64位/Ubuntu 22.04 LTS+ / |
| **CPU** | 8 核+ |
| **内存** | 16 GB RAM+ |
| **存储空间** | 100 GB+ 可用空间（SSD） |
| **网络** | 稳定网络连接 |
| **带宽** | 上行/下行各 100 Mbps+ |
| **负载均衡** | 建议配置 Nginx 反向代理 |
| **备份** | 定期备份策略（数据库 + 用户文件） |

> 企业级配置支持高并发访问和 50+ 用户同时在线。

---

## 资源消耗说明

### CPU 消耗

| 场景 | CPU 占用 |
|-|-|
| 系统空闲 | < 1% |
| API 响应处理 | 1-5% |
| 多用户并发 | 5-20% |

> **注意**：视频生成、图片生成等计算任务由外部 API 处理，不占用本机 CPU。

### 内存消耗

| 组件 | 内存占用（估算） |
|-|-|
| 基础服务进程 | 200-500 MB |
| 数据库 | 500 MB - 1 GB（随数据量增长） |
| 每个活跃用户会话 | 10-50 MB |

### 存储空间

| 数据类型 | 空间消耗（估算） |
|-|-|
| 系统文件 | 500 MB - 1 GB |
| 数据库（空） | 50 MB |
| 用户上传文件 | 根据使用情况 |

---

## 网络要求

### 单机版

- **最低**：稳定宽带连接，下载速度 > 10 Mbps
- **推荐**：宽带连接，上传/下载速度均 > 50 Mbps
- **用途**：调用外部 API（LLM、TTS、视频生成服务）

### 多用户版

- **最低**：服务器上行/下行各 10 Mbps
- **推荐**：服务器上行/下行各 100 Mbps
- **其他**：

  - 建议配置静态 IP 或域名
  - 考虑 CDN 加速（可搭配对象存储服务）
  - 配置防火墙规则（仅开放必要端口）

---

## 端口配置

| 端口角色 | 协议 | 说明 |
|-|-|-|
| 主端口 | HTTP | Web 服务主端口，具体端口号可在配置文件中配置 |
| 安全端口（可选） | HTTPS | Web 服务安全访问端口，具体端口号可在配置文件中配置 |

> **注意**：多用户部署时，建议仅对外开放 Web 服务端口，其他端口配置防火墙限制。

---

## 部署建议

### 单机版部署

1. **安装 MySQL**：使用项目自带的 `bin/mysql` 目录
2. **配置环境变量**：设置 `PYTHONUTF8=1`（Windows）
3. **双击启动**：运行 `start.bat` 或 `点我启动.bat`
4. **访问地址**：`http://localhost`（默认端口，可在配置文件中修改）

### 多用户版部署

1. **选择服务器**：使用云服务器或自建服务器
2. **配置环境**：安装 Python 3.10、MySQL 8.0+
3. **服务管理**：使用 systemd/supervisor 管理服务进程
4. **反向代理**：配置 Nginx 处理 HTTPS、负载均衡
5. **监控告警**：配置日志监控和异常告警（如 Sentry）
6. **备份策略**：定期备份数据库和用户文件

---

## 性能优化建议

### 单机版

1. 使用 SSD 存储数据和日志
2. 定期清理 `logs/` 目录日志文件

### 多用户版

1. **应用层优化**：

   - 使用 gunicorn 多 Worker 模式（Windows 环境使用 uvicorn，由 `scripts/running/run_prod.py` 按平台自动选择）
2. **监控**：

   - 配置 Prometheus + Grafana 监控
   - 使用 Sentry 收集错误日志

---

## 故障排查

### 内存不足

- 症状：服务响应慢
- 解决：增加内存、清理缓存

### 磁盘空间不足

- 症状：无法上传文件、生成任务失败
- 解决：清理 `files/` 目录、迁移到更大存储、启用云存储

### 数据库连接池耗尽

- 症状：大量 500 错误、响应超时
- 解决：增加 MySQL `max_connections`、优化查询、增加连接池大小

---

## 附录：并发配置参考

### 关于 max_concurrent_slots 配置

视频生成服务配置项中的 `max_concurrent_slots` 参数**不与服务器硬件性能相关**，而是根据您为视频生成服务购买的并发套餐来确定。每个套餐有对应的并发任务上限，请根据您的套餐设置此值（第三方服务配置项详见配置文件）。

### 单机版并发配置

```YAML
# config.yml
# max_concurrent_slots 位于配置文件中第三方视频生成服务配置段下
max_concurrent_slots: 3  # 根据视频生成服务的并发套餐设置

workflow:
  poll_status_interval: 30  # 轮询间隔（秒）
```

### 多用户版并发配置

```YAML
# config.yml
# max_concurrent_slots 位于配置文件中第三方视频生成服务配置段下
max_concurrent_slots: 10  # 根据视频生成服务的并发套餐设置

task_queue:
  max_retry_count: 50  # 增加重试次数
  task_expire_days: 14  # 延长任务有效期

workflow:
  poll_status_interval: 15  # 更频繁轮询
```

---

> **更新时间**：2026-03-09