【笔记】Ant Design+FastAPI 项目 Linux 服务器内网部署完整笔记

核心原则：前端仅需上传打包后的dist文件夹，后端上传源码 / 依赖文件，分别启动前端静态服务 和后端 FastAPI 服务 ，配合 Linux 防火墙 / 端口开放，实现内网所有设备访问。全程适配CentOS/Debian/Ubuntu（主流 Linux 发行版），步骤清晰可落地，兼顾简易部署和稳定运行。

一、前期准备（Linux 服务器 + 本地文件）

1. Linux 服务器基础要求

能联网（临时拉取依赖，部署后可断网）；
开放指定端口：前端 8080、后端 8003（可自定义，需统一）；
建议创建专用部署目录（避免权限问题）：

bash 复制代码

# 新建前端/后端部署目录，/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 拉取依赖版本不一致）：

bash 复制代码

# 本地后端项目目录执行
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 通用）

bash 复制代码

# 上传前端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，只需安装虚拟环境工具：

bash 复制代码

# 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 虚拟环境

bash 复制代码

# 进入后端部署目录
cd /opt/fastapi-back
# 创建虚拟环境（命名为venv，通用规范）
python3 -m venv venv
# 激活虚拟环境（Linux核心命令，激活后命令行前会出现(venv)）
source venv/bin/activate

步骤 3：安装后端依赖（基于 requirements.txt）

bash 复制代码

# 激活虚拟环境后执行，拉取指定版本依赖
pip install -r requirements.txt
# 验证安装：能看到fastapi、uvicorn、pydantic等依赖即成功
pip list

步骤 4：启动 FastAPI 服务（后台运行 + 绑定所有网卡）

方式 1：nohup 后台运行（简易，推荐内网部署）

bash 复制代码

# 激活虚拟环境后执行，后台运行并输出日志，绑定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 服务（稳定，推荐正式部署，开机自启）

新建 systemd 配置文件：

bash 复制代码

sudo vim /etc/systemd/system/fastapi.service

2.写入配置（替换User和WorkingDirectory为你的实际信息）：

bash 复制代码

