556 lines
11 KiB
Markdown
556 lines
11 KiB
Markdown
# 部署与运行说明文档
|
||
|
||
本文档详细说明 Finyx AI Prototype 项目的部署和运行流程。
|
||
|
||
## 📋 目录
|
||
|
||
- [环境准备](#环境准备)
|
||
- [本地开发](#本地开发)
|
||
- [生产构建](#生产构建)
|
||
- [部署方式](#部署方式)
|
||
- [静态文件部署](#静态文件部署)
|
||
- [Docker 部署](#docker-部署)
|
||
- [Nginx 配置](#nginx-配置)
|
||
- [环境变量配置](#环境变量配置)
|
||
- [常见问题](#常见问题)
|
||
|
||
## 🔧 环境准备
|
||
|
||
### 系统要求
|
||
|
||
- **操作系统**: Linux / macOS / Windows
|
||
- **Node.js**: >= 16.0.0 (推荐使用 LTS 版本)
|
||
- **npm**: >= 7.0.0 或 **yarn**: >= 1.22.0
|
||
- **内存**: 至少 2GB 可用内存
|
||
- **磁盘空间**: 至少 500MB 可用空间
|
||
|
||
### 检查环境
|
||
|
||
```bash
|
||
# 检查 Node.js 版本
|
||
node -v
|
||
# 应显示 v16.x.x 或更高版本
|
||
|
||
# 检查 npm 版本
|
||
npm -v
|
||
# 应显示 7.x.x 或更高版本
|
||
```
|
||
|
||
### 安装 Node.js（如未安装）
|
||
|
||
#### Linux (Ubuntu/Debian)
|
||
```bash
|
||
# 使用 NodeSource 仓库安装
|
||
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
```
|
||
|
||
#### macOS
|
||
```bash
|
||
# 使用 Homebrew
|
||
brew install node
|
||
```
|
||
|
||
#### Windows
|
||
从 [Node.js 官网](https://nodejs.org/) 下载安装包并安装
|
||
|
||
## 💻 本地开发
|
||
|
||
### 1. 克隆项目
|
||
|
||
```bash
|
||
git clone <repository-url>
|
||
cd finyx_data_frontend
|
||
```
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
如果安装速度慢，可以使用国内镜像：
|
||
|
||
```bash
|
||
# 使用淘宝镜像
|
||
npm install --registry=https://registry.npmmirror.com
|
||
|
||
# 或使用 cnpm
|
||
npm install -g cnpm --registry=https://registry.npmmirror.com
|
||
cnpm install
|
||
```
|
||
|
||
### 3. 启动开发服务器
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
启动成功后，终端会显示：
|
||
|
||
```
|
||
VITE v5.x.x ready in xxx ms
|
||
|
||
➜ Local: http://localhost:5173/
|
||
➜ Network: http://192.168.x.x:5173/
|
||
```
|
||
|
||
可以通过以下方式访问：
|
||
- **本地访问**: `http://localhost:5173`
|
||
- **局域网访问**: 使用终端显示的 Network 地址（例如：`http://192.168.1.100:5173`）
|
||
|
||
**注意**: 开发服务器已配置为允许外部访问，可以通过局域网 IP 地址访问，方便移动设备测试或远程调试。
|
||
|
||
### 4. 开发模式特性
|
||
|
||
- **热模块替换 (HMR)**: 代码修改后自动刷新
|
||
- **快速构建**: Vite 提供极速的开发体验
|
||
- **TypeScript 支持**: 实时类型检查
|
||
- **ESLint 检查**: 代码质量检查
|
||
|
||
### 5. 修改端口和主机配置（如需要）
|
||
|
||
如果 5173 端口被占用，可以通过以下方式修改：
|
||
|
||
**方式一：命令行参数**
|
||
```bash
|
||
# 修改端口
|
||
npm run dev -- --port 3000
|
||
|
||
# 指定主机（允许外部访问）
|
||
npm run dev -- --host 0.0.0.0 --port 3000
|
||
```
|
||
|
||
**方式二：修改 vite.config.ts**
|
||
```typescript
|
||
export default defineConfig({
|
||
server: {
|
||
host: '0.0.0.0', // 允许外部访问
|
||
port: 3000, // 自定义端口
|
||
strictPort: false, // 端口被占用时自动尝试下一个
|
||
}
|
||
})
|
||
```
|
||
|
||
**获取本机 IP 地址**:
|
||
```bash
|
||
# Linux/macOS
|
||
ip addr show | grep "inet " | grep -v 127.0.0.1
|
||
# 或
|
||
ifconfig | grep "inet " | grep -v 127.0.0.1
|
||
|
||
# Windows
|
||
ipconfig
|
||
# 查找 IPv4 地址
|
||
```
|
||
|
||
## 🏗️ 生产构建
|
||
|
||
### 1. 构建生产版本
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
构建完成后，会在 `dist/` 目录生成优化后的静态文件：
|
||
|
||
```
|
||
dist/
|
||
├── index.html
|
||
├── assets/
|
||
│ ├── index-[hash].js
|
||
│ ├── index-[hash].css
|
||
│ └── ...
|
||
```
|
||
|
||
### 2. 预览生产构建
|
||
|
||
在部署前，可以本地预览生产版本：
|
||
|
||
```bash
|
||
npm run preview
|
||
```
|
||
|
||
访问 `http://localhost:4173` 查看预览效果。
|
||
|
||
### 3. 构建优化
|
||
|
||
生产构建已自动启用以下优化：
|
||
- 代码压缩和混淆
|
||
- Tree-shaking（移除未使用代码）
|
||
- 资源压缩（CSS、JS）
|
||
- 代码分割（按需加载）
|
||
|
||
## 🚀 部署方式
|
||
|
||
### 静态文件部署
|
||
|
||
#### 方式一：直接部署 dist 目录
|
||
|
||
1. **构建项目**
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
2. **上传 dist 目录**
|
||
将 `dist/` 目录下的所有文件上传到 Web 服务器
|
||
|
||
3. **配置 Web 服务器**
|
||
参考下面的 [Nginx 配置](#nginx-配置)
|
||
|
||
#### 方式二：使用 CI/CD 自动部署
|
||
|
||
**GitHub Actions 示例** (`.github/workflows/deploy.yml`):
|
||
|
||
```yaml
|
||
name: Deploy
|
||
|
||
on:
|
||
push:
|
||
branches: [ main ]
|
||
|
||
jobs:
|
||
build-and-deploy:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v3
|
||
|
||
- name: Setup Node.js
|
||
uses: actions/setup-node@v3
|
||
with:
|
||
node-version: '18'
|
||
|
||
- name: Install dependencies
|
||
run: npm install
|
||
|
||
- name: Build
|
||
run: npm run build
|
||
|
||
- name: Deploy
|
||
uses: peaceiris/actions-gh-pages@v3
|
||
with:
|
||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||
publish_dir: ./dist
|
||
```
|
||
|
||
### Docker 部署
|
||
|
||
#### 1. 创建 Dockerfile
|
||
|
||
在项目根目录创建 `Dockerfile`:
|
||
|
||
```dockerfile
|
||
# 构建阶段
|
||
FROM node:18-alpine AS builder
|
||
|
||
WORKDIR /app
|
||
|
||
# 复制 package 文件
|
||
COPY package*.json ./
|
||
|
||
# 安装依赖
|
||
RUN npm ci
|
||
|
||
# 复制源代码
|
||
COPY . .
|
||
|
||
# 构建应用
|
||
RUN npm run build
|
||
|
||
# 生产阶段
|
||
FROM nginx:alpine
|
||
|
||
# 复制构建产物到 nginx
|
||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||
|
||
# 复制 nginx 配置
|
||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
||
|
||
EXPOSE 80
|
||
|
||
CMD ["nginx", "-g", "daemon off;"]
|
||
```
|
||
|
||
#### 2. 创建 .dockerignore
|
||
|
||
```
|
||
node_modules
|
||
dist
|
||
.git
|
||
.env
|
||
*.log
|
||
.DS_Store
|
||
```
|
||
|
||
#### 3. 构建和运行 Docker 容器
|
||
|
||
```bash
|
||
# 构建镜像
|
||
docker build -t finyx-frontend .
|
||
|
||
# 运行容器
|
||
docker run -d -p 80:80 --name finyx-app finyx-frontend
|
||
```
|
||
|
||
#### 4. 使用 Docker Compose
|
||
|
||
创建 `docker-compose.yml`:
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
frontend:
|
||
build: .
|
||
ports:
|
||
- "80:80"
|
||
restart: unless-stopped
|
||
volumes:
|
||
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
|
||
```
|
||
|
||
运行：
|
||
```bash
|
||
docker-compose up -d
|
||
```
|
||
|
||
### Nginx 配置
|
||
|
||
创建 `nginx.conf` 文件：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
root /usr/share/nginx/html;
|
||
index index.html;
|
||
|
||
# Gzip 压缩
|
||
gzip on;
|
||
gzip_vary on;
|
||
gzip_min_length 1024;
|
||
gzip_types text/plain text/css text/xml text/javascript application/javascript application/xml+rss application/json;
|
||
|
||
# 静态资源缓存
|
||
location ~* \.(jpg|jpeg|png|gif|ico|css|js|svg|woff|woff2|ttf|eot)$ {
|
||
expires 1y;
|
||
add_header Cache-Control "public, immutable";
|
||
}
|
||
|
||
# SPA 路由支持
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
|
||
# 安全头
|
||
add_header X-Frame-Options "SAMEORIGIN" always;
|
||
add_header X-Content-Type-Options "nosniff" always;
|
||
add_header X-XSS-Protection "1; mode=block" always;
|
||
|
||
# 错误页面
|
||
error_page 404 /index.html;
|
||
}
|
||
```
|
||
|
||
部署到服务器：
|
||
|
||
```bash
|
||
# 复制配置文件
|
||
sudo cp nginx.conf /etc/nginx/sites-available/finyx-frontend
|
||
|
||
# 创建软链接
|
||
sudo ln -s /etc/nginx/sites-available/finyx-frontend /etc/nginx/sites-enabled/
|
||
|
||
# 测试配置
|
||
sudo nginx -t
|
||
|
||
# 重启 Nginx
|
||
sudo systemctl restart nginx
|
||
```
|
||
|
||
## 🔐 环境变量配置
|
||
|
||
### 开发环境
|
||
|
||
创建 `.env.development`:
|
||
|
||
```env
|
||
VITE_API_BASE_URL=http://localhost:3000/api
|
||
VITE_APP_TITLE=Finyx AI Prototype (Dev)
|
||
```
|
||
|
||
### 生产环境
|
||
|
||
创建 `.env.production`:
|
||
|
||
```env
|
||
VITE_API_BASE_URL=https://api.yourdomain.com
|
||
VITE_APP_TITLE=Finyx AI Prototype
|
||
```
|
||
|
||
### 使用环境变量
|
||
|
||
在代码中使用：
|
||
|
||
```typescript
|
||
const apiUrl = import.meta.env.VITE_API_BASE_URL;
|
||
```
|
||
|
||
**注意**: Vite 要求环境变量必须以 `VITE_` 开头才能在客户端代码中访问。
|
||
|
||
## ❓ 常见问题
|
||
|
||
### 1. 端口被占用
|
||
|
||
**问题**: `Error: Port 5173 is already in use`
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 查找占用端口的进程
|
||
lsof -i :5173 # macOS/Linux
|
||
netstat -ano | findstr :5173 # Windows
|
||
|
||
# 杀死进程或使用其他端口
|
||
npm run dev -- --port 3000
|
||
```
|
||
|
||
### 1.1 无法通过 IP 地址访问
|
||
|
||
**问题**: 只能通过 localhost 访问，无法通过局域网 IP 地址访问
|
||
|
||
**解决方案**:
|
||
1. **检查配置**: 确保 `vite.config.ts` 中 `server.host` 设置为 `'0.0.0.0'`（已默认配置）
|
||
2. **检查防火墙**: 确保防火墙允许端口访问
|
||
```bash
|
||
# Ubuntu/Debian
|
||
sudo ufw allow 5173/tcp
|
||
sudo ufw reload
|
||
|
||
# CentOS/RHEL
|
||
sudo firewall-cmd --add-port=5173/tcp --permanent
|
||
sudo firewall-cmd --reload
|
||
|
||
# macOS (如果启用了防火墙)
|
||
# 系统偏好设置 > 安全性与隐私 > 防火墙 > 防火墙选项
|
||
```
|
||
3. **检查网络**: 确保设备在同一局域网内
|
||
4. **获取本机 IP**:
|
||
```bash
|
||
# Linux/macOS
|
||
ip addr show | grep "inet " | grep -v 127.0.0.1
|
||
# 或
|
||
hostname -I # Linux
|
||
ifconfig | grep "inet " | grep -v 127.0.0.1 # macOS
|
||
|
||
# Windows
|
||
ipconfig
|
||
# 查找 IPv4 地址（通常是 192.168.x.x 或 10.x.x.x）
|
||
```
|
||
5. **使用 Network 地址**: 启动开发服务器后，终端会显示 Network 地址，使用该地址访问
|
||
|
||
### 2. 依赖安装失败
|
||
|
||
**问题**: `npm install` 失败或很慢
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 清除 npm 缓存
|
||
npm cache clean --force
|
||
|
||
# 删除 node_modules 和 package-lock.json 重新安装
|
||
rm -rf node_modules package-lock.json
|
||
npm install
|
||
|
||
# 或使用国内镜像
|
||
npm install --registry=https://registry.npmmirror.com
|
||
```
|
||
|
||
### 3. 构建失败
|
||
|
||
**问题**: `npm run build` 报错
|
||
|
||
**解决方案**:
|
||
- 检查 Node.js 版本是否符合要求
|
||
- 清除缓存和依赖重新安装
|
||
- 检查 TypeScript 类型错误：`npm run lint`
|
||
|
||
### 4. 路由刷新 404
|
||
|
||
**问题**: 刷新页面后出现 404
|
||
|
||
**解决方案**:
|
||
确保 Web 服务器配置了 SPA 路由支持（参考上面的 Nginx 配置）
|
||
|
||
### 5. 跨域问题
|
||
|
||
**问题**: 开发时 API 请求跨域
|
||
|
||
**解决方案**: 在 `vite.config.ts` 中配置代理：
|
||
|
||
```typescript
|
||
export default defineConfig({
|
||
server: {
|
||
proxy: {
|
||
'/api': {
|
||
target: 'http://localhost:3000',
|
||
changeOrigin: true,
|
||
rewrite: (path) => path.replace(/^\/api/, '')
|
||
}
|
||
}
|
||
}
|
||
})
|
||
```
|
||
|
||
### 6. 内存不足
|
||
|
||
**问题**: 构建时内存溢出
|
||
|
||
**解决方案**:
|
||
```bash
|
||
# 增加 Node.js 内存限制
|
||
NODE_OPTIONS="--max-old-space-size=4096" npm run build
|
||
```
|
||
|
||
## 📊 性能优化建议
|
||
|
||
### 1. 代码分割
|
||
- 使用 React.lazy() 进行路由级别的代码分割
|
||
- 按需加载大型组件库
|
||
|
||
### 2. 资源优化
|
||
- 压缩图片资源
|
||
- 使用 WebP 格式
|
||
- 启用 CDN 加速静态资源
|
||
|
||
### 3. 缓存策略
|
||
- 配置合理的 HTTP 缓存头
|
||
- 使用 Service Worker 进行离线缓存
|
||
|
||
### 4. 监控和分析
|
||
- 集成性能监控工具（如 Sentry）
|
||
- 使用 Web Vitals 监控核心指标
|
||
|
||
## 🔍 健康检查
|
||
|
||
部署后，可以通过以下方式检查应用状态：
|
||
|
||
```bash
|
||
# 检查 HTTP 响应
|
||
curl -I http://your-domain.com
|
||
|
||
# 检查页面内容
|
||
curl http://your-domain.com | head -20
|
||
```
|
||
|
||
## 📞 技术支持
|
||
|
||
如遇到部署问题，请：
|
||
1. 查看本文档的常见问题部分
|
||
2. 检查服务器日志
|
||
3. 联系开发团队获取支持
|
||
|
||
---
|
||
|
||
**最后更新**: 2024年
|
||
**文档版本**: 1.0.0
|