Ubuntu 24.04 一站式 Flask 生产部署：pyenv + PyCharm + Gunicorn + Nginx + systemd

---

环境说明

操作系统：Ubuntu 24.04.1 LTS
pyenv 版本：2.6.12
Python 版本：3.10.19
pip 版本：23.0.1
gunicorn 版本：23.0.0
PyCharm 版本：2025.2.4
Visual Studio Code 版本：1.105.1
Nginx 版本：1.24.0 (Ubuntu)

---

1、前言：Python 版本说明 & 多版本管理 & 虚拟环境

Python 各版本生命周期

以下截图来源 Python 官网

多版本&虚拟环境：

• pyenv 只管“让哪个 Python 解释器出现在你的 PATH 最前面”，它本身不创建虚拟环境。
• python -m venv（或 python3 -m venv）是官方虚拟环境创建工具，它需要一个“已安装且能用的 Python 解释器”当母体。
• 因此最常见组合：pyenv 先提供/切换解释器 → 再用这个解释器执行 python -m venv 生成虚拟环境 → 最后激活该 venv 隔离依赖。

---

2、搭建 Python 开发环境

2.1、安装 pyenv（多版本神器）

# 依赖
sudo apt install -y git curl build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev libffi-dev tk-dev
# 安装
curl https://pyenv.run | bash

环境变量配置，把下方内容追加到 ~/.bashrc

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# 国内加速
# 阿里云镜像
export PYTHON_BUILD_MIRROR_URL="https://registry.npmmirror.com/-/binary/python"
# 如觉得还慢，可以手动下载对应的安装包，放到目录 ~/.pyenv/cache 后再执行 pyenv install 3.10.19 即可实现手动加速的效果
# 如 pyenv 已使用过，再添加国内加速地址，则使用前需要先更新
# pyenv update

配置生效

source ~/.bashrc
# 查看版本
pyenv --version

安装 3.10 版本

pyenv install 3.10.19
pyenv global 3.10.19
# 验证
python --version

小贴士：Ubuntu 24 自带 Python 3.12，但用 pyenv 能精确切换、隔离，比 apt 更灵活。

---

3、IDE

3.1、PyCharm

（1）安装
说明：不推荐 snap 安装。因为本人不喜欢自动更新！

官方下载地址：https://www.jetbrains.com/pycharm/download/?section=linux

Linux 安装包，解压后，鼠标双击 pycharm 即可运行

（2）创建桌面快捷方式
Ctrl + Alt + T 打开终端

# 进入桌面文件夹
cd /home/change_it_user_name/桌面/
# 创建桌面快捷方式（内容参考下面）
nano PyCharm.desktop
# 增加权限
chmod +x ~/Desktop/PyCharm.desktop
# 鼠标右键 - 允许运行
# 鼠标双击即可正常打开 PyCharm 了

PyCharm.desktop 文件内容如下

[Desktop Entry]
Version=1.0
Name=PyCharm
Exec="/change_it_pycharm_install_dir/bin/pycharm" %F
Icon=/change_it_pycharm_install_dir/bin/pycharm.png
Terminal=false
Type=Application
Categories=Development;IDE;
Comment=The Python IDE for Professional Developers

（3）中文包
说明：不建议安装中文包。因为回头查入口的时候，不容易找，很多文章写的都是英文，容易对不上
安装方式：选择 UI 主题 → 跳过导入 → 插件市场搜索“Chinese”装中文包

（4）首次启动向导
New Project → Pure Python → Location: /home/change_it_username/PycharmProjects/flask-demo
其中 Python Version 下拉选项中，可以看到上面通过 pyenv 安装的版本并且目录对应 ~/pyenv/versions/…… 即代表可以使用 pyenv 安装的 Python 版本了

---

3.2、Visual Studio Code

（1）安装
方法一：通过“应用中心”安装，版本 latest （当前 1.105.1 ）
方法二：官网下载 code_1.105.1-1760482543_amd64.deb 文件，手动安装，版本任选

（2）插件
Flask 开发推荐插件（Python Web 框架）

插件名称	功能说明
Python（ms-python.python）	官方 Python 插件，提供语法高亮、智能提示、调试支持、虚拟环境识别等。
Pylance（ms-python.vscode-pylance）	高性能 Python 语言服务器，提供更智能的类型提示和自动补全。
Flask Snippets	提供 Flask 常用代码片段，快速生成路由、视图函数等模板。
Python Environment Manager	管理 Python 虚拟环境，方便切换解释器。
autoDocstring	自动生成 Python 函数的文档字符串（docstring）。
Indenticator	显示缩进层级，提升代码可读性。
Docker（可选）	如果项目使用容器化部署，Docker 插件可方便管理镜像和容器。
VS Code Remote - WSL / SSH / Containers（可选）	支持远程开发，适合在 Linux 容器或远程服务器上开发 Flask 应用。

Vue 开发推荐插件（Vue 3 推荐）
注意：Vue 2 已于 2023 年底停止维护，新项目建议使用 Vue 3 + Volar 插件。

以下内容为 Markdown 表格格式，可直接复制使用：

