跳到主内容

环境变量与系统配置

ShopFaaS 私有化部署配置完整清单(环境变量对齐 packages/boots-core/src/env/env.ts,系统配置对齐 sys_config 表)。

ShopFaaS 的配置分为两类:环境变量(不可变,启动期注入)与系统配置(可动态修改,运行时通过管理后台调整)。

生产环境(NODE_ENV=production)启动时会强校验关键环境变量,使用开发默认值或弱密钥将阻止启动。

配置分类说明

1. 环境变量(不可变)

通过 .env 文件或容器环境变量注入,修改后必须重启服务才能生效。适合存放:

  • 基础设施凭据:DATABASE_URL / REDIS_URL / JWT_SECRET / INTERNAL_API_KEY 等(启动期必需,无法通过管理后台修改)
  • 启动期单例参数:PG_POOL_SIZE / CACHE_L2_ENABLED / RATE_LIMIT_REDIS_ENABLED 等(在连接池/缓存层/限流器初始化时一次性读取)
  • 构建期/部署形态常量:NODE_ENV / PORT / DEPLOY_MODE / EDITION 等
  • 主密钥本身:CREDENTIALS_ENCRYPTION_KEY(用于加解密 sys_config 中的敏感字段,必须 env 注入,禁止入库)

2. 系统配置(可动态修改)

存储在 sys_config 表中,通过 suite 管理后台 → 系统 → 系统配置 界面 CRUD 修改,修改后自动热重载生效(部分配置项需重建单例)。适合存放:

  • 运行时可调参数:http.cors_origin / http.body_size_limit / log.level / db.slow_query_ms / rate_limit.* 等
  • 业务参数:payment.app_url / chat.ws_url 等
  • 第三方服务凭证(AES-256-GCM 加密存储):payment.stripe.secret_key / payment.stripe.webhook_secret / storage.s3.secret_access_key / email.smtp.password / security.fingerprint_salt 等

敏感字段(含 secret / password / salt 关键字)在写入时自动 AES-256-GCM 加密,读取时自动解密;列表/详情默认返回脱敏值,需点击”显示明文”才能查看。加密密钥派生自 CREDENTIALS_ENCRYPTION_KEY 环境变量。

必填环境变量

变量名说明示例
DATABASE_URLPostgreSQL 连接字符串postgres://shopfaas:password@localhost:5432/shopfaas
REDIS_URLRedis 连接字符串redis://:password@localhost:6379

生产环境另需 JWT_SECRET、INTERNAL_API_KEY,详见认证配置章节。

应用配置

变量名默认值说明
NODE_ENVdevelopment运行环境（production / development / test）
PORT4322HTTP 服务器监听端口
DEPLOY_MODEprivate部署模式：private(私有化部署) / saas(SaaS 多租户运营)
LOG_DIR./logs日志文件目录（启动期确定,不可热重载）
PLATFORM_DOMAIN空SaaS 模式平台主域名(逗号分隔,支持多域名)。store 的 shop-resolver 每请求从 host 提取 shop_code 识别店铺;suite 拼接店铺访问地址。属于启动期必需的基础设施配置,不走 sys_config

LOG_LEVEL 与 CORS_ORIGIN 已迁移到系统配置(对应 log.level / http.cors_origin),详见系统配置章节。环境变量保留作为 fallback 兜底(仅启动期首次读取,后续以 sys_config 为准)。

APP_URL 已迁移到系统配置(对应 payment.app_url),详见系统配置章节。环境变量保留作为 fallback 兜底(仅 shopfaas-pay 启动期首次读取,后续以 sys_config 为准)。生产环境应通过管理后台配置 payment.app_url,不在 .env 中保留,避免 Vite build 时 baked-in 到 dist。

数据库配置

变量名默认值说明
DATABASE_RESOLVER_URL空域名解析专用 PG 连接串（BYPASSRLS 角色）。SaaS 模式必填；私有化留空回退主连接
DATABASE_SYSTEM_URL空系统级操作专用 PG 连接串（BYPASSRLS 角色）。SaaS 模式必填；私有化留空回退主连接
PG_POOL_SIZE20PostgreSQL 连接池大小（启动期单例,不可热重载）

DB_SLOW_QUERY_MS 与 BODY_SIZE_LIMIT 已迁移到系统配置(对应 db.slow_query_ms / http.body_size_limit),详见系统配置章节。

Redis 配置

变量名默认值说明
CACHE_L2_ENABLEDfalse是否启用缓存 L2 Redis 层。SaaS 生产环境强制 true(启动期单例)
RATE_LIMIT_REDIS_ENABLEDfalse是否启用 Redis 分布式限流。SaaS 生产环境强制 true(启动期单例)

RATE_LIMIT_WINDOW_MS / RATE_LIMIT_MAX_REQUESTS / RATE_LIMIT_TENANT_MAX_REQUESTS 已迁移到系统配置(对应 rate_limit.window_ms / rate_limit.max_requests / rate_limit.tenant_max_requests),详见系统配置章节。修改后自动重建限流器。

对象存储配置

留空 S3_ENDPOINT 时不启用对象存储,回退到 LOCAL_STORAGE_DIR 本地存储(仅适合单机部署)。

S3 配置已迁移到系统配置(storage.s3.* 系列),详见系统配置章节。S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY 等环境变量保留作为 fallback 兜底;storage.s3.secret_access_key 在 sys_config 中以 AES-256-GCM 加密存储。

S3_FORCE_PATH_STYLE 不是环境变量。S3 兼容端点(RustFS / MinIO)的 path-style 访问由 boots-core/storage 自动检测处理,无需也无法通过环境变量配置。

变量名默认值说明
S3_ENDPOINT空S3 兼容对象存储端点(启动期 fallback,运行时以 storage.s3.endpoint 为准)
S3_PUBLIC_BASE_URL空S3 公共访问基础 URL(同上,对应 storage.s3.public_base_url)
S3_ACCESS_KEY_ID空S3 访问密钥 ID(同上,对应 storage.s3.access_key_id)
S3_SECRET_ACCESS_KEY空S3 秘密访问密钥(同上,对应 storage.s3.secret_access_key,加密存储)
S3_BUCKET空S3 存储桶名称(同上,对应 storage.s3.bucket)
S3_REGIONus-east-1S3 区域(同上,对应 storage.s3.region)
LOCAL_STORAGE_DIR../storages本地存储根目录(启动期 fallback,运行时以 storage.local.dir 为准)

认证配置

变量名默认值说明
JWT_SECRETdev-jwt-secret-change-in-productionJWT 签名密钥。生产环境强制校验：不能使用默认值且长度 ≥32 字符
INTERNAL_API_KEYdev-internal-key内部 API 共享密钥（服务间鉴权 X-Internal-API-Key 头）。生产环境禁止使用默认值

邮件 SMTP 凭证(email.smtp.password)已迁移到系统配置,加密存储,详见系统配置章节。

License 签发(仅 suite 侧)

仅 suite 侧配置,store 侧不消费这两个变量。

变量名默认值说明
LICENSE_SECRET空License 签发与部署配置加密密钥（仅 suite 侧使用）。用途：签发部署令牌（HMAC-SHA256 签名）、加密/解密部署配置（AES-256-GCM，经 SHA-256 派生 32 字节密钥）。安全约束：仅 suite 侧配置，store 侧不引用此变量；生产环境必须配置长度 ≥ 16 的强密钥；留空时 suite 侧部署相关功能（deploy-token/config-crypto）会拒绝执行
LICENSE_SIGNING_KEY空License 响应签名 Ed25519 私钥（仅 suite 侧使用，方案 B1）。用途：suite 对心跳响应做 Ed25519 非对称签名，store 用公钥校验（防客户伪造 suite 响应）。格式：128 字符 hex（64 字节，Ed25519 PKCS8 DER 编码）。未配置时：开发环境自动生成临时密钥；生产环境必须显式配置。安全约束：仅 suite 侧配置，绝对不下发给客户（store 只持有公钥）

加密主密钥

变量名默认值说明
CREDENTIALS_ENCRYPTION_KEY空敏感字段加密主密钥(64 字符 hex = 32 字节)。用于加解密 sys_config 中的敏感字段(Stripe 密钥 / SMTP 密码 / S3 密钥 / 指纹盐等)。必须 env 注入,禁止入库;留空时加密工具返回原文 + warn(不阻塞业务,但存在明文存储风险)

联动配置(store → suite)

仅 store 子项目消费。suite 永远在平台方部署,不消费这些变量。store 通过 SUITE_API_URL 调用 suite;suite 不可达时 store 降级 NoOp 兜底。

store 侧认证 cookie 名称为 auth_token,suite 侧认证 cookie 名称为 suite_auth_token。二者通过 HTTP 头传递,不是环境变量,不会出现在本表或 env.ts 中。

变量名默认值说明
SUITE_API_URL空shopfaas-suite 联动 API 基址。SaaS 模式必填；私有化留空禁用联动（NoOp 兜底）；开发环境默认 http://localhost:4323

2026-07-22 重构：DEV_SHOP_HOSTS 与 SHOP_DEV_FALLBACK 已删除。私有化部署模式下，未匹配自定义域名的请求自动回退到首个 ACTIVE 店铺（按 createdAt 升序），无需任何环境变量配置；多店铺场景请通过 shop_domain 表绑定域名。

License 与翻译

2026-07-22 重构:LICENSE_SKIP 环境变量已废弃。License 校验行为由 DEPLOY_MODE + SUITE_API_URL 自动推导:

  • 非生产环境:自动跳过 License 校验(无需任何配置)
  • 生产环境 + 私有化部署 + 未配置 SUITE_API_URL:自动跳过(独立部署模式)
  • 生产环境 + SaaS 模式:必须配置 SUITE_API_URL(否则启动失败)
  • 生产环境 + 配置了 SUITE_API_URL:正常激活 License 校验
变量名默认值说明
TRANSLATION_API_BASE空机器翻译 API 端点（OpenAI 兼容 chat completions，留空则禁用）
TRANSLATION_API_KEY空机器翻译 API 密钥（留空则禁用）
TRANSLATION_API_MODELgpt-4o-mini机器翻译 API 模型名称

一键更新与部署配置

仅 store 消费。用于 store 容器内通过 docker CLI（挂载 /var/run/docker.sock）派生 update-runner 容器完成”下载镜像 → 加载 → 重启服务 → 健康检查 → 失败回滚”全流程。

变量名默认值说明
STORE_AUTO_UPDATE_ENABLEDfalse是否启用一键更新功能。启用后 store 容器内可通过 docker CLI（挂载 /var/run/docker.sock）派生 update-runner 容器，完成”下载镜像 → 加载 → 重启服务 → 健康检查 → 失败回滚”全流程。Docker 部署：由 docker-compose.yml 默认设为 true（客户通过部署本 compose 文件明确启用）；开发模式：默认 false（无 docker.sock 挂载，功能不可用）。安全提示：启用此功能等于赋予 store 容器宿主机 docker daemon 控制权，仅适用于私有化部署场景（客户自有机器，数据自主）
HOST_DEPLOY_DIR空宿主机部署目录的绝对路径。用于一键更新功能：update-runner 容器需挂载此目录以访问 docker-compose.yml。由 start.sh / start.ps1 自动设置为 $(pwd) 或 $PWD.Path，客户无需手动配置。Linux 部署：如 /home/user/privatemode；WSL2 部署：如 /mnt/c/Users/…/privatemode；Windows 原生路径（如 C:…）：不兼容，需通过 WSL2 部署。留空时：一键更新功能不可用（getUpdateStatus 返回 unavailable，executeUpdate 拒绝执行）。注意：此值同时作为 bind mount 的 host 路径和容器内路径（更新容器内的工作目录）。在 Linux 部署环境两者一致；Windows + Docker Desktop 测试环境需用 HOST_DEPLOY_HOST_PATH 显式指定 Windows 格式的 host 路径（因容器内 Linux 不认识 Windows 路径）
HOST_DEPLOY_HOST_PATH空宿主机部署目录的”宿主机视角”路径（可选）。用于 Windows + Docker Desktop 测试环境：update-runner 派生容器的 bind mount host 路径需用 Windows 格式（如 D:/ShopFaas/.../deploy-dir），但容器内路径需用 Linux 格式（如 /deploy-dir）。HOST_DEPLOY_DIR 是容器内路径，HOST_DEPLOY_HOST_PATH 是 host 路径。Linux 生产环境：留空（默认），host 路径和容器内路径都用 HOST_DEPLOY_DIR；Windows 测试环境：设为 Windows 格式路径（如 D:/.../deploy-dir）；留空时：update-runner.ts 回退到 HOST_DEPLOY_DIR（默认行为）

系统配置

系统配置存储在 sys_config 表中,通过 suite 管理后台 → 系统 → 系统配置 界面 CRUD 修改。所有配置项支持运行时修改,部分配置项修改后自动热重载(无需重启服务)。

缓存机制:sys_config 通过 Bentocache L1(进程内)+L2(Redis)二级缓存,TTL 5 分钟。写操作后自动失效缓存,下次读取拉取最新值。

热重载机制:

  • http.cors_origin / http.body_size_limit / db.slow_query_ms — 中间件每次请求 hash 比对,变更后零开销重建(下次请求生效)
  • rate_limit.* — 写操作后主动重建限流器(保留内部计数状态)
  • log.level — 写操作后更新主服务 logger + Worker 池 logger level
  • payment.stripe.* — 下次调用 payment 服务时 hash 比对重建 Stripe 实例

敏感字段加密:含 secret / password / salt 关键字的 configKey 自动 AES-256-GCM 加密存储,加密密钥派生自 CREDENTIALS_ENCRYPTION_KEY 环境变量。列表/详情默认返回脱敏值(如 sk_***xxxx),需点击”显示明文”按钮并具备 sys:config:update 权限才能查看明文。

HTTP 分组

configKey默认值类型加密说明热重载
http.cors_origin*STRING否CORS 允许的源(逗号分隔;* 表示允许所有源;SaaS 生产环境禁止 *)下次请求生效
http.body_size_limit10485760NUMBER否全局请求体大小上限(字节,默认 10MB),适用于绝大多数 API下次请求生效
http.upload_body_size_limit209715200NUMBER否上传专用请求体大小上限(字节,默认 200MB),仅 /api/manage/upload 路由(version-releases 模块)下次请求生效

SYSTEM 分组

configKey默认值类型加密说明热重载
log.leveldebugSTRING否日志级别(trace/debug/info/warn/error/fatal)写后立即生效(主服务 + Worker 池)

DATABASE 分组

configKey默认值类型加密说明热重载
db.slow_query_ms1000NUMBER否慢查询阈值(毫秒,超过此值记录 warn 日志)下次查询生效

RATE_LIMIT 分组

configKey默认值类型加密说明热重载
rate_limit.window_ms60000NUMBER否限流时间窗口(毫秒)写后重建限流器
rate_limit.max_requests600NUMBER否限流窗口内单用户/IP 最大请求数写后重建限流器
rate_limit.tenant_max_requests6000NUMBER否租户维度限流窗口内最大请求数(默认为单用户的 10 倍)写后重建限流器

限流开关 RATE_LIMIT_REDIS_ENABLED 仍为环境变量(启动期单例),修改后需重启服务。

PAYMENT 分组

configKey默认值类型加密说明热重载
payment.stripe.secret_key空STRING是Stripe API 密钥(用于服务端调用 Stripe API)下次调用 payment 服务时重建实例
payment.stripe.publishable_key空STRING否Stripe 公钥(供 store 前端加载 Stripe.js)下次调用时生效
payment.stripe.webhook_secret空STRING是Stripe Webhook 签名密钥(用于验证 Webhook 请求来源)下次 Webhook 验证时生效
payment.app_url空STRING否应用 URL（suite 平台自身 SaaS 支付流程用，shopfaas-pay 必填，用于构造支付回调 URL）。注：shopfaas-store 侧的 APP_URL 已迁移到 shop_payment_method.extra.appUrl（收款设置页支付通道配置），不走此 sys_config下次调用时生效

WEBSOCKET 分组

configKey默认值类型加密说明热重载
chat.ws_url空STRING否客服聊天 WebSocket URL(开发环境显式配置如 ws://localhost:8330/ws;生产环境留空,客户端用 wss://${host}/ws)下次页面加载生效

STORAGE 分组

configKey默认值类型加密说明热重载
storage.s3.endpoint空STRING否S3 兼容服务端点(如 http://127.0.0.1:9000)下次存储操作生效
storage.s3.access_key_id空STRING否S3 访问密钥 ID下次存储操作生效
storage.s3.secret_access_key空STRING是S3 秘密访问密钥(加密存储)下次存储操作生效
storage.s3.bucket空STRING否S3 存储桶名称下次存储操作生效
storage.s3.regionus-east-1STRING否S3 区域下次存储操作生效
storage.s3.public_base_url空STRING否S3 公共访问基础 URL(CDN 域名或公开访问端点,留空则用预签名 URL)下次存储操作生效
storage.local.dir../storagesSTRING否本地存储根目录(仅 LOCAL 模式生效,与子项目平级的 storages 目录)下次存储操作生效

EMAIL 分组

configKey默认值类型加密说明热重载
email.smtp.host空STRING否SMTP 服务器主机名(如 smtp.gmail.com、smtp.qq.com、smtp.163.com)下次发信生效
email.smtp.port587NUMBER否SMTP 端口(587=STARTTLS / 465=SSL/TLS 直连)下次发信生效
email.smtp.user空STRING否SMTP 认证用户名(留空表示匿名发送)下次发信生效
email.smtp.password空STRING是SMTP 密码(加密存储)下次发信生效
email.smtp.securefalseBOOLEAN否是否使用 SSL/TLS 直连(true=端口465 / false=端口587 STARTTLS)下次发信生效

SECURITY 分组

configKey默认值类型加密说明热重载
security.fingerprint_salt空STRING是部署指纹 salt(加密存储;用于 license-tool 生成部署绑定指纹,防止 License 被复制)下次指纹生成生效

生产环境检查清单

部署到生产环境前,请确认:

  • JWT_SECRET 已设置为至少 32 字符的随机字符串（不能使用默认值）
  • INTERNAL_API_KEY 已设置为随机字符串（不能使用默认值）
  • CREDENTIALS_ENCRYPTION_KEY 已设置为 64 字符 hex 字符串(32 字节,用于加密 sys_config 敏感字段)
  • License 行为由 DEPLOY_MODE + SUITE_API_URL 自动推导（无需 LICENSE_SKIP,该变量已废弃）
  • DEPLOY_MODE=saas 时：http.cors_origin 系统配置已指定具体域名白名单（禁止 *）
  • DEPLOY_MODE=saas 时：RATE_LIMIT_REDIS_ENABLED=true（多实例限流安全）
  • DEPLOY_MODE=saas 时：CACHE_L2_ENABLED=true（多实例缓存一致性）
  • 数据库密码、Redis 密码均已修改为强密码
  • DATABASE_RESOLVER_URL 与 DATABASE_SYSTEM_URL 已配置 BYPASSRLS 角色连接串（SaaS 模式）
  • STORE_AUTO_UPDATE_ENABLED=true 时，确认 HOST_DEPLOY_DIR 已设置为宿主机部署目录绝对路径
  • sys_config 中 payment.stripe.secret_key / payment.stripe.webhook_secret 已通过管理后台配置(加密存储)
  • sys_config 中 storage.s3.* 已通过管理后台配置(若使用对象存储)
  • sys_config 中 email.smtp.* 已通过管理后台配置(若使用邮件通知)

相关文档

此页面有帮助吗?

在 GitHub 上编辑此页