部署总览

CatPull 由四个服务组成，需要分别部署：

服务	技术栈	默认端口
主服务器	Express + Sequelize + TypeScript	9090
云函数服务	Express + vm2	3001
设计器前端	Vue 3 + Vite	80
预览端	uni-app + Vue 3	80

环境要求

依赖	最低版本	说明
Node.js	>= 20.0.0	主服务器要求
pnpm	>= 8	设计器前端包管理器
MySQL	>= 5.7	字符集需支持 utf8mb4
Nginx	>= 1.18	反向代理 + 静态资源托管

架构总览

                        ┌─────────────────────────┐
                        │         浏览器           │
                        │ (设计器 / 管理台 / 预览)  │
                        └───────────┬─────────────┘
                                    │
                             HTTPS / HTTP
                                    │
                        ┌───────────▼───────────┐
                        │        Nginx          │
                        │      (80/443)         │
                        └──┬─────────┬────────┬─┘
                           │         │        │
                 静态资源   │   静态资源│  /api/*
                 (设计器)   │  (预览端) │        │
                           │         │        │
                ┌──────────▼──┐ ┌───▼──────┐ ┌▼───────────────┐
                │  dist/      │ │  dist/   │ │  主服务器       │
                │  @catpull/  │ │ (uni-app)│ │ (Express:9090) │
                │  library/   │ │          │ └──┬─────────┬───┘
                └─────────────┘ └──────────┘    │         │
                                          ┌─────▼───┐ ┌──▼────────┐
                                          │  MySQL  │ │ 云函数服务 │
                                          │ (3306)  │ │ (:3001)   │
                                          └─────────┘ └───────────┘

完整部署流程

以下是从零开始的完整部署命令序列：

# 1. 克隆代码
git clone https://github.com/your-org/catpull-uni-vue3.git
cd catpull-uni-vue3

# 2. 部署主服务器
cd catpull-v3-server/server
npm install
cp .env.example .env
# 编辑 .env 填写实际配置
npm run build
pm2 start dist/index.js --name catpull-server

# 3. 部署云函数服务
cd ../cloud
npm install
pm2 start app.js --name catpull-cloud

# 4. 构建设计器前端
cd ../../catpull-v3
pnpm install
# 编辑 catpull-designer/.env 填写实际配置
pnpm build:designer

# 5. 构建预览端
cd catpull-uni
pnpm install
# 编辑 .env 填写 VITE_APP_ID、VITE_APP_KEY
pnpm build:h5

# 6. 部署到 Nginx
sudo cp -r ../catpull-designer/dist/* /var/www/catpull-designer/dist/
sudo cp -r dist/build/h5/* /var/www/catpull-uni/dist/
# 配置 Nginx 并重载
sudo nginx -t && sudo nginx -s reload

# 7. 保存 PM2 进程列表
pm2 save

常见问题

API 请求认证失败（app_id 为空）

现象：开发环境正常，部署到 Nginx 后后端收到的 app_id 请求头为 undefined，但 sign 请求头正常。

原因：Nginx 默认会丢弃包含下划线（_）的 HTTP 请求头。这是 Nginx 的安全设计——HTTP 规范（RFC 7230）将下划线视为不推荐在头部名称中使用的字符，因为某些 CGI 服务器会将下划线和连字符混淆。因此 Nginx 的 ngx_http_parse_header_line 解析器默认跳过含下划线的请求头，导致 app_id、app_platform 等请求头在反向代理时被静默丢弃。

解决方案：在 Nginx 的 server 块中添加 underscores_in_headers on;：

server {
    # 允许请求头包含下划线
    underscores_in_headers on;

    # ... 其他配置
}

注意

underscores_in_headers 必须放在 server 或 http 块中，不能放在 location 块中。如果多个 server 都需要，可以放在 http 块中全局生效。