插件名称	功能说明
Vue Language Features (Volar)	Vue 3 官方插件，支持语法高亮、类型检查、模板补全、Composition API 支持等。必须安装。
TypeScript Vue Plugin (Volar)	支持 .vue 文件中的 TypeScript 类型推导（如使用 TS 开发 Vue）。
Vue VSCode Snippets	快速生成 Vue 模板代码（如 vbase → 基础组件结构）。
Vue 3 Snippets	提供 Vue 3 和 Composition API 的代码片段。
ESLint	检查 JavaScript/TypeScript/Vue 代码规范，提升代码质量。
Prettier - Code formatter	自动格式化代码，统一代码风格。
Auto Rename Tag	修改 HTML/XML 标签时自动同步闭合标签。
Path Intellisense	自动补全文件路径，方便引入组件或模块。
npm Intellisense	自动补全 import 时的 npm 包名。
Live Server（可选）	本地快速预览静态页面，适合调试 Vue 页面（但不适用于 Vite 项目）。
Vue Peek	快速跳转到 Vue 组件定义处，方便组件导航。

通用插件（前后端通用）

插件名称	功能说明
GitLens	强大的 Git 集成工具，查看提交历史、代码作者等。
Material Icon Theme	美化文件图标，提升项目结构可读性。
One Dark Pro	流行的暗色主题，护眼舒适。
Bracket Pair Colorizer	彩色括号匹配，提升代码可读性。
Code Runner	快速运行小段代码（适合测试 Python 脚本）。

4、Flask

官网：https://flask.palletsprojects.com/en/stable/

4.1、开发 Demo

注意：代码提交一定要排除 .venv 和 venv 文件夹。否则后患无穷！

利用上面步骤创建的项目

（1）最小可运行，经典的 Hello, World!
新建 hello.py
参考：https://flask.palletsprojects.com/en/stable/quickstart/

from flask import Flaskapp = Flask(__name__)@app.route("/")
def hello_world():return "<p>Hello, World!</p>"

终端操作
说明：PyCharm 默认使用的是 .venv 的虚拟环境，无需创建新的虚拟环境。pip install 等命令也可通过 PyCharm 实现，无需命令行手动运行。

# 在项目根目录创建虚拟环境文件夹 venv（使用当前 pyenv 指定的 Python 版本）
python -m venv venv
# 激活虚拟环境；激活后 PATH 最前面加入 venv/bin，pip 指向隔离目录
source venv/bin/activate
# 说明：退出虚拟环境 - deactivate
# 升级 pip 自身，再安装 Flask 与常用扩展（支持 .env 加载与 WSGI 服务器）
pip install -U pip flask python-dotenv gunicorn
# 可通过清华仓库加速 pip install -U pip flask python-dotenv gunicorn -i https://pypi.tuna.tsinghua.edu.cn/simple
# 以调试模式启动开发服务器；自动加载 .env 并开启热重载
flask --app hello.py --debug run

验证 - 浏览器访问 http://localhost:5000 看到 Hello, World! ，代表项目正常启动

（2）工厂模式（便于测试 & 部署）

新建 application.py

from flask import Flask, jsonifydef create_app():app = Flask(__name__)@app.get("/")def index():return jsonify(msg="Hello from factory", version="2.0.0")return app

运行

gunicorn -w 4 -b 0.0.0.0:8000 'application:create_app()'

验证 - 浏览器访问 http://localhost:8000 看到 JSON，代表项目正常启动

（3）打包脚本
生成 requirements.txt 文件

pip freeze > requirements.txt

scripts/build.sh

#!/usr/bin/env bash
# 设置错误选项，任何命令返回非零状态码时立即退出
set -e# 切换到脚本所在目录的上级目录（项目根目录）
cd "$(dirname "$0")/.."# 激活虚拟环境
source venv/bin/activate# 安装或更新依赖包
pip install -r requirements.txt# 设置 Flask 应用入口点环境变量
export FLASK_APP=application:create_app# 运行单元测试，只有测试通过才会继续执行
# 说明:当前代码不包含单元测试,生产环境部署前应完善
# pytest# 使用 gunicorn 启动应用，4个工作进程，绑定到0.0.0.0:8000端口
gunicorn -w 4 -b 0.0.0.0:8000 'application:create_app()'

增加脚本运行权限

chmod +x scripts/build.sh

打包测试

scripts/build.sh

验证 - 浏览器访问 http://localhost:8000 看到 JSON，代表项目正常启动

4.2、部署（服务器）

说明：操作系统版本与开发环境相同，只是没有桌面。

用户访问路径： user → Nginx → Gunicorn → 应用，因此需要部署 Nginx、Python 环境、Gunicorn、应用。

（1）服务器基本设置

# 时区
sudo timedatectl set-timezone Asia/Shanghai
# 查看
sudo timedatectl# 防火墙
# 查看状态
sudo ufw status
# 开通端口
sudo ufw allow 80/tcp
sudo ufw allow 22/tcp
sudo ufw allow 10001/tcp
# 重新加载
sudo ufw reload
# 启用
sudo ufw enable
# 停用
sudo ufw disable

