# 部署与运行说明文档

本文档详细说明 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