网硕互联帮助中心核心原则：前端仅需上传打包后的dist文件夹，后端上传源码 / 依赖文件，分别启动前端静态服务和后端 FastAPI 服务，配合 Linux 防火墙 / 端口开放，实现内网所有设备访问。全程适配CentOS/Debian/Ubuntu（主流 Linux 发行版），步骤清晰可落地，兼顾简易部署和稳定运行。
一、前期准备（Linux 服务器 + 本地文件）
1. Linux 服务器基础要求
- 能联网（临时拉取依赖，部署后可断网）；
- 开放指定端口：前端 8080、后端 8003（可自定义，需统一）；
- 建议创建专用部署目录（避免权限问题）：
# 新建前端/后端部署目录，/opt/是Linux常用应用部署目录
sudo mkdir -p /opt/antd-front /opt/fastapi-back
# 赋予普通用户操作权限（避免后续sudo繁琐，替换为你的Linux用户名，如ubuntu）
sudo chown -R 你的用户名:你的用户名 /opt/antd-front /opt/fastapi-back
2. 本地准备好待上传文件
前端（仅需 dist 文件夹）
- 本地项目根目录执行npm run build，确保dist文件夹生成成功（无报错）；
- 确认src/app.ts中baseURL已配置为Linux 服务器局域网 IP + 后端端口（如http://192.168.66.100:8003），打包后不可修改，改了需重新打包。
后端（FastAPI 项目）
- 整理后端源码文件：包含main.py（入口文件）、requirements.txt（依赖清单，必须有）；
- 本地生成requirements.txt（避免 Linux 拉取依赖版本不一致）：
# 本地后端项目目录执行
pip freeze > requirements.txt
- 后端文件清单示例：main.py、requirements.txt、其他业务代码 / 配置文件（无多余文件）。
3. 本地文件上传到 Linux（2 种简易方式）
方式 1：Xshell/Xftp（可视化，Windows 推荐）
- Xftp 连接 Linux 服务器，直接将本地dist拖到/opt/antd-front/，后端文件拖到/opt/fastapi-back/。
方式 2：scp 命令（无可视化，Windows/Mac/Linux 通用）
# 上传前端dist（本地dist路径 → Linux前端目录）
scp -r 本地dist绝对路径 你的Linux用户名@Linux服务器IP:/opt/antd-front/
# 示例：scp -r D:\\code\\login-ant\\dist ubuntu@192.168.66.100:/opt/antd-front/
# 上传后端文件（本地后端目录 → Linux后端目录）
scp -r 本地后端项目路径/* 你的Linux用户名@Linux服务器IP:/opt/fastapi-back/
# 示例：scp -r D:\\code\\fastapi-back\\* ubuntu@192.168.66.100:/opt/fastapi-back/
✅ 验证上传：Linux 服务器执行ls /opt/antd-front/和ls /opt/fastapi-back/，能看到 dist 和后端文件即成功。
二、Linux 后端 FastAPI 服务部署（核心：虚拟环境 + 后台运行）
步骤 1：安装 Python3 + 虚拟环境（避免系统依赖冲突）
Linux 默认自带 Python3，只需安装虚拟环境工具：
# CentOS/RHEL
sudo yum install -y python3-pip python3-venv
# Debian/Ubuntu
sudo apt update && sudo apt install -y python3-pip python3-venv
步骤 2：创建并激活 Python 虚拟环境
# 进入后端部署目录
cd /opt/fastapi-back
# 创建虚拟环境（命名为venv，通用规范）
python3 -m venv venv
# 激活虚拟环境（Linux核心命令，激活后命令行前会出现(venv)）
source venv/bin/activate
步骤 3：安装后端依赖（基于 requirements.txt）
# 激活虚拟环境后执行，拉取指定版本依赖
pip install -r requirements.txt
# 验证安装：能看到fastapi、uvicorn、pydantic等依赖即成功
pip list
步骤 4：启动 FastAPI 服务（后台运行 + 绑定所有网卡）
方式 1：nohup 后台运行（简易，推荐内网部署）
# 激活虚拟环境后执行，后台运行并输出日志，绑定0.0.0.0（内网所有设备可访问）
nohup uvicorn main:app –host 0.0.0.0 –port 8003 > fastapi.log 2>&1 &
- 命令说明：
- nohup … &：后台运行，关闭终端不中断服务；
- > fastapi.log 2>&1：所有日志输出到fastapi.log，方便排查错误；
- main:app：FastAPI 入口（main 是入口文件名，app 是 FastAPI 实例名，需和后端代码一致）。
方式 2：systemd 服务（稳定，推荐正式部署，开机自启）
sudo vim /etc/systemd/system/fastapi.service
2.写入配置（替换User和WorkingDirectory为你的实际信息）：
[Unit]
Description=FastAPI Backend Service
After=network.target
[Service]
User=你的Linux用户名 # 如ubuntu/root
WorkingDirectory=/opt/fastapi-back # 后端部署目录
ExecStart=/opt/fastapi-back/venv/bin/uvicorn main:app –host 0.0.0.0 –port 8003
Restart=always # 服务崩溃自动重启
[Install]
WantedBy=multi-user.target
3.启动并设置开机自启：
# 重新加载配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start fastapi
# 设置开机自启
sudo systemctl enable fastapi
# 查看服务状态（无error即成功）
sudo systemctl status fastapi
步骤 5：验证后端服务是否可用
# Linux本地执行curl请求，返回接口数据即成功
curl http://127.0.0.1:8003/api/currentUser
✅ 若返回 JSON 数据，说明后端服务正常；若报错，查看日志：
- nohup 方式：cat /opt/fastapi-back/fastapi.log
- systemd 方式：sudo journalctl -u fastapi -f
三、Linux 前端 Ant Design 部署（核心：pm2 托管 anywhere，稳定不中断）
步骤 1：安装 Node.js+npm（anywhere 依赖 Node 环境）
# 安装Node.js 18.x（稳定版，兼容anywhere）
# CentOS/RHEL
curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash –
sudo yum install -y nodejs
# Debian/Ubuntu
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo bash –
sudo apt install -y nodejs
# 验证安装（输出版本即成功）
node -v
npm -v
步骤 2：全局安装 anywhere+pm2（pm2 用于管理前端服务，后台运行）
# 安装anywhere（静态服务）和pm2（进程管理）
npm install -g anywhere pm2
# 验证安装
anywhere -v
pm2 -v
步骤 3：用 pm2 启动 anywhere，托管 dist 文件夹
# 进入前端部署目录
cd /opt/antd-front
# 用pm2启动anywhere，指定端口8080，托管dist，绑定0.0.0.0
pm2 start anywhere — -p 8080 -d dist -h 0.0.0.0
# 关键：保存pm2配置，开机自启
pm2 save
pm2 startup
# 按终端提示执行生成的命令（如sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u 用户名 –hp /home/用户名）
步骤 4：验证前端服务是否可用
# Linux本地执行curl，返回HTML页面即成功
curl http://127.0.0.1:8080
✅ 若返回大量 HTML 代码，说明前端静态服务正常；若报错，用pm2 logs查看日志。
pm2 常用命令（前端服务管理）
# 查看运行的服务
pm2 list
# 重启前端服务
pm2 restart anywhere
# 停止前端服务
pm2 stop anywhere
# 查看实时日志
pm2 logs
# 删除前端服务
pm2 delete anywhere
四、Linux 端口开放（核心：让内网设备访问，2 种方式）
前端 8080、后端 8003 端口需开放，否则内网设备会被 Linux 防火墙拦截，二选一即可。
方式 1：firewalld（CentOS7+/RHEL，默认防火墙）
# 开放8080和8003端口（永久生效）
sudo firewall-cmd –add-port=8080/tcp –permanent
sudo firewall-cmd –add-port=8003/tcp –permanent
# 重新加载防火墙配置
sudo firewall-cmd –reload
# 验证端口是否开放
sudo firewall-cmd –list-ports
方式 2：ufw（Debian/Ubuntu，轻量防火墙）
# 先启用ufw（若未启用）
sudo ufw enable
# 开放8080和8003端口
sudo ufw allow 8080/tcp
sudo ufw allow 8003/tcp
# 验证端口是否开放
sudo ufw status
五、内网访问验证（所有步骤的最终检验）
- ✅ 页面正常加载：前端静态服务部署成功；
- ✅ 能正常登录（POST /api/login/account）：前后端通信正常，CORS 配置生效；
- ✅ 能获取用户信息（GET /api/currentUser）：后端接口正常，端口开放成功；
- ✅ 刷新页面不 404：anywhere 适配单页应用路由成功。
六、项目更新（后续迭代代码，最简流程）
前端更新
后端更新
- nohup 方式：先杀进程再重启（ps -ef | grep uvicorn → kill -9 进程号 → 重新执行 nohup 命令）；
- systemd 方式：sudo systemctl restart fastapi；
cd /opt/fastapi-back
source venv/bin/activate
pip install -r requirements.txt
七、Linux 部署避坑点（必看，避免踩雷）
八、进阶：生产环境 Nginx 托管前端（可选，性能更高）
若内网访问设备较多（如几十台），推荐用Nginx替代anywhere+pm2，性能更高、稳定性更强，适配高并发。
步骤 1：安装 Nginx
# CentOS/RHEL
sudo yum install -y nginx
# Debian/Ubuntu
sudo apt update && sudo apt install -y nginx
# 启动并设置开机自启
sudo systemctl start nginx
sudo systemctl enable nginx
步骤 2：配置 Nginx，托管 dist 并适配 SPA 路由
sudo vim /etc/nginx/conf.d/antd-front.conf
3.写入配置（替换server_name为 Linux 服务器内网 IP）：
server {
listen 80; # 端口可改为80，浏览器访问时无需输端口
server_name 192.168.66.100; # Linux服务器内网IP
# 指向前端dist文件夹的绝对路径
root /opt/antd-front/dist;
index index.html; # 单页应用唯一入口
# 核心：适配Ant Design SPA路由，避免刷新404
try_files $uri $uri/ /index.html;
# 可选：配置静态资源缓存，提升访问速度
location ~* \\.(js|css|png|jpg|ico)$ {
expires 7d; # 缓存7天
add_header Cache-Control "public, max-age=604800";
}
}
4.验证配置并重启 Nginx：
# 验证配置语法（无error即成功）
sudo nginx -t
# 重启Nginx
sudo systemctl restart nginx
5.访问方式：内网设备直接输入http://Linux服务器内网IP（无需加 80 端口），更简洁。
步骤 3：停止原有 anywhere 服务
pm2 delete anywhere
核心总结
按以上步骤操作，就能在 Linux 服务器上稳定运行 Ant Design+FastAPI 项目，内网所有设备均可正常访问和使用。
评论前必须登录！
注册