部署

部署 AdonisJS 应用程序与部署标准 Node.js 应用程序没有区别。你需要一台运行 Node.js >= 20.6 以及 npm 的服务器来安装生产依赖项。

本指南将介绍在生产环境中部署和运行 AdonisJS 应用程序的通用指南。

创建生产构建

第一步，你必须通过运行 build 命令来创建 AdonisJS 应用程序的生产构建。

node ace build

编译输出写入 ./build 目录。如果你使用 Vite，其输出将写入 ./build/public 目录。

创建生产构建后，你可以将 ./build 文件夹复制到生产服务器。从现在开始，build 文件夹将成为你应用程序的根目录。

创建 Docker 镜像

如果你使用 Docker 部署应用程序，可以使用以下 Dockerfile 创建 Docker 镜像。

dockerfile

FROM node:22.16.0-alpine3.22 AS base

# 所有依赖阶段
FROM base AS deps
WORKDIR /app
ADD package.json package-lock.json ./
RUN npm ci

# 仅生产依赖阶段
FROM base AS production-deps
WORKDIR /app
ADD package.json package-lock.json ./
RUN npm ci --omit=dev

# 构建阶段
FROM base AS build
WORKDIR /app
COPY --from=deps /app/node_modules /app/node_modules
ADD . .
RUN node ace build

# 生产阶段
FROM base
ENV NODE_ENV=production
WORKDIR /app
COPY --from=production-deps /app/node_modules /app/node_modules
COPY --from=build /app/build /app
EXPOSE 8080
CMD ["node", "./bin/server.js"]

你可以根据需要修改 Dockerfile。

配置反向代理

Node.js 应用程序通常部署在反向代理服务器后面，如 Nginx。因此，端口 80 和 443 上的传入流量将首先由 Nginx 处理，然后转发到你的 Node.js 应用程序。

以下是你可以用作起点的示例 Nginx 配置文件。

WARNING

确保替换尖括号 <> 中的值。

nginx

server {
  listen 80;
  listen [::]:80;

  server_name <APP_DOMAIN.COM>;

  location / {
    proxy_pass http://localhost:<ADONIS_PORT>;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_cache_bypass $http_upgrade;
  }
}

定义环境变量

如果你在裸机服务器上部署应用程序，如 DigitalOcean Droplet 或 EC2 实例，可以使用 .env 文件来定义环境变量。确保该文件安全存储，只有授权用户才能访问它。

TIP

如果你使用像 Heroku 或 Cleavr 这样的部署平台，可以使用它们的控制面板来定义环境变量。

假设你在 /etc/secrets 目录中创建了 .env 文件，你必须按以下方式启动生产服务器。

ENV_PATH=/etc/secrets node build/bin/server.js

ENV_PATH 环境变量指示 AdonisJS 在提到的目录中查找 .env 文件。

启动生产服务器

你可以通过运行 node server.js 文件来启动生产服务器。但是，建议使用像 pm2 这样的进程管理器。

PM2 将在后台运行你的应用程序，而不会阻塞当前终端会话。
如果你的应用程序在处理请求时崩溃，它会重新启动应用程序。
此外，PM2 使在集群模式下运行应用程序变得非常简单。

以下是你可以用作起点的示例 pm2 ecosystem 文件。

// title: ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'web-app',
      script: './server.js',
      instances: 'max',
      exec_mode: 'cluster',
      autorestart: true,
    },
  ],
}

// title: 启动服务器
pm2 start ecosystem.config.js

迁移数据库

如果你使用 SQL 数据库，你必须在生产服务器上运行数据库迁移以创建所需的表。

如果你使用 Lucid，可以运行以下命令。

node ace migration:run --force

在生产环境中运行迁移时，需要 --force 标志。

何时运行迁移

另外，你应该总是在重新启动服务器之前运行迁移。然后，如果迁移失败，不要重新启动服务器。

使用像 Cleavr 或 Heroku 这样的托管服务，它们可以自动处理这种用例。否则，你将不得不在 CI/CD 管道中运行迁移脚本，或通过 SSH 手动运行它。

不要在生产环境中回滚

在生产环境中回滚迁移是一项有风险的操作。迁移文件中的 down 方法通常包含破坏性操作，如删除表、删除列等。

建议在 config/database.ts 文件中关闭生产环境中的回滚，而是创建一个新的迁移来修复问题并在生产服务器上运行它。

禁用生产环境中的回滚将确保 node ace migration:rollback 命令导致错误。

{
  pg: {
    client: 'pg',
    migrations: {
      disableRollbacksInProduction: true,
    }
  }
}

并发迁移

如果你在具有多个实例的服务器上运行迁移，你必须确保只有一个实例运行迁移。

对于 MySQL 和 PostgreSQL，Lucid 将获取建议锁以确保不允许并发迁移。但是，最好首先避免从多个服务器运行迁移。

文件上传的持久存储

像 Amazon EKS、Google Kubernetes、Heroku、DigitalOcean Apps 等环境在临时文件系统中运行你的应用程序代码，这意味着默认情况下，每次部署都会清除现有文件系统并创建一个新的。

如果你的应用程序允许用户上传文件，你必须使用像 Amazon S3、Google Cloud Storage 或 DigitalOcean Spaces 这样的持久存储服务，而不是依赖本地文件系统。

写入日志

AdonisJS 默认使用 pino 日志记录器，它以 JSON 格式将日志写入控制台。你可以设置外部日志服务从 stdout/stderr 读取日志，或将它们转发到同一服务器上的本地文件。

提供静态资源

有效地提供静态资源对于应用程序的性能至关重要。无论你的 AdonisJS 应用程序有多快，静态资源的交付对于更好的用户体验起着巨大作用。

使用 CDN

最佳方法是使用 CDN（内容分发网络）从你的 AdonisJS 应用程序交付静态资源。

使用 Vite 编译的前端资源默认带有指纹，这意味着文件名根据其内容进行哈希。这允许你永久缓存资源并从 CDN 提供它们。

根据你使用的 CDN 服务和部署技术，你可能需要在部署过程中添加一个步骤，将静态文件移动到 CDN 服务器。简而言之，它应该是这样工作的。

更新 vite.config.js 和 config/vite.ts 配置以使用 CDN URL。
运行 build 命令来编译应用程序和资源。
将 public/assets 的输出复制到你的 CDN 服务器。例如，这是我们用来将资源发布到 Amazon S3 存储桶的命令。

使用 Nginx 交付静态资源

另一种选择是将提供资源的任务交给 Nginx。如果你使用 Vite 编译前端资源，你必须积极缓存所有静态文件，因为它们带有指纹。

将以下块添加到你的 Nginx 配置文件。确保替换尖括号 <> 中的值。

nginx

location ~ \.(jpg|png|css|js|gif|ico|woff|woff2) {
  root <PATH_TO_ADONISJS_APP_PUBLIC_DIRECTORY>;
  sendfile on;
  sendfile_max_chunk 2m;
  add_header Cache-Control "public";
  expires 365d;
}

使用 AdonisJS 静态文件服务器

你也可以依靠 AdonisJS 内置的静态文件服务器从 public 目录提供静态资源，以保持简单。

无需额外配置。只需像往常一样部署你的 AdonisJS 应用程序，静态资源的请求将自动得到服务。

WARNING

不建议在生产环境中使用静态文件服务器。最好使用 CDN 或 Nginx 来提供静态资源。

部署 ​

创建生产构建 ​

创建 Docker 镜像 ​

配置反向代理 ​

定义环境变量 ​

启动生产服务器 ​

迁移数据库 ​

何时运行迁移 ​

不要在生产环境中回滚 ​

并发迁移 ​

文件上传的持久存储 ​

写入日志 ​

提供静态资源 ​

使用 CDN ​

使用 Nginx 交付静态资源 ​

使用 AdonisJS 静态文件服务器 ​

部署