Deployment

用 ./install.sh 准备主机，用 Docker Compose 运行 Quan ERP 基础栈，按 build → available → installed 发布插件，并为预发 / 生产做好加固。

概述

Quark ERP / Quan ERP 以基础栈加版本化插件方式部署。新服务器上先用 ./install.sh 安装 Docker / Nginx 并启动 compose。

installation/ — ./install.sh（install | start | stop）
docker-compose.yaml — 平台服务
quan-erp CLI → available-plugins/
UI 安装 → installed-plugins/
切勿在 UAT / 生产对 module 表做 SQL seed

1. 主机引导（./install.sh）

在 installation/ 下以普通用户运行（不要用 root）。install 安装 Docker、Compose 插件与 Nginx；start / stop 启停 compose 服务。

命令：install | start | stop（见 ./install.sh --help）
不要用 root 运行 — 仅在需要时使用 sudo
install — 在 Ubuntu/Debian 或 RHEL 系安装 Docker + Compose + Nginx
start — docker compose up -d
stop — docker compose stop
支持系统：Ubuntu、Debian、RHEL、CentOS、Fedora、Rocky、AlmaLinux
install 后可能需要重新登录以使 docker 组生效

SHTerminal

cd installation
chmod +x ./install.sh   # or ./installation.sh

# One-time host setup (Docker + Compose + Nginx)
./install.sh install

# Start compose services
./install.sh start

# Stop compose services
./install.sh stop

2. 基础栈（Docker Compose）

本地模板用 cd base && docker compose up -d；服务器优先用 ./install.sh start。服务：db、redis、backend、frontend（app-network）。

