# AI 克隆系统部署文档

本文档面向运维/交付人员，描述后端、管理端、uni-app/小程序的部署方式。

## 1. 部署拓扑（推荐）

- 后端（Spring Boot）部署在一台服务器（或容器）上，对外提供 HTTP API。
- 管理端（`admin/dist`）部署为静态站点：
  - 方案 A：Nginx 提供静态文件（推荐）
  - 方案 B：`pm2 serve` 提供静态文件（简化，无 Nginx）
- uni-app/小程序不直接部署在服务器上（小程序发布到对应平台），只需正确配置后端 API 地址。

## 2. 后端部署（Linux 服务器）

### 2.1 环境要求

- JDK：**8**（与 `ai-clone/pom.xml` 保持一致）
- Maven：如需在服务器编译（推荐本地/CI 编译后上传 jar）
- MySQL：8.x（或已有外部 MySQL）
- 可选：FFmpeg（如视频合成链路依赖，需以实际实现为准）

### 2.2 配置准备

后端配置文件：`ai-clone/src/main/resources/application.properties`

部署前请将以下配置替换为生产值（建议通过外置配置或环境变量注入，避免明文进入代码仓库）：

- `dashscope.api.key`
- `spring.datasource.*`
- `wechat.mini.*`
- `aliyun.sms.*`
- `filehosting.local.path`、`filehosting.url.prefix`
- `server.port`（默认 20002）

### 2.3 打包

在项目目录 `ai-clone/` 执行：

```bash
mvn -U clean package
```

生成：`ai-clone/target/voice-cloning-1.0.0.jar`

### 2.4 运行

#### 方式 A：直接运行（适合临时）

```bash
java -jar voice-cloning-1.0.0.jar \
  --server.port=20002
```

#### 方式 B：使用仓库脚本（示例）

仓库根目录提供了 `start.sh`（示例生产脚本），包含：

- 停止旧进程（PID 文件）
- 释放端口
- 创建目录（logs/static/temp/uploads 等）
- `nohup java -jar ...` 后台启动

注意：`start.sh` 中 `PROJECT_DIR`、`PORT`、`JAVA_BIN`、`SPRING_PROFILE` 需要按你的服务器实际路径/Java 版本调整。

### 2.5 端口与防火墙

- 默认端口：`20002`
- 需要在：
  - 服务器防火墙
  - 云厂商安全组
  放行对应 TCP 端口。

### 2.6 验证

- `GET http://<host>:20002/api/voice/health`

期望返回：`{"status":"ok", ...}`

## 3. 管理端部署（admin）

管理端现有详细文档：

- `admin/部署说明.md`
- `admin/宝塔部署指南.md`

这里给出标准化流程（推荐 Nginx 方案）。

### 3.1 本地构建

```bash
# 进入管理端
cd admin
npm install
npm run build
```

产物目录：`admin/dist/`

### 3.2 上传

将 `dist/` 上传到服务器站点目录，例如：

- `/www/wwwroot/fh.admin-ai.cloud/`

### 3.3 Nginx 配置（示例）

> 说明：端口/域名/路径按实际替换。

```nginx
server {
    listen 80;
    server_name <admin-domain>;

    root /www/wwwroot/<admin-site>/;
    index index.html;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # 可选：同域名转发后端（避免跨域）
    location /api {
        proxy_pass http://127.0.0.1:20002;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### 3.4 配置管理端 API 地址

管理端使用 `.env.production` 指定 `VITE_API_BASE`，但该文件当前在仓库中可能被 `.gitignore` 忽略。

部署时请确认：

- `VITE_API_BASE=http(s)://<backend-host>:20002`

若采用 Nginx 同域 `/api` 反代，则可配置为相对路径：

- `VITE_API_BASE=/api`

## 4. uni-app / 小程序（frontend-ai）

### 4.1 API 地址配置

配置文件：`frontend-ai/config/api.js`

- 开发/生产环境的 `API_BASE` 可切换
- 说明文档：`frontend-ai/config/README.md`

### 4.2 打包发布

按 uni-app / HBuilderX 的标准流程：

- 小程序：构建后上传微信公众平台审核发布
- App：云打包/本地打包发布

服务器侧只需保证：

- 后端域名/端口可访问
- HTTPS（如小程序要求）

## 5. 常见问题与排障

- **页面刷新 404（管理端 SPA）**
  - Nginx 需配置：`try_files $uri $uri/ /index.html;`
- **API 请求失败**
  - 检查后端是否启动、端口是否放行、域名解析是否正确
  - 若跨域：检查后端 CORS 或通过 Nginx 反代统一域
- **后端静态资源无法访问**
  - 检查 `spring.web.resources.static-locations`、`filehosting.local.path` 与服务器实际目录一致
- **配置泄露风险**
  - 生产环境请移除/替换明文 Key、数据库密码，并通过环境变量或外置配置管理