手动部署

手动安装 ShopFaaS 各组件，适合需要定制化部署场景的客户。

手动部署适合不使用 Docker 的场景，如需使用系统包管理器安装、或需要深度定制组件配置。

前置条件

服务器满足最低配置要求
已安装 Node.js 20+（运行预构建产物只需 Node 运行时；Bun 仅开发环境需要）
拥有 root 或 sudo 权限

1. 安装 PostgreSQL 18

# Ubuntu/Debian
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

创建数据库与用户：

sudo -u postgres psql << 'EOF'
CREATE USER shopfaas WITH PASSWORD 'your-strong-password';
CREATE DATABASE shopfaas OWNER shopfaas;
\c shopfaas
CREATE EXTENSION IF NOT EXISTS vector;
EOF

2. 安装 Redis 8

# Ubuntu/Debian
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

# 启动并设置开机自启
sudo systemctl enable --now redis-server

配置密码（编辑 /etc/redis/redis.conf）：

requirepass your-strong-password

重启 Redis：

sudo systemctl restart redis-server

3. 安装 RustFS（对象存储）

RustFS 是 ShopFaaS 使用的 S3 兼容对象存储，用于存储商品图片、主题文件等。推荐使用 Docker 运行（镜像版本为 1.0.0-beta.10，对应 rustfs/rustfs:latest tag）：

mkdir -p /opt/rustfs/data

docker run -d \
  --name rustfs \
  --restart unless-stopped \
  -p 9000:9000 \
  -v /opt/rustfs/data:/data \
  -e RUSTFS_ACCESS_KEY=shopfaas \
  -e RUSTFS_SECRET_KEY=your-strong-secret \
  rustfs/rustfs:latest

4. 下载 ShopFaaS 预构建产物包

从 GitHub Releases 下载对应版本的预构建产物包（仅含 dist/ + entry.mjs + package.json，不含源码与构建配置）：

# 替换 ${VERSION} 为目标版本号（如 v1.2.0）
mkdir -p /opt/shopfaas && cd /opt/shopfaas
curl -L -o shopfaas-store-dist.tar.gz \
  https://github.com/shopfaas/shopfaas/releases/download/${VERSION}/shopfaas-store-${VERSION}-dist.tar.gz

# 解压（覆盖到当前目录）
tar -xzf shopfaas-store-dist.tar.gz
rm shopfaas-store-dist.tar.gz

5. 配置环境变量

cp .env.example .env

编辑 .env 文件，填写实际配置，完整环境变量见环境变量参考。

# 数据库
DATABASE_URL=postgres://shopfaas:your-strong-password@localhost:5432/shopfaas

# Redis
REDIS_URL=redis://:your-strong-password@localhost:6379

# 对象存储
S3_ENDPOINT=http://localhost:9000
S3_ACCESS_KEY_ID=shopfaas
S3_SECRET_ACCESS_KEY=your-strong-secret
S3_BUCKET=shopfaas

# 部署模式
DEPLOY_MODE=private

# 其他必填项见环境变量参考

6. 数据库自动初始化

数据库初始化逻辑已内置于 entry.mjs，首次启动服务时自动执行（建表 + 写入 init-data：权限码、系统角色、默认配置），无需手动运行命令。

entry.mjs 启动时会检测数据库是否已初始化，未初始化则自动按 docs/schemas/ 下的 SQL 文件创建表结构并写入种子数据，幂等可重复执行。

7. 启动服务

使用 systemd（推荐）

创建 /etc/systemd/system/shopfaas.service：

[Unit]
Description=ShopFaaS Application
After=network.target postgresql.service redis-server.service

[Service]
Type=simple
User=shopfaas
WorkingDirectory=/opt/shopfaas
ExecStart=/usr/bin/node entry.mjs
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

# 创建专用用户
sudo useradd -r -s /bin/false -d /opt/shopfaas shopfaas
sudo chown -R shopfaas:shopfaas /opt/shopfaas

# 启动并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now shopfaas

# 查看状态
sudo systemctl status shopfaas

手动启动（测试用）

node entry.mjs

8. 访问店铺

启动完成后，访问：

店铺前台：http://your-server-ip:4322
店铺后台：http://your-server-ip:4322/admin
默认店长账号：admin / admin123（首次登录后请立即修改密码）

升级

升级时下载新版本预构建产物包，解压覆盖，重启服务即可：

# 1. 停止服务
sudo systemctl stop shopfaas

# 2. 备份数据库
pg_dump -U shopfaas shopfaas > backup_$(date +%Y%m%d).sql

# 3. 下载新版本预构建产物包（替换 ${VERSION} 为目标版本）
cd /opt/shopfaas
curl -L -o shopfaas-store-dist.tar.gz \
  https://github.com/shopfaas/shopfaas/releases/download/${VERSION}/shopfaas-store-${VERSION}-dist.tar.gz

# 4. 解压覆盖（保留 .env 与 storages/）
tar -xzf shopfaas-store-dist.tar.gz
rm shopfaas-store-dist.tar.gz

# 5. 修正属主
sudo chown -R shopfaas:shopfaas /opt/shopfaas

# 6. 重启服务（容器启动时自动执行数据库迁移，无需手动 init-db）
sudo systemctl start shopfaas

# 7. 查看迁移日志（可选）
sudo journalctl -u shopfaas -f

反向代理

建议使用 Nginx 反向代理配置 HTTPS，配置方式与 Docker 部署的反向代理相同。