phoenix-ops

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phoenix Operations and Deployment (Elixir/BEAM)

Phoenix运维与部署（Elixir/BEAM）

Production-ready Phoenix apps rely on releases, runtime configuration, telemetry, clustering, and secure endpoints. The BEAM enables rolling restarts and supervision resilience when configured correctly.

可用于生产环境的Phoenix应用依赖版本发布、运行时配置、可观测性、集群和安全端点。配置正确的情况下，BEAM支持滚动重启和监督机制带来的高可用性。

Releases and Runtime Config

版本发布与运行时配置

bash

MIX_ENV=prod PHX_SERVER=true mix assets.deploy
MIX_ENV=prod mix release
_build/prod/rel/my_app/bin/my_app eval "IO.puts(:os.type())"
_build/prod/rel/my_app/bin/my_app start

config/runtime.exs

for env-driven settings:

elixir

config :my_app, MyApp.Repo,
  url: System.fetch_env!("DATABASE_URL"),
  pool_size: String.to_integer(System.get_env("POOL_SIZE", "10")),
  ssl: true

config :my_app, MyAppWeb.Endpoint,
  url: [host: System.fetch_env!("PHX_HOST"), port: 443, scheme: "https"],
  http: [ip: {0,0,0,0}, port: String.to_integer(System.get_env("PORT", "4000"))],
  secret_key_base: System.fetch_env!("SECRET_KEY_BASE"),
  server: true

Secrets

Prefer env vars or secret stores (AWS/GCP KMS, Vault); avoid embedding in configs.
Generate
```
SECRET_KEY_BASE
```
with
```
mix phx.gen.secret
```
.

bash

MIX_ENV=prod PHX_SERVER=true mix assets.deploy
MIX_ENV=prod mix release
_build/prod/rel/my_app/bin/my_app eval "IO.puts(:os.type())"
_build/prod/rel/my_app/bin/my_app start

config/runtime.exs

用于读取环境变量驱动的配置：

elixir

config :my_app, MyApp.Repo,
  url: System.fetch_env!("DATABASE_URL"),
  pool_size: String.to_integer(System.get_env("POOL_SIZE", "10")),
  ssl: true

config :my_app, MyAppWeb.Endpoint,
  url: [host: System.fetch_env!("PHX_HOST"), port: 443, scheme: "https"],
  http: [ip: {0,0,0,0}, port: String.to_integer(System.get_env("PORT", "4000"))],
  secret_key_base: System.fetch_env!("SECRET_KEY_BASE"),
  server: true

密钥管理

优先使用环境变量或密钥存储服务（AWS/GCP KMS、Vault）；避免直接嵌入到配置文件中。
使用
```
mix phx.gen.secret
```
生成
```
SECRET_KEY_BASE
```
。

Clustering and PubSub/Presence

集群与PubSub/Presence

Add

libcluster

for automatic node discovery:

elixir

undefined

添加

libcluster

实现节点自动发现：

elixir

undefined

mix.exs deps

mix.exs 依赖项

{:libcluster, "~~> 3.3"}, {:phoenix_pubsub, "~~> 2.1"},

application.ex

topologies = [ dns_poll: [ strategy: Cluster.Strategy.DNSPoll, config: [poll_interval: 5_000, query: "my-app.internal"], connect: {:net_adm, :ping} ] ]

children = [ {Cluster.Supervisor, [topologies, [name: MyApp.ClusterSupervisor]]}, {Phoenix.PubSub, name: MyApp.PubSub}, MyAppWeb.Endpoint ]


**Guidelines**
- Share `secret_key_base` across nodes for consistent session signing.
- Use distributed PubSub for Presence; ensure node connectivity before enabling Presence-heavy features.
- For blue/green, keep cookies compatible between versions.

拓扑配置 = [ dns_poll: [ strategy: Cluster.Strategy.DNSPoll, config: [poll_interval: 5_000, query: "my-app.internal"], connect: {:net_adm, :ping} ] ]

子进程列表 = [ {Cluster.Supervisor, [topologies, [name: MyApp.ClusterSupervisor]]}, {Phoenix.PubSub, name: MyApp.PubSub}, MyAppWeb.Endpoint ]


**规范**
- 所有节点共享`secret_key_base`以保证会话签名一致性。
- Presence功能使用分布式PubSub；在启用重度依赖Presence的功能前先确保节点连通性。
- 蓝绿部署时，不同版本之间的cookie要保持兼容。

Telemetry, Logging, and Metrics

可观测性、日志与指标

Install
```
opentelemetry_phoenix
```
and
```
opentelemetry_ecto
```
for traces/metrics.
Add
```
Plug.Telemetry
```
and
```
LoggerJSON
```
or structured logging.
Export metrics (Prometheus/OpenTelemetry) via
```
:telemetry_poller
```
for VM stats (reductions, memory, schedulers).
Set
```
LOGGER_LEVEL=info
```
in prod; use
```
:debug
```
only for troubleshooting.

