python/finyx_data_frontend

Fork 0

李季 873efbe647 原型设计，初始化提交。

2026-01-07 08:13:50 +08:00

11 KiB

Raw Permalink Blame History

部署与运行说明文档

本文档详细说明 Finyx AI Prototype 项目的部署和运行流程。

📋 目录

环境准备
本地开发
生产构建
部署方式
环境变量配置
常见问题

🔧 环境准备

系统要求

操作系统: Linux / macOS / Windows
Node.js: >= 16.0.0 (推荐使用 LTS 版本)
npm: >= 7.0.0 或 yarn: >= 1.22.0
内存: 至少 2GB 可用内存
磁盘空间: 至少 500MB 可用空间

检查环境

# 检查 Node.js 版本
node -v
# 应显示 v16.x.x 或更高版本

# 检查 npm 版本
npm -v
# 应显示 7.x.x 或更高版本

安装 Node.js（如未安装）

Linux (Ubuntu/Debian)

# 使用 NodeSource 仓库安装
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS

# 使用 Homebrew
brew install node

Windows

从 Node.js 官网下载安装包并安装

💻 本地开发

1. 克隆项目

git clone <repository-url>
cd finyx_data_frontend

2. 安装依赖

npm install

如果安装速度慢，可以使用国内镜像：

# 使用淘宝镜像
npm install --registry=https://registry.npmmirror.com

# 或使用 cnpm
npm install -g cnpm --registry=https://registry.npmmirror.com
cnpm install

3. 启动开发服务器

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 端口被占用，可以通过以下方式修改：

方式一：命令行参数

# 修改端口
npm run dev -- --port 3000

# 指定主机（允许外部访问）
npm run dev -- --host 0.0.0.0 --port 3000

方式二：修改 vite.config.ts

export default defineConfig({
  server: {
    host: '0.0.0.0', // 允许外部访问
    port: 3000,      // 自定义端口
    strictPort: false, // 端口被占用时自动尝试下一个
  }
})

获取本机 IP 地址:

# 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. 构建生产版本

npm run build

构建完成后，会在 dist/ 目录生成优化后的静态文件：

dist/
├── index.html
├── assets/
│   ├── index-[hash].js
│   ├── index-[hash].css
│   └── ...

2. 预览生产构建

在部署前，可以本地预览生产版本：

npm run preview

访问 http://localhost:4173 查看预览效果。

3. 构建优化

生产构建已自动启用以下优化：

代码压缩和混淆
Tree-shaking（移除未使用代码）
资源压缩（CSS、JS）
代码分割（按需加载）

🚀 部署方式

静态文件部署

方式一：直接部署 dist 目录

构建项目
```
npm run build
```
上传 dist 目录 将 dist/ 目录下的所有文件上传到 Web 服务器
配置 Web 服务器 参考下面的 Nginx 配置

方式二：使用 CI/CD 自动部署

GitHub Actions 示例 (.github/workflows/deploy.yml):

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:

# 构建阶段
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 容器

# 构建镜像
docker build -t finyx-frontend .

# 运行容器
docker run -d -p 80:80 --name finyx-app finyx-frontend

4. 使用 Docker Compose

创建 docker-compose.yml:

version: '3.8'

services:
  frontend:
    build: .
    ports:
      - "80:80"
    restart: unless-stopped
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro

运行：

docker-compose up -d

Nginx 配置

创建 nginx.conf 文件：

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;
}

部署到服务器：

# 复制配置文件
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:

VITE_API_BASE_URL=http://localhost:3000/api
VITE_APP_TITLE=Finyx AI Prototype (Dev)

生产环境

创建 .env.production:

VITE_API_BASE_URL=https://api.yourdomain.com
VITE_APP_TITLE=Finyx AI Prototype

使用环境变量

在代码中使用：

const apiUrl = import.meta.env.VITE_API_BASE_URL;

注意: Vite 要求环境变量必须以 VITE_ 开头才能在客户端代码中访问。

❓ 常见问题

1. 端口被占用

问题: Error: Port 5173 is already in use

解决方案:

# 查找占用端口的进程
lsof -i :5173  # macOS/Linux
netstat -ano | findstr :5173  # Windows

# 杀死进程或使用其他端口
npm run dev -- --port 3000

1.1 无法通过 IP 地址访问

问题: 只能通过 localhost 访问，无法通过局域网 IP 地址访问

解决方案:

检查配置: 确保 vite.config.ts 中 server.host 设置为 '0.0.0.0'（已默认配置）

检查防火墙: 确保防火墙允许端口访问

# 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 (如果启用了防火墙)
# 系统偏好设置 > 安全性与隐私 > 防火墙 > 防火墙选项

检查网络: 确保设备在同一局域网内

获取本机 IP:

# 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）

使用 Network 地址: 启动开发服务器后，终端会显示 Network 地址，使用该地址访问

2. 依赖安装失败

问题: npm install 失败或很慢

解决方案:

# 清除 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 中配置代理：

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:3000',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      }
    }
  }
})

6. 内存不足

问题: 构建时内存溢出

解决方案:

# 增加 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 监控核心指标

🔍 健康检查

部署后，可以通过以下方式检查应用状态：

# 检查 HTTP 响应
curl -I http://your-domain.com

# 检查页面内容
curl http://your-domain.com | head -20

📞 技术支持

如遇到部署问题，请：

查看本文档的常见问题部分
检查服务器日志
联系开发团队获取支持

最后更新: 2024年 文档版本: 1.0.0

11 KiB Raw Permalink Blame History Unescape Escape

部署与运行说明文档

📋 目录

🔧 环境准备

系统要求

检查环境

安装 Node.js（如未安装）

Linux (Ubuntu/Debian)

macOS

Windows

💻 本地开发

1. 克隆项目

2. 安装依赖

3. 启动开发服务器

4. 开发模式特性

5. 修改端口和主机配置（如需要）

🏗️ 生产构建

1. 构建生产版本

2. 预览生产构建

3. 构建优化

🚀 部署方式

静态文件部署

方式一：直接部署 dist 目录

方式二：使用 CI/CD 自动部署

Docker 部署

1. 创建 Dockerfile

2. 创建 .dockerignore

3. 构建和运行 Docker 容器

4. 使用 Docker Compose

Nginx 配置

🔐 环境变量配置

开发环境

生产环境

使用环境变量

❓ 常见问题

1. 端口被占用

1.1 无法通过 IP 地址访问

2. 依赖安装失败

3. 构建失败

4. 路由刷新 404

5. 跨域问题

6. 内存不足

📊 性能优化建议

1. 代码分割

2. 资源优化

3. 缓存策略

4. 监控和分析

🔍 健康检查

📞 技术支持

11 KiB

Raw Permalink Blame History