Python项目完整部署文档（本地导出 + 服务器双方案部署）

文章目录

- 一、文档简介与部署方案说明
- 二、前置核心原理（部署前必懂，解决90%新手疑问）
- - [2.1 什么是Python虚拟环境？](#2.1 什么是Python虚拟环境？)
  - [2.2 为什么本地一定要建虚拟环境？](#2.2 为什么本地一定要建虚拟环境？)
  - [2.3 未激活虚拟环境执行 pip freeze 会下载所有依赖吗？（关键避坑）](#2.3 未激活虚拟环境执行 pip freeze 会下载所有依赖吗？（关键避坑）)
  - [2.4 IDEA 内置虚拟环境是否需要手动激活？](#2.4 IDEA 内置虚拟环境是否需要手动激活？)
  - [2.5 为什么部署一定要升级pip？会不会版本不匹配？](#2.5 为什么部署一定要升级pip？会不会版本不匹配？)
- [三、本地环境准备 & 纯净依赖导出（所有部署通用前置步骤）](#三、本地环境准备 & 纯净依赖导出（所有部署通用前置步骤）)
- - [3.1 进入本地项目根目录](#3.1 进入本地项目根目录)
  - [3.2 本地创建并激活纯净虚拟环境](#3.2 本地创建并激活纯净虚拟环境)
  - [3.3 升级虚拟环境内pip](#3.3 升级虚拟环境内pip)
  - [3.4 安装项目依赖并导出清单](#3.4 安装项目依赖并导出清单)
- 四、服务器基础环境初始化（首次部署必做）
- - [4.1 CentOS 安装Python3](#4.1 CentOS 安装Python3)
  - [4.2 Ubuntu 安装Python3](#4.2 Ubuntu 安装Python3)
  - [4.3 验证环境是否安装成功](#4.3 验证环境是否安装成功)
- 五、方案A：服务器虚拟环境部署（生产推荐、标准方案）
- - [5.1 创建项目目录并进入](#5.1 创建项目目录并进入)
  - [5.2 创建服务器专属虚拟环境](#5.2 创建服务器专属虚拟环境)
  - [5.3 激活虚拟环境](#5.3 激活虚拟环境)
  - [5.4 升级当前环境pip](#5.4 升级当前环境pip)
  - [5.5 上传本地项目至服务器](#5.5 上传本地项目至服务器)
  - [5.6 一键安装所有项目依赖](#5.6 一键安装所有项目依赖)
  - [5.7 项目运行（测试 + 生产常驻）](#5.7 项目运行（测试 + 生产常驻）)
  - [5.8 退出虚拟环境](#5.8 退出虚拟环境)
- 六、方案B：服务器全局环境部署（无虚拟环境、极简临时方案）
- - [6.1 直接使用服务器全局Python环境](#6.1 直接使用服务器全局Python环境)
  - [6.2 全局安装依赖](#6.2 全局安装依赖)
  - [6.3 项目运行命令](#6.3 项目运行命令)
  - [6.4 退出虚拟环境](#6.4 退出虚拟环境)
  - [6.5 方案优缺点总结](#6.5 方案优缺点总结)
- 七、服务器精准运维命令（优化版，告别杂乱进程）
- - [7.1 精准查询项目进程（支持按项目名/脚本名查询，彻底告别过多进程）](#7.1 精准查询项目进程（支持按项目名/脚本名查询，彻底告别过多进程）)
  - [7.2 停止项目进程（不止PID一种方法）](#7.2 停止项目进程（不止PID一种方法）)
  - [7.3 查看项目运行日志](#7.3 查看项目运行日志)
  - [7.4 退出虚拟环境](#7.4 退出虚拟环境)
  - [7.5 进阶：服务器Crontab定时运行Python脚本（核心实用功能）](#7.5 进阶：服务器Crontab定时运行Python脚本（核心实用功能）)
  - - [7.5.1 Crontab 基础语法](#7.5.1 Crontab 基础语法)
    - [7.5.2 编辑定时任务列表](#7.5.2 编辑定时任务列表)
    - [7.5.3 方案1：虚拟环境脚本定时执行（推荐、无冲突）](#7.5.3 方案1：虚拟环境脚本定时执行（推荐、无冲突）)
    - [7.5.4 方案2：全局环境脚本定时执行](#7.5.4 方案2：全局环境脚本定时执行)
    - [7.5.5 常用定时规则参考](#7.5.5 常用定时规则参考)
    - [7.5.6 定时任务运维命令](#7.5.6 定时任务运维命令)
    - [7.5.7 定时任务避坑要点](#7.5.7 定时任务避坑要点)
  - [7.6 运维命令总览总结](#7.6 运维命令总览总结)
- 八、项目迭代更新流程（后续改代码、加依赖通用步骤）
- 九、常见问题避坑汇总

一、文档简介与部署方案说明

本文档适用于 Python 单文件脚本 、Python 多文件整套系统 的 Linux 服务器生产部署（CentOS、Ubuntu 通用）。

文档包含两套完整部署方案，按需选择：

方案A（推荐）：虚拟环境隔离部署 ------ 多项目互不干扰、无依赖冲突、生产标准方案
方案B（极简）：服务器全局环境部署 ------ 仅适合服务器只跑一个Python项目的临时场景

全流程由浅入深：环境原理说明 → 本地纯净依赖导出 → 服务器环境搭建 → 项目部署运行 → 日常运维 → 迭代更新 → 问题避坑。

二、前置核心原理（部署前必懂，解决90%新手疑问）

本节提前讲透虚拟环境核心逻辑，避免后续部署看不懂、不敢操作。

2.1 什么是Python虚拟环境？

虚拟环境是 Python 官方自带的 独立、隔离的微型运行环境 。它不会复制对方电脑的环境、不会联网同步，只会 克隆当前本机的Python解释器 生成一套独立的 python、pip、依赖库。

本地执行 python3 -m venv .venv：克隆本地电脑Python（用于纯净导出依赖）
服务器执行 python3 -m venv .venv：克隆服务器Linux Python（用于正式运行项目）

两套环境完全独立，仅通过 requirements.txt 同步依赖版本。

2.2 为什么本地一定要建虚拟环境？

本地虚拟环境唯一核心目的：提纯依赖，只导出项目真正需要的库。

如果用电脑全局Python，会包含大量历史安装的冗余库
直接导出会导致服务器安装大量无用依赖，引发版本冲突、运行报错
本地虚拟环境是空白干净环境，只装项目所需依赖，导出的清单100%适配项目

2.3 未激活虚拟环境执行 pip freeze 会下载所有依赖吗？（关键避坑）

结论：会！100% 导出你电脑全局所有Python包，极度危险。

如果本地终端没有进入/激活 .venv，此时执行：

Plain 复制代码

pip freeze > requirements.txt

读取的是 电脑全局Python环境，不是项目环境。会把你电脑所有历史安装的库全部导出，导致：

依赖文件巨大、杂乱
服务器安装大量无用包
版本冲突、部署报错、项目跑不起来

只有终端前缀显示 (.venv) 激活成功后，导出的依赖才是纯净的项目依赖。

2.4 IDEA 内置虚拟环境是否需要手动激活？

结论：IDE 内运行代码不用手动激活，终端部署必须手动激活。

你在 IDEA 中配置好 .venv 解释器后，点击运行代码、调试代码，IDE 自动使用该虚拟环境，无需执行激活命令
但是！你在 IDEA 终端、CMD、PowerShell、服务器终端手动敲 pip / python 命令，必须手动激活

简单区分：IDE 点运行 = 自动激活；自己敲命令 = 必须手动激活 。

2.5 为什么部署一定要升级pip？会不会版本不匹配？

升级pip绝对安全，不会导致依赖版本错乱，核心区分：

pip：只是安装工具，不参与项目代码运行
pymysql/openpyxl等：是项目真实依赖，版本由requirements.txt锁定

依赖清单只记录业务库版本，不记录pip版本；旧pip漏洞多、解析依赖容易失败，新版pip向下兼容所有旧依赖，是部署必做步骤。

三、本地环境准备 & 纯净依赖导出（所有部署通用前置步骤）

无论服务器用虚拟环境还是全局环境，本地都必须按此步骤导出纯净依赖，保证本地、服务器运行环境一致。

3.1 进入本地项目根目录

终端 CD 到你的项目最外层根目录（包含所有py文件、配置文件）：

Plain 复制代码

cd /你的项目绝对路径

3.2 本地创建并激活纯净虚拟环境

目的：清空冗余依赖，保证导出清单干净无垃圾。

Windows 系统：

Plain 复制代码

# 创建本地虚拟环境
python -m venv .venv
# 激活本地虚拟环境
.venv\Scripts\activate

Mac / Linux 系统：

Plain 复制代码

python3 -m venv .venv
source .venv/bin/activate

激活成功：终端前缀出现 (.venv) 标识。

3.3 升级虚拟环境内pip

Plain 复制代码

pip install --upgrade pip

pip：当前虚拟环境内的 pip 程序
install：安装
--upgrade：升级
最后一个pip：要升级的包名（pip 本身）

注：

只升级【当前这个虚拟环境】里面的 pip，完全不动服务器全局 pip，也不影响其他项目虚拟环境。
如果失败了，可以试试这个命令：python.exe -m pip install --upgrade pip

3.4 安装项目依赖并导出清单

先安装你项目需要的所有依赖（pymysql、openpyxl等），再导出锁定版本：

Plain 复制代码

# 导出当前环境所有依赖版本到标准文件
pip freeze > requirements.txt

参数解释：

pip freeze：读取当前环境所有第三方库精准版本
>：重定向输出，将内容写入文件

执行后项目根目录生成 requirements.txt，必须和项目代码一起上传服务器。

四、服务器基础环境初始化（首次部署必做）

服务器新装Python3环境，为两种部署方案提供基础运行依赖。

4.1 CentOS 安装Python3

Plain 复制代码

yum update -y
yum install python3 python3-pip python3-venv -y

4.2 Ubuntu 安装Python3

Plain 复制代码

apt update -y
apt install python3 python3-pip python3-venv -y

4.3 验证环境是否安装成功

Plain 复制代码

python3 --version
pip3 --version

正常输出版本号即为安装完成。

五、方案A：服务器虚拟环境部署（生产推荐、标准方案）

适用：服务器多项目并存、长期运行、需要稳定无冲突的生产场景。

5.1 创建项目目录并进入

Plain 复制代码

mkdir -p /home/python_project
cd /home/python_project

5.2 创建服务器专属虚拟环境

Plain 复制代码

python3 -m venv .venv

命令解释：基于服务器本机Python3，创建当前项目独立隔离环境。

5.3 激活虚拟环境

Plain 复制代码

source .venv/bin/activate

💡 重要常识：虚拟环境是临时会话生效，断开Xshell/重新连接服务器后，需要重新执行此命令激活环境，否则会使用系统全局Python。

激活标识：终端前缀变为 (.venv)。

5.4 升级当前环境pip

Plain 复制代码

pip install --upgrade pip

激活虚拟环境后直接用 pip，无需 pip3。

5.5 上传本地项目至服务器

将本地所有py文件、配置文件、requirements.txt 完整上传至 /home/python_project 目录。

推荐上传方式：SFTP(FileZilla 22端口)、Xshell传输、Git克隆。

5.6 一键安装所有项目依赖

Plain 复制代码

pip install -r requirements.txt

自动复刻本地所有依赖版本，实现环境完全一致。

5.7 项目运行（测试 + 生产常驻）

前台测试运行（排查报错）：

Plain 复制代码

# 替换为你的项目入口文件：main.py / run.py / app.py
python main.py

无报错、正常输出日志，即可 Ctrl+C 终止，切换生产后台运行。

生产后台永久常驻运行：

Plain 复制代码

nohup python main.py > run.log 2>&1

参数解释：

nohup：关闭终端不停止进程
> run.log：正常日志写入文件
2>&1：错误日志同步写入日志文件
&：后台运行

5.8 退出虚拟环境

Plain 复制代码

deactivate

退出后终端 (.venv) 标识消失，回到服务器全局环境。

六、方案B：服务器全局环境部署（无虚拟环境、极简临时方案）

适用：服务器仅部署一个Python项目、无其他Python业务、临时测试使用。

❌ 禁止多项目服务器使用：会造成全局依赖覆盖、版本冲突、旧项目报错。

6.1 直接使用服务器全局Python环境

无需创建、激活虚拟环境，直接在项目目录操作。

6.2 全局安装依赖

Plain 复制代码

pip3 install --upgrade pip
pip3 install -r requirements.txt

6.3 项目运行命令

Plain 复制代码

# 前台测试
python3 main.py

# 后台常驻
nohup python3 main.py > run.log 2>&1

6.4 退出虚拟环境

Plain 复制代码

deactivate

退出后终端 (.venv) 标识消失，回到服务器全局环境。

6.5 方案优缺点总结

优点：步骤少、无需管理虚拟环境、上手简单
缺点：依赖全局共用，无法多项目共存，生产稳定性差

七、服务器精准运维命令（优化版，告别杂乱进程）

摒弃老旧杂乱的全局 grep 查询，使用精准命令定位项目进程。

7.1 精准查询项目进程（支持按项目名/脚本名查询，彻底告别过多进程）

原有 ps 命令会查出所有Python进程，依然很乱。生产推荐按项目脚本名称精准匹配PID，是最干净的查询方式。

语法：根据你的入口文件名精准过滤（例：你的项目是 main.py 就查 main）

Plain 复制代码

# 根据脚本名精准查询PID（替换 main 为你的文件名，如 run、app）
pgrep -f main

# 查看详细进程信息
ps -ef | grep main | grep -v grep

优势：直接只过滤当前项目进程，其他系统Python进程全部屏蔽，多项目服务器完美适配。

7.2 停止项目进程（不止PID一种方法）

方式1：通过PID停止（传统常用）

Plain 复制代码

kill -9 进程号

方式2：直接按项目脚本名批量杀进程（更方便、推荐）

Plain 复制代码

# 一键杀掉该项目所有进程（替换main为你的入口文件名）
pkill -f main

无需手动找PID，一条命令直接关停对应项目所有后台进程，日常迭代更新首选。

优势：自动过滤系统冗余进程、grep自身进程，只展示用户部署的项目进程。

7.3 查看项目运行日志

Plain 复制代码

# 实时滚动查看最新日志（常用）
tail -f run.log

# 查看完整全部日志
cat run.log

7.4 退出虚拟环境

Plain 复制代码

deactivate

退出后终端 (.venv) 标识消失，回到服务器全局环境。

7.5 进阶：服务器Crontab定时运行Python脚本（核心实用功能）

适用于：需要定时自动执行Python脚本的场景（定时爬虫、定时数据同步、定时报表、定时清理任务等），支持虚拟环境、全局环境两种配置，Linux自带无需额外安装。

7.5.1 Crontab 基础语法

定时规则：分时日月周执行命令

* 代表任意时间
示例：0 3 * * * 代表每天凌晨3点执行

7.5.2 编辑定时任务列表

Plain 复制代码

# 编辑当前用户定时任务
crontab -e

7.5.3 方案1：虚拟环境脚本定时执行（推荐、无冲突）

必须填写虚拟环境python绝对路径 + 脚本绝对路径，crontab不会自动加载终端虚拟环境。

示例（每天凌晨3点执行一次脚本）：

Plain 复制代码

0 3 * * * /home/python_project/.venv/bin/python /home/python_project/main.py &gt;&gt; /home/python_project/cron_log.log 2&gt;&amp;1

命令逐段解释：

0 3 * * *：定时规则，每天03:00执行
/home/python_project/.venv/bin/python：项目虚拟环境Python绝对解释器路径（关键，避免全局环境错乱）
/home/python_project/main.py：Python脚本绝对路径
>> cron_log.log 2>&1：保存定时任务执行日志，方便排查报错

7.5.4 方案2：全局环境脚本定时执行

仅适合单项目全局部署场景：

Plain 复制代码

0 3 * * * /usr/bin/python3 /home/python_project/main.py >> /home/python_project/cron_log.log 2>&1

7.5.5 常用定时规则参考

Plain 复制代码

# 每1分钟执行一次
* * * * *

# 每小时整点执行
0 * * * *

# 每天凌晨3点执行
0 3 * * *

# 每周日凌晨3点执行
0 3 * * 0

7.5.6 定时任务运维命令

Plain 复制代码

# 查看已存在的定时任务
crontab -l

# 删除所有定时任务（谨慎操作）
crontab -r

# 查看crontab运行日志（排查任务不执行问题）
tail -f /var/log/cron

7.5.7 定时任务避坑要点

crontab 无法识别终端相对路径，必须全部使用绝对路径（解释器、脚本、日志文件）
虚拟环境定时必须指定.venv/bin/python，否则会调用系统全局Python，依赖缺失报错
定时任务默认无终端输出，务必配置日志输出，方便排查异常
后台常驻项目和定时任务可共存：常驻接口服务 + 定时任务自动执行业务脚本

7.6 运维命令总览总结

汇总所有高频运维命令，方便日常复制使用：

Plain 复制代码

# 精准查进程
ps -ef | grep main | grep -v grep
pgrep -f main

# 杀进程
kill -9 进程ID
pkill -f main

# 查看日志
tail -f run.log

# 虚拟环境退出
deactivate

# 定时任务管理
crontab -l
crontab -e
# 替换PID为查到的项目进程号
kill -9 PID

八、项目迭代更新流程（后续改代码、加依赖通用步骤）

本地修改代码、新增第三方依赖；
本地虚拟环境中重新执行 pip freeze > requirements.txt 更新依赖清单；
上传新代码和新的requirements.txt到服务器，直接覆盖就行；
服务器对应环境更新依赖：
1. 虚拟环境方案：激活环境后 pip install -r requirements.txt
2. 全局环境方案：直接 pip3 install -r requirements.txt
杀死旧进程，重新后台启动项目完成更新。

九、常见问题避坑汇总

重新连接服务器后Python环境失效 ：虚拟环境为会话临时生效，重连需重新执行 source .venv/bin/activate
服务器依赖安装报错：优先检查本地是否在虚拟环境导出纯净依赖，全局环境冗余包会导致冲突
后台运行看不到打印输出：正常现象，后台日志全部存入 run.log，前台运行仅用于测试
项目启动端口占用：部署前确认端口未被占用，云服务器需放行安全组端口、服务器开启防火墙端口
多项目部署错乱：严禁多项目使用全局环境，必须每个项目单独配置虚拟环境