本地开发

本地部署 ShopFaaS 体验完整功能，或为开发应用与主题做准备。6 步安装指南，含 Bun/PostgreSQL/Redis 版本要求与平台差异说明。

本地开发适合以下场景：

评估者：想完整体验功能后再决定是否采用托管服务
主题开发者：为店铺前台开发自定义主题
应用开发者：开发应用扩展上架应用市场
贡献者：参与 ShopFaaS 开源项目贡献

前置准备

运行时版本

组件	最低版本	推荐版本	说明
Bun	1.3.14+	最新	JavaScript 运行时与包管理器（推荐最新版）
PostgreSQL	18.4	18.4	必须使用 `pgvector/pgvector:pg18` 镜像，无最低版本兼容
Redis	8.8.0	8.8.0	必须使用 `redis:8-alpine` 镜像，无最低版本兼容
Git	—	最新	版本控制

操作系统

推荐 macOS 12+。使用 Homebrew 安装 Bun 与 Redis：

brew install bun redis git
brew services start redis

PostgreSQL 安装方式

Homebrew 暂未提供 postgresql@18，建议使用 Docker 启动 PostgreSQL：

docker run -d --name pg \
  -e POSTGRES_PASSWORD=shopfaas \
  -p 5432:5432 \
  pgvector/pgvector:pg18

或参考 PostgreSQL 官方安装指南。

推荐 Ubuntu 20.04+ / Debian 11+ / CentOS 8+。

# 安装 Bun
curl -fsSL https://bun.sh/install | bash

# 安装 Redis
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis.gpg
echo "deb [signed-by=/usr/share/keyrings/redis.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list
sudo apt update
sudo apt install -y redis git
sudo systemctl enable --now redis-server

# 安装 PostgreSQL 18（通过 PGDG 官方仓库）
curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo gpg --dearmor -o /usr/share/keyrings/postgresql.gpg
echo "deb [signed-by=/usr/share/keyrings/postgresql.gpg] http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" | sudo tee /etc/apt/sources.list.d/postgresql.list
sudo apt update
sudo apt install -y postgresql-18
sudo systemctl enable --now postgresql

推荐 Windows 10/11 + WSL2（PowerShell 脚本已兼容）。

# 在 WSL2 Ubuntu 中安装
curl -fsSL https://bun.sh/install | bash
sudo apt install -y postgresql-18 redis-server git
sudo systemctl enable --now postgresql redis-server

硬件配置（开发环境）

资源	最低	推荐
CPU	2 vCPU	4 vCPU
内存	4 GB	8 GB
磁盘	20 GB	50 GB SSD

安装步骤

克隆仓库

git clone https://github.com/shopfaas/shopfaas.git
cd shopfaas

安装依赖
```
bun install
```

配置环境变量

仓库已含 .env.development 团队共享开发配置，本地按需覆盖：

# .env.development 主要配置项
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=shopfaas_dev
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
REDIS_HOST=localhost
REDIS_PORT=6379
JWT_SECRET=change-me-in-production-at-least-32-chars
PORT=4322

初始化数据库

4.1 创建数据库与扩展：

CREATE DATABASE shopfaas_dev ENCODING 'UTF8';
\c shopfaas_dev
CREATE EXTENSION IF NOT EXISTS vector;

4.2 执行 Schema 初始化脚本：

bun run scripts/init-db.ts install

该命令自动按模块顺序执行 schema → cross-fk → init-data。

4.3 安装示例数据（可选）：

# 安装 Demo Fashion Store 演示数据
bun run scripts/init-db.ts install-sample

生成 Kysely 类型
```
bun run db:gen-types
```
表结构变更后必做
任何表结构变更后必须重新生成类型，否则 TypeScript 类型检查会失败。
启动开发服务器
```
bun run dev
```
启动成功后访问 http://localhost:4322/。

测试账号

初始化数据中的默认账号：

角色	邮箱	密码	入口
Demo 店长	`owner@demo-fashion.com`	`Admin@123456`	`/login` → `/admin`
Demo 员工	`staff@demo-fashion.com`	`Admin@123456`	`/login` → `/admin`
访客	—	—	`/`（无需登录）

此账号为本地开发种子数据（scripts/init-db.ts install-sample 生成），生产环境默认账号为 admin / admin123，详见手动部署 → 访问店铺。

常用命令

命令	说明
`bun run dev`	启动开发服务器（端口 4322）
`bun run build`	构建生产产物
`bun run start`	启动生产服务器（需先 build）
`bun run check`	类型检查 + Astro 检查 + ESLint + Prettier
`bun run format:fix`	自动格式化代码
`bun test`	运行单元测试
`bun run db:gen-types`	重新生成 Kysely 类型
`bun run scripts/init-db.ts install`	初始化数据库 Schema

下一步

功能介绍

了解店铺后台与前台功能。

开发者指南

主题开发与应用扩展开发。

私有化部署

生产环境部署指南。

贡献指南

参与开源贡献。