1. 项目概述最近在帮客户部署一个基于Ant Design前端和FastAPI后端的内部管理系统时遇到了不少坑。这个项目需要在Linux服务器上进行内网部署让公司内部的所有设备都能访问。经过几天的折腾终于把整个流程跑通了现在把完整的部署笔记分享给大家。这个方案适用于CentOS、Ubuntu等主流Linux发行版前端使用Ant Design Pro框架后端采用FastAPI构建API接口。部署完成后系统可以在内网环境中稳定运行无需连接外网。2. 前期准备2.1 服务器环境配置首先需要准备好Linux服务器建议使用较新的LTS版本。我测试过Ubuntu 20.04/22.04和CentOS 7/8都能完美运行。服务器基础要求至少2核CPU、4GB内存实测1核2GB也能跑但性能较差50GB以上磁盘空间临时联网能力用于安装依赖部署完成后可断网开放前端8080和后端8003端口可自定义注意如果是生产环境建议使用8GB以上内存特别是当并发量较大时。2.2 项目目录结构为了避免权限问题建议创建专用部署目录sudo mkdir -p /opt/antd-front /opt/fastapi-back sudo chown -R $USER:$USER /opt/antd-front /opt/fastapi-back这里使用/opt目录是Linux下存放第三方应用的常规位置比放在home目录更规范。2.3 本地项目准备前端项目确保项目能正常build检查src/app.ts中的baseURL配置为服务器内网IP执行npm run build生成dist目录后端项目整理代码确保main.py是入口文件生成requirements.txtpip freeze requirements.txt移除不必要的测试文件和开发配置文件3. 后端FastAPI部署3.1 Python环境配置虽然Linux自带Python3但建议单独配置# Ubuntu/Debian sudo apt update sudo apt install -y python3-pip python3-venv # CentOS/RHEL sudo yum install -y python3-pip python3-venv3.2 虚拟环境创建使用虚拟环境可以避免系统Python环境被污染cd /opt/fastapi-back python3 -m venv venv source venv/bin/activate激活后命令行前缀会显示(venv)表示已在虚拟环境中。3.3 依赖安装在虚拟环境中安装依赖pip install -r requirements.txt常见问题如果遇到SSL错误先执行pip install --upgrade pip国内服务器建议使用清华源-i https://pypi.tuna.tsinghua.edu.cn/simple3.4 服务启动方案方案一nohup简单部署nohup uvicorn main:app --host 0.0.0.0 --port 8003 fastapi.log 21 适合测试环境简单但不够稳定。方案二systemd生产部署创建服务文件/etc/systemd/system/fastapi.service[Unit] DescriptionFastAPI Backend Service Afternetwork.target [Service] Useryour_username WorkingDirectory/opt/fastapi-back ExecStart/opt/fastapi-back/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8003 Restartalways [Install] WantedBymulti-user.target然后启用服务sudo systemctl daemon-reload sudo systemctl start fastapi sudo systemctl enable fastapi4. 前端Ant Design部署4.1 Node.js环境安装# Ubuntu/Debian curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # CentOS/RHEL curl -fsSL https://rpm.nodesource.com/setup_18.x | sudo bash - sudo yum install -y nodejs验证安装node -v # 应显示v18.x npm -v # 应显示8.x4.2 静态服务部署安装anywhere和pm2npm install -g anywhere pm2启动服务cd /opt/antd-front pm2 start anywhere -- -p 8080 -d dist -h 0.0.0.0 pm2 save pm2 startup按照提示执行生成的命令设置开机自启。5. 网络配置5.1 防火墙设置# CentOS/RHEL (firewalld) sudo firewall-cmd --add-port8080/tcp --permanent sudo firewall-cmd --add-port8003/tcp --permanent sudo firewall-cmd --reload # Ubuntu/Debian (ufw) sudo ufw allow 8080/tcp sudo ufw allow 8003/tcp sudo ufw enable5.2 内网访问测试获取服务器内网IPip addr在局域网其他设备访问http://[服务器IP]:80806. 生产环境优化6.1 Nginx替代anywhere安装Nginx# Ubuntu/Debian sudo apt install -y nginx # CentOS/RHEL sudo yum install -y nginx配置/etc/nginx/conf.d/antd-front.confserver { listen 80; server_name your_server_ip; root /opt/antd-front/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location ~* \.(js|css|png|jpg|ico)$ { expires 7d; add_header Cache-Control public, max-age604800; } }重启Nginxsudo nginx -t sudo systemctl restart nginx6.2 后端性能优化使用GunicornUvicorn workerpip install gunicorn gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app启用中间件缓存数据库连接池配置7. 常见问题排查7.1 前端访问空白页可能原因资源路径错误 - 检查nginx配置的root目录路由问题 - 确保有try_files $uri $uri/ /index.htmlAPI请求失败 - 检查浏览器控制台网络请求7.2 后端接口超时排查步骤检查服务是否运行ps -ef | grep uvicorn查看日志journalctl -u fastapi -f测试本地访问curl http://127.0.0.1:8003/api/test7.3 跨域问题FastAPI需配置CORSfrom fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins[http://localhost:8080, http://your-server-ip], allow_credentialsTrue, allow_methods[*], allow_headers[*], )8. 项目更新流程8.1 前端更新本地修改代码并build上传新dist目录到服务器重启服务pm2 restart anywhere # 或如果是nginx sudo systemctl restart nginx8.2 后端更新上传修改后的代码如果有新依赖source venv/bin/activate pip install -r requirements.txt重启服务# systemd方式 sudo systemctl restart fastapi # nohup方式 pkill -f uvicorn nohup uvicorn main:app --host 0.0.0.0 --port 8003 fastapi.log 21 9. 安全加固建议使用HTTPS内网也可以自签名证书配置防火墙只允许内网IP访问定期更新依赖pip-review和npm update设置API访问频率限制启用Basic Auth保护管理接口10. 监控与维护10.1 基础监控# CPU内存监控 top htop # 网络连接监控 netstat -tulnp ss -tulnp # 磁盘监控 df -h du -sh /opt/*10.2 日志管理配置logrotate轮转日志使用ELK或Grafana Loki集中管理日志设置关键错误报警10.3 备份策略每日备份数据库每周备份代码和配置文件使用rsync同步到备份服务器这个部署方案已经在多个客户环境中验证过稳定性很好。最大的经验就是一定要做好权限管理和服务守护避免终端断开后服务停止。另外就是记得在开发环境充分测试后再部署到生产环境。