# GovAI 硬件部署要求

本文档定义 GovAI（政智通）政务AI智能应用平台的硬件部署要求，适用于不同规模的部署场景。

---

## 系统组件概览

| 组件 | 技术栈 | 说明 |
|------|--------|------|
| 后端服务 | Go 1.25+ | REST API，处理业务逻辑 |
| 前端 | Next.js 16 + React 19 | 用户界面（SSR/SSG） |
| PPT Worker | Python + FastAPI | 异步 PPT 生成微服务 |
| 数据库 | PostgreSQL 17 (pgvector) | 关系数据 + 向量检索 |
| 缓存 | Redis 7 | 会话、队列、限流 |
| 对象存储 | MinIO | 文档、图片等文件存储 |

---

## 场景一：开发 / 最小化部署

适用：本地开发调试、个人使用、Demo 演示。

| 资源项 | 最低要求 | 推荐配置 |
|--------|---------|---------|
| **CPU** | 4 核 | 8 核 |
| **内存** | 8 GB | 16 GB |
| **磁盘** | 50 GB | 100 GB+ |
| **操作系统** | macOS 12+ / Linux / Windows (WSL2) | — |

所有服务（Go 后端、Next.js 前端、PPT Worker、PostgreSQL、Redis、MinIO）可在单台机器上通过 Docker Compose 一键启动。

---

## 场景二：单服务器生产部署（50 ~ 100 用户）

适用：50 ~ 100 人规模的小型单位（如科室、局委办），全部服务集中部署于一台物理服务器或虚拟机。

### 推荐配置

| 资源项 | 最低要求 | 推荐配置 |
|--------|---------|---------|
| **CPU** | 8 核 | 16 核 |
| **内存** | 16 GB | 32 GB |
| **系统盘** | 100 GB SSD | 200 GB SSD |
| **数据盘** | 300 GB SSD | 500 GB SSD |
| **操作系统** | Linux (Ubuntu 22.04+ / CentOS 8+) | — |

### 资源分配方案

| 组件 | 资源占用 | 说明 |
|------|---------|------|
| Go 后端 | 2 核 + 1 GB 内存 | 2 实例 |
| Next.js 前端 | 2 核 + 1 GB 内存 | 1 实例 |
| PostgreSQL | 2 核 + 8 GB 内存 | 含 pgvector，SSD 存储 |
| Redis | 1 核 + 2 GB 内存 | 会话 + 队列 |
| MinIO | 1 核 + 2 GB 内存 | 文档/图片存储（~200 GB） |
| PPT Worker | 2~4 核 + 8 GB 内存 | 1 实例，按需生成 PPT |
| **系统预留** | 2~4 核 + 4~8 GB | 内核、SSH、Docker 等开销 |

### 性能预估

| 指标 | 数值 |
|------|------|
| 并发用户 | 50 ~ 100 |
| 预估 QPS | 100 ~ 300 req/s |
| 同时 PPT 生成 | 1 ~ 3 个 |
| 每日活跃用户 | 占总用户 30%~50% |
| 月数据增量 | ~1 GB（100 用户场景） |
| 存储规划 | 500 GB SSD 可用约 3~5 年 |

### 部署方式

推荐使用 Docker Compose 在该服务器上一键启动所有容器：

```bash
# 基础设施（PostgreSQL + Redis + MinIO）
docker compose -f docker/docker-compose.yml up -d

# 后端
cd server && go run ./cmd/server

# 前端
cd apps/web && npm run dev    # 开发模式
# 或 npm run build && npm start  # 生产模式

# PPT Worker
make dev-ppt
```

### 注意事项

- **CPU 敏感**：PPT Worker 在文档解析和渲染时 CPU 占用较高，如并发使用建议提升至 16 核
- **内存峰值**：PPT 生成期间内存可能瞬时冲高到 12 GB+，建议保留足够 swap 或选用 32 GB 配置
- **网络**：服务器需访问通义千问/ OpenAI API，建议带宽 20 Mbps+
- **备份**：数据盘建议配置 RAID 或定期快照备份

