快速开始

目标：从零开始，把图模工坊在一台开发机上跑起来，10 分钟内看到用户端 H5 + 编辑器 + 管理后台都能登录并互通。

0. 环境前置

Windows / macOS / Linux 都跑得动，主项目以 Bun 为最小公因子。

1. 拉代码

1
2
3

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

bun install 会按 package.json 的 workspaces 自动安装 apps/* + packages/* 的依赖。

2. 起依赖服务

最快路径是 docker compose（自备一份 docker-compose.yml）：

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

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: mysql
      MYSQL_DATABASE: pf-manage
    ports: ["3306:3306"]

  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"      # S3 API
      - "9001:9001"      # Console

1

docker compose up -d

在 MinIO 控制台 http://localhost:9001 用 minio / passwdminio 登录，创建 bucket pf-bucket，并将其访问策略设为公共读（或后续都走预签名）。

3. 配置 pf-service

apps/pf-service/config.json 自带开发默认值，无需改动即可对接上面起的容器：

1
2
3
4
5
6
7

{
  "server": { "port": 3000, "jobs": { "composition": { "enabled": true, "intervalMs": 10000 } } },
  "db":     { "url": "mysql://root:mysql@localhost:3306/pf-manage" },
  "redis":  { "host": "127.0.0.1", "port": 6379, "username": "default", "password": "redis", "db": 0 },
  "s3":     { "accessKeyId": "minio", "secretAccessKey": "passwdminio", "bucket": "pf-bucket", "endpoint": "http://localhost:1280" },
  "faceService": { "baseUrl": "http://localhost:3010", "timeoutMs": 8000 }
}

如果你改了任何凭证 / 端口，把这里同步好。

4. 初始化数据库

1
2
3

cd apps/pf-service
bun db:push        # Drizzle 同步 schema 到 pf-manage 库
bun run src/db/seed.ts  # 写入默认管理员、若干分类、样板模板

执行完后 pf-manage 库里能看到 20+ 张表。

5. 准备人脸模型

把 scrfd_500m_bnkps.onnx（InsightFace 公开模型）放到：

1

apps/pf-face-service/models/scrfd_500m_bnkps.onnx

模型下载地址参见 InsightFace 仓库；模型校验/兼容策略见 人脸检测服务。

6. 启动全部服务

回到仓库根目录，一行命令并行起：

1

bun dev

这会通过 concurrently 同时拉起：

1
2
3
4
5

editor  → bun run --filter @wangijun/pf-editor dev        http://localhost:9000
app     → bun run --filter @wangijun/pf-app dev           http://localhost:8000
manage  → bun run --filter soybean-admin dev              http://localhost:9527
service → bun run --filter @wangijun/pf-service dev       http://localhost:3000
face    → bun run --filter @wangijun/pf-face-service dev  http://localhost:3010

如果不想一次起全部，使用单独脚本：

1
2
3
4
5

bun dev:service     # 只起后端
bun dev:editor      # 只起编辑器
bun dev:app         # 只起用户端
bun dev:manage      # 只起后台
bun dev:face        # 只起人脸服务

7. 健康自检

1
2
3
4
5

curl http://localhost:3000/health
# → { "code": "0000", "data": null, "message": "服务正常", ... }

curl http://localhost:3010/health
# → { "code": "0000", "data": { "status": "ok", ... } }

Swagger 文档：http://localhost:3000/docs

8. 首次登录

打开 http://localhost:9527（管理后台），用 seed 中的默认管理员账号（参见 apps/pf-service/src/db/seed.ts）登录。

进入”模板治理”→ 上架若干样板模板 → 在 http://localhost:8000（用户端 H5）就能看到模板列表，选一张进入工坊页传图体验全流程。

9. 联调验证清单

跑完一遍以下场景代表整条链路通了：

• 后台登录、新增/编辑用户、菜单可用
• 编辑器创建一张模板并上架
• 用户端能看到该模板
• 工坊页能成功传图（小图 / 大图 / 批量）
• 提交后在后台能看到 pending 提交
• 10 秒内自动转为 processing → completed
• 合成产物 URL 可在浏览器打开
• 带 faceSafe 节点的模板，人脸不被裁掉

10. 常见踩坑

下一步

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