（2）Nginx 安装

# 安装
sudo apt install nginx -y
# 验证及版本查看
sudo nginx -t
sudo nginx -version
# 可通过浏览器访问 http://server_ip 看到 Nginx 欢迎页即代表部署成功

说明：也可按照 Nginx 官方文档：http://nginx.org/en/linux_packages.html#Ubuntu 进行安装。

Nginx 配置，配置文件 /etc/nginx/conf.d/flask-demo.conf

server {listen 10001;server_name  _;location / {proxy_pass http://127.0.0.1:8000;proxy_set_header Host $host;proxy_set_header X-Real-IP $remote_addr;}
}

Nginx 重新加载配置

# 验证配置是否正确
sudo nginx -t
# 重新加载配置
sudo nginx -s reload

验证 - 浏览器访问 http://server_ip:10001 显示 502（应用还没部署）

（3）Python 环境准备
说明：与上文中《安装 pyenv（多版本神器） 》内容相同

# 依赖
sudo apt install -y git curl build-essential libssl-dev zlib1g-dev \
libbz2-dev libreadline-dev libsqlite3-dev libffi-dev tk-dev
# 安装
curl https://pyenv.run | bash

环境变量配置，把下方内容追加到 ~/.bashrc

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"
# 国内加速
# 阿里云镜像
export PYTHON_BUILD_MIRROR_URL="https://registry.npmmirror.com/-/binary/python"
# 如觉得还慢，可以手动下载对应的安装包，放到目录 ~/.pyenv/cache 后再执行 pyenv install 3.10.19 即可实现手动加速的效果
# 如 pyenv 已使用过，再添加国内加速地址，则使用前需要先更新
# pyenv update

配置生效

source ~/.bashrc
# 查看版本
pyenv --version

安装 3.10 版本

pyenv install 3.10.19
pyenv global 3.10.19
# 验证
python --version

小贴士：Ubuntu 24 自带 Python 3.12，但用 pyenv 能精确切换、隔离，比 apt 更灵活。

（4）应用部署

开发环境打包

# 注意：打包一定要排除 .venv 和 venv 文件夹（否则后续会出现虚拟环境不生效等难处理的问题）
zip -r flask-demo.zip flask-demo -x "flask-demo/__pycache__/*" -x "flask-demo/tests/*" -x "flask-demo/.venv/*" -x "flask-demo/venv/*" -x "flask-demo/.idea/*" -x "flask-demo/.pytest_cache/*"
# 复制到服务器 ~/projects/ 文件夹并解压
scp flask-demo.zip changeit_username@server_ip:~

服务器部署

# 安装依赖
sudo apt install unzip -y
# 解压到 /home/changeit_username/projects
# 进入到 flask-demo 目录
# 在项目根目录创建虚拟环境文件夹 venv（使用当前 pyenv 指定的 Python 版本）
python -m venv venv
# 运行脚本
scripts/build.sh
# 脚本会先下载相关的 Python 包，然后启动服务
# 看到 Listening at: http://0.0.0.0:8000 表示服务正常启动了

验证 - 通过浏览器访问 http://server_ip:10001 显示 json 表示服务部署成功

# 停止服务
# 退出虚拟环境
deactivate
# 进行下一步

（5）开机自启动

配置开机自启，文件 /etc/systemd/system/flask-demo.service

[Unit]
Description=Flask Demo
After=network.target[Service]
User=changeit_username
WorkingDirectory=/home/changeit_username/projects/flask-demo
ExecStart=/home/changeit_username/projects/flask-demo/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 'application:create_app()'
Restart=always[Install]
WantedBy=multi-user.target

操作

# 重新加载配置文件
sudo systemctl daemon-reload
# 开机自启
sudo systemctl enable --now flask-demo

验证 - 通过浏览器访问 http://server_ip 可以看到 JSON 返回

（6）常用命令

# 停止服务
sudo systemctl stop flask-demo
# 查看状态
sudo systemctl status flask-demo
# 启动服务
sudo systemctl start flask-demo# 日志
# 只看该服务，从最远一条开始（Shift+G 跳到末尾，q 退出）
journalctl -u flask-demo.service
# 同时跟踪实时日志（类似 tail -f）
journalctl -u flask-demo.service -f
# 时间范围示例（今天 14:00 以后）
journalctl -u flask-demo.service --since "14:00" --no-pager

---

5、FAQ

Q1. pyenv 必须吗？PyCharm 不是能直接建 venv？
A：PyCharm 只能“用”解释器，不能“生”解释器。要测 3.7/3.8/3.10 还是得 pyenv 或其他工具建立虚拟环境。

Q2. systemd 启动失败？
A:
（1）路径错误。 sudo journalctl -u flask-demo -f 看实时日志；确认 WorkingDirectory 与 ExecStart 都用绝对路径。
（2）虚拟环境没生效

---

总结

• pyenv 装多版本，系统 Python 保持原厂
• PyCharm 解释器指向 pyenv，图形化秒切
• Flask 工厂模式 + Gunicorn + systemd + Nginx，生产就绪