twelve-factor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Twelve-Factor App

十二因素应用

The Twelve-Factor App methodology is a set of best practices for building software-as-a-service apps. In 2025, it remains the gold standard for Cloud Native microservices and containerized applications.

十二因素应用方法论是一套构建软件即服务（SaaS）应用的最佳实践。在2025年，它仍然是Cloud Native微服务和容器化应用的黄金标准。

When to Use

适用场景

ALWAYS, for any web application or service destined for the cloud (Kubernetes, PaaS, Serverless).
Migrating legacy apps to the cloud (Replatforming).

任何面向云环境（Kubernetes、PaaS、Serverless）的Web应用或服务，均应遵循该方法论。
将遗留应用迁移至云环境（重新平台化）时。

The Twelve Factors (2025 Context)

2025语境下的十二项因素

Codebase: One codebase tracked in revision control (Git), many deploys.
Dependencies: Explicitly declare and isolate dependencies (Docker, package.json). No system-wide installs.
Config: Store config in the environment (Env Vars, Secrets Manager). Never in code.
Backing Services: Treat backing services (DB, Queue, Cache) as attached resources (URL/Credentials).
Build, Release, Run: Strictly separate build and run stages. CI/CD pipelines are mandatory.
Processes: Execute the app as one or more stateless processes. State goes to backing services (Redis/DB).
Port Binding: Export services via port binding (e.g.,
```
app.listen(8080)
```
). No reliance on server injection (Tomcat).
Concurrency: Scale out via the process model (Replicas in K8s).
Disposability: Maximize robustness with fast startup and graceful shutdown (SIGTERM handling).
Dev/Prod Parity: Keep development, staging, and production as similar as possible (Docker helps here).
Logs: Treat logs as event streams. Do not write to files; write to
```
stdout
```
/
```
stderr
```
.
Admin Processes: Run admin/management tasks as one-off processes (e.g., DB migrations) in the same environment.

代码库：一个代码库通过版本控制系统（Git）追踪，可部署至多个环境。
依赖项：显式声明并隔离依赖项（Docker、package.json），不使用系统级安装。
配置：将配置存储在环境中（环境变量、Secrets Manager），绝不要放在代码里。
支撑服务：将支撑服务（数据库、队列、缓存）视为附加资源（通过URL/凭证访问）。
构建、发布、运行：严格分离构建与运行阶段，CI/CD流水线是必备项。
进程：将应用作为一个或多个无状态进程执行，状态存储在支撑服务（Redis/数据库）中。
端口绑定：通过端口绑定暴露服务（例如：
```
app.listen(8080)
```
），不依赖服务器注入（如Tomcat）。
并发：通过进程模型横向扩展（如K8s中的副本Replicas）。
可处置性：通过快速启动和优雅关闭（处理SIGTERM信号）最大化健壮性。
开发/生产一致性：尽可能保持开发、预发布和生产环境的一致性（Docker可助力实现）。
日志：将日志视为事件流，不要写入文件，应输出到
```
stdout
```
/
```
stderr
```
。
管理进程：在相同环境中以一次性进程运行管理/运维任务（如数据库迁移）。

Quick Start (Dockerized App)

快速入门（Docker化应用）

dockerfile

undefined

dockerfile

undefined

Dockerfile embodies dependencies, port binding, and build/run separation

Dockerfile体现了依赖项、端口绑定以及构建/运行分离

FROM node:20-alpine AS builder WORKDIR /app COPY package.json . RUN npm ci COPY . . RUN npm run build

FROM node:20-alpine WORKDIR /app

FROM node:20-alpine AS builder WORKDIR /app COPY package.json . RUN npm ci COPY . . RUN npm run build

FROM node:20-alpine WORKDIR /app

Dependencies

依赖项

COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules

Config via Env

通过环境变量配置

ENV PORT=8080

Port Binding

端口绑定

EXPOSE 8080

Disposability (Process 1)

可处置性（进程1）

CMD ["node", "dist/main.js"]

undefined