---

## 场景三：多服务器生产（50 ~ 200 并发用户）

适用：部门级或区县级部署，支撑日常政务办公。

### 服务器规划（3 台）

| 服务器 | 部署内容 | CPU | 内存 | 系统盘 | 数据盘 |
|--------|---------|-----|------|--------|--------|
| **Server A** | Go 后端（2~4 实例） + Redis 主 | 8 核 | 16 GB | 100 GB SSD | — |
| **Server B** | PostgreSQL 主库 + MinIO 主 | 8 核 | 16 GB | 100 GB SSD | 500 GB SSD |
| **Server C** | PPT Worker（2 实例） + 渲染队列 | 8 核 | 16 GB | 100 GB SSD | 200 GB SSD |

### 组件级配置明细

#### Go 后端服务

| 项目 | 配置 |
|------|------|
| 实例数 | 2 ~ 4（水平扩展） |
| 内存单实例 | ~200 MB |
| 并发承载 | 单实例约 50 ~ 100 并发（CPU-bound） |
| 连接池 | PostgreSQL 最多 25 连接 / 实例 |
| 预估总 QPS | 200 ~ 500 req/s |
| 建议资源 | 8 核 16 GB 服务器，容器/进程管理 |

#### Next.js 前端

| 项目 | 配置 |
|------|------|
| 部署模式 | `next start`（Node.js 生产模式）或容器化 |
| 内存单实例 | ~500 MB ~ 1 GB |
| 建议资源 | 独立 4 核 8 GB 服务器（或与后端混部） |
| CDN 加速 | 建议接入 CDN 加速静态资源和图片 |

#### PPT Worker（Python 微服务）

| 项目 | 配置 |
|------|------|
| 实例数 | 2 |
| 内存单实例 | 峰值可达 4 GB（文档解析、PPT 渲染） |
| 并发任务 | 单实例约 5 ~ 10 个任务并行 |
| 建议资源 | 8 核 16 GB 服务器（CPU 密集型） |
| 临时存储 | 每个任务约 50 ~ 200 MB 临时文件，需定期清理 |

#### PostgreSQL（pgvector）

| 项目 | 配置 |
|------|------|
| 版本 | PostgreSQL 17 + pgvector |
| 并发连接 | 最大 100 ~ 150 连接 |
| 共享缓冲 | 建议 4 ~ 8 GB（总内存的 25%~50%） |
| 建议资源 | 8 核 16 GB 服务器，SSD 存储 |
| 数据量预估 | 50 用户每日产生 ~1 GB 数据/月，500 GB SSD 可用 3 年+ |
| 高可用 | 可选主从流复制（2 台） |

#### Redis

| 项目 | 配置 |
|------|------|
| 内存 | 2 ~ 4 GB |
| 持久化 | 建议开启 RDB + AOF |
| 建议资源 | 与后端同机或独立 2 核 4 GB |
| 高可用 | 可选 Sentinel（1 主 2 从） |

#### MinIO（对象存储）

| 项目 | 配置 |
|------|------|
| 存储量 | 200 GB ~ 1 TB（视知识库文档量） |
| 建议资源 | 与 PostgreSQL 同机或独立 4 核 8 GB |
| 冗余 | 建议 2 节点以上，纠删码模式 |

### 中等规模汇总

| 类别 | 数量 | 规格 | 用途 |
|------|------|------|------|
| 应用服务器 | 1~2 | 8 核 16 GB | Go 后端 + 前端（可混部） |
| 数据库服务器 | 1 | 8 核 16 GB + 500 GB SSD | PostgreSQL + MinIO |
| PPT Worker 服务器 | 1 | 8 核 16 GB | PPT 生成 |
| **合计** | **3~4 台** | — | — |

### 网络要求