[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.启动并设置开机自启：

bash 复制代码

# 重新加载配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start fastapi
# 设置开机自启
sudo systemctl enable fastapi
# 查看服务状态（无error即成功）
sudo systemctl status fastapi

步骤 5：验证后端服务是否可用

bash 复制代码

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

bash 复制代码

# 安装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 用于管理前端服务，后台运行）

bash 复制代码

# 安装anywhere（静态服务）和pm2（进程管理）
npm install -g anywhere pm2
# 验证安装
anywhere -v
pm2 -v

步骤 3：用 pm2 启动 anywhere，托管 dist 文件夹

bash 复制代码

# 进入前端部署目录
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：验证前端服务是否可用

bash 复制代码

# Linux本地执行curl，返回HTML页面即成功
curl http://127.0.0.1:8080

✅ 若返回大量 HTML 代码，说明前端静态服务正常；若报错，用pm2 logs查看日志。

pm2 常用命令（前端服务管理）

bash 复制代码

# 查看运行的服务
pm2 list
# 重启前端服务
pm2 restart anywhere
# 停止前端服务
pm2 stop anywhere
# 查看实时日志
pm2 logs
# 删除前端服务
pm2 delete anywhere

四、Linux 端口开放（核心：让内网设备访问，2 种方式）

前端 8080、后端 8003 端口需开放，否则内网设备会被 Linux 防火墙拦截，二选一即可。

方式 1：firewalld（CentOS7+/RHEL，默认防火墙）

bash 复制代码

# 开放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，轻量防火墙）

bash 复制代码

# 先启用ufw（若未启用）
sudo ufw enable
# 开放8080和8003端口
sudo ufw allow 8080/tcp
sudo ufw allow 8003/tcp
# 验证端口是否开放
sudo ufw status

五、内网访问验证（所有步骤的最终检验）

查看 Linux 服务器的局域网 IP：

bash 复制代码

ip addr # 找到inet开头的内网IP，如192.168.66.100（ens33/eth0网卡）

内网任意设备（电脑 / 手机）打开浏览器，输入：
bash 复制代码
```
http://Linux服务器内网IP:8080
```
验证核心功能：
- ✅ 页面正常加载：前端静态服务部署成功；
- ✅ 能正常登录（POST /api/login/account）：前后端通信正常，CORS 配置生效；
- ✅ 能获取用户信息（GET /api/currentUser）：后端接口正常，端口开放成功；
- ✅ 刷新页面不 404：anywhere 适配单页应用路由成功。

六、项目更新（后续迭代代码，最简流程）

前端更新

本地修改代码→重新执行npm run build生成新 dist；
上传新 dist 覆盖 Linux 上的/opt/antd-front/dist；
重启前端服务：pm2 restart anywhere。

后端更新

本地修改代码→更新requirements.txt（若新增依赖）；
上传新代码覆盖 Linux 上的/opt/fastapi-back/；
重启后端服务：
- 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 部署避坑点（必看，避免踩雷）

权限问题 ：部署目录建议用/opt/，并赋予普通用户权限，避免全程 sudo 导致的文件权限错误；
虚拟环境：后端必须用 Python 虚拟环境，否则会和系统 Python 依赖冲突，导致服务启动失败；
IP 配置 ：前端打包前baseURL必须是Linux 服务器内网 IP ，而非localhost/127.0.0.1，否则前端请求会指向本机；
端口冲突：若 8080/8003 端口被占用，可更换端口（如前端 80、后端 8000），需同步修改前端 baseURL 和 Linux 端口开放命令；
后台运行 ：禁止直接用anywhere/uvicorn启动服务（关闭终端即中断），必须用pm2/nohup/systemd后台运行；
日志排查：服务启动失败时，优先查看日志（pm2 logs/fastapi.log/journalctl），日志会明确提示错误原因（如依赖缺失、端口被占、代码语法错误）；
CORS 配置 ：后端 FastAPI 的allow_origin_regex必须包含 Linux 服务器内网网段（如192.168.66.\d+），否则会跨域拦截；
文件路径 ：Linux 路径区分大小写，且无盘符，部署时避免中文 / 空格（如/opt/前端项目 → 改为/opt/antd-front）。

八、进阶：生产环境 Nginx 托管前端（可选，性能更高）

若内网访问设备较多（如几十台），推荐用Nginx 替代anywhere+pm2，性能更高、稳定性更强，适配高并发。

步骤 1：安装 Nginx

bash 复制代码

# 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 mv /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf.bak；
新建前端配置文件：

bash 复制代码

sudo vim /etc/nginx/conf.d/antd-front.conf

3.写入配置（替换server_name为 Linux 服务器内网 IP）：

bash 复制代码

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：

bash 复制代码

# 验证配置语法（无error即成功）
sudo nginx -t
# 重启Nginx
sudo systemctl restart nginx

5.访问方式：内网设备直接输入http://Linux服务器内网IP（无需加 80 端口），更简洁。

步骤 3：停止原有 anywhere 服务

复制代码

pm2 delete anywhere

核心总结

Linux 部署核心 ：前端仅传dist，后端传源码 +requirements.txt，分别启动服务并开放端口；
后端必用虚拟环境 ，避免依赖冲突，服务后台运行用nohup（简易）/systemd（正式）；
前端用anywhere+pm2 快速部署，高并发场景替换为 Nginx，均需适配 SPA 路由避免刷新 404；
端口开放是关键，内网访问失败优先检查 Linux 防火墙是否开放 8080/8003 端口；
更新项目仅需覆盖文件并重启服务，无需重新配置环境，简化维护流程；
所有配置均适配内网部署，无需公网 IP，兼顾安全性和可访问性。

按以上步骤操作，就能在 Linux 服务器上稳定运行 Ant Design+FastAPI 项目，内网所有设备均可正常访问和使用。