Python 十二要素应用在 Python 项目中的落地检查

十二要素应用的核心是彻底分离配置与代码：环境变量注入所有外部依赖，禁用硬编码和本地路径，procfile 明确进程类型，日志输出到 stdout，端口动态读取，确保一份代码在任意环境无修改部署。

怎么判断你的 python 项目算不算“十二要素应用”

不是靠 checklist 打钩，而是看 config 是否彻底和代码分离、__main__.py 是否只负责启动、requirements.txt 是否不含 -e 或本地路径。真正在生产环境跑起来时，换一套环境变量就能切走数据库、日志地址、API 密钥——这才是落地的信号。

常见错误现象：os.environ.get('DB_URL', 'sqlite:///dev.db') 这种兜底写法，会让本地开发“跑得通”，但上线后因环境变量缺失退回到 sqlite，查半天才发现不是配置没传，是代码偷偷 fallback 了。

• 所有外部依赖（数据库、缓存、消息队列）必须通过环境变量注入，不能有硬编码或文件读取逻辑
• manage.py 或 app.py 不该直接 import settings.py；应该用 os.getenv('FLASK_ENV', 'production') 动态加载对应配置模块
• 静态资源路径（如 Static_ROOT）也要从环境变量来，别写死 '/var/www/static'

Python 里哪些地方最容易违反“一份代码，多份部署”原则

核心矛盾在 setup.py 和 pyproject.toml 的写法，以及 import 路径设计。比如用 pip install -e . 本地调试很爽，但容器镜像里如果还这么装，就等于把开发机路径（/home/user/myproj）带进了生产环境，导致 __file__ 计算路径出错、模板找不到、迁移脚本读不到 migrations/ 目录。

使用场景：docker 构建时用 copy . /app 后执行 pip install .，而不是 pip install -e .。

立即学习“Python免费学习笔记（深入）”；

• pyproject.toml 里删掉 editable = true，或压根不用它控制安装方式
• 避免在代码里用 os.path.dirname(__file__) 拼配置路径；改用 importlib.resources.files('myapp').joinpath('config.yaml')（Python 3.9+）
• 测试用的 conftest.py 别塞进 src/ 或 app/ 目录，否则打包会混进去

为什么 Procfile 在 Python 项目里常被忽略，又为什么它其实关键

很多人觉得 Python 没有 web、worker 这种进程类型区分，就跳过 Procfile。但 Heroku、Render、甚至自建的 systemd + supervisor 管理，都靠它识别进程角色。缺了它，你就没法让 Web 服务和 Celery worker 分开扩缩容，也没法让 sentry 自动标记不同进程的错误来源。

参数差异：web: gunicorn app:app 和 worker: celery -A tasks worker 必须写清楚，不能合并成一条命令。

• Procfile 必须放在项目根目录，且不加扩展名（不是 Procfile.txt）
• 命令里不要用 && 连多个服务，每个进程类型只能有一条命令
• 如果用 fastapi，web: 行别写 uvicorn main:app，要加 --host 0.0.0.0:8000 --proxy-headers，否则反向代理下 request.url 会错

日志和端口暴露怎么才算符合十二要素的“无状态”要求

Python 默认把日志打到 stderr 是对的，但很多人忘了关掉 RotatingFileHandler，或者在 gunicorn.conf.py 里写了 accesslog = '/var/log/gunicorn_access.log'。一旦用了文件写入，就违背了“日志由执行环境收集”的原则——容器里根本没这个目录，或者多个副本抢写一个文件。

性能影响：用 sys.stdout.write() 写结构化 json 日志比用 Logging.FileHandler 快 3–5 倍，且能被 Docker 或 kubernetes 的日志驱动原生解析。

• 删掉所有 FileHandler、TimedRotatingFileHandler 实例
• PORT 必须从 os.getenv('PORT', '8000') 读，不能写死 app.run(port=8000)；Gunicorn 启动参数也得用 --bind :$PORT
• 健康检查接口（如 /healthz）返回值里别带内存占用、连接池数等运行时状态，只返回服务是否可响应

真正难的不是写对这十几条，而是每次加新功能时，下意识检查它有没有悄悄引入环境耦合——比如新增一个 excel 导出，顺手把 open('/tmp/report.xlsx', 'wb') 写进去了，就破功了。