- 服务器之间内网带宽：**千兆（1 Gbps）** 推荐
- 对外带宽：**50 Mbps ~ 100 Mbps**（视 AI API 调用量）
- AI API 延迟：后端到通义千问/OpenAI 的 RTT 建议 < 200 ms
- 端口：前端 3000、后端 8080、PPT Worker 8090、PostgreSQL 5432、Redis 6379、MinIO 9000/9001

---

## 场景三：大规模 / 高可用分布式（200+ 并发用户）

适用：市级或省级平台，多机构、海量用户。

### 推荐架构

```
                    ┌──────────────┐
                    │   负载均衡    │  (Nginx / 云 LB)
                    │  (2 台冗余)  │
                    └──────┬───────┘
           ┌───────────────┼───────────────┐
           │               │               │
    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
    │  Go 后端     │ │  Go 后端     │ │  Go 后端     │
    │  (多实例)    │ │  (多实例)    │ │  (多实例)    │
    │  4~8 实例    │ │  4~8 实例    │ │  4~8 实例    │
    └──────┬──────┘ └──────┬──────┘ └──────┬──────┘
           │               │               │
    ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
    │ PostgreSQL  │ │ PostgreSQL  │ │  Redis      │
    │  主库        │ │  从库(只读)  │ │  Cluster    │
    └──────┬──────┘ └──────┬──────┘ └─────────────┘
           │
    ┌──────▼──────┐ ┌──────▼──────┐
    │ MinIO 集群  │ │ PPT Worker  │
    │ (纠删码)    │ │ (4~8 实例)  │
    └─────────────┘ └─────────────┘
```

### 资源配置

| 组件 | 节点数 | 单节点规格 | 存储 |
|------|--------|---------|------|
| 负载均衡器 | 2 | 4 核 8 GB | — |
| Go 后端 | 6~12 | 8 核 16 GB | — |
| PostgreSQL 主库 | 1 | 16 核 32 GB | 1 TB SSD |
| PostgreSQL 从库 | 2 | 16 核 32 GB | 1 TB SSD |
| Redis Cluster | 6 节点 | 4 核 8 GB | — |
| MinIO 集群 | 4 | 8 核 16 GB | 4×1 TB |
| PPT Worker | 4~8 | 8 核 16 GB | 200 GB SSD |
| **服务器合计** | **约 20+ 台** | — | — |

---

## 软件环境总览

| 软件 | 版本 | 用途 |
|------|------|------|
| Go | 1.25+ | 后端运行时 |
| Node.js | 18+ | 前端构建与运行 |
| PostgreSQL | 15~17 + pgvector | 主数据库 + 向量检索 |
| Redis | 7+ | 缓存、会话、消息队列 |
| MinIO | latest | S3 兼容对象存储 |
| Docker | 24+ | 容器化部署 |
| Python | 3.10+ | PPT Worker 运行时 |

---

## AI API 说明

GovAI 的 AI 能力依赖外部大模型服务（通义千问 / OpenAI 兼容接口），**不占用服务器本地算力**。

- 默认使用通义千问（`qwen-max`）
- 通过 `OPENAI_BASE_URL` 配置可切换为 OpenAI、Claude 等
- 网络要求：服务器需访问互联网，建议延迟 < 200 ms
- API 成本：按调用量计费，与硬件无关

---

## 快速参考对照表

| 场景 | 用户规模 | 并发 | 服务器数量 | 单机规格 |
|------|---------|------|-----------|---------|
| 开发调试 | 1~5 | < 10 | 1 台 | 8 核 16 GB |
| **单服务器生产** | **50 ~ 100** | **50 ~ 100** | **1 台** | **8 核 16 GB ~ 16 核 32 GB** |
| 多服务器生产 | 50 ~ 200 | 50 ~ 200 | 3~4 台 | 8 核 16 GB |
| 大规模高可用 | 200+ | 200+ | 20+ 台 | 8~16 核 16~32 GB |