前端构建与私有部署

1. 文档边界

本章只说明 PE Agent 前端应用及其前端可选辅助服务。API_SERVER_URL 指向的后端服务以对应后端文档为准。

2. 生产构建

pnpm install
pnpm build

next.config.js 当前配置：

• 构建目录：build/；
• 输出模式：standalone；
• 保留 Tailwind/Oxide/Lightning CSS 运行依赖；
• 支持 bundle analyzer 开关。

生产运行需要完整保留：

build/standalone/
build/static/
public/

不能只复制 server.js 或部分 chunk。

3. 构建平台

当前生产镜像基于 Node.js 24 slim 和 glibc。由于存在原生依赖：

• 不要将 macOS 构建产物直接复制到 Linux 生产镜像；
• 不要未经验证改为 Alpine/musl；
• 构建平台的架构和 libc 应与运行平台兼容；
• 最稳妥方式是在兼容 Linux 构建环境生成 standalone。

4. Docker 镜像

根目录 Dockerfile：

• 使用 Node.js 24 slim；
• 复制已经生成的 standalone、static 和 public；
• 以 node 用户运行；
• 容器监听 3000；
• 执行 node server.js。

Dockerfile 不负责安装依赖和执行 pnpm build，镜像构建前必须准备完整构建产物。

5. Compose 服务

服务	文件	是否必需
PE Agent 前端	docker/app/docker-compose.yaml	必需
Sandpack Bundler	docker/sandpack/docker-compose.yaml	使用代码预览时需要
ONLYOFFICE	docker/onlyoffice/docker-compose.yaml	使用 Office 在线预览时需要
OpenSandbox	docker/opensandbox/docker-compose.yaml	使用项目沙箱预览时需要

当前 Compose 文件使用外部网络 pe-agent-web。部署前需要先创建该网络，并确认所有启用服务使用相同网络。

核对旧文档

前端仓库部分旧部署说明曾使用其他网络名。实际部署应以当前 Compose 文件中的 pe-agent-web 为准，并在所有部署文件中统一名称。

6. 端口与网络

仓库 Compose 默认映射：

服务	宿主机端口	容器端口
PE Agent	9800	3000
Sandpack	9801	80
ONLYOFFICE	7100	80
OpenSandbox	9803	9803

生产环境建议：

• 公网只开放 80/443；
• 应用和辅助服务端口只监听本机或受控内网；
• Nginx 统一终止 HTTPS；
• OpenSandbox 控制面和动态端口不得直接暴露公网；
• Docker socket 权限按高风险资产管理。

当前 Compose 的端口映射未全部显式绑定 127.0.0.1，部署前必须根据网络区划调整。

7. Nginx 要求

反向代理至少需要：

• 透传 Host、客户端 IP 和协议头；
• 正确代理页面、/_next/*、/server/* 和 /api/*；
• 支持配置的 APP_BASE_PATH；
• 为 SSE 和长任务配置足够长的读写超时；
• 关闭不必要的代理缓存和流缓冲；
• 为上传配置匹配项目需求的 body size；
• 仅通过 HTTPS 对外提供生产服务。

当 PE Agent 部署在二级路径时，Nginx 可以保留前缀交给应用处理，也可以转发时剥离，但必须统一验证：

• 页面跳转；
• 根级 /_next/*；
• /server/* 和 /api/*；
• Cookie Path；
• ONLYOFFICE 回调；
• /project-preview/*；
• /api/health。

若同域另一个 Next.js 应用占用根级 /_next/*，优先为 PE Agent 使用独立子域名。

8. 可选辅助服务

8.1 Sandpack

用于浏览器代码预览。前端通过 SANDPACK_BUNDLER_URL 指向部署地址，Tailwind CSS 编译由 PE Agent 自身 /api/sandpack/tailwind-css 处理。

8.2 ONLYOFFICE

主应用的 ONLYOFFICE_JWT_SECRET 必须与 ONLYOFFICE 容器的 JWT_SECRET 一致。还要验证：

• 浏览器能访问 ONLYOFFICE；
• ONLYOFFICE 能访问交付物文件；
• 文件 URL 满足允许前缀；
• HTTPS 和回调地址正确。

8.3 OpenSandbox

OpenSandbox 需要 Docker socket、控制面 API Key、预览基础镜像和持久化目录。生产环境建议独立主机或安全边界，并评估 gVisor 等安全运行时。

9. 健康检查

前端健康接口：

GET {APP_BASE_PATH}/api/health

成功返回 HTTP 200 和 { "message": "ok" }。

该接口只证明 Next.js Route Handler 可以响应，不检查：

• 后端 API；
• Sandpack；
• ONLYOFFICE；
• OpenSandbox；
• Agent SSE。

上线前需要额外执行依赖级和业务级检查。

10. 日志

应用服务端日志输出到 stdout/stderr，主应用 Compose 使用 Docker json-file 日志驱动并配置轮转。前端还会将受控的客户端 warn/error 批量上传到 /api/client-logs。

排障时优先使用：

• x-request-id；
• x-session-id；
• 页面 errorId；
• 时间和请求路径；
• 容器版本或镜像标签。

生产上线前必须检查日志不会记录完整 Token、密码、验证码和 API 密钥，并限制 Docker 和集中日志平台的访问权限。

11. 发布与回滚

当前发布版本来源是 package.json:version。建议生产部署使用不可变版本标签或镜像 digest，不只依赖 latest。

回滚流程应包括：

1. 记录当前镜像、配置和品牌资源版本；
2. 选择已验证的上一版本镜像；
3. 保持兼容的运行时配置；
4. 重新创建容器；
5. 执行健康检查和核心业务冒烟；
6. 记录回滚原因和验证结果。

仓库中名为 zero-downtime 的部署脚本实际会删除旧容器后再启动新容器，存在中断窗口。需要严格零停机时，应采用双实例、负载均衡或滚动发布方案。

12. 常见部署问题

现象	优先检查
Compose 提示网络不存在	是否创建 pe-agent-web
页面可开但静态资源 404	APP_BASE_PATH、/_next/*、STATIC_BASE_URL
登录后循环跳转	Cookie Path/Domain、HTTPS、认证接口
SSE 中断或 504	Nginx/网关超时、缓冲、上游长连接
Office 无法预览	JWT 一致性、文件可达性、允许前缀
Sandpack 仍访问外部服务	运行时 URL、容器重启、Nginx 代理
OpenSandbox 预览失败	API URL/Key、镜像、Docker 网络和 socket
容器启动缺少模块	构建平台不兼容或 standalone 复制不完整