deploy

Elixir/Phoenix 部署参考

Elixir/Phoenix 应用部署速查。

铁律——绝不可违反

1. 在运行时配置，而非编译时——config.exs 中的密钥会被打包进 release 二进制文件。使用 runtime.exs 和环境变量，以便在启动时解析密钥
2. 优雅关闭时间 ≥ 60 秒——更短的超时时间会在操作进行到一半时终止正在处理的请求和 WebSocket 连接，导致用户数据丢失
3. 必须配置健康检查——如果没有启动、存活和就绪端点，编排器就无法区分正在启动的节点和已停止的节点，进而导致级联重启
4. 验证数据库 SSL——跳过 verify: :verify_peer 会使应用与数据库之间的连接遭受中间人攻击；生产数据会通过该连接传输
5. 不设置 CPU 限制——BEAM 调度器假定自己拥有所有核心；cgroups CPU 限制会导致调度器崩溃，使 VM 认为自己拥有的核心数多于实际可用数，进而引发延迟飙升
6. 按需检查可选服务凭据——每次 release 启动时都会运行 runtime.exs，包括基于 eval 的迁移命令。只有在启用相关集成时，才要求提供 S3、Redis 等服务的凭据

快速配置

runtime.exs（必需）

if config_env() == :prod do
  database_url = System.get_env("DATABASE_URL") || raise "DATABASE_URL is required"
  secret_key_base = System.get_env("SECRET_KEY_BASE") || raise "SECRET_KEY_BASE is required"
  host = System.get_env("PHX_HOST") || raise "PHX_HOST is required"

  config :my_app, MyApp.Repo,
    url: database_url,
    pool_size: String.to_integer(System.get_env("POOL_SIZE") || "10"),
    ssl: true,
    ssl_opts: [verify: :verify_peer]

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

检查可选服务

将 DATABASE_URL 和 SECRET_KEY_BASE 等核心启动密钥设为必需项。 仅当启用相关集成的同一功能开关打开时，才要求提供可选集成的凭据：

s3_config =
  if System.get_env("STORAGE_BACKEND") == "s3" do
    [
      access_key_id:
        System.get_env("S3_ACCESS_KEY") ||
          raise("S3_ACCESS_KEY is required when STORAGE_BACKEND=s3"),
      secret_access_key:
        System.get_env("S3_SECRET_KEY") ||
          raise("S3_SECRET_KEY is required when STORAGE_BACKEND=s3")
    ]
  else
    []
  end

config :my_app, :s3_config, s3_config

这样，不使用 S3 的 release 任务可以在没有 S3 凭据的情况下启动；而选择使用 S3 时，缺少凭据仍会导致启动快速失败。

健康检查 Plug

def call(%{path_info: ["health", "readiness"]} = conn, _opts) do
  case Ecto.Adapters.SQL.query(MyApp.Repo, "SELECT 1", []) do
    {:ok, _} -> send_resp(conn, 200, ~s({"status":"ok"})) |> halt()
    {:error, _} -> send_resp(conn, 503, ~s({"status":"error"})) |> halt()
  end
end

快速决策

平台选择

需求	使用
简单、托管式	Fly.io
企业环境、已有 K8s	Kubernetes
自定义基础设施	Docker + 你的编排器

资源限制

资源	建议
CPU	不设限制（BEAM 调度器问题）
内存	设置限制（通常为 256Mi-512Mi）
优雅关闭	≥ 60 秒

部署检查清单

• 所有密钥均通过 runtime.exs 中的环境变量配置
• 仅当启用相关集成时才要求提供可选服务凭据
• endpoint 配置中设置 server: true
• 验证数据库连接的 SSL
• 健康检查端点：/health/startup、/health/liveness、/health/readiness
• 优雅关闭时间 ≥ 60 秒
• 不设置 CPU 限制（仅设置内存限制）
• 在部署流程中执行迁移

资源管道说明

Phoenix 1.8 使用 esbuild + tailwind（无需 Node.js）：

• 在 config/config.exs 的 :esbuild 和 :tailwind 下配置
• mix assets.deploy 会构建生产资源
• mix assets.setup 会在首次运行时安装二进制文件
• 自定义 JS 打包工具：在 config/config.exs 中配置

参考资料

详细模式请参阅：

• ${CLAUDE_SKILL_DIR}/references/docker-config.md - 多阶段 Dockerfile 和最佳实践
• ${CLAUDE_SKILL_DIR}/references/flyio-config.md - fly.toml、集群和命令