企业微信自动化通知系统搭建与排错笔记-虚拟环境
Python 虚拟环境开发与容器化部署全流程笔记
一、 核心架构思路：开发与部署分离
在实际工程中，遵循“开发时轻量、部署时标准”的原则：
- 排错与试错阶段（虚拟环境）：不使用 Podman，直接在宿主机的隔离虚拟环境中运行
app.py。改动代码后秒级重启，拥有极高的调试效率和直观的日志输出。 - 定型与生产阶段（容器镜像）：代码完全通过验证后，将虚拟环境的依赖固化，并构建只读的容器镜像，确保生产环境的稳定、安全与资源隔离。
二、 虚拟环境下的多次排错与试错步骤
步骤 1：初始化并进入虚拟环境
在服务器的项目根目录下，创建一个完全纯净、不污染宿主机的虚拟环境：
# 1. 创建名为 venv 的虚拟环境文件夹
python3 -m venv venv
# 2. 激活并进入该虚拟环境
source venv/bin/activate
激活后，终端命令行最前端会出现 (venv) 标记，表明当前处于隔离环境中。
步骤 2：安装基础排错依赖
在虚拟环境中，直接使用 pip 安装开发所需的组件。由于环境隔离，此操作不需要 sudo 权限：
pip install fastapi uvicorn requests
3. 注入环境变量与多次循环排错
为了让 app.py 能够读取到企业微信的各种凭证，同时不把密钥硬编码在代码里，每次运行脚本前在终端直接通过 export 注入临时环境变量。
# 1. 注入排错所需的测试变量
export CORP_ID="ww71f41256ef5996d0"
export KF_SECRET="wvFzT8Y3Zp1f1huKrClLwzFroQp0MAEmGND2fxhN2aQ"
export TO_USER_ID="ZhaoPengPeng" # 试错阶段，可根据探测结果随时更换
# 2. 启动服务，直接观察终端输出
python3 -m uvicorn app:app --host 0.0.0.0 --port 8000
多次循环试错逻辑：
- 测试接口：在另一个终端或浏览器中请求
http://localhost:8000/webhook?msg=测试。 - 捕获报错：如果遇到
40058（缺少参数）或60111（UserID不存在），在代码内部加入print(res)直接打印腾讯的原始返回。 - 快速重载：发现逻辑问题后，使用
nano app.py修改代码。在终端按下Ctrl + C终止进程，接着按方向键上 + 回车即可在 1 秒内重新启动，继续下一次测试。
三、 确定最终方案与向镜像过渡
当自建应用成功将消息砸入手机、终端不再出现任何报错、业务通路彻底闭环时，说明方案已经定型。此时开启向容器镜像转换的标准化流转：
步骤 1：环境快照（固化依赖清单）
在虚拟环境中，利用 pip freeze 自动收集当前成功运行所依赖的第三方库及精确版本号，生成标准的 requirements.txt：
pip freeze > requirements.txt
这保证了未来容器内部安装的依赖包与当前排错成功的环境分毫不差。
步骤 2：退出虚拟环境
环境清单生成完毕后，即可退出并释放宿主机的虚拟环境：
deactivate
退出后，可以放心删除 venv 文件夹（rm -rf venv），宿主机全局环境未受任何污染。
四、 最终 Build 镜像与一键部署
回到生产部署视角，利用固化好的文件进行 Podman 镜像构建。
1. 编写最终版 Dockerfile
确保项目目录下存在 app.py、requirements.txt 和以下 Dockerfile：
FROM python:3.10-slim
WORKDIR /app
# 复制依赖清单并利用国内源安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
# 复制经过虚拟环境严苛测试的正式版代码
COPY app.py .
EXPOSE 8000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
2. 执行构建与常驻运行 (r.sh)
将完全通过验证的逻辑固化为不可变镜像，并挂载宿主机端口与守护进程：
# 1. 编译构建正式版镜像
podman build -t localhost/zwechat-adapter:v1 .
# 2. 编写或运行启动脚本 r.sh
podman run -d \
--name myz \
-p 8000:8000 \
-m 50m \
--restart always \
-e CORP_ID="ww71f41256ef5996d0" \
-e KF_SECRET="wvFzT8Y3Zp1f1huKrClLwzFroQp0MAEmGND2fxhN2aQ" \
-e TO_USER_ID="TaiHeXin" \
localhost/zwechat-adapter:v1
五、 总结：双剑合璧的工作流
整个从排错到落地的科学规范可以总结为三步：
- 在虚拟环境中疯狂试错：利用
venv获得极速的修改、重启和打印调试体验，阻断环境污染。 - 通过 freeze 提取成果：用
requirements.txt作为纽带，把开发成果无损平移。 - 在容器镜像中固化投产：用
podman build锁定环境，通过资源硬限制（-m 50m）和自愈配置（--restart always）保障生产级别的长期稳定运行。