快速开始

目标：从零把图模工坊在一台开发机上跑起来，看到三端 + API + 合成 + 人脸服务互通。

0. 环境前置

1. 拉代码

1
2
3

git clone https://gitcode.com/<your-account>/printing-factory.git
cd printing-factory
bun install

bun install 按 workspaces 装 apps/* + packages/* 依赖。合成服务首次需装 Chromium：bun compose:install-browser。人脸模型 scrfd_500m_bnkps.onnx 已在 apps/pf-face-service/models/。

2. 起依赖服务（PostgreSQL / Redis / MinIO）

自备一份 docker-compose.yml（注意是 PostgreSQL，不是 MySQL）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: printing-factory
    ports: ["5432:5432"]

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass redis
    ports: ["6379:6379"]

  minio:
    image: minio/minio:latest
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minio
      MINIO_ROOT_PASSWORD: passwdminio
    ports: ["1280:9000", "9001:9001"]

1

docker compose up -d

MinIO 控制台 http://localhost:9001（minio / passwdminio）创建 bucket pf-bucket。

3. 配置 pf-service

apps/pf-service/config.json 自带开发默认值，对接上面容器无需改动（db.url = postgres://postgres:postgres@localhost:5432/printing-factory、composeService.baseUrl = http://localhost:3030、faceService.baseUrl = http://localhost:3010）。改了凭据/端口就同步这里。

4. 初始化数据库

1
2

cd apps/pf-service
bun db:push                 # Drizzle 同步 schema（26 张表）到 printing-factory 库

RBAC 默认数据（超管账号、角色、菜单）由服务启动时 ensureDefaultRbacData() 幂等写入，无需手动跑种子。想要演示商品/相册/模板数据，可选跑 bun scripts/seed_ecommerce.ts / seed_albums.ts / seed_ai_templates.ts。

5. 启动全部服务

回到仓库根目录：

1

bun dev

这会用 concurrently 同时拉起 7 个进程（含本地 Caddy 网关）：

1
2
3
4
5
6
7

caddy   → tools/caddy/caddy.exe                             http://localhost:9800（统一入口）
editor  → bun run --filter @wangijun/pf-editor dev          http://localhost:8100  (/editor/)
app     → bun run --filter @wangijun/pf-app dev             http://localhost:8000  (/app/)
manage  → bun run --filter @wangijun/pf-manage dev          http://localhost:9527  (/manage/)
service → bun run --filter @wangijun/pf-service dev         http://localhost:3000
compose → bun run --filter @wangijun/pf-compose-service dev http://localhost:3030
face    → bun run --filter @wangijun/pf-face-service dev    http://localhost:3010（cargo run）

推荐直接访问网关 http://localhost:9800（/ 会重定向到 /manage/），三端 + /api/ + /storage/ 同源。也可用子集脚本：bun dev:frontend / dev:backend / dev:admin，或单独 bun dev:service / dev:compose / dev:face / dev:download。

首次 cargo run 编译 pf-face-service 会稍慢（Rust 编译）；合成服务首次会启动 Chromium Worker 池。

6. 健康自检

1
2
3

curl http://localhost:3000/health   # → { "code": "0000", ..., "message": "服务正常" }
curl http://localhost:3030/health   # → { "code": "0000", "data": { "status": "ready", "workers": {...} } }
curl http://localhost:3010/health   # → { "code": "0000", "data": { "status": "ok", "modelLoaded": true } }

Swagger：http://localhost:3000/docs。

7. 首次登录与联调

打开 http://localhost:9800/manage/，用 RBAC 种子的默认超管账号登录（见 services/seedService.ts 中的常量）。上架样板模板后，在 /app/ 打开工坊传图，提交后：

• 后台/DB 能看到 pending 提交
• 10 秒内 Job 抢占 → 调合成服务 → processing → completed
• 合成产物 publicUrl（/storage/composition/...）可打开
• 首页快捷门户可跳到 /editor/ 与 /app/

8. 联调验证清单

• 后台登录、用户/角色/菜单可用
• 编辑器创建并上架一张模板（乐观上传占位正常）
• 用户端看到模板、成功传图（小图/大图/批量，失败可重试）
• 提交后 10s 内 pending → processing → completed
• 合成产物可打开，缩略图走 ?w= imgproxy
• 带 faceSafe 的模板人脸不被裁掉
• （可选）pf-download 登录并下载成品

9. 常见踩坑

下一步

• 想看上线/分布式部署 → 部署
• 想看配置项细节 → 配置参考
• 想接入电商主站 → 电商集成方案