夜雨聆风12-Factor App，也常写作 The Twelve-Factor App，是一套面向现代 Web 应用和 SaaS 应用的工程方法论。它最早由 Heroku 总结出来，目标是让应用更容易部署、更容易扩缩容，也更适合在云环境中运行。
它并不是某一种框架，也不是某一种具体技术，而是一组设计原则。今天我们常说的云原生、容器化、持续交付、基础设施即代码、平台工程，很多实践都能在 12-Factor App 里找到影子。
官方站点在这里：12factor.net。
12-Factor App 解决什么问题
一个应用刚开始通常很简单：开发者在本地写代码，连一个本地数据库，启动一个进程，手动改配置，手动部署。
但应用一旦进入真实生产环境，问题就会变多：
同一套代码要部署到开发、测试、预发、生产多个环境； 数据库、缓存、消息队列、对象存储等外部依赖越来越多； 配置、密钥、连接串不能写死在代码里； 应用需要水平扩容； 发布要可回滚； 日志要能被统一采集； 线上进程要能快速启动、优雅退出； 临时脚本、数据库迁移、管理任务也要可控执行。
12-Factor App 的核心就是：把应用设计成一个可移植、可配置、可扩展、易部署的服务单元。
一句话概括 12 个原则
下面逐个展开。
1. Codebase：一份代码库，多份部署
一个应用应该对应一个代码库，这份代码库通过 Git 之类的版本控制系统管理。
同一份代码可以部署到多个环境，比如：
本地开发环境； 测试环境； 预发环境； 生产环境； 不同客户的私有化环境。
这些环境不应该靠维护多份代码来区分，而应该通过不同配置、不同发布版本来区分。
这条原则看似简单，但它能避免很多混乱：生产环境临时改了一份代码、本地分支和线上不一致、某个客户版本长期游离在主线之外，这些都会让系统越来越难维护。
2. Dependencies：显式声明并隔离依赖
应用依赖什么，就应该明确写出来，而不是依赖机器上“刚好装了什么”。
比如：
Java 用 pom.xml、build.gradle；Node.js 用 package.json、package-lock.json；Python 用 requirements.txt、pyproject.toml、uv.lock；Ruby 用 Gemfile、Gemfile.lock。
同时，依赖还应该被隔离。不同应用之间不应该共享一套不可控的全局依赖。
容器、虚拟环境、语言自带的依赖管理工具，都是在帮我们实现这一点。这样做的结果是：新机器、新环境、CI/CD 流水线都能根据声明文件稳定地安装依赖，而不是靠口口相传的部署文档。
3. Config：配置存放在环境中
配置是指不同部署环境之间会变化的内容，例如：
数据库连接串； Redis 地址； API Key； 第三方服务地址； 日志级别； 功能开关； 密钥和证书路径。
12-Factor App 主张把这些配置从代码中分离出来，放到环境变量中。
核心思想不是“环境变量本身最完美”，而是：代码和配置必须分离。
在 Kubernetes 中，配置可能来自 ConfigMap、Secret；在云平台中，可能来自参数管理、密钥管理服务；在传统部署中，也可能来自 .env 文件或启动脚本。无论具体形式如何，都不应该把生产数据库密码写进代码仓库。
4. Backing services：后端服务都是可替换资源
应用通常会依赖很多外部服务：
数据库； 缓存； 消息队列； 对象存储； 邮件服务； 搜索引擎； 第三方 API。
12-Factor App 把这些都称为 backing services，也就是应用背后的支撑服务。
重点是：应用不应该假设这些服务一定部署在哪里，或者一定是某个固定实例。它们应该像资源一样被“挂载”到应用上。
比如，应用只需要知道数据库 URL，而不需要知道数据库是本机进程、Docker 容器、云数据库，还是临时测试库。只要连接信息变化，应用就能切换到新的后端服务。
这让故障迁移、环境切换、云服务替换都变得更容易。
5. Build, release, run：分离构建、发布和运行
12-Factor App 把应用生命周期分成三个阶段：
- Build：
把代码转换成可运行制品，例如 jar 包、镜像、静态文件； - Release：
把构建产物和环境配置组合起来，形成某一次可部署发布； - Run：
在目标环境中启动发布版本。
这三个阶段应该严格分离。
一个常见的反例是：生产环境启动时再拉代码、编译、打包、修改配置、直接运行。这样做的问题是不可重复，也很难回滚。
更好的方式是：CI 里完成构建，生成不可变制品；发布系统把制品和配置组合成一个版本；运行环境只负责启动这个版本。如果出现问题，就回滚到上一个 release。
6. Processes：应用以无状态进程运行
12-Factor App 要求应用进程是无状态的。
所谓无状态，不是说应用不能有数据，而是说：进程本身不应该保存必须长期存在的状态。
长期状态应该放在数据库、缓存、对象存储等外部服务里。应用进程可以随时被杀掉、重启、替换，用户请求不应该依赖某个固定进程才能继续。
这条原则是水平扩容的基础。如果应用状态绑定在单个进程上，那么负载均衡、滚动发布、自动伸缩都会变得麻烦。
当然，现实中仍然会有一些内存缓存、连接池、本地临时文件，但这些都应该被视为可丢弃的运行时状态，而不是核心业务状态。
7. Port binding：通过端口绑定提供服务
一个 12-Factor App 应该自包含地启动服务，并通过端口对外提供能力。
例如，一个 Web 应用启动后监听 8080 端口，平台或反向代理再把外部流量转发过来。
这和早期把应用打成 war 包丢进外部应用服务器的模式不同。12-Factor App 更倾向于让应用自己包含运行时，自己监听端口，对平台暴露一个清晰的服务入口。
这也是为什么 Spring Boot、Express、FastAPI、Go HTTP Server 这类自启动服务模型在云环境中很常见。
8. Concurrency：通过进程模型水平扩展
当访问量变大时，不应该只想着把单个进程做得越来越复杂，而应该通过增加进程数量来扩展。
例如：
增加更多 Web 进程处理 HTTP 请求； 增加更多 Worker 进程处理异步任务； 增加更多 Consumer 进程消费消息队列； 为不同任务类型使用不同进程模型。
在 Kubernetes 里，这通常对应增加 Pod 副本数；在传统进程管理中，可能对应增加进程数或机器数。
这条原则的重点是：应用架构要允许横向扩展，而不是只能依赖一台更大的机器。
9. Disposability：快速启动，优雅终止
云环境里的进程随时可能被调度、重启、替换、扩容、缩容。
所以应用应该做到两点：
- 快速启动：
新实例可以尽快加入服务； - 优雅终止：
收到退出信号后，停止接收新请求，处理完当前请求，释放资源，然后退出。
这对滚动发布、自动扩缩容、故障恢复都很重要。
比如，在 Kubernetes 中，应用应该正确处理 SIGTERM，配合 readiness probe、liveness probe、preStop hook 等机制，避免流量还没摘除就被强制杀掉。
10. Dev/prod parity：开发、预发、生产尽量一致
很多线上问题来自环境不一致：
本地用 SQLite，生产用 PostgreSQL； 本地没有消息队列，生产有消息队列； 开发环境版本很旧，生产环境版本很新； 测试数据和真实数据形态差异太大； 部署流程在不同环境里完全不同。
12-Factor App 主张尽量缩小开发、预发、生产之间的差距。
这并不是说所有环境都要完全一样，而是说关键依赖、运行方式、发布流程应该尽量一致。Docker Compose、Dev Container、测试环境自动化、基础设施即代码，都是在降低这种差距。
环境越接近，问题越早暴露；问题越早暴露，修复成本越低。
11. Logs：日志作为事件流输出
应用不应该自己负责管理日志文件的生命周期，比如切割、压缩、归档、上传。
12-Factor App 的建议是：应用把日志当作事件流，直接输出到标准输出或标准错误。
日志的采集、存储、搜索、分析，交给运行平台处理，例如：
Docker logging driver； Kubernetes 日志采集； Fluent Bit / Fluentd； Elasticsearch / OpenSearch； Loki； 云厂商日志服务。
这样做的好处是应用更简单，平台也更容易统一管理日志。
12. Admin processes：管理任务作为一次性进程运行
应用除了正常处理请求，还经常需要执行一些管理任务：
数据库迁移； 数据修复； 创建管理员账号； 批量导入数据； 临时统计脚本； 清理历史数据。
这些任务不应该靠开发者 SSH 到服务器上手工执行一段不受版本控制的脚本。
更好的方式是：管理任务和应用代码一起纳入版本控制，使用和应用相同的依赖、相同的配置、相同的发布环境，以一次性进程的方式执行。
比如：
# Railsrails db:migrate# Djangopython manage.py migrate# Spring Bootjava -jar app.jar migrate# Kubernetes Jobkubectl apply -f migration-job.yaml
这样管理任务也变成了可审计、可重复、可回滚的发布体系的一部分。
12-Factor App 和云原生的关系
12-Factor App 出现得比今天很多云原生概念更早，但它和云原生非常契合。
如果把一个应用按照 12-Factor App 的方式设计，那么它通常会比较容易迁移到：
Docker； Kubernetes； PaaS 平台； Serverless 平台； CI/CD 流水线； 自动扩缩容环境。
可以这样理解：
12-Factor App 关注的是应用应该怎么写； 容器关注的是应用怎么打包； Kubernetes 关注的是应用怎么调度和运行； CI/CD 关注的是应用怎么构建、测试和发布； 可观测性平台关注的是运行后怎么监控和排障。
这些东西组合起来，才是一套完整的现代应用交付体系。
实践时不要教条化
12-Factor App 很有价值，但也不需要机械照搬。
比如“配置放环境变量”这条，在小应用里很方便，但在复杂企业系统里，配置中心、密钥管理、动态配置也许更合适。关键不是必须用环境变量，而是要做到配置和代码分离。
再比如“无状态进程”，对于普通 Web API 很自然，但对于实时协作、游戏服务器、流处理任务、长连接服务，就需要更精细的状态设计。
所以更合理的态度是：把 12-Factor App 当作一组架构检查清单，而不是宗教戒律。
