当前位置：首页 > news >正文

Dify：启动 Web 服务的详细指南

news 来源：原创 2025/6/5 11:13:13

1. 进入 `web` 目录

cd web

解释：

cd 是 “change directory” 的缩写，用于切换当前工作目录。
您需要进入项目的 web 目录，这是前端代码所在的位置。在这个目录下，您可以执行构建和启动 Web 服务的相关命令。

2. 安装依赖

pnpm install --frozen-lockfile

解释：

pnpm 是一个快速、节省磁盘空间的包管理器，类似于 npm 和 yarn。
install 命令用于安装 package.json 文件中列出的所有依赖包。
--frozen-lockfile 选项表示在安装时不会修改 pnpm-lock.yaml 文件。如果当前的 pnpm-lock.yaml 与 package.json 不匹配，将会报错。这有助于确保所有开发人员使用相同的依赖版本，避免由于依赖版本不一致导致的问题。

注意：

在执行此命令之前，请确保已在系统上全局安装了 pnpm。如果还未安装，可以使用以下命令进行安装：
```
npm install -g pnpm
```

3. 准备环境变量配置文件

步骤：

在当前目录（web 目录）中创建一个名为 .env.local 的文件。
将 .env.example 文件的内容复制到新的 .env.local 文件中。
根据您的需求，修改 .env.local 中的环境变量的值。

环境变量详解：

a. `NEXT_PUBLIC_DEPLOY_ENV`

# For production release, change this to PRODUCTION
NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT

用途： 指定应用的部署环境。
可能的值：
- DEVELOPMENT：开发环境。
- PRODUCTION：生产环境。
说明： 如果您正在进行开发或测试，请保留 DEVELOPMENT。如果准备部署到生产环境，请将其更改为 PRODUCTION。

b. `NEXT_PUBLIC_EDITION`

# The deployment edition, SELF_HOSTED or CLOUD
NEXT_PUBLIC_EDITION=SELF_HOSTED

用途： 指定应用的部署版本。
可能的值：
- SELF_HOSTED：自托管版本。
- CLOUD：云端版本。
说明： 如果您计划在自己的服务器上运行应用，请选择 SELF_HOSTED。如果您使用的是云服务提供的托管服务，请选择 CLOUD。

c. `NEXT_PUBLIC_API_PREFIX`

# The base URL of console application, refers to the Console base URL of WEB service if console domain is
# different from api or web app domain.
# example: http://cloud.dify.ai/console/api
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api

用途： 设置控制台应用程序的基础 API URL。
说明：
- 如果您的控制台域名与 API 或 Web 应用程序的域名不同，您需要在这里指定完整的基础 URL。
- 示例： 如果您的控制台 API 运行在 http://cloud.dify.ai/console/api，请将此变量设置为该 URL。
- 对于本地开发环境，通常使用 http://localhost:5001/console/api。

d. `NEXT_PUBLIC_PUBLIC_API_PREFIX`

# The URL for Web APP, refers to the Web App base URL of WEB service if web app domain is different from
# console or api domain.
# example: http://udify.app/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api

用途： 设置 Web 应用程序的公共 API 基础 URL。
说明：
- 如果您的 Web 应用程序的域名与控制台或 API 域名不同，需要在这里指定完整的基础 URL。
- 示例： 如果您的 Web 应用程序 API 运行在 http://udify.app/api，请将此变量设置为该 URL。
- 对于本地开发环境，通常使用 http://localhost:5001/api。

e. Sentry 配置

# SENTRY
NEXT_PUBLIC_SENTRY_DSN=
NEXT_PUBLIC_SENTRY_ORG=
NEXT_PUBLIC_SENTRY_PROJECT=

用途： 配置 Sentry，用于应用的错误跟踪和性能监控。
变量说明：
- NEXT_PUBLIC_SENTRY_DSN：您的 Sentry 数据源名称（DSN），用于将错误和性能数据发送到 Sentry。
- NEXT_PUBLIC_SENTRY_ORG：您的 Sentry 组织名称。
- NEXT_PUBLIC_SENTRY_PROJECT：您的 Sentry 项目名称。
说明： 如果您没有使用 Sentry，可以将这些变量留空。

4. 构建 Web 服务

pnpm build

解释：

此命令使用 pnpm 运行构建脚本，通常是在 package.json 中定义的 build 命令。
对于使用 Next.js 框架的项目，pnpm build 会执行以下操作：
- 编译 TypeScript 文件（如果有）。
- 优化和压缩代码，使其适合于生产环境。
- 生成服务端渲染（SSR）和静态优化所需的文件。

注意：

确保在构建之前，所有依赖都已正确安装，并且环境变量配置正确。

5. 启动 Web 服务

pnpm start

解释：

