从源码构建

从源码构建#

在本节中，我们将介绍如何从源码开始构建3DAC Web应用。我们提供两种方式构建Web应用：开发模式和生产模式。如果要在不修改功能的情况下部署应用，建议使用生产模式。否则，请在开发模式下构建应用。

Note

本教程仅提供Web应用构建说明。要启动完整的3DAC系统，还需要部署中间件和后端服务，如orchestrator、web后端。我们建议使用docker compose启动所有服务，详细内容请查看这里。

开发构建#

安装依赖#

Web应用的源码文件位于app目录。package.json包含构建应用所需的依赖项，可以使用Node Package Manager(npm)或其高性能替代pnpm进行安装。nvm的安装说明请参见这里。应用使用Node.js 18.18构建。正确配置Node.js后，安装pnpm：

npm install -g pnpm

然后，安装所需的依赖：

# 确保当前工作目录为项目根目录
cd dlp3d.ai

# 使用package.json中的配置安装依赖
pnpm install

设置SSL证书#

为什么需要HTTPS？#

Web应用需要使用您设备的麦克风。出于安全考虑，现代浏览器只允许在安全上下文中访问设备硬件，例如麦克风和摄像头。

地址类型 示例 允许访问
本机地址 (HTTP) http://localhost 或 http://127.0.0.1 ✅ 开发环境例外
局域网IP (HTTP) http://192.168.x.x ❌ 非安全上下文
局域网IP (HTTPS) https://192.168.x.x ✅ 需要信任自签名证书
公共 HTTPS 域名 https://example.com ✅ 需要有效证书

生成证书#

确保已安装openssl。然后，执行以下命令：

# 确保当前工作目录为项目根目录
cd dlp3d.ai

# 创建证书目录
mkdir ssl

# 使用 openssl 生成证书
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ssl/key.pem \
  -out ssl/cert.pem \
  -days 365

# 按照提示完成证书生成

生成的证书将组织如下：

dlp3d.ai/ssl/
├── cert.pem  ← 证书文件
└── key.pem   ← 私钥文件

运行Web应用#

如果您在同一设备上部署和测试应用（即localhost），则不需要SSL证书。但是，如果您在一台设备上部署应用并在其他设备上测试（局域网IP），则需要SSL证书。

本机地址#

pnpm run dev

要创建Web应用窗口，请打开浏览器并访问https://127.0.0.1:3000。

局域网#

pnpm run dev_ws

要创建Web应用窗口，请打开浏览器并访问https://${YOUR_IP_ADDRESS}。首次访问时，浏览器可能会提示连接不安全。这是因为我们使用的是自签名证书。要绕过此问题，请点击Advanced按钮，然后点击Proceed to 127.0.0.1 (unsafe)：

不安全连接错误

一旦被信任，站点将被浏览器视为”安全上下文”。

生产构建#

对于生产构建，Web应用会被编译成静态网页。您可以通过CLI或使用docker镜像构建应用。

命令行构建#

要通过命令行构建项目：

# 确保当前工作目录为项目根目录
cd dlp3d.ai

# 构建网页
pnpm run build

构建输出将存储在.next目录中。要部署网页：

pnpm start

网页将在http://localhost:3000提供服务。

GitHub Pages 静态导出#

GitHub Pages 部署是一种额外的静态导出模式，不会替代上面的命令行或 Docker 部署方式。

Pages workflow 位于 .github/workflows/pages.yml，仅在推送 tag、发布 GitHub Release 或手动执行 workflow_dispatch 时运行。普通 main 分支 push 不会自动发布站点。

workflow 使用以下环境变量构建：

DEPLOY_TARGET=github-pages
NEXT_PUBLIC_SITE_BASE_PATH=/dlp3d.ai
NEXT_PUBLIC_ORCHESTRATOR_HOST=u1-api.sensenova.cn
NEXT_PUBLIC_ORCHESTRATOR_PORT=443
NEXT_PUBLIC_ORCHESTRATOR_PATH_PREFIX=/dlp3d-ai/orchestrator
NEXT_PUBLIC_BACKEND_HOST=u1-api.sensenova.cn
NEXT_PUBLIC_BACKEND_PORT=443
NEXT_PUBLIC_BACKEND_PATH_PREFIX=/dlp3d-ai/backend

NEXT_PUBLIC_SITE_BASE_PATH 用于配置 GitHub Pages 项目路径。当前维护的托管站点 https://dlp3d-ai.github.io/dlp3d.ai/ 使用 /dlp3d.ai；只有在明确部署到根域名时才应使用空值。

静态导出不支持 Next.js API routes。Pages workflow 会在构建前临时禁用 app/api/LLM。Docker 和命令行 standalone 构建仍会保留该 API route。

Docker构建#

要通过docker生成生产构建：

# 确保当前工作目录为项目根目录
cd dlp3d.ai

# 构建 docker 镜像并添加标签
docker build -f ./dockerfiles/web/Dockerfile . -t dlp3d_web:dev

这将自动构建一个标记为dlp3d_web:dev的docker镜像。要启动docker镜像：

docker run dlp3d_web:dev -p 3000:3000

网页将在http://localhost:3000提供服务。

Contents