B2BC 平台部署指南

專案代號: B2BC
版本: 2.1.0
更新日期: 2026-03-03
狀態: 生產就緒

1. 專案概述

B2BC (Business-to-Business Collective) 是一個現代化的企業對企業團購平台，提供：

功能模組	說明
B2B 採購	供應商與團購主之間的批發交易
B2C 銷售	團購主向消費者的零售團購
財務系統	預繳餘額、平台費用、自动扣費
關係管理	供應商-團購主-消費者關係管理
驗證系統	用戶身份驗證與分級
即時下單	無購物車直接下單，1小時內可撤銷

技術棧

元件	技術	版本
後端 API	NestJS + TypeORM	Node.js 18+
資料庫	PostgreSQL + PostGIS	15+
緩存	Redis	6+
前端後台	React + Ant Design	Vite 5+
行動應用	Flutter	3.0+
監控	Prometheus + Grafana	-

2. 系統架構

┌─────────────────────────────────────────────────────────────────────┐
│                        B2BC 系統架構                                 │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │              React + Ant Design (統一後台)                      │ │
│  │   • 總管理員視角 (super_admin)                                 │ │
│  │   • 供應商視角 (supplier)                                     │ │
│  │   • 團購主視角 (leader)                                       │ │
│  │   • 消費者商店 (consumer)                                     │ │
│  └────────────────────────────┬───────────────────────────────────┘ │
│                               ▼                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │                   NestJS API Server                             │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│  │  │  Auth API   │ │  B2B API    │ │  B2C API    │ │ Finance API│ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ │ │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌────────────┐ │ │
│  │  │  Cart API   │ │ Invite API  │ │ Bonus API   │ │ Notify API │ │ │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └────────────┘ │ │
│  └────────────────────────────┬───────────────────────────────────┘ │
│                               ▼                                      │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │              PostgreSQL 15 + PostGIS 3.4                        │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                     │
│  ┌────────────────────────────────────────────────────────────────┐ │
│  │            統一 Flutter App (依 role 顯示不同功能)               │ │
│  └────────────────────────────────────────────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

角色權限

角色	後台視角	API 權限
super_admin	總後台全部功能	所有 API
supplier	供應商管理	B2B, 財務, 訂單
leader	團購主管理	B2B 採購, B2C, 訂單
consumer	消費者商店	B2C 購買, 購物金

3. 前置需求

硬體需求

環境	CPU	RAM	磁碟
開發環境	2 核心	4 GB	20 GB
生產環境	4 核心	8 GB	50 GB

軟體需求

# 必需軟體
- Node.js >= 18.0.0
- npm >= 9.0.0
- PostgreSQL >= 15.0
- Redis >= 6.0
- Docker >= 24.0
- Docker Compose >= 2.0

# 開發工具 (可選)
- Git
- VS Code (推薦)
- PostgreSQL Client (pgAdmin/DBeaver)

安裝 Node.js

# 使用 nvm 安裝 (推薦)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18

# 或直接安裝
# https://nodejs.org/

安裝 Docker

# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose

# 啟動 Docker
sudo systemctl start docker
sudo systemctl enable docker

# 將用戶加入 docker 群組
sudo usermod -aG docker $USER

4. 環境配置

4.1 複製環境文件

# 複製開發環境配置
cp .env.example .env

# 複製生產環境配置模板
cp .env.production.template .env.production

4.2 環境變數說明

# ===========================================
# 資料庫配置
# ===========================================
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=your_password
DB_DATABASE=b2bc

# ===========================================
# Redis 配置
# ===========================================
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password

# ===========================================
# API 伺服器配置
# ===========================================
PORT=3000
NODE_ENV=development

# ===========================================
# JWT 配置
# ===========================================
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRES_IN=7d
JWT_REFRESH_SECRET=your-refresh-secret-key-change-in-production
JWT_REFRESH_EXPIRES_IN=30d