此命令使用 pnpm 运行启动脚本，通常是在 package.json 中定义的 start 命令。
对于 Next.js 项目，pnpm start 会启动 Next.js 服务，以生产模式运行应用程序。

运行后效果：

应用程序将在默认的端口 3000 上启动。
服务将监听来自本地和网络的请求。

6. 预期输出

运行 pnpm start 后，您应该在控制台中看到类似以下的输出：

   ▲ Next.js 15- Local:        http://localhost:3000- Network:      http://0.0.0.0:3000✓ Starting...✓ Ready in 73ms

解释：

▲ Next.js 15：表示正在使用 Next.js 框架的版本，这里是版本 15。
Local: http://localhost:3000：指示您可以在本地通过此地址访问应用程序。
Network: http://0.0.0.0:3000：表示应用程序正在监听所有网络接口，外部设备（在同一网络中）可以通过您的 IP 地址访问该端口。
✓ Starting...：表示服务器正在启动中。
✓ Ready in 73ms：表示服务器已成功启动并准备就绪，用时 73 毫秒。

总结

通过上述步骤，您已经成功地：

进入了项目的 web 目录，这是所有前端代码和配置所在的位置。
使用 pnpm 安装了所有项目依赖，确保了依赖版本的一致性。
创建并配置了环境变量文件 .env.local，这个文件对应用的运行环境和行为起着关键作用。
构建了应用程序，将源代码编译和优化为适合生产环境运行的代码。
启动了应用程序，使其在本地服务器上运行，您可以在浏览器中访问并测试应用。

附加说明

关于 pnpm

如果您不熟悉 pnpm，它与 npm 和 yarn 类似，但具有更快的安装速度和节省磁盘空间的优势。
您可以在 pnpm 官方网站了解更多信息。

常见问题排查

端口被占用： 如果端口 3000 已被其他程序使用，您可以指定其他端口启动：
```
pnpm start -- -p 4000
```
这将在端口 4000 上启动应用程序。
依赖安装失败： 如果在执行 pnpm install 时遇到错误，检查是否有网络问题，或者尝试删除 node_modules 目录和 pnpm-lock.yaml，然后重新安装。
环境变量未生效： 确保 .env.local 文件位于 web 目录下，并且变量名没有拼写错误。环境变量的修改可能需要重新构建才能生效。

关于环境变量的安全性

敏感信息： 不要在环境变量中泄露敏感信息，如数据库密码、API 密钥等。对于前端应用，NEXT_PUBLIC_ 前缀的环境变量会在客户端代码中暴露，一定要谨慎处理。

提升性能和安全性

使用 HTTPS： 在生产环境中，建议配置 HTTPS 来加密客户端和服务器之间的通信。
开启缓存和压缩： 通过配置服务器，启用静态资源的缓存和压缩，以提高加载速度。

部署到生产环境

准备工作： 在部署到生产环境之前，确保将 NEXT_PUBLIC_DEPLOY_ENV 设置为 PRODUCTION，并进行充分的测试。
CI/CD 集成： 考虑使用持续集成和持续部署（CI/CD）工具来自动化构建、测试和部署流程。

使用 Sentry 进行监控

如果您希望使用 Sentry 进行错误跟踪和性能监控，确保在 Sentry 上创建项目，并在 .env.local 中正确配置相关的 DSN、组织和项目名称。
集成 Sentry 后，应用的错误和性能数据将被发送到您的 Sentry 仪表板，帮助您及时发现和解决问题。

为什么需要指定完整的基础 URL，以及为什么会有多个域名

在现代 Web 应用程序中，通常由多个组件组成，每个组件可能运行在不同的域名或子域名上。这些组件包括但不限于：

Web 前端应用程序（Web App）：用户直接交互的界面，通常是一个运行在浏览器中的单页应用（SPA）。
API 服务：后端服务，提供数据和业务逻辑处理，通常以 RESTful API 或 GraphQL 的形式存在。
管理控制台（Console）：用于管理和配置应用程序的后台界面，通常只有管理员才能访问。

由于安全、性能、维护等各种原因，这些组件可能部署在不同的域名或子域名下。例如：

Web 应用程序运行在 www.example.com
API 服务运行在 api.example.com
管理控制台运行在 admin.example.com

为什么会有多个域名？

安全性：将不同的服务划分到不同的域名，可以实现更细粒度的安全策略。例如，可以为 API 服务设置更严格的访问控制。
性能优化：不同的服务可以独立部署、扩展和优化，互不影响。例如，可以为静态资源开启 CDN 加速，而 API 服务可能需要降低延迟。
职责分离：通过域名的划分，可以更清晰地分离不同的功能模块，方便团队协作和维护。
跨域请求：在某些情况下，不同的服务需要部署在不同的域下，前端需要通过跨域请求（CORS）来访问后端 API。

为什么需要指定完整的基础 URL？

当您的前端应用程序需要与后端服务（API、控制台等）通信时，需要知道这些服务的准确地址。如果这些服务运行在不同的域名或端口上，前端无法自动推断出后端服务的地址，因此需要在环境变量中显式指定。

具体解释环境变量

1. `NEXT_PUBLIC_API_PREFIX`

# 控制台应用程序的基础 API URL
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api

用途：指定前端应用程序与 管理控制台 API 服务 通信的基础 URL。
为什么需要完整的基础 URL？
- 如果控制台的域名与前端应用程序的域名不同，前端需要知道准确的 URL 才能正确地向后端发送请求。
- 例如，假设您的前端应用运行在 www.example.com，而控制台 API 服务运行在 admin-api.example.com，则需要将 NEXT_PUBLIC_API_PREFIX 设置为 http://admin-api.example.com/console/api。
示例：
- 相同域名：如果控制台 API 服务与前端应用在同一域名下且路径结构清晰，例如 www.example.com/console/api，可以设置为相对路径。
- 不同域名：如果在不同域名下，则必须指定完整的基础 URL，包括协议（http/https）、域名和端口（如果非标准端口）。

2. `NEXT_PUBLIC_PUBLIC_API_PREFIX`

# Web 应用程序的公共 API 基础 URL
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api

用途：指定前端应用程序与 公共 API 服务（通常供普通用户使用的 API）通信的基础 URL。
为什么需要完整的基础 URL？
- 同理，如果公共 API 服务的域名与前端应用的域名不同，前端需要知道准确的 URL 以便发送请求。
- 例如，假设您的前端应用运行在 app.example.com，而公共 API 服务运行在 api.example.com，则需要将 NEXT_PUBLIC_PUBLIC_API_PREFIX 设置为 http://api.example.com/api。

实际场景举例

假设您的项目有以下部署结构：

前端应用程序（Web App）：
- 域名：https://app.example.com
公共 API 服务（Public API）：
- 域名：https://api.example.com
管理控制台（Console）：
- 域名：https://admin.example.com
控制台 API 服务（Console API）：
- 域名：https://admin-api.example.com

在这种情况下，您的环境变量应该设置为：

# 部署环境
NEXT_PUBLIC_DEPLOY_ENV=PRODUCTION# 部署版本
NEXT_PUBLIC_EDITION=SELF_HOSTED# 控制台 API 的基础 URL
NEXT_PUBLIC_API_PREFIX=https://admin-api.example.com/console/api# 公共 API 的基础 URL
NEXT_PUBLIC_PUBLIC_API_PREFIX=https://api.example.com/api# 其他配置（例如 Sentry）...

解释：

NEXT_PUBLIC_API_PREFIX：
- 前端应用需要与管理控制台的 API 服务通信，但由于它们运行在不同的域名（app.example.com 和 admin-api.example.com）下，因此必须指定完整的基础 URL。
NEXT_PUBLIC_PUBLIC_API_PREFIX：
- 前端应用需要与公共 API 服务通信，同样，由于域名不同，需要指定完整的基础 URL。

为什么不能使用相对路径或默认值？

相对路径的局限性：
- 相对路径是基于当前页面的 URL，如果后端服务与前端应用不在同一域名或端口下，使用相对路径将无法定位到正确的后端服务。
- 例如，使用相对路径 /api，浏览器会请求 https://app.example.com/api，而如果实际的 API 服务在 https://api.example.com/api，请求将失败。
默认值可能不匹配实际部署环境：
- 默认值通常适用于开发或测试环境，而在生产环境中，服务的域名和端口可能会有所不同。
- 为了使应用能够在不同的环境中正确运行，必须根据实际的部署情况配置正确的基础 URL。

跨域（CORS）考虑

当前端应用和后端 API 服务运行在不同的域名或端口下时，浏览器会认为它们属于不同的源，这会涉及到 跨域资源共享（CORS） 的问题。

什么是同源策略？
- 浏览器的安全机制，阻止从一个源加载的文档或脚本与另一个源的资源进行交互。
什么是跨域请求？
- 当前端应用向与其自身域名不同的后端服务发送请求时，就是跨域请求。
如何解决跨域问题？
- 后端配置 CORS：在后端服务器中，允许特定的源访问其资源。通常通过设置响应头 Access-Control-Allow-Origin 来实现。
- 代理服务器：使用反向代理，将对后端服务的请求代理到同一域名下，从而避免跨域。
为什么这与配置完整的基础 URL 有关？
- 当指定了不同的基础 URL，前端会向不同的域名发送请求，这会触发跨域请求，因此需要确保后端已正确配置 CORS。