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

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. 准备环境变量配置文件

步骤：

1. 在当前目录（web 目录）中创建一个名为 .env.local 的文件。
2. 将 .env.example 文件的内容复制到新的 .env.local 文件中。
3. 根据您的需求，修改 .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 毫秒。

---

总结

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

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

---

附加说明

关于 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 应用程序中，通常由多个组件组成，每个组件可能运行在不同的域名或子域名上。这些组件包括但不限于：

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

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

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

为什么会有多个域名？

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

---

总结

• 多个域名的原因：

  • 不同的服务组件可能出于安全、性能、维护等考虑，运行在不同的域名或子域名下。

• 指定完整基础 URL 的必要性：

  • 由于前端应用无法自动推断不同域名下的后端服务地址，必须在环境变量中明确指定，以确保应用能够正确地与后端服务通信。

• 环境变量的作用：

  • 通过在 .env.local 文件中配置正确的环境变量，您可以根据不同的部署环境（开发、测试、生产）灵活地调整应用的行为。

• 注意跨域问题：

  • 当前端和后端服务不在同一个域名下时，需要处理跨域请求的问题，确保后端配置了适当的 CORS 策略。

---

实用建议

• 统一管理域名配置：

  • 可以在配置文件或环境变量中集中管理所有服务的域名，方便维护和更新。

• 使用环境变量区分环境：

  • 利用环境变量，可以针对开发、测试、生产环境配置不同的服务地址，避免硬编码。

• 测试跨域请求：

  • 在开发阶段，使用浏览器调试工具观察网络请求，确保请求的 URL 正确，且未被浏览器阻止。

• 考虑使用代理：

  • 在开发环境中，可以使用开发服务器的代理功能，将请求代理到后端服务，简化配置，避免跨域问题。

---