# ===========================================
# 前端配置
# ===========================================
VITE_API_URL=http://localhost:3000
VITE_APP_TITLE=B2BC 管理系統

4.3 生產環境安全配置

# 生產環境必須修改以下變數
JWT_SECRET=$(openssl rand -base64 32)
JWT_REFRESH_SECRET=$(openssl rand -base64 32)
DB_PASSWORD=$(openssl rand -base64 16)
REDIS_PASSWORD=$(openssl rand -base64 16)

5. 本地開發環境

5.1 安裝依賴

# 安裝 API 伺服器依賴
cd api-server
npm install

# 安裝前端依賴
cd ../admin-web
npm install

5.2 啟動資料庫服務

# 使用 Docker 啟動 PostgreSQL 和 Redis
cd ..
docker-compose -f docker/docker-compose.dev.yml up -d

# 驗證服務運行
docker-compose -f docker/docker-compose.dev.yml ps

5.3 初始化資料庫

# 執行資料庫遷移
cd api-server
npm run migration:run

# 或者同步實體 (開發環境)
npm run sync-entities

5.4 啟動服務

# 終端機 1: 啟動 API 伺服器
cd api-server
npm run start:dev

# 終端機 2: 啟動前端
cd admin-web
npm run dev

5.5 訪問服務

服務	網址
前端後台	http://localhost:5173
API 伺服器	http://localhost:3000
Swagger API 文件	http://localhost:3000/api/docs

6. 生產部署

6.1 生產環境檢查清單

# 部署前確認事項
- [ ] 生產資料庫已配置並可訪問
- [ ] Redis 實例已配置密碼
- [ ] 所有環境變數已正確設置
- [ ] SSL/TLS 憑證已準備
- [ ] 備份策略已配置
- [ ] 監控系統已設置

6.2 使用部署腳本

# 給腳本執行權限
chmod +x scripts/deploy-production.sh

# 執行部署
./scripts/deploy-production.sh

6.3 手動部署

# 1. 构建后端
cd api-server
npm run build

# 2. 构建前端
cd ../admin-web
npm run build

# 3. 启动服务 (使用 PM2)
cd ../api-server
pm2 start dist/main.js --name b2bc-api

# 4. 配置 Nginx 反向代理
sudo cp nginx-prod.conf /etc/nginx/sites-available/b2bc
sudo nginx -t
sudo systemctl reload nginx

7. Docker 部署

7.1 構建 Docker 映像

# 構建 API 伺服器映像
cd api-server
docker build -t b2bc-api:latest .

# 構建前端映像
cd ../admin-web
docker build -t b2bc-admin:latest .

7.2 使用 Docker Compose

# 啟動所有服務
docker-compose -f docker/docker-compose.prod.yml up -d

# 查看服務狀態
docker-compose -f docker/docker-compose.prod.yml ps

# 查看日誌
docker-compose -f docker/docker-compose.prod.yml logs -f

7.3 生產 Docker Compose 配置

# docker/docker-compose.prod.yml
version: '3.8'

services:
  postgres:
    image: postgis/postgis:15-3.4
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: b2bc
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: always

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    restart: always

  api:
    image: b2bc-api:latest
    environment:
      - NODE_ENV=production
      - DB_HOST=postgres
      - REDIS_HOST=redis
    depends_on:
      - postgres
      - redis
    restart: always

  admin:
    image: b2bc-admin:latest
    ports:
      - "80:80"
    depends_on:
      - api

volumes:
  postgres_data:
  redis_data:

8. 監控系統

8.1 啟動監控服務

# 啟動監控堆疊
docker-compose -f monitoring/docker-compose.monitoring.yml up -d

8.2 訪問監控儀表板

服務	網址	預設帳號
Prometheus	http://localhost:9090	-
Grafana	http://localhost:3001	admin/admin
Alertmanager	http://localhost:9093	-

8.3 監控指標

