3. 开发环境搭建：Python虚拟环境、Docker环境、Git版本控制、项目初始化
好，咱们正式开始动手了。
这一章，说白了就是先把“家伙事儿”备齐。我见过太多人，代码写了一半，发现环境冲突、版本不对、部署失败——最后查出来是Python包没隔离好。嗯，这种坑我踩过不止一次。
所以，咱们一步到位，把开发环境整得干干净净。
3.1 Python虚拟环境：为什么必须隔离？
你想想看，一个项目用Flask 2.0，另一个项目用Flask 3.0。如果都装在系统全局，那不就打架了吗？
Python虚拟环境就是干这个的——每个项目有自己的“小房间”，互不干扰。
核心原则：每个OTA项目，单独建一个虚拟环境。别偷懒。
3.1.1 创建虚拟环境
我个人习惯用 venv，Python 3.3+ 自带，不用装额外工具。
# 进入你的项目目录
mkdir ota-platform
cd ota-platform
# 创建虚拟环境（名字叫 venv 是惯例）
python3 -m venv venv
# 激活虚拟环境
# Linux/Mac:
source venv/bin/activate
# Windows:
venv\Scripts\activate
# 看到终端前面多了 (venv) 就对了
小技巧：激活后，用 which python 看看路径。如果指向了 venv 目录下的 python，说明隔离成功了。
3.1.2 安装依赖包
咱们这个平台需要几个核心库。我先把常用的列出来：
# 升级 pip 到最新
pip install --upgrade pip
# 安装核心依赖
pip install flask==2.3.0
pip install flask-sqlalchemy==3.0.0
pip install requests==2.31.0
pip install paho-mqtt==1.6.1
pip install gunicorn==20.1.0
为什么要固定版本号？我在项目中遇到过，某次升级 Flask 后，路由注册方式变了，整个后端崩了。从那以后，我所有项目都用 requirements.txt 锁死版本。
# 导出当前环境的依赖列表
pip freeze > requirements.txt
# 以后别人拉代码后，一键安装
pip install -r requirements.txt
3.2 Docker环境：让部署不再“玄学”
Python虚拟环境解决了本地开发的问题。但到了服务器上呢？操作系统不同、系统库版本不同，照样跑不起来。
Docker 就是终极方案——把你的应用和所有依赖打包成一个“集装箱”，到哪都能跑。
3.2.1 安装 Docker
这个我就不细说了，去官网下载对应系统的 Docker Desktop 就行。安装完记得启动。
验证一下：
docker --version
docker compose version
注意：Linux 用户安装后，记得把当前用户加入 docker 组，否则每次都要 sudo。
sudo usermod -aG docker $USER
# 然后退出重新登录3.2.2 编写 Dockerfile
咱们的 OTA 平台后端，用 Python 写的。Dockerfile 长这样：
# 使用官方 Python 3.10 镜像作为基础
FROM python:3.10-slim
# 设置工作目录
WORKDIR /app
# 先复制依赖文件，再安装依赖
# 这样做可以利用 Docker 的缓存机制，加快构建速度
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# 复制项目代码
COPY . .
# 暴露端口
EXPOSE 5000
# 启动命令
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]
这里有个细节：COPY requirements.txt . 和 COPY . . 分开写。为什么？因为 Docker 构建时，每一行命令都会生成一个缓存层。如果代码改了但依赖没变，Docker 会直接复用之前的缓存，省时间。
3.2.3 使用 Docker Compose 编排服务
咱们的平台不止一个服务——后端、数据库、可能还有 MQTT 消息队列。用 docker-compose.yml 统一管理：
version: '3.8'
services:
web:
build: .
ports:
- "5000:5000"
depends_on:
- db
environment:
- DATABASE_URL=postgresql://ota_user:ota_pass@db:5432/ota_platform
db:
image: postgres:15
environment:
- POSTGRES_USER=ota_user
- POSTGRES_PASSWORD=ota_pass
- POSTGRES_DB=ota_platform
volumes:
- pgdata:/var/lib/postgresql/data
volumes:
pgdata:
避坑指南：我曾经把数据库密码直接写在 docker-compose.yml 里，结果不小心提交到了 Git 仓库。嗯，从那以后我改用 .env 文件来管理敏感信息。
3.3 Git版本控制：代码的“后悔药”
没有 Git 的项目，就像没有刹车的车——你敢开吗？
我见过有人用“最终版v3”、“最终版v4_真的不改了”这种文件名来管理代码。说实话，那场面挺惨的。
3.3.1 初始化 Git 仓库
# 在项目根目录执行
git init
# 创建 .gitignore 文件，排除不需要跟踪的文件
echo "venv/" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore
echo ".env" >> .gitignore
echo ".DS_Store" >> .gitignore
# 添加所有文件并提交
git add .
git commit -m "初始化 OTA 升级管理平台项目"
3.3.2 分支管理策略
我个人习惯用这种分支结构：
| 分支名 | 用途 |
|---|---|
main |
生产环境代码，只从 release 分支合并 |
develop |
日常开发的主分支 |
feature/xxx |
新功能开发，从 develop 拉出，完成后合并回去 |
release/x.x |
发布前的测试分支 |
hotfix/xxx |
紧急修复，从 main 拉出，修完合并到 main 和 develop |
说白了，就是别在 main 上直接改代码。我刚开始工作时，有次直接在 main 上改了个 bug，结果忘了合并回 develop，后面同事一拉代码，bug 又回来了……那叫一个尴尬。
3.4 项目初始化：搭好架子
环境都准备好了，咱们把项目目录结构搭起来。一个清晰的目录结构，能让后面少走很多弯路。
ota-platform/
├── app/ # 应用主代码
│ ├── __init__.py
│ ├── models/ # 数据库模型
│ ├── routes/ # API 路由
│ ├── services/ # 业务逻辑
│ └── utils/ # 工具函数
├── migrations/ # 数据库迁移文件
├── tests/ # 测试代码
├── docker/ # Docker 相关配置
├── docs/ # 文档
├── .env # 环境变量（不提交到 Git）
├── .gitignore
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── app.py # 应用入口
创建目录的命令：
mkdir -p app/{models,routes,services,utils}
mkdir -p migrations tests docker docs
touch app/__init__.py app.py
到这里，开发环境就搭好了。你可以用 git status 看看当前状态，然后提交一次：
git add .
git commit -m "搭建项目目录结构"3.5 验证一下
最后，咱们跑个简单的 Flask 应用，验证整个环境是否通顺。
在 app.py 里写：
from flask import Flask
app = Flask(__name__)
@app.route('/')
def hello():
return "OTA Platform is running!"
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5000, debug=True)
然后启动：
# 确保虚拟环境已激活
python app.py
浏览器打开 http://localhost:5000，看到 "OTA Platform is running!" 就说明环境搭建成功了。
小提示：如果你用 Docker，可以试试 docker compose up 启动整个服务栈。看到 web 和 db 两个容器都正常运行，那你的 Docker 环境也没问题了。
嗯，环境搭建这块就这些。下一章咱们开始写真正的 OTA 业务逻辑——设备注册和固件上传。到时候你会发现，今天搭的环境有多重要。