容器内主机名是服务名（db、redis），不要用 localhost
常见卷：./data、./available-plugins、./backend/installed-plugins、./backend/logs
BASE_VERSION / 镜像标签需与插件 @quan-erp/* 版本一致
模板密钥仅用于本地/开发 — 共享环境前务必更换

SHLocal template

cd base
docker compose up -d
docker compose ps

SHServer (via install script)

cd installation
./install.sh start
./install.sh stop

2b. 示例 docker-compose.yaml

复制下方本地/开发模板，替换所有 change-me，将 VITE_BACKEND_API 设为浏览器可达地址。Backend 直连 db:5432。

DATABASE_HOST / DB_HOST=db，DB_PORT=5432 — 本模板无连接池中间件
OPENAI_* / FIREBASE_CONFIG — 仅在需要时配置；切勿提交私钥

YAMLdocker-compose.yaml

services:
  db:
    image: postgres:17
    container_name: postgres
    restart: always
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: change-me
      POSTGRES_DB: quan-erp
    ports:
      - "5432:5432"
    volumes:
      - ./data/db-data:/var/lib/postgresql/data
    networks:
      - app-network

  redis:
    image: redis:7
    container_name: quanerp-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    command: >
      redis-server
      --requirepass "change-me"
      --appendonly yes
    volumes:
      - ./data/redis:/data
    networks:
      - app-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping", "-a", "change-me"]
      interval: 5s
      timeout: 2s
      retries: 5

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile
    image: theparadance/quan-erp-base-backend:1.0.0
    restart: unless-stopped
    platform: linux/amd64
    container_name: backend
    ports:
      - "8080:8080"
      - "8081:8081"
    environment:
      NODE_ENV: production
      MODE: dev
      BASE_VERSION: 1.0.0
      ORGANIZATION_ID: quan-erp

      FRONTEND_URL: http://localhost
      BACKEND_URL: http://localhost:8080
      DEV_TOOL_URL: http://localhost:8081
      PLUGIN_SERVER_URL: http://localhost:8082

      ACCESS_TOKEN_SECRET: change-me
      ACCESS_TOKEN_SECRET_EXPIRATION_TIME: 15m
      REFRESH_TOKEN_SECRET: change-me
      REFRESH_TOKEN_SECRET_EXPIRATION_TIME: 30d

      DATABASE_HOST: db
      DB_HOST: db
      DB_USERNAME: postgres
      DB_PASSWORD: change-me
      DB_PORT: 5432
      DB_SCHEMA: quan-erp
      DB_SYNC: true

      REDIS_HOST: redis
      REDIS_PORT: 6379
      REDIS_PASSWORD: change-me

      CLUSTER_MODE: false
      CLUSTER_MAX_COUNT: 2
      ENV_ENCRYPTION_KEY: change-me-32-char-hex-or-secret
      FIREBASE_CONFIG: ''

      OPENAI_BASE_URL: https://api.deepseek.com
      OPENAI_API_KEY: <sk-key>

      CORS_ALLOWED_ORIGINS: http://localhost:3000,http://127.0.0.1:3000,http://localhost,https://localhost

      AVAILABLE_PLUGINS_FOLDER: /app/available-plugins
      INSTALLED_PLUGINS_FOLDER: /app/installed-plugins
      APP_DATA_FOLDER: /app/data/data/
      UPLOAD_FILE_TEMP_FOLDER: /app/data/temp
      UPLOAD_FILE_FOLDER: /app/data/data/
      PLUGINS_ENV_FILE: /app/data/data/plugin.env.json
      RUNNER_FLOW_FILE: /app/data/data/workflows/

      ROOT_ADMIN_USERNAME: admin
      ROOT_ADMIN_PASSWORD: change-me
      DEVELOPER_CONFIG_PASSWORD: change-me

      MAX_USER_LIMIT: 5
      MAX_ACTIVE_USER_LIMIT: 5
      MAX_USER_SESSION_LIMIT_PER_USER: 1
      MAX_ORGANIZATION_BRANCH: 1
      MAX_ROLE_LIMIT: 5
      MAX_SUBSCRIPTION_GRACE_PERIOD_DAYS: 14
      SUBSCRIPTION_END_DATE: '2099-01-01'
    volumes:
      - ./backend/installed-plugins:/app/installed-plugins
      - ./data:/app/data
      - ./backend/logs:/app/logs
      - ./available-plugins:/app/available-plugins
    depends_on:
      - db
      - redis
    networks:
      - app-network
    dns:
      - 1.1.1.1
      - 8.8.8.8

  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile
    image: theparadance/quan-erp-base-frontend:1.0.0
    restart: unless-stopped
    platform: linux/amd64
    container_name: frontend
    environment:
      VITE_BACKEND_API: http://localhost:8080
      VITE_MODE: dev
    ports:
      - "80:80"
    volumes:
      - ./data/frontend/web-env.json:/usr/share/nginx/html/web-env.json
    networks:
      - app-network

networks:
  app-network:
    driver: bridge

3. 服务与端口

db:5432（DB_HOST）、redis:6379、backend:8080/8081、frontend:80、主机 Nginx。生产勿对外暴露 db/redis。

db (postgres:17) — 5432；DB_HOST=db、DB_PORT=5432；schema quan-erp；./data/db-data
redis — 6379；REDIS_HOST=redis + REDIS_PASSWORD；./data/redis
backend — :8080 / :8081；挂载 plugins、data、logs
frontend — :80；VITE_BACKEND_API 必须浏览器可达
主机 Nginx — ./install.sh install 用于 TLS / 反向代理

4. 部署插件

使用 quan-erp build:prod|watch|pack:prod 暂存，再在 ERP UI 中安装。

构建产物 → available-plugins/<name>/<version>/
UI 安装后 → installed-plugins/<name>/
后端加载 installed=true 的模块
前端加载 module.js 并调用 register(AppRegistry)
仅本地/开发可插入 module 行 — 切勿在 UAT/生产这样做

TSBuild & stage

# From repo root
quan-erp build:prod sample-es
# Continuous during development
quan-erp watch sample-es

# Distributable zip (frontend + backend + metadata)
quan-erp pack:prod sample-es
quan-erp pack:prod sample-es ./dist-archives

5. 版本对齐

保持 base 镜像标签与插件 @quan-erp/* 版本一致。

插件 package.json 中的 @quan-erp/* 需与 base 镜像同版本
compose 镜像标签与 BASE_VERSION 保持同步
module.metadata.json 的 pluginVersion / requiredBasedVersion 需匹配
升级 base 后，用对应 @quan-erp/* 重建插件

6. 环境配置

DB_* 指向 db:5432，配置 REDIS_*、令牌、CORS、URL，并用卷持久化插件与数据目录。生产使用 migrations。

DB_* / DATABASE_HOST — 示例栈用 db:5432；DB_SCHEMA 对应 POSTGRES_DB
REDIS_* — 必须匹配 redis 的 requirepass
ACCESS_TOKEN_* / REFRESH_TOKEN_* / ENV_ENCRYPTION_KEY — 勿用模板值
CORS_ALLOWED_ORIGINS — 填入浏览器来源
FRONTEND_URL / BACKEND_URL / VITE_BACKEND_API — 可达 URL
插件 / 数据目录路径 — 用卷持久化
BASE_VERSION + 镜像标签 — 与插件版本对齐
DB_SYNC — 仅本地/开发；预发/生产用 migrations
MODE — 模板多为 dev；生产使用生产模式

7. 预发与生产清单

先运行 ./install.sh install，更换默认密钥，勿暴露 db/redis，用 Nginx 做 TLS，勿把 Firebase / npm 密钥提交进 git，禁止生产 seed。

首次启动前运行 ./install.sh install
更换 Postgres / Redis / ROOT_ADMIN_* / 令牌与加密密钥
勿公开 Postgres / Redis 端口；用 Nginx 终止 TLS
持久化并备份 ./data、plugins、logs
上线前关闭 DB_SYNC=true、过宽 CORS、示例密钥
通过 UI 安装插件 — 生产禁止 SQL seed
用 migrations 管理 schema，勿依赖 synchronize
FRONTEND_URL / BACKEND_URL / VITE_BACKEND_API 需匹配公网主机名
升级前对齐 base 与 @quan-erp/* 版本
切勿把 FIREBASE / npm 密钥提交进 git

8. 日常运维

使用 ./install.sh start|stop，并规划 base / 插件升级、日志、备份与回滚。

启停：cd installation && ./install.sh start|stop
升级 base：换新镜像标签后重建容器
升级插件：quan-erp build:prod|pack:prod → available-plugins → UI 安装
健康检查：docker compose ps；查看 backend 日志
数据：备份 Postgres 卷与 APP_DATA_FOLDER
回滚：保留旧插件版本目录与镜像标签

YAMLUseful compose commands

cd installation   # or cd base for the Node template
docker compose logs -f backend
docker compose restart backend frontend
docker compose down
./install.sh start

排查

install 失败 — OS / sudo / Docker 源
docker 权限 — 重新登录以生效 docker 组
start 失败 — 检查 POSTGRES_* / REDIS_* / 镜像标签
连不上 DB — DB_HOST=db、DB_PORT=5432
前端调不通 API — VITE_BACKEND_API 需为浏览器可达地址
UI 无插件 — available-plugins / 版本 / 本地 module 行
页面空白 — 重建前端并重新安装
CORS / 认证失败 — FRONTEND_URL 与 origins
版本错误 — base 与 @quan-erp/* 不一致

部署遇到问题？

若在部署 Quark ERP 时遇到困难，可向 The Paradance 寻求支持。根据具体情况，协助可能免费，也可能另行收费——取决于工作范围、紧急程度与环境。

请提供 BASE_VERSION / 镜像标签、操作系统、compose 日志与复现步骤
简单指引可能免费；动手搭建、生产加固或定制运维可能收费
开始收费工作前会先明确免费或付费

Support →Email The Paradance →