系統指標: CPU、記憶體、磁碟使用率
API 指標: 請求延遲、錯誤率、併發數
資料庫指標: 連接數、查詢延遲、慢查詢
業務指標: 訂單數、活躍用戶、營業額

9. 資料庫設置

9.1 初始化腳本

# 執行初始化腳本
psql -U postgres -d b2bc -f init-scripts/init.sql

9.2 用戶初始化

# 使用初始化腳本創建測試用戶
bash scripts/init-users.sh

9.3 類別初始化

# 初始化 B2B 商品類別
bash scripts/init-categories.sh

10. 測試帳號

角色	帳號	密碼	說明
總管理員	admin@b2bc.com	newpass123	完全權限
供應商	supplier@b2bc.com	newpass123	B2B 商品管理
團購主	test@example.com	newpass123	B2B 採購/B2C 銷售
消費者	consumer@test.com	newpass123	購物功能

11. API 文件

11.1 Swagger API 文件

部署完成後訪問: http://localhost:3000/api/docs

11.2 主要 API 端點

# 認證
POST /api/auth/register
POST /api/auth/login
POST /api/auth/refresh
POST /api/auth/logout
GET  /api/auth/me

# B2B
GET    /api/b2b/products
POST   /api/b2b/products
GET    /api/b2b/orders
POST   /api/b2b/orders
GET    /api/b2b/relationships
POST   /api/b2b/relationships

# B2C
GET    /api/b2c/products
GET    /api/b2c/products/nearby
POST   /api/b2c/orders
GET    /api/b2c/orders
GET    /api/b2c/pickup-points

# 財務
GET    /api/bonus
GET    /api/fees
GET    /api/payments

# 購物車
GET    /api/cart
POST   /api/cart/items
PUT    /api/cart/items/:id
DELETE /api/cart/items/:id

# 驗證
GET    /api/verification/status
POST   /api/verification/validate-id
POST   /api/verification/upload-document

12. 故障排除

12.1 常見問題

資料庫連接失敗

# 檢查 PostgreSQL 服務狀態
docker-compose ps postgres

# 檢查連接
psql -h localhost -U postgres -d b2bc

# 檢查日誌
docker-compose logs postgres

Redis 連接問題

# 測試 Redis 連接
redis-cli -h localhost -p 6379 -a your_password ping

# 檢查日誌
docker-compose logs redis

API 服務啟動失敗

# 檢查端口是否被佔用
lsof -i :3000

# 檢查環境變數
cd api-server
npm run start:dev

# 查看詳細錯誤日誌
npm run start:dev 2>&1 | tee logs/error.log

前端構建失敗

# 清除緩存並重新安裝
cd admin-web
rm -rf node_modules package-lock.json
npm install

# 檢查 TypeScript 錯誤
npm run typecheck

12.2 日誌位置

服務	日誌位置
API 伺服器	`api-server/logs/`
Docker	`docker logs <container-name>`
Nginx	`/var/log/nginx/`
Systemd	`journalctl -u b2bc-api`

13. 安全配置

13.1 生產環境安全檢查清單

13.2 SSL/TLS 配置

# nginx-prod.conf
server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location / {
        proxy_pass http://localhost:5173;
    }

    location /api {
        proxy_pass http://localhost:3000;
    }
}

14. 維運指南

14.1 日常維護

# 資料庫備份 (每日)
pg_dump -U postgres b2bc > backup_$(date +%Y%m%d).sql

# 清理舊備份 (保留 30 天)
find /backups -name "*.sql" -mtime +30 -delete

# 清理 Docker 資源
docker system prune -f

14.2 監控檢查

# 檢查服務狀態
docker-compose ps

# 檢查資源使用
docker stats

# 檢查磁碟空間
df -h

14.3 緊急修復

# 重啟單一服務
docker-compose restart api

# 滾動回滾
docker-compose down
docker-compose -f docker-compose.backup.yml up -d

# 恢復資料庫
psql -U postgres b2bc < backup_20260301.sql

