Deployment

部署与运维指南

HiCAD 的部署目标是简单、可复制、适合私有化。前端构建为静态文件由 Nginx 托管，后端通过 PM2 运行 NestJS 编译产物，数据保存在服务器文件系统中。

1. 本地验证

每次上线前，应优先执行分包构建，而不是只依赖根目录构建。

pnpm --filter frontend build
pnpm --filter backend build
pnpm --filter backend eval:ai

命令	目的
frontend build	验证 Vue、路由、组件和静态资源打包。
backend build	验证 NestJS、Controller、Service 和类型编译。
eval:ai	生成 AI 基线质量报告，确保 codegen 没有退化。

2. 环境变量

文档和仓库中只能保留占位示例，真实密钥应通过服务器 .env 或部署系统注入。

NODE_ENV=production
PORT=your_backend_port
JWT_ACCESS_SECRET=your_access_secret
JWT_REFRESH_SECRET=your_refresh_secret
AI_ADAPTER=deepseek
DEEPSEEK_API_KEY=your_deepseek_key
LANGFUSE_PUBLIC_KEY=your_langfuse_public_key
LANGFUSE_SECRET_KEY=your_langfuse_secret_key
LANGFUSE_BASE_URL=https://cloud.langfuse.com
JITPAY_KEY=your_payment_key
JITPAY_SECRET=your_payment_secret

注意：不要把真实 API Key、JWT Secret、支付密钥、服务器 IP、用户邮箱写入公开文档。

3. 推荐部署流程

本地构建

前端生成 dist，后端生成 dist/backend/src/main.js。

上传产物

前端静态文件上传到服务器 frontend 目录，后端 dist 和 package.json 上传到 backend。

安装依赖

后端生产环境安装 npm 依赖，含 bcrypt 等原生模块时需服务器本地编译。

重启服务

使用 PM2 restart 后端，并执行健康检查。

验证页面

访问首页、编辑器、管理后台、AI 评测面板和核心 API。

4. Nginx SPA 配置

Vue 使用 history 路由时，直达子路由必须 fallback 到 index.html，否则刷新或直接访问会 404 或重定向异常。

server {
  listen 443 ssl;
  server_name your-domain.com;

  root /path/to/hicad/frontend;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:your_backend_port/;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
    proxy_read_timeout 300s;
  }
}

5. 观测与质量监控

HiCAD 的观测分为两层：Langfuse 关注 AI Trace，AI 评测系统关注生成质量。

Langfuse Trace

记录 prompt、model、pipeline、latency、success、output length，用于排查 AI 请求链路。

质量评测报告

通过 /api/ai/evaluation/baseline 和 eval:ai 命令持续观察生成质量。

# 基线评测
pnpm --filter backend eval:ai

# 管理后台页面
/admin/ai-evaluation

6. 常见排障清单

问题	排查方式	修复建议
路由直达跳首页	检查线上包是否包含对应页面关键词，检查 Nginx try_files。	重新部署前端，确认 root 指向实际静态目录。
AI Trace 看不到	用最小 Trace 测试，查询 Langfuse API，检查时间范围和项目。	确认 key、baseURL、flushAsync 和 UI 筛选。
后端模块缺失	查看 PM2 日志和 NODE_PATH，确认生产依赖安装。	在服务器后端目录重新 npm install --omit=dev。
JSCAD 渲染失败	查看 Worker 错误、main 函数、module.exports、NaN 坐标。	提示用户修复代码，或使用 AI 一键优化。
质量评分过低	查看 7 维指标中低分项。	增加参数化、装配 union、材质 ID 和需求关键词。

7. 发布前安全审查

发布前必须检查：无真实密钥、无用户隐私、无服务器内网信息、无订单敏感数据、无测试账号密码。

配置文件使用 .env.example 占位，不提交 .env。
技术文档中的 API Key 一律写成 your_xxx_key。
示例域名使用 your-domain.com，不写真实生产域名。
截图或演示数据使用测试账号。
部署日志如需外发，先清理 IP、路径和密钥。