Back to Details

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语境下的十二项因素

  1. Codebase: One codebase tracked in revision control (Git), many deploys.
  2. Dependencies: Explicitly declare and isolate dependencies (Docker, package.json). No system-wide installs.
  3. Config: Store config in the environment (Env Vars, Secrets Manager). Never in code.
  4. Backing Services: Treat backing services (DB, Queue, Cache) as attached resources (URL/Credentials).
  5. Build, Release, Run: Strictly separate build and run stages. CI/CD pipelines are mandatory.
  6. Processes: Execute the app as one or more stateless processes. State goes to backing services (Redis/DB).
  7. Port Binding: Export services via port binding (e.g., 
    app.listen(8080)
    ). No reliance on server injection (Tomcat).
  8. Concurrency: Scale out via the process model (Replicas in K8s).
  9. Disposability: Maximize robustness with fast startup and graceful shutdown (SIGTERM handling).
  10. Dev/Prod Parity: Keep development, staging, and production as similar as possible (Docker helps here).
  11. Logs: Treat logs as event streams. Do not write to files; write to 
    stdout
    /
    stderr
    .
  12. Admin Processes: Run admin/management tasks as one-off processes (e.g., DB migrations) in the same environment.
  1. 代码库：一个代码库通过版本控制系统（Git）追踪，可部署至多个环境。
  2. 依赖项：显式声明并隔离依赖项（Docker、package.json），不使用系统级安装。
  3. 配置：将配置存储在环境中（环境变量、Secrets Manager），绝不要放在代码里。
  4. 支撑服务：将支撑服务（数据库、队列、缓存）视为附加资源（通过URL/凭证访问）。
  5. 构建、发布、运行：严格分离构建与运行阶段，CI/CD流水线是必备项。
  6. 进程：将应用作为一个或多个无状态进程执行，状态存储在支撑服务（Redis/数据库）中。
  7. 端口绑定：通过端口绑定暴露服务（例如：
    app.listen(8080)
    ），不依赖服务器注入（如Tomcat）。
  8. 并发：通过进程模型横向扩展（如K8s中的副本Replicas）。
  9. 可处置性：通过快速启动和优雅关闭（处理SIGTERM信号）最大化健壮性。
  10. 开发/生产一致性：尽可能保持开发、预发布和生产环境的一致性（Docker可助力实现）。
  11. 日志：将日志视为事件流，不要写入文件，应输出到
    stdout
    /
    stderr
    。
  12. 管理进程：在相同环境中以一次性进程运行管理/运维任务（如数据库迁移）。

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
COPY --from=builder /app/dist ./dist COPY --from=builder /app/node_modules ./node_modules

Config via Env

通过环境变量配置

ENV PORT=8080
ENV PORT=8080

Port Binding

端口绑定

EXPOSE 8080
EXPOSE 8080

Disposability (Process 1)

可处置性（进程1）

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

Best Practices

最佳实践

Do:
  • Use Docker to satisfy dependencies and dev/prod parity.
  • Use Environment Variables for secrets and config.
  • Implement Graceful Shutdown to stop accepting new requests and finish current ones.
Don't:
  • Don't hardcode IP addresses or file paths.
  • Don't rely on "Sticky Sessions" (violates Statelessness).
  • Don't log to local files in a container (they vanish).
建议做法：
  • 使用Docker来满足依赖项管理和开发/生产一致性需求。
  • 使用环境变量存储密钥和配置。
  • 实现优雅关闭，停止接收新请求并完成当前处理的请求。
不建议做法：
  • 不要硬编码IP地址或文件路径。
  • 不要依赖“粘性会话（Sticky Sessions）”（违反无状态原则）。
  • 不要在容器中写入本地文件（容器销毁后文件会消失）。

References

参考资料