- 12-Factor App 解决什么问题
- 一句话概括 12 个原则
- 1. Codebase：一份代码库，多份部署
- 2. Dependencies：显式声明并隔离依赖
- 3. Config：配置存放在环境中
- 4. Backing services：后端服务都是可替换资源
- 5. Build, release, run：分离构建、发布和运行
- 6. Processes：应用以无状态进程运行
- 7. Port binding：通过端口绑定提供服务
- 8. Concurrency：通过进程模型水平扩展
- 9. Disposability：快速启动，优雅终止
- 10. Dev/prod parity：开发、预发、生产尽量一致
- 11. Logs：日志作为事件流输出
- 12. Admin processes：管理任务作为一次性进程运行
- 12-Factor App 和云原生的关系
- 实践时不要教条化
12-Factor App，也常写作 The Twelve-Factor App，是一套面向现代 Web 应用和 SaaS 应用的工程方法论。它最早由 Heroku 总结出来，目标是让应用更容易部署、更容易扩缩容，也更适合在云环境中运行。
它并不是某一种框架，也不是某一种具体技术，而是一组设计原则。今天我们常说的云原生、容器化、持续交付、基础设施即代码、平台工程，很多实践都能在 12-Factor App 里找到影子。
官方站点在这里：12factor.net。
12-Factor App 解决什么问题
一个应用刚开始通常很简单：开发者在本地写代码，连一个本地数据库，启动一个进程，手动改配置，手动部署。
但应用一旦进入真实生产环境，问题就会变多：
- 同一套代码要部署到开发、测试、预发、生产多个环境；
- 数据库、缓存、消息队列、对象存储等外部依赖越来越多；
- 配置、密钥、连接串不能写死在代码里；
- 应用需要水平扩容；
- 发布要可回滚；
- 日志要能被统一采集；
- 线上进程要能快速启动、优雅退出；
- 临时脚本、数据库迁移、管理任务也要可控执行。
12-Factor App 的核心就是：把应用设计成一个可移植、可配置、可扩展、易部署的服务单元。
一句话概括 12 个原则
| 序号 | Factor | 核心含义 |
|---|---|---|
| 1 | Codebase | 一份代码库，多份部署 |
| 2 | Dependencies | 显式声明并隔离依赖 |
| 3 | Config | 配置存放在环境中 |
| 4 | Backing services | 后端服务都当作可替换资源 |
| 5 | Build, release, run | 严格分离构建、发布、运行 |
| 6 | Processes | 应用以无状态进程运行 |
| 7 | Port binding | 通过端口绑定对外提供服务 |
| 8 | Concurrency | 通过进程模型水平扩展 |
| 9 | Disposability | 快速启动，优雅终止 |
| 10 | Dev/prod parity | 尽量保持开发、预发、生产一致 |
| 11 | Logs | 日志作为事件流输出 |
| 12 | Admin processes | 管理任务作为一次性进程运行 |
下面逐个展开。
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 到服务器上手工执行一段不受版本控制的脚本。
更好的方式是：管理任务和应用代码一起纳入版本控制，使用和应用相同的依赖、相同的配置、相同的发布环境，以一次性进程的方式执行。
比如：
# Rails
rails db:migrate
# Django
python manage.py migrate
# Spring Boot
java -jar app.jar migrate
# Kubernetes Job
kubectl 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 当作一组架构检查清单，而不是宗教戒律。