安装
```
opentelemetry_phoenix
```
和
```
opentelemetry_ecto
```
采集链路追踪与指标数据。
接入
```
Plug.Telemetry
```
和
```
LoggerJSON
```
实现结构化日志。
通过
```
:telemetry_poller
```
导出指标（Prometheus/OpenTelemetry），采集虚拟机统计数据（规约数、内存、调度器）。
生产环境设置
```
LOGGER_LEVEL=info
```
；仅在排查问题时使用
```
:debug
```
级别。

HTTP and Network Hardening

HTTP与网络安全加固

Enforce HTTPS (
```
force_ssl
```
), HSTS, secure cookies (
```
same_site
```
,
```
secure
```
), and proper
```
content_security_policy
```
.
CORS: configure
```
cors_plug
```
for API origins.
Rate limiting: apply plugs (ETS/Cachex token bucket) or edge (NGINX/Cloudflare).
Uploads: prefer presigned URLs; limit request body size (
```
:max_request_line_length
```
,
```
:max_header_value_length
```
).

强制HTTPS（
```
force_ssl
```
）、HSTS、安全Cookie（
```
same_site
```
、
```
secure
```
）以及合理的
```
content_security_policy
```
配置。
CORS：通过
```
cors_plug
```
配置允许的API来源。
限流：在应用层使用插件（ETS/Cachex令牌桶）或在边缘层配置（NGINX/Cloudflare）实现。
文件上传：优先使用预签名URL；限制请求体大小（
```
:max_request_line_length
```
、
```
:max_header_value_length
```
）。

Assets and Static Delivery

静态资源与交付

```
mix assets.deploy
```
runs npm/tailwind/esbuild and digests assets.
Serve static files via CDN/reverse proxy; ensure
```
cache-control
```
headers set in Endpoint.
Disable unused watchers in production to trim image size.

```
mix assets.deploy
```
会执行npm/tailwind/esbuild构建并为资源添加哈希戳。
通过CDN/反向代理提供静态资源服务；确保在Endpoint中配置了正确的
```
cache-control
```
响应头。
生产环境禁用未使用的监听程序以减小镜像体积。

Background Jobs

后台任务

Oban recommended for retries/backoff, scheduled jobs, and isolation; supervise in
```
application.ex
```
.
Configure queues via runtime env; monitor with Oban Web/Pro or telemetry.
For CPU-heavy tasks, consider pooling or external workers to avoid blocking schedulers.

推荐使用Oban实现重试/退避、定时任务和隔离执行；在
```
application.ex
```
中配置监督。
通过运行时环境变量配置队列；使用Oban Web/Pro或可观测性工具监控队列状态。
对于CPU密集型任务，考虑使用池化或外部Worker避免阻塞调度器。

Deployment Patterns

部署模式

Containers: multi-stage builds; run

mix deps.get --only prod

mix compile

mix assets.deploy

, then

mix release

Systemd: run release binary as service with
```
Environment=
```
secrets; add
```
Restart=on-failure
```
.
Fly/Gigalixir/Render: supply env vars, attach Postgres/Redis, open long-lived WebSocket ports.
Blue/green or canary: keep DB migrations compatible; deploy code first, then run migrations; keep feature flags for schema changes.

容器部署：使用多阶段构建；依次执行
```
mix deps.get --only prod
```
、
```
mix compile
```
、
```
mix assets.deploy
```
，最后执行
```
mix release
```
。
Systemd部署：将发布的二进制文件作为服务运行，通过
```
Environment=
```
配置密钥；添加
```
Restart=on-failure
```
配置。
Fly/Gigalixir/Render平台部署：配置环境变量、绑定Postgres/Redis服务、开放长连接WebSocket端口。
蓝绿或金丝雀部署：保证数据库迁移的兼容性；先部署代码，再执行迁移；为schema变更添加功能开关。

Observability and Health

可观测性与健康检查

Add
```
/health
```
and
```
/ready
```
endpoints (Repo check + PubSub/Presence check).
Export VM metrics: run
```
:telemetry_poller
```
for scheduler utilization and memory.
Alert on error rates, DB timeouts, queue depths, and VM memory.

添加
```
/health
```
和
```
/ready
```
端点（检查数据库连接 + PubSub/Presence状态）。
导出虚拟机指标：运行
```
:telemetry_poller
```
采集调度器利用率和内存数据。
针对错误率、数据库超时、队列深度、虚拟机内存配置告警。

Common Pitfalls

常见陷阱

Building releases without
```
PHX_SERVER=true
```
(endpoint won’t start).
Missing runtime config in
```
config/runtime.exs
```
; relying on compile-time config for secrets.
No cluster discovery configured → Presence inconsistencies across nodes.
Leaving default
```
secret_key_base
```
or per-node keys → invalid sessions after deploy.
Large assets without digests/CDN → slow cold loads.

构建版本时未设置
```
PHX_SERVER=true
```
（端点不会启动）。
```
config/runtime.exs
```
中缺少运行时配置；依赖编译时配置存储密钥。
未配置集群发现 → 不同节点间的Presence数据不一致。
保留默认的
```
secret_key_base
```
或每个节点使用独立的密钥 → 部署后会话失效。
大型静态资源未添加哈希戳或未接入CDN → 冷加载速度慢。