附錄

A. 專案結構

B2BC/
├── api-server/              # NestJS 後端
│   ├── src/
│   │   ├── modules/        # 功能模組
│   │   │   ├── auth/      # 認證
│   │   │   ├── b2b/       # B2B 業務
│   │   │   ├── b2c/       # B2C 業務
│   │   │   ├── finance/  # 財務系統
│   │   │   └── ...
│   │   └── main.ts
│   ├── dist/              # 編譯輸出
│   └── Dockerfile
│
├── admin-web/              # React 前端
│   ├── src/
│   │   ├── components/   # 共用元件
│   │   ├── pages/        # 頁面
│   │   ├── services/     # API 服務
│   │   └── context/      # 狀態管理
│   ├── dist/             # 編譯輸出
│   └── Dockerfile
│
├── doc/                   # 專案文檔
│   ├── deployment/       # 部署文檔
│   ├── development/      # 開發文檔
│   └── reports/         # 測試報告
│
├── docker/                # Docker 配置
├── monitoring/           # 監控配置
├── scripts/              # 部署腳本
└── init-scripts/          # 資料庫初始化

B. 快速命令參考

# 開發環境
npm run dev              # 啟動開發伺服器
npm run build            # 構建生產版本
npm run lint             # 程式碼檢查

# Docker
docker-compose up -d     # 啟動服務
docker-compose down      # 停止服務
docker-compose logs -f   # 查看日誌

# 資料庫
npm run migration:run    # 執行遷移
npm run sync-entities   # 同步實體

# PM2
pm2 list                 # 查看進程
pm2 logs                 # 查看日誌
pm2 restart all         # 重啟所有服務

文件資訊

建立日期: 2026-02-28
更新日期: 2026-03-03
版本: 2.1.0
專案狀態: 生產就緒

如需更多詳細信息，請參閱 doc/ 目錄中的其他文檔。

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github/workflows		.github/workflows
admin-web		admin-web
api-server		api-server
b2bc_mobile_app		b2bc_mobile_app
doc		doc
docker		docker
init-scripts/production		init-scripts/production
monitoring		monitoring
scripts		scripts
.env.example		.env.example
.env.production.template		.env.production.template
.gitignore		.gitignore
DailyProgress.md		DailyProgress.md
MinmaxPlan.md		MinmaxPlan.md
README.md		README.md
melos.yaml		melos.yaml

Folders and files

Latest commit

History

Repository files navigation

B2BC 平台部署指南

目錄

1. 專案概述

技術棧

2. 系統架構

角色權限

3. 前置需求

硬體需求

軟體需求

安裝 Node.js

安裝 Docker

4. 環境配置

4.1 複製環境文件

4.2 環境變數說明

4.3 生產環境安全配置

5. 本地開發環境

5.1 安裝依賴

5.2 啟動資料庫服務

5.3 初始化資料庫

5.4 啟動服務

5.5 訪問服務

6. 生產部署

6.1 生產環境檢查清單

6.2 使用部署腳本

6.3 手動部署

7. Docker 部署

7.1 構建 Docker 映像

7.2 使用 Docker Compose

7.3 生產 Docker Compose 配置

8. 監控系統

8.1 啟動監控服務

8.2 訪問監控儀表板

8.3 監控指標

9. 資料庫設置

9.1 初始化腳本

9.2 用戶初始化

9.3 類別初始化

10. 測試帳號

11. API 文件

11.1 Swagger API 文件

11.2 主要 API 端點

12. 故障排除

12.1 常見問題

資料庫連接失敗

Redis 連接問題

API 服務啟動失敗

前端構建失敗

12.2 日誌位置

13. 安全配置

13.1 生產環境安全檢查清單

13.2 SSL/TLS 配置

14. 維運指南

14.1 日常維護

14.2 監控檢查

14.3 緊急修復

附錄

A. 專案結構

B. 快速命令參考

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages