部署指南

部署架构

---

Docker Compose 部署（推荐）

docker-compose.yml

version: '3.8'
services:
  backend:
    image: yunstack/backend:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@postgres:5432/yunstack
      - REDIS_URL=redis://redis:6379
      - MQTT_BROKER_URL=mqtt://emqx:1883
      - JWT_SECRET=your-secret-key
      - SALT_SECRET=your-salt-key
    depends_on:
      - postgres
      - redis
      - influxdb
      - emqx

  emqx:
    image: emqx/emqx:5.7.0
    ports:
      - "1883:1883"     # MQTT
      - "8083:8083"     # WebSocket
      - "18083:18083"   # Dashboard
    environment:
      - EMQX_NAME=emqx
      - EMQX_HOST=127.0.0.1

  postgres:
    image: postgres:16
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=yunstack
      - POSTGRES_PASSWORD=your-password
      - POSTGRES_DB=yunstack
    volumes:
      - pg_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  influxdb:
    image: influxdb:2.7
    ports:
      - "8086:8086"
    environment:
      - DOCKER_INFLUXDB_INIT_MODE=setup
      - DOCKER_INFLUXDB_INIT_USERNAME=admin
      - DOCKER_INFLUXDB_INIT_PASSWORD=your-password
      - DOCKER_INFLUXDB_INIT_ORG=yunstack
      - DOCKER_INFLUXDB_INIT_BUCKET=yunstack_telemetry
    volumes:
      - influxdb_data:/var/lib/influxdb2

volumes:
  pg_data:
  redis_data:
  influxdb_data:

启动

docker compose up -d

---

PM2 部署（后端）

# 安装 PM2
npm install -g pm2

# 构建
cd yunstack-backend
pnpm build

# 启动
pm2 start pm2.config.js

# 管理
pm2 status            # 查看状态
pm2 logs              # 查看日志
pm2 restart backend   # 重启
pm2 stop backend      # 停止

---

前端部署

Web 管理后台

cd yunstack-web
pnpm build           # 构建到 dist/
# 将 dist/ 部署到 Nginx 或 CDN

Nginx 配置

server {
    listen 80;
    server_name admin.yunstack.com;

    # 前端静态文件
    root /var/www/yunstack-web/dist;
    index index.html;

    # API 代理
    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # MQTT WebSocket 代理
    location /mqtt {
        proxy_pass http://127.0.0.1:8083;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

---

文档部署 (Cloudflare Pages)

配置项	值
Build command	npm run docs:build
Build output	.vitepress/dist
Framework	VitePress

cd yunstack-docs
pnpm docs:build
npx wrangler pages deploy .vitepress/dist

---

环境变量参考

变量	必填	说明
DATABASE_URL	是	PostgreSQL 连接串
REDIS_URL	是	Redis 连接串
REDIS_PASSWORD	否	Redis 密码
MQTT_BROKER_URL	是	EMQX Broker 地址
MQTT_USERNAME	否	MQTT 用户名
MQTT_PASSWORD	否	MQTT 密码
JWT_SECRET	是	JWT 签名密钥
SALT_SECRET	是	密码加密盐值
INFLUX_URL	否	InfluxDB 地址
INFLUX_TOKEN	否	InfluxDB Token
SERVER_PORT_HTTP	否	HTTP 端口（默认 9876）
CORS_ORIGINS	否	允许的跨域来源
UPLOAD_TYPE	否	上传方式：local/oss

---

数据库初始化

cd yunstack-backend

# 生成 Prisma Client
pnpm db:generate

# 开发环境迁移
pnpm db:migrate

# 生产环境推送（不生成迁移文件）
pnpm db:push

# 填充初始数据
pnpm prisma db seed

---

健康检查

# 后端健康
curl http://localhost:3000/api/v1/

# 系统状态（需 admin token）
curl -H "Authorization: Bearer <token>" http://localhost:3000/api/v1/system/status

# EMQX Dashboard
open http://localhost:18083  # 默认 admin/public

---

生产环境检查清单

• [ ] .env 文件已配置且密钥强度足够
• [ ] 数据库已初始化并迁移
• [ ] EMQX PostgreSQL 认证 + 内置 ACL 规则已配置
• [ ] Nginx SSL 证书已设置
• [ ] 防火墙仅开放必要端口（443, 8883）
• [ ] 日志目录已配置并设置了轮转
• [ ] 监控